Audit Logging

KubeMQ records a built-in audit trail of security, control-plane, and data-plane error events. Every audit event follows the CloudEvents v1.0 specification, so the trail is interoperable with any CloudEvents-aware tooling, and it is queryable through a REST API on the management API port (:8080).

Overview

Audit logging is on by default. Events are persisted to a local durable store on each node and synchronized across cluster nodes over the cluster mesh, so every node holds the full audit trail for the entire cluster. Each event is a CloudEvents v1.0 envelope carrying a structured data payload that captures who did what, on which channel, over which transport, and whether it succeeded.

Three kinds of events are recorded:

• Control events — security, connection lifecycle, and administrative operations (authentication, authorization, client connect/disconnect, subscriptions, channel create/delete, cluster membership, server lifecycle).
• Data error events — failures in message send and receive operations across the patterns.
• System error events — infrastructure-level failures such as storage or broker errors.

Configure it

Audit logging has three settings: a master enable toggle, the retention window in hours, and how often expired records are purged.

audit:
  enable: true                  # on by default
  retentionHours: 720           # retain events for 30 days
  cleanupIntervalMinutes: 60    # purge expired events hourly

spec:
  audit:
    enable: true                # on by default
    retentionHours: 720         # retain events for 30 days
    cleanupIntervalMinutes: 60  # purge expired events hourly

For the full settings table — types, defaults, valid values, and the Docker/Helm naming for each key — see the Observability settings reference.

Event format

Each audit event is a CloudEvents v1.0 envelope. The envelope carries the standard CloudEvents attributes; the audit-specific payload lives in data.

{
  "specversion": "1.0",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "source": "kubemq://my-cluster/node-1",
  "type": "io.kubemq.audit.auth.success",
  "time": "2026-03-26T12:34:56.789Z",
  "datacontenttype": "application/json",
  "data": {
    "category": "control",
    "subcategory": "success",
    "client_id": "my-producer",
    "source_ip": "10.0.0.5",
    "transport": "grpc",
    "channel": "orders",
    "action": "auth.success",
    "outcome": "success",
    "metadata": {
      "method": "SendEvent"
    }
  }
}

Envelope fields

Data fields

Event catalog

Control events

Control-plane events track security, connection lifecycle, and administrative operations. These events carry category: "control".

A channel monitor watches for channels appearing and disappearing and emits channel.created / channel.deleted control events accordingly.

Data error events

Data-plane error events track failures in message send and receive operations. These events carry category: "data".

System error events

System-level errors from infrastructure components. These events carry category: "system".

Retention & cleanup

Audit events are retained for the window set by retentionHours (default 720 hours = 30 days). A background cleanup runs at the interval set by cleanupIntervalMinutes (default 60 minutes) and deletes every event older than the retention window. Both settings accept a minimum of 1. Tune retentionHours to your compliance window and lower cleanupIntervalMinutes only if you need expired events purged more aggressively.

Retention applies per node, but because the trail is synchronized over the cluster mesh, every node holds — and prunes — the same cluster-wide set of events.

Query the audit log (REST)

The audit trail is queryable through the management API port (:8080). Two endpoints are available: one to list matching events and one to aggregate them.

List events

GET /api/v1/audit

curl "http://localhost:8080/api/v1/audit?category=control&event_type=auth.failure&limit=10"

Aggregate statistics

GET /api/v1/audit/stats

curl "http://localhost:8080/api/v1/audit/stats?group_by=category&from=2026-03-25T00:00:00Z"

Error responses

Access control

When control-plane authentication is enabled, the audit query endpoints require at least the ReadOnly role, like the rest of the management API. See the Management API overview for the response envelope, status codes, and access-control model.

Feed a SIEM

The REST query API makes it straightforward to feed audit events into an external SIEM. Poll GET /api/v1/audit on an interval, advancing the from / to window each pass, and forward the returned CloudEvents records into Splunk, Elastic, or any log-management platform. Because the trail is synchronized cluster-wide, you can poll a single node and still capture every event from the cluster.

Related

• Observability settings reference — the audit configuration keys with their Docker and Helm naming, defaults, and valid values.
• Management API — the response envelope, status codes, and access-control model shared by the audit query endpoints.