Prometheus Metrics

KubeMQ exposes an always-on Prometheus exporter that reports message counts, byte volumes, client counts, queue health, RPC latency, cluster state, and agent-platform activity. It needs no configuration — it is running the moment KubeMQ starts.

Overview

The Prometheus exporter is always on. The same in-process metrics also power the built-in dashboard and its snapshot system, so the numbers you scrape with Prometheus and the numbers you see in the dashboard come from one source.

Metrics are served in-process by the management API at GET /metrics on the management API port (:8080) — the same port that serves health probes, stats, and the dashboard. There is no separate listener and no extra setup; the endpoint returns standard Prometheus text format.

Scraping KubeMQ

Read the endpoint directly with curl:

curl http://localhost:8080/metrics

Point Prometheus at the same endpoint with a scrape_config:

scrape_configs:
  - job_name: kubemq
    metrics_path: /metrics
    static_configs:
      - targets: ["kubemq:8080"]

Labels

Core messaging metrics carry a shared label set. The type and side label values are determined by the messaging pattern.

Core messaging metrics

These collectors track message activity across all five patterns. They share the label set above.

Queue health metrics

These series give queue operators visibility into redelivery, dead-letter dispositions, backlog age, and dwell time. They use the standard four-label set (node, type, side, channel) — client_id is aggregated away — except where a row notes an extra label.

RPC latency metrics

These series measure command and query round-trip latency on the send side. They use the standard four-label set.

Latency histograms

Three histogram instruments expose latency distributions (so you can compute percentiles with histogram_quantile), labeled by node, type, and side.

All three histograms share one bucket set (seconds), giving a consistent latency vocabulary across /metrics:

0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60

Cluster & infra metrics

These gauges expose node health, cluster role, and configured peer state, labeled by node (and role where noted).

On a single-node (standalone) server, kubemq_cluster_leader = 1, kubemq_cluster_role{role="standalone"} = 1, kubemq_cluster_ready = 1 once ready, and kubemq_cluster_peers = 1. On a multi-node cluster, exactly one node has kubemq_cluster_leader = 1 at any given time.

Agent-platform metrics

KubeMQ's agent platform emits its own series for MCP tool calls and A2A agent traffic. These use domain-specific labels rather than the core messaging label set.

The MCP tool-call histogram (kubemq_mcp_tool_duration_seconds) uses the bucket set 0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10; the A2A request-duration histogram (kubemq_a2a_request_duration_seconds) uses 0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60.

In a cluster, these counters are aggregated across all nodes, so the totals reflect the whole deployment rather than a single replica.

PromQL examples

# RPC p99 latency (commands) — rolling 5-minute window
histogram_quantile(0.99,
  rate(kubemq_rpc_latency_histogram_seconds_bucket{type="commands"}[5m])
)

# Queue dwell p95 across all nodes
histogram_quantile(0.95,
  sum(rate(kubemq_queue_dwell_histogram_seconds_bucket[5m])) by (le)
)

# Alert: no leader exists across the cluster
sum(kubemq_cluster_leader) == 0

# Alert: a node has been not-ready for more than 60 seconds
kubemq_cluster_ready == 0 and kubemq_cluster_state_seconds > 60

Grafana

Point Grafana at the Prometheus instance scraping KubeMQ and build dashboards on the series above — message rates from kubemq_messages_count, queue health from the kubemq_queue_* series, latency percentiles from the histogram buckets, and cluster state from the kubemq_cluster_* gauges.

Internal channels

Internal cluster channels are filtered out of the user-facing metrics, so they never appear in the series above.