metalbear-co/mirrord / skills/skills/mirrord-propagation-discovery
mirrord-propagation-discovery
VerifiedScans a live Kubernetes environment with `mirrord dump` to find an identifier mirrord can filter traffic on: a header, a `baggage` or `tracestate` member, a tenant or user id, a trace id (W3C, B3, X-Ray, Google, Jaeger), a JWT claim, a cookie, a path segment, or a JSON body field that is present on every hop of a request chain, unique to one developer's traffic, and settable by that developer. Runs mirror-only dumps on each service, sends a tagged probe request at the edge or observes real traffic, scores the candidates, and produces the matching `http_filter` (regex, jq on headers, path, method, body, or combinations) plus a per-hop report of where each identifier is dropped. Installs the mirrord CLI through a package manager when it is missing. Use when the user asks what to filter on, whether the cluster already propagates a request id or trace context, how to isolate their own requests on a shared staging cluster, how to filter on a JWT or cookie with mirrord, or wants to inspect live traffic with mirrord dump. Changes no application code: propagation gaps go to the mirrord-header-propagation skill.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 3.4 KB |
| SKILL.md | skill md | 17.9 KB |
| references/carriers.md | markdown | 13.9 KB |
| references/filter-recipes.md | markdown | 11.8 KB |
| references/identifier-catalog.md | markdown | 8.2 KB |
| references/reading-dumps.md | markdown | 9.4 KB |
| references/report-template.md | markdown | 4.8 KB |
| scripts/dump_stats.pyexecutable | script | 16.7 KB |
| scripts/request_recorder.pyexecutable | script | 2.1 KB |
references/identifier-catalog.md
View on GitHub# Identifier catalog
What to look for in dump output, ranked. A candidate is usable only when it has all three properties on every hop in scope:
| Property | Meaning | How to check |
|----------|---------|--------------|
| **Present** | The value reaches every hop, on every request in the flow | Presence per hop ≈ 100% in the dump stats; the probe value shows up in every hop's dump |
| **Unique** | It separates one developer's traffic from everyone else's. Either unique per request (a correlation id the developer mints) or unique per identity (a claim or tenant only that developer uses) | Distinct-value ratio in the stats: ~1.0 means per request; a stable value per caller means per identity |
| **Controllable** | The developer can put their own value on the request at the edge, or own the identity the value refers to | Can be set with `curl -H`, the mirrord browser extension, or a test account the developer owns |
Identifiers that are unique but not controllable (an ingress-minted request id the client cannot override) only work for one-off inspection, not for routing a developer's session.
`carriers.md` is the long list of everything that can travel between hops (vendor trace headers, legacy baggage names, auth-proxy identity headers, routing and feature-flag headers, queue and event carriers). This file keeps only the shapes worth filtering on.
## Candidates, best first
### 1. `baggage` (W3C)
- **Who sets it:** the caller. Members are `key=value` pairs separated by commas; mirrord's convention is `mirrord-session=<key>`.
- **Propagated by:** OpenTelemetry (baggage propagator enabled), Datadog on recent tracers, Spring/Micrometer with `remote-fields`, or an explicit propagation layer. See the `mirrord-header-propagation` skill.
- **Filter:** `"header_filter": "^baggage:\s*(.*,\s*)?mirrord-session={{ key }}\s*([,;].*)?$"` (member boundaries on both sides, see `filter-recipes.md`)
- **Pitfalls:** only reaches hops whose service forwards it. Gateways with header allowlists drop it. Sentry and other SDKs add their own members, so match the member, never the whole value.
### 2. `tracestate` (W3C)
- **Who sets it:** the caller, as `vendor=value` entries.
- **Propagated by:** the tracecontext propagator. Most SDKs forward unknown entries unchanged.
- **Filter:** `"header_filter": "^tracestate:\s*(.*,\s*)?mirrord-session={{ key }}\s*(,.*)?$"`
- **Pitfalls:** the spec caps it at 32 entries and some SDKs truncate or rewrite it. Some proxies only forward it together with a valid `traceparent`, so send both.
### 3. Correlation-id headers: `x-request-id`, `x-correlation-id`, `request-id`, `x-amzn-trace-id`, `x-cloud-trace-context`, `x-b3-traceid`
- **Who sets it:** often the ingress or mesh (NGINX ingress, Envoy/Istio, ALB, Google front ends) when the client sends none. Apps must forward it by hand; Istio documents which headers an app has to copy.
- **Unique per:** request.
- **Filter:** `"header_filter": "^x-request-id: {{ key }}$"`
- **Pitfalls:** the ingress may overwrite a client-supplied value. The probe tells you: if the value at hop 1 differs from what you sent, it is not controllable from outside. Load balancers may inject their own id on a different header than the one the apps forward.
### 4. JWT claims in `authorization: Bearer <jwt>` (or a cookie holding a JWT)
- **Who sets it:** the identity provider. Claims such as `sub`, `email`, `preferred_username`, `tenant_id`, `org_id`.
- **Unique per:** identity. Controllable when the developer has their own user or tenant.
- **Filter:** jq on the header, see `filter-recipes.md`. Match a claim, never the raw token: tokens rotate and must not be written into config.
- **Pitfalls:** gateways often exchange the user token for a service token or strip `authorization` on internal calls, so the claim exists at the edge but not downstream. Opaque (non-JWT) tokens carry no claims. Encrypted JWTs (JWE, five dot-separated parts) cannot be decoded by the filter.
### 5. Identity headers set after auth: `x-user-id`, `x-tenant-id`, `x-account-id`, `x-org-id`
- **Who sets it:** the gateway or the first service after authentication.
- **Unique per:** identity.
- **Filter:** `"header_filter": "^x-tenant-id: {{ key }}$"`
- **Pitfalls:** only present downstream of the component that sets it. Often absent on service-to-service calls that use a system identity.
### 6. `traceparent` trace-id
- **Who sets it:** the caller, or the first instrumented component. Format `00-<trace-id 32 hex>-<span-id 16 hex>-<flags>`.
- **Propagated by:** every W3C-aware tracer; the trace-id stays constant, the span-id changes at each hop, so only ever match the trace-id.
- **Filter:** `"header_filter": "^traceparent: 00-{{ key }}-"` with a 32-hex-char key.
- **Pitfalls:** the developer has to mint a trace-id per request, so this suits scripted or `curl` traffic, not a browser session, unless the browser extension sets it. Some SDKs start a fresh trace when the incoming `traceparent` is unsampled (`-00`), so send `-01`.
#### Other trace-id carriers
Clusters that predate W3C tracecontext carry the same trace id under a vendor header. The dump shows which one the tracer uses; the trace id is the part the developer controls and the filter anchors on:
| Header | Format | Trace-id part | Filter |
|--------|--------|---------------|--------|
| `x-b3-traceid` (Zipkin/B3 multi) | `<16 or 32 hex>` | whole value | `^x-b3-traceid: {{ key }}$` |
| `b3` (B3 single) | `<trace>-<span>-<sampled>` | first segment | `^b3: {{ key }}-` |
| `x-cloud-trace-context` (Google) | `<32 hex>/<span>;o=1` | before `/` | `^x-cloud-trace-context: {{ key }}/` |
| `x-amzn-trace-id` (AWS X-Ray) | `Root=1-<8 hex>-<24 hex>;Parent=...;Sampled=1` | `Root=` value | `^x-amzn-trace-id: .*Root={{ key }}(;\|$)` |
| `uber-trace-id` (Jaeger) | `<trace>:<span>:<parent>:<flags>` | first segment | `^uber-trace-id: {{ key }}:` |
The same pitfalls as `traceparent` apply: the span part changes per hop, a service that starts a new trace breaks the chain downstream, and ALB / API Gateway may overwrite `x-amzn-trace-id` with their own `Root`. `dump_stats.py` extracts the trace-id part of each of these as `<header>:trace-id` so you can compare it across hops directly.
### 7. Cookies
- **Who sets it:** the app or the identity provider at login.
- **Unique per:** session or identity.
- **Filter:** `"header_filter": "^cookie:\s*(.*;\s*)?session_id={{ key }}\s*(;.*)?$"`, or jq when the cookie holds a JWT.
- **Pitfalls:** cookies rarely survive past the first service. Treat as edge-only unless the dump proves otherwise.
### 8. Path segments and query parameters
- **Examples:** `/tenants/{id}/...`, `/users/{id}/...`, `?session={key}`.
- **Filter:** `"path_filter": "^/tenants/{{ key }}/"` (the path filter is matched against the path and the query string).
- **Pitfalls:** internal calls usually use different routes, so the segment exists on the edge route only. Unique per tenant, not per request.
### 9. JSON body fields
- **Examples:** `user_id`, `tenant`, `metadata.session`.
- **Filter:** `body_filter` with a JSONPath query and a regex on the result, see `filter-recipes.md`.
- **Pitfalls:** only on requests with a JSON body (never `GET`). The agent must buffer each body to evaluate it. Every hop must carry the field in its own body, which is rare on fan-out calls.
## Hops `mirrord dump` cannot show
- **Queue consumers:** the consumer's input arrives over a connection the pod opened to the broker, so it is outgoing traffic and does not show in a dump of the consumer. Inspect messages directly (Kafka `kcat -C -f '%h\n'`, `aws sqs receive-message --message-attribute-names All`, RabbitMQ management "Get messages") and check for the same identifier as a message header or attribute. The `mirrord-kafka` and `mirrord-header-propagation` skills cover filtering and propagation there.
- **TLS terminated by the target itself:** the dump shows `TLS` connections with hex payloads and no headers. Filtering those needs the Operator's HTTPS stealing setup. Traffic decrypted by a service mesh sidecar shows as plain HTTP.
- **Non-HTTP protocols:** database, Redis, and custom TCP traffic show as raw bytes. mirrord HTTP filters do not apply to them.
- **Responses:** mirrord filters match request headers, path, method and JSON body only. A value that exists only in a response (a `set-cookie`, a response id) cannot be filtered on.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |