exploring-apm-traces

posthog:apm-trace-get
{
  "trace_id": "<hex_trace_id>"
}

The response is { results: [span, span, …], _posthogUrl: "…" } — a flat list of every span in the trace. The list can be very large for fan-out request flows; when it exceeds the inline limit, Claude Code auto-persists it to a file.

From the result you get:

• Every span with name, service_name, kind, status_code, parent_span_id, duration_nano, is_root_span
• The _posthogUrl — a deep link to this trace in the tracing UI; always include this in your response so the user can click through

When the result is persisted to a file (traces with hundreds of spans across services), use the parsing scripts to explore it.

Start with the summary to get the full picture, then drill into specifics:

# 1. Overview: services, span count, slowest spans, errors
python3 scripts/print_summary.py /path/to/persisted-file.json

# 2. Indented chronological tree (DFS by parent_span_id)
python3 scripts/print_timeline.py /path/to/persisted-file.json

# 3. Drill into a specific span by name
SPAN="HTTP GET /api/users" python3 scripts/extract_span.py /path/to/persisted-file.json

# 4. Search for a keyword across span names, services, IDs
SEARCH="keyword" python3 scripts/search_spans.py /path/to/persisted-file.json

# 5. When the JSON shape looks unfamiliar
python3 scripts/show_structure.py /path/to/persisted-file.json

All scripts support MAX_LEN=N env var to control truncation (0 = unlimited).

1. Every span from apm-trace-get carries self_time_nano — duration not covered by children. Sort by it: the top span is where wall-clock actually went. A parent with large self_time_nano is an uninstrumented gap (the work happened inside it, not in any recorded child).
2. Run print_summary.py — it surfaces the top-5 slowest spans by duration_nano.
3. For a noisy trace, run print_timeline.py and scan the indented durations — you can see whether time is dominated by one child span or fan-out across many.
4. To dig into one slow span, SPAN="<name>" python3 scripts/extract_span.py FILE.
5. For aggregate "which child dominates" questions use apm-spans-tree and read calls_per_parent_invocation — it separates a child that's slow per call from one that merely runs 20× per parent.

1. print_summary.py lists every span with status_code == 2 (Error). Each entry shows service, span name, and parent context.
2. Walk up the tree from an error span via parent_span_id to see what request path led there.
3. Error detail lives in each span's attributes map (e.g. exception.message, exception.type), which is returned in the trace payload — read it directly off the error span. apm-attribute-values-list is for discovering values across spans, not a prerequisite for reading one span's attributes.

1. Run print_summary.py — it prints the set of services involved in the trace.
2. If service X is missing, the request never reached it (or instrumentation is missing — check apm-services-list to confirm X has emitted spans recently at all).

1. Scope to the bad population: filterGroup with status_code = Error, or a duration threshold.
2. Discover candidate keys with apm-attributes-list — typical suspects: server.address, http.response.status_code, db.system, resource keys like k8s.pod.name / service.version.
3. Run apm-attribute-breakdown per candidate key on the bad set. A value owning most of the count is the signature.
4. Confirm over-representation: re-run without the bad-set filter (or compare error_count / count per row). A value at 95% of errors but 10% of traffic is the culprit; one at 95% of both is just volume.

1. apm-spans-sparkline with your filters → total counts per time bucket (zero-filled, ~50 adaptive buckets per window).
2. The same call with statusCodes: [2] → error counts per bucket.
3. Error rate per bucket = errors / total; the bucket where the ratio jumps is when the spike started.
4. Zoom in: re-run with a narrower dateRange around that bucket, then pull raw spans via query-apm-spans.

1. apm-spans-duration-histogram → trace counts per log-scale (1-2-5 series) duration bucket of the ROOT span.
2. A second hump or a fat tail = a distinct slow population; note its bucket_ns range.
3. Fetch the actual slow traces with query-apm-spans using a duration filter (nanoseconds) and orderBy: "duration".

1. print_timeline.py shows the indentation — wide trees mean parallel calls, deep trees mean sequential dependencies.
2. Look for spans of kind Client (3) followed by matching Server (2) spans on the called service — that's a synchronous downstream call.

Each span carries an attributes map (span-level OTel attributes like http.method, db.statement) in the payload — so for a span you already have, just read it. Resource attributes (k8s labels, service.version) are not in the payload. To filter the whole dataset by an attribute:

1. Use apm-attributes-list / apm-attribute-values-list to discover keys and values (resource attributes especially).
2. Re-issue query-apm-spans with a filterGroup entry of type span_attribute or span_resource_attribute.

Before constructing filters, discover what's actually in the project:

1. Confirm services exist — call apm-services-list to see which services have emitted spans.
2. Find filterable attributes — call apm-attributes-list with attribute_type: "span" or "resource".
3. Get actual values — call apm-attribute-values-list with a key to see the real values in use.

Only then construct query-apm-spans filters. Custom attributes vary per project and cannot be guessed.

• Durations are nanoseconds. 1 second = 1_000_000_000. Filter values in query-apm-spans for duration are also nanoseconds.
• status_code == 2 is Error. 0 is Unset, 1 is OK. Use OK to match {0, 1} in the UI filter.
• kind is an integer 0–5: 0 Unspecified, 1 Internal, 2 Server, 3 Client, 4 Producer, 5 Consumer.
• parent_span_id of a root span is "0000000000000000" (16 zero hex chars, matching the 8-byte span ID width — not the 16-byte trace ID width), not null.

[{ "type": "text", "text": "{\"results\": [...], \"_posthogUrl\": \"...\"}" }]

Every script in scripts/ unwraps this envelope before parsing.