> For the complete documentation index, see [llms.txt](https://metalbear.com/mirrord/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://metalbear.com/mirrord/docs/using-mirrord/subscribe.md). # Subscribing to Events Use mirrord subscribe to stream the events of a mirrord session as JSON, for example in CI. `mirrord subscribe` lets you stream live events from an active mirrord session — HTTP requests, queue messages, and operator notifications as JSON to stdout. It's useful in CI/tests: assert that a request actually got stolen to your local process instead of silently hitting the real service, so a broken interception fails the build instead of going green. {% hint style="info" %} For centrally collected records that do not require a running subscriber, see [message processing functional logs](https://metalbear.com/mirrord/docs/managing-mirrord/monitoring.md#message-processing). Functional logs use the Operator's normal logging pipeline, while `mirrord subscribe` provides a live event stream filtered by session key. {% endhint %} **When do you receive events?** * HTTP - you receive an event for each request/response that was routed to or from a target workload by mirrord and matches your subscribed key. * Queue - while queue splitting is active, you receive an event for each message that matches your subscribed key. If no splitting session is active, no events are received. Queue events support Amazon SQS, Azure Service Bus, GCP Pub/Sub, RabbitMQ, BullMQ, Kafka, NATS, NATS Pub/Sub, and Redis Pub/Sub. In both cases: no active mirrord session = no events. Pass `--unmatched` to also receive the queue messages your filter did *not* take, so you can see what your split is missing. See [Unmatched messages](#unmatched-messages). {% hint style="info" %} HTTP events come from redirected requests/responses. Queue events require [queue splitting](https://metalbear.com/mirrord/docs/sharing-the-cluster/queue-splitting.md) configured for the session, and every supported broker emits them, with these exceptions: * **Temporal** is not currently supported. * **Kafka Streams** consumers are not currently supported (standard Kafka consumers are). Need support for more events? [Open a GitHub issue](https://github.com/metalbear-co/mirrord/issues) or reach out in the [mirrord Slack community](https://metalbearcommunity.slack.com/ssb/redirect) {% endhint %} ## Prerequisites * A running session started with a known key: `mirrord exec --key ...`. If you don't pass `--key`, a random key is generated for the session (`mirrord up` is the exception, it defaults to your OS username). With CLI `3.272.0` and operator `3.210.0` or newer you can also subscribe without a key and get every session's events. ## Usage In one terminal, run the session you want to observe: ```sh mirrord exec --key my-key -t deployment/my-app -- ``` In another, subscribe to its events: ```sh mirrord subscribe --key my-key ``` The key can also come from the `key` field in your mirrord config (e.g. `mirrord subscribe -f mirrord.json`) To watch every session on the cluster at once, leave the key out (CLI `3.272.0` and operator `3.210.0` or newer; an older CLI insists on a key). Each event then carries a `session_key` field naming the session it belongs to: ```sh mirrord subscribe ``` Events stream to stdout, one compact JSON object per line, as the operator intercepts traffic for that key. Status messages go to stderr, so you can pipe events straight into `jq`: ```sh mirrord subscribe --key my-key | jq 'select(.data.http_request)' ``` You may also pass `--pretty` to pretty-print each event. ## Options All flags are off by default. | Flag | Effect | | --------------------- | -------------------------------------------------------------------- | | `--session-key-field` | Adds a `session_key` field naming the session each event belongs to. | | `--unmatched` | Also delivers queue messages that matched no session's filter. | These flags need operator `3.210.0` or newer to take effect. ## Unmatched messages By default you receive a queue message only when your filter claimed it. With `--unmatched` you also receive the ones nobody claimed. ```sh mirrord subscribe --key my-key --unmatched | jq 'select(.data.queue_message.mode == "filtered")' ``` {% hint style="info" %} This covers queue messages only. An HTTP request that matches no filter never reaches the operator. {% endhint %} ## Events Every event has the same envelope — `service_name` (the intercepted workload), `timestamp`, and a `data` payload. On a [multi-cluster](https://metalbear.com/mirrord/docs/using-mirrord/multi-cluster.md) Primary the envelope also has `cluster`, see [Multi-cluster](#multi-cluster) below: {% hint style="info" %} The Operator's header and property redaction, and `operator.hideHeadersAndProperties`, apply only to the [Operator's logs](https://metalbear.com/mirrord/docs/managing-mirrord/monitoring.md). The `subscribe` stream carries header and property values as they are, so restrict who can subscribe accordingly. {% endhint %} ```json { "service_name": "my-app", "timestamp": "2026-06-17T12:00:00Z", "data": { "http_request": { "method": "GET", "uri": "/health", "headers": { "host": "my-app" }, "version": "HTTP/1.1" } } } ``` (examples are pretty-printed for clarity; actual output is compact unless `--pretty` is passed) To work with just the payload, extract `.data` with `jq`: ```sh mirrord subscribe --key my-key | jq '.data' ``` Every payload that describes an intercepted message carries `mode`: `steal` if only your session received it, `mirror` if the workload received a copy too, or `filtered` if it matched no filter (see [Unmatched messages](#unmatched-messages)). `http_response` has none - a response is routed with the request it answers - and neither does `lagged`, which is about the stream rather than a message. **`data` is one of the following (payloads shown on their own):** * **`http_request`** — an intercepted (stolen) request: ```json { "http_request": { "mode": "steal", "connection_id": 4, "request_id": 1, "method": "GET", "uri": "/health", "headers": { "host": "my-app" }, "version": "HTTP/1.1" } } ``` * **`http_response`** — the response to a stolen request: ```json { "http_response": { "connection_id": 4, "request_id": 1, "status": 200, "version": "HTTP/1.1", "headers": { "content-type": "application/json" } } } ``` A request and its response are separate events. Pair them on `connection_id` **and** `request_id` together: `request_id` is only unique within its connection. * **`queue_message`** — a queue message routed to your session. `queue_type` is one of `sqs`, `azure_service_bus`, `gcppubsub`, `rmq`, `bullmq`, `nats`, or `natspubsub`. `message_id` and `correlation_id` are included only when the broker provides them (SQS, GCP Pub/Sub and BullMQ have no `correlation_id`). `properties` is the message's attribute bag, with values stringified: text as-is, and **binary values base64-encoded**. An Azure Service Bus message (its application properties become `properties`): ```json { "queue_message": { "queue_type": "azure_service_bus", "queue_name": "orders", "correlation_id": "trace-123", "properties": { "tenant": "test" } } } ``` An SQS message, where the `payload` message attribute was binary (its bytes come back base64-encoded): ```json { "queue_message": { "queue_type": "sqs", "queue_name": "orders", "message_id": "9f2c...", "properties": { "tenant": "test", "payload": "c29tZSBlcGljIHBheWxvYWQ=" } } } ``` A GCP Pub/Sub message. `queue_name` is the subscription being split, and `properties` are the message's attributes: ```json { "queue_message": { "queue_type": "gcppubsub", "queue_name": "orders-sub", "message_id": "11041...", "properties": { "tenant": "test" } } } ``` A RabbitMQ message. `queue_name` is the queue the message was consumed from, and `properties` are the AMQP headers: ```json { "queue_message": { "queue_type": "rmq", "queue_name": "orders", "correlation_id": "trace-123", "properties": { "tenant": "test" } } } ``` A BullMQ job. `message_id` is the job ID, and `properties` are the top-level fields of the job's `data` payload — the same fields BullMQ splits filter on: ```json { "queue_message": { "queue_type": "bullmq", "queue_name": "orders", "message_id": "42", "properties": { "tenant": "test", "body": "hello" } } } ``` * **`kafka_message`** — a Kafka message stolen to your session. Kafka uses a **different schema** than `queue_message`: `topic`, `partition`, `offset`, an optional `key`, and `headers` (values stringified — text as-is, binary base64). There is no `queue_type` or `correlation_id`. ```json { "kafka_message": { "topic": "orders", "partition": 0, "offset": 42, "key": "order-7", "headers": { "tenant": "test" } } } ``` * **`redis_message`** — a Redis Pub/Sub message relayed to your session. Redis also uses a **different schema**: just the `channel` the message was published to and its `payload_size` in bytes. Pub/Sub messages carry no ID, headers, or attribute bag, and the payload itself is not included. ```json { "redis_message": { "channel": "orders", "payload_size": 52 } } ``` For a pattern subscription (`PSUBSCRIBE`), `channel` is the concrete channel the message arrived on — not the pattern. So an app subscribed to `orders.*` that receives a message on `orders.created` reports: ```json { "redis_message": { "channel": "orders.created", "payload_size": 52 } } ``` * **`lagged`** — your consumer fell behind and the operator dropped `count` events: ```json { "lagged": { "count": 12 } } ``` Lagging takes place whenever the consumer is not able to keep up with the messages and receive them in a timely fashion (e.g. due to a slow network connection). By default, the operator buffers up to 2048 messages (configurable in `values.yaml` through `subscribeEventBufferSize`), and lagging will take place if more than this many messages accumulate in the internal buffer without the consumer receiving them. Note that lagging only affects slow consumers — functioning consumers will continue to receive all events even in the presence of slow peers. ## Multi-cluster In a [multi-cluster](https://metalbear.com/mirrord/docs/using-mirrord/multi-cluster.md) setup, one `mirrord subscribe` against the Primary cluster streams the events of every cluster, with or without a key. This is useful when a session spans several Workload clusters: you no longer need a subscription per cluster to see which one intercepted a request. ```sh mirrord subscribe --key my-key --context primary ``` Every event names the cluster that intercepted it in `cluster`, using the cluster names from the Primary's `operator.multiCluster.clusters` configuration (the Primary's own events carry its `operator.multiCluster.clusterName`): ```json { "cluster": "eu-west-1", "service_name": "my-app", "timestamp": "2026-06-17T12:00:00Z", "data": { "http_request": { "mode": "steal", "method": "GET", "uri": "/health", "headers": { "host": "my-app" }, "version": "HTTP/1.1" } } } ``` If the Primary cannot reach a Workload cluster's operator, the stream keeps going with the other clusters' events and reports the missing one once, as a `cluster_unavailable` event. The Primary keeps retrying that cluster in the background, so its events resume on their own once it is reachable again: ```json { "cluster": "eu-west-1", "service_name": "", "timestamp": "2026-06-17T12:00:00Z", "data": { "cluster_unavailable": { "message": "opening the event stream failed: ..." } } } ``` This needs operator `3.219.0` or newer on the Primary. Each Workload cluster's operator must let the Primary watch `events`: the chart grants this through the `mirrord-operator-envoy-remote` role as of the same version, so a Workload cluster on an older chart shows up as `cluster_unavailable` with a message naming the missing permission until its chart is upgraded. Subscribing directly to a Workload cluster still works and streams that cluster alone, without a `cluster` field. ## Direct Kube API access (no mirrord CLI required) `mirrord subscribe` is a thin wrapper over an operator endpoint that emits [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) (`text/event-stream`). You can access it directly through the Kubernetes API, without requiring the mirrord CLI: ```sh kubectl get --raw \ "/apis/operator.metalbear.co/v1/events?watch=true&session_key=my-key" ``` The `subscribe` arguments `--session-key-field` and `--unmatched` correspond to the query parameters `include_session_key=true` and `include_unmatched=true`. Omit `session_key` to receive every session's events on one stream. Such a stream always names the session each event belongs to, regardless of the value of `include_session_key`. This is what `mirrord subscribe` without `--key` and the [local UI](https://metalbear.com/mirrord/docs/using-mirrord/local-ui.md) do. On a multi-cluster Primary, `local_only=true` limits the stream to events the Primary intercepted itself, leaving out the Workload clusters. The Primary sets it on the streams it relays, so you normally never need it. or with `kubectl proxy` + `curl`: ```sh kubectl proxy & curl -N "http://127.0.0.1:8001/apis/operator.metalbear.co/v1/events?watch=true&session_key=my-key" ``` `watch=true` is necessary to stop the Kube API server from cutting out the stream after \~60s. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://metalbear.com/mirrord/docs/using-mirrord/subscribe.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.