# Connections & Observability (/connectors/amqp/reference/connections-endpoint) This reference documents the AMQP 1.0 connector's observability surface: the **HTTP detail endpoints**, the **11 Prometheus metric families**, the **SSE metrics group**, and the **audit events** the connector emits. ## HTTP detail endpoints [#http-detail-endpoints] The connector registers two read-only JSON routes on the internal API port (`8080`), network-protected like all `/api/*` routes. They are registered up front and nil-check the live provider, so they respond `200` with **empty lists** until the connector is wired (and even when AMQP 1.0 is disabled), returning `503` only while the API service is not yet ready. | Method & path | Returns | | ----------------------------- | --------------------------------------------------------- | | `GET /api/amqp10/connections` | `{ "connections": [Amqp10ConnectionDTO…], "total": }` | | `GET /api/amqp10/links` | `{ "links": [Amqp10LinkDTO…], "total": }` | ### `Amqp10ConnectionDTO` [#amqp10connectiondto] | JSON field | Type | Meaning | | -------------- | ------ | ------------------------------------------------- | | `client_id` | string | auth ClientID, or the container-id when anonymous | | `container_id` | string | OPEN container-id (sanitized) | | `product` | string | from OPEN properties, if the client sent them | | `version` | string | from OPEN properties, if sent | | `sessions` | int | live sessions on the connection | | `links` | int | live links across all sessions | | `connected_at` | string | RFC3339 timestamp | | `source_ip` | string | peer IP | | `sasl` | string | `plain` / `anonymous` / `external` / `none` | | `tls` | bool | TLS-terminated connection | ### `Amqp10LinkDTO` [#amqp10linkdto] | JSON field | Type | Meaning | | ----------- | ------ | ----------------------------------------------------------------- | | `client_id` | string | owning connection's ClientID | | `name` | string | peer-assigned link name | | `role` | string | `sender` / `receiver` (**server** perspective) | | `address` | string | resolved terminus address | | `pattern` | string | `queues` / `events` / `events-store` / `commands` / `queries` / … | | `channel` | string | resolved KubeMQ channel | | `credit` | int64 | current link credit (server view) | | `unsettled` | int64 | deliveries awaiting settlement | | `durable` | bool | durable subscription link | | `dynamic` | bool | dynamic-node terminus link | AMQP 1.0 has no exchange/binding topology, so there is **no topology endpoint** (unlike the AMQP 0-9-1 / RabbitMQ connector). The link list *is* the topology view. ## Prometheus metrics — 11 families [#prometheus-metrics--11-families] The connector exposes **11** `kubemq_amqp10_*` metric families: **3 gauges + 8 counters**. All are scraped from the standard KubeMQ metrics endpoint. ### Gauges (3) [#gauges-3] | Metric | Labels | Meaning | | --------------------------- | ---------------------------- | ------------------------------------- | | `kubemq_amqp10_connections` | — | current open connector connections | | `kubemq_amqp10_sessions` | — | current open connector sessions | | `kubemq_amqp10_links` | `role` (`sender`/`receiver`) | current attached links by server role | ### Counters (8) [#counters-8] | Metric | Labels | Meaning | | -------------------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------- | | `kubemq_amqp10_transfers_total` | `direction` (`in`/`out`), `pattern` | transfers by direction and KubeMQ pattern | | `kubemq_amqp10_dispositions_total` | `outcome` (`accepted`/`released`/`modified`/`rejected`) | terminal dispositions by outcome | | `kubemq_amqp10_rpc_requests_total` | `pattern` (`commands`/`queries`) | RPC requests routed through the connector | | `kubemq_amqp10_errors_total` | `scope` (`conn`/`session`/`link`) | connector error conditions by scope | | `kubemq_amqp10_transfers_in_dropped_total` | — | **inbound transfers dropped: oversize / no-consumer / pre-settled failure** | | `kubemq_amqp10_events_dropped_no_credit_total` | — | events dropped on an outbound link with **no credit** (fire-hose semantics) | | `kubemq_amqp10_events_store_dropped_stalled_total` | — | events-store messages dropped when the **credit-0 buffer stalled** (link DETACH) | | `kubemq_amqp10_rpc_late_responses_total` | — | RPC responses arriving **after the requester went away** | ### The two drop counters to watch [#the-two-drop-counters-to-watch] These are the connector's **data-loss footgun signals** — on a healthy producer/consumer they should stay at **0**: * **`kubemq_amqp10_events_dropped_no_credit_total`** — increments every time the connector has an `events/` message to deliver but the consumer link has **zero credit**. Events are at-most-once fire-hose: with no credit the message is **silently dropped**. Grant standing credit continuously. * **`kubemq_amqp10_events_store_dropped_stalled_total`** — increments when a durable events-store consumer stops granting credit and the credit-0 bounded buffer overflows, forcing a **DETACH with lost messages**. Replenish credit eagerly. **`kubemq_amqp10_transfers_in_dropped_total` covers three causes, not one.** Its help text is *"inbound AMQP 1.0 transfers dropped (oversize, no consumer, pre-settled failure)"*. It counts an **oversize** inbound transfer, a transfer with **no consumer**, **and** a **pre-settled routing failure** — do not read it as pre-settled-only. ## SSE metrics group [#sse-metrics-group] The live dashboard streams a snapshot of these metrics as an `api.Amqp10MetricsGroup` over the metrics SSE channel. The store mirrors the same gauges and counters as the Prometheus families above (the store clamps gauges at 0 and the Prometheus mirror follows the clamp, so the two never diverge). ## Audit events [#audit-events] **The AMQP 1.0 connector emits exactly two audit events: `auth.success` and `auth.failure`.** It does **not** emit `client.connected` or `client.disconnected` — those are **not** part of this connector's audit surface. Both come from the SASL layer: | Event | When | Fields | | -------------- | --------------- | ------------------------------------------------------------------------------------------------ | | `auth.success` | SASL outcome OK | `ClientID`, `Transport: "amqp10"`, `SourceIP`, `Metadata{mechanism}` | | `auth.failure` | SASL rejected | `ClientID`, `Transport: "amqp10"`, `SourceIP`, `Error` (sanitized reason), `Metadata{mechanism}` | The `mechanism` metadata is `plain` / `anonymous` / `external`, and `SourceIP` is the peer IP. The **full failure reason** lives only in the `auth.failure` audit record — the SASL **wire** outcome carries the code alone (the no-leak rule; see [Error Conditions](/connectors/amqp/reference/error-conditions)). To observe connection lifecycle (count, age, source IP, SASL mechanism), poll `GET /api/amqp10/connections` or scrape `kubemq_amqp10_connections` — **not** the audit log. ## Related [#related]