# Connections & Observability (/connectors/stomp/reference/connections-endpoint) This reference documents how to see what the KubeMQ STOMP connector is doing: the **management HTTP API**, the **Prometheus series**, the **web dashboard**, and the **audit taxonomy**. These are the tools you use to verify STOMP is actually listening — the connector loader is **availability-first**: a bind failure logs `error loading stomp connector, continuing without STOMP` and the server keeps running without STOMP, so a clean boot does **not** prove the listener is up. ## Management API — `GET /api/stomp/*` [#management-api--get-apistomp] Two node-local, read-only HTTP endpoints, registered on the server's web API group. They are wired before the connector exists and nil-check the provider, so they return `200` with empty lists even when STOMP is disabled — UI-safe. | Method & path | Returns | | ------------------------------ | ------------------------------------------------------------ | | `GET /api/stomp/connections` | `{ "connections": [StompConnectionDTO…], "total": }` | | `GET /api/stomp/subscriptions` | `{ "subscriptions": [StompSubscriptionDTO…], "total": }` | ### `GET /api/stomp/connections` [#get-apistompconnections] Lists the live STOMP client connections on this node. ```bash curl -s http://localhost:8080/api/stomp/connections ``` ```json { "connections": [ { "client_id": "stomp-my-app", "remote_addr": "10.0.0.7:54321", "version": "1.2", "connected_at": "2026-06-15T09:41:12Z", "subscriptions": 2 } ], "total": 1 } ``` Each element is a `StompConnectionDTO`: | JSON field | Type | Notes | | --------------- | ------ | ------------------------------------------------------- | | `client_id` | string | derived session id (`stomp-` or `stomp-`) | | `remote_addr` | string | TCP peer address | | `version` | string | `1.0` / `1.1` / `1.2` (negotiated) | | `connected_at` | string | RFC3339 | | `subscriptions` | int | active subscription count | ### `GET /api/stomp/subscriptions` [#get-apistompsubscriptions] Lists the active subscriptions on this node. ```bash curl -s http://localhost:8080/api/stomp/subscriptions ``` ```json { "subscriptions": [ { "id": "sub-1", "client_id": "stomp-my-app", "destination": "/queue/jobs/email", "pattern": "queues", "channel": "jobs.email", "ack_mode": "client-individual" } ], "total": 1 } ``` Each element is a `StompSubscriptionDTO`: | JSON field | Type | Notes | | ------------- | ------ | --------------------------------------------- | | `id` | string | the SUBSCRIBE `id` (or auto-generated on 1.0) | | `client_id` | string | owning connection | | `destination` | string | the STOMP destination as subscribed | | `pattern` | string | `queues` / `events` / `store` / `reply` | | `channel` | string | resolved KubeMQ channel (slash → dot) | | `ack_mode` | string | `auto` / `client` / `client-individual` | ### Status codes [#status-codes] | Condition | Response | | ---------------------------------- | -------------------------------------------------------- | | ready | `200` + the list wrapper | | API service not ready | `503` (`api service not ready`) | | STOMP disabled / no provider wired | `200` + empty list (`{ "connections": [], "total": 0 }`) | The dashboard tables poll these endpoints every **5 s**. Both are **node-local** — in a cluster, query each node. ## Prometheus metrics — 3 series, 11-op closed set [#prometheus-metrics--3-series-11-op-closed-set] The connector exposes exactly **three** Prometheus series: | Metric | Type | Labels | Notes | | ----------------------------------------- | --------- | --------------------- | --------------------------------------------------------------------------------------------------- | | `kubemq_stomp_connections` | Gauge | — | active connections; floor-clamped at 0 | | `kubemq_stomp_operations_total` | Counter | `operation`, `status` | per-operation counts | | `kubemq_stomp_operation_duration_seconds` | Histogram | `operation` | only sampled when duration > 0 (per-message deliver ops pass duration 0 and are counted, not timed) | ### The 11-operation closed set [#the-11-operation-closed-set] `operation` is one of exactly eleven values: | Operation | Emitted on | | ----------------- | ------------------------------------------------------------ | | `connect` | a completed CONNECT handshake | | `send` | a SEND to events / store / queues / RPC | | `subscribe` | a SUBSCRIBE | | `unsubscribe` | an UNSUBSCRIBE | | `deliver` | one events / store MESSAGE delivered | | `deliver_queues` | one queue MESSAGE delivered | | `deliver_headers` | per egress header outcome (notably `dropped` — CR/LF gotcha) | | `ack` | an ACK | | `nack` | a NACK | | `rpc_request` | an RPC SEND dispatched | | `rpc_response` | an RPC reply delivered | ### The status label [#the-status-label] `status` is one of three values: `success` / `error` / `dropped`. `dropped` appears for **best-effort** paths that do not close the connection — a full output buffer dropping an event delivery (`deliver` / `deliver_queues`), an unrepresentable header (`deliver_headers` / `dropped`), or a dropped RPC reply (`rpc_response` / `dropped`). ### Verifying STOMP is up via metrics [#verifying-stomp-is-up-via-metrics] ```text # non-zero means the listener is up and at least one client connected kubemq_stomp_connections # header drops (CR/LF to 1.0/1.1 subscribers) kubemq_stomp_operations_total{operation="deliver_headers", status="dropped"} # RPC failures (timeouts / logical errors arriving as stomp-error MESSAGEs) kubemq_stomp_operations_total{operation="rpc_response", status="error"} ``` The `kubemq_stomp_connections` gauge being **present and ≥ 0** is one of the three ways to confirm the STOMP listener is actually up — the other two are the `/stomp` dashboard and `GET /api/stomp/connections`. Do **not** infer the listener from a successful server boot; the loader is availability-first. ## Web dashboard — `/stomp` [#web-dashboard--stomp] The server exposes a web route at **`/stomp`** showing live STOMP connections, subscriptions, and per-operation stats. Per-operation stats are pushed on the `connectors` Server-Sent-Events stream under the key `stomp`. The dashboard's connection and subscription tables are backed by the two `GET /api/stomp/*` endpoints above and poll every 5 s. ## Audit taxonomy — `Transport = stomp` [#audit-taxonomy--transport--stomp] Every STOMP audit event carries `Transport = "stomp"`. ### Control-plane events [#control-plane-events] | Event | Emitted on | | ---------------------- | ------------------------------------------------------------ | | `client.connected` | a successful CONNECT handshake | | `client.disconnected` | a connection closing (graceful or otherwise) | | `client.timeout` | the heartbeat watchdog force-closing a dead peer (2× cutoff) | | `auth.success` | a `passcode` JWT accepted | | `auth.failure` | a `passcode` JWT rejected | | `subscription.created` | a queue or events / store subscription activated | | `subscription.closed` | a subscription torn down | | `subscription.error` | a subscription failing during registration / activation | ### Data-plane errors [#data-plane-errors] | Event | Emitted on | | ---------------------- | --------------------------------------------------------------------------------------------------------- | | `publish.error` | an array publish call returning an error (surfaces to the client as `message rejected`) | | `queue.delivery.error` | a queue delivery failure, **including the ack-timeout sweeper requeue** (`ack timeout, message requeued`) | | `rpc.error` | an RPC transport error / timeout (delivered to the client as a `stomp-error` MESSAGE) | The ack-timeout sweeper's `queue.delivery.error` audit is the operator-side signal of the `redelivered:true` redelivery — there is no client-side DLQ. ## Related [#related]