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/*`

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": <n> }`
`GET /api/stomp/subscriptions`	`{ "subscriptions": [StompSubscriptionDTO…], "total": <n> }`

`GET /api/stomp/connections`

Lists the live STOMP client connections on this node.

curl -s http://localhost:8080/api/stomp/connections

{
  "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-<login>` or `stomp-<uuid8>`)
`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`

Lists the active subscriptions on this node.

curl -s http://localhost:8080/api/stomp/subscriptions

{
  "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

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

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

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

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

# 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`

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`

Every STOMP audit event carries Transport = "stomp".

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

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.

Connections & Observability