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/report-template.md
View on GitHub# Report template
The skill ends with this report, printed in the conversation and saved to `.mirrord/propagation-discovery.md` next to the generated config (or the path the user asks for). The example below is filled in for a fictional four-service flow so the shape is clear; replace every value with what the dumps showed. Header **names** and value **shapes** only: never a token, cookie, or captured trace id.
---
# Propagation discovery — `staging`, `POST /v1/orders`
**Filter on:** the `mirrord-session` member of the `baggage` header.
**Why:** it reached 3 of 4 services with the value sent at the edge, the developer sets it per request (`curl -H`, browser extension), and the OpenTelemetry Node and Java agents on those services already forward it. No code change is needed for the covered services.
## Services covered (3 of 4)
| Service | Port | How the identifier arrives | Dump evidence |
|---------|------|----------------------------|---------------|
| `deployment/gateway` | 8080 | set by the client | probe value seen in `baggage` on 1/1 probe request; 100% of 212 observed requests carry `baggage` |
| `deployment/orders` | 8080 | forwarded by OTel Node auto-instrumentation | probe value seen; 100% of 198 requests |
| `deployment/inventory` | 9090 (gRPC) | forwarded by OTel Java agent | probe value seen as gRPC metadata; 100% of 187 requests |
## Services not covered (1 of 4)
| Service | Port | What arrives instead | Why it is dropped | Fix (who) |
|---------|------|----------------------|-------------------|-----------|
| `deployment/billing` | 8080 | `traceparent` with a **new** trace id, no `baggage`, `authorization` is a service token | `inventory` calls billing through a hand-built `http.Client` without the OTel transport, so no context is injected | wrap that client with `otelhttp.NewTransport` (app team, `mirrord-header-propagation` skill) |
## Not observable with `mirrord dump`
| Hop | Reason | How to check |
|-----|--------|--------------|
| `deployment/notifications-worker` | consumes SQS `order-events`; inbound is an outgoing connection to SQS | `aws sqs receive-message --message-attribute-names All` on a test message; filter with `split_queues` `message_filter` on `baggage` (`mirrord-kafka` skill pattern) |
| `deployment/payments` | terminates TLS in the pod (dump shows `TLS` connections, hex payloads) | Operator HTTPS stealing setup, then re-run the dump |
## Candidates considered
| Identifier | gateway | orders | inventory | billing | Unique | Controllable | Verdict |
|------------|---------|--------|-----------|---------|--------|--------------|---------|
| `baggage` mirrord-session | ✅ | ✅ | ✅ | ❌ | per request | yes | **chosen** |
| `tracestate` mirrord-session | ✅ | ✅ | ❌ rewritten by Java agent | ❌ | per request | yes | no |
| `traceparent` trace-id | ✅ | ✅ | ✅ | ❌ new trace | per request | yes (curl only) | runner-up, same gap |
| `x-request-id` | ✅ rewritten by NGINX ingress | ✅ | ✅ | ✅ | per request | **no** | not controllable |
| `authorization` jwt.sub | ✅ | ✅ | ✅ | ❌ service token | per user | yes (own user) | runner-up for browser flows |
| `x-tenant-id` | ❌ | ✅ set by orders | ✅ | ✅ | per tenant | yes (own tenant) | starts one hop too late |
| `cookie` session | ✅ | ❌ | ❌ | ❌ | per session | yes | edge only |
## mirrord.json
Saved to `.mirrord/mirrord.json`. Run with `mirrord exec -f .mirrord/mirrord.json --key <your-name> -- <command>` and send requests with `-H "baggage: mirrord-session=<your-name>"`. Mirror mode first; switch `"mode"` to `"steal"` once only your requests arrive.
```json mirrord
{
"target": {
"path": "deployment/orders",
"namespace": "staging"
},
"feature": {
"network": {
"incoming": {
"mode": "mirror",
"ports": [8080],
"http_filter": {
"header_filter": "^baggage:\\s*(.*,\\s*)?mirrord-session={{ key }}\\s*([,;].*)?$",
"ports": [8080]
}
}
}
}
}
```
Change `target.path` and both `ports` for `gateway` (8080) or `inventory` (9090); the filter is the same.
## Next steps
1. `inventory → billing`: add the OTel transport to the billing client so `baggage` reaches billing (`mirrord-header-propagation`).
2. `notifications-worker`: confirm `baggage` is on the SQS message attributes; if not, the same propagation work covers the producer in `orders`.
3. `payments`: set up HTTPS stealing, then re-run this discovery for that hop.
**Verified:** mirror session on `deployment/inventory` with the config above and `scripts/request_recorder.py` as the local process received the tagged probe and not the untagged one. `billing` not verified (identifier does not reach it). `inventory` runs 2 replicas; both were dumped.
**Dumps:** 3-minute window on each service plus 2 active probes, 2026-10-13; logs deleted.
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 |