AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

exploring-apm-traces

Investigates distributed application performance using PostHog APM (OpenTelemetry span) data via MCP. Use when the user asks about service traces, slow HTTP/database spans, error spans, error-rate trends or spikes, latency distributions, trace IDs, or span attributes — not AI observability traces or product logs. Uses posthog:apm-service-health, posthog:query-apm-spans, posthog:apm-trace-get, posthog:apm-spans-sparkline, posthog:apm-services-list, posthog:apm-attributes-list, and posthog:apm-attribute-values-list.

Original source
posthog
License
MIT
Pinned revision
cac7c80a9e5b73484d18eda1bffb47297c938e0c

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read posthog--exploring-apm-traces at revision cac7c80a9e5b73484d18eda1bffb47297c938e0c, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 2

references/spans-and-fields.md

APM span field reference

Fields returned by apm-trace-get and query-apm-spans.

Span fields

| Field | Type | Description | | ---------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | uuid | string | Internal row UUID (rarely useful for analysis) | | trace_id | hex string | 32-char hex ID linking every span in one trace | | span_id | hex string | 16-char hex ID for this span | | parent_span_id | hex string | Parent span's hex ID. Zero-padded "00000000…" for root spans | | name | string | Operation name (e.g. HTTP GET /api/users, db.query) | | kind | int 0–5 | OpenTelemetry span kind (see enum below) | | service_name | string | Service that emitted the span | | status_code | int 0–2 | OpenTelemetry status (see enum below). 2 is the only error indicator | | timestamp | ISO 8601 | Start time | | end_time | ISO 8601 | End time | | duration_nano | int | Duration in nanoseconds (1s = 1_000_000_000) | | is_root_span | bool | Convenience flag for the trace entry — prefer this over comparing parent ID | | matched_filter | int 0/1 | 1 if this span matched the query-apm-spans filter; 0 if it only shares a trace with a match (root/prefetched sibling). Always present; only meaningful from query-apm-spans | | attributes | map | Span-level OTel attributes the span set, e.g. http.method, db.statement, net.peer.name. A string-keyed map | | self_time_nano | int | apm-trace-get only. Duration not covered by child spans (interval union — overlapping/parallel children counted once). Leaf: own duration. Parent: the unaccounted gap — sort by this to find where wall-clock actually went |

Returned in the payload: span-level attributes (above) — read them straight off the span.

Not returned in the payload: resource attributes (k8s labels, service.version, deployment metadata). Discover them via apm-attributes-list (type resource) and fetch values via apm-attribute-values-list.

kind enum (OpenTelemetry span kind)

| Value | Label | Meaning | | ----- | ------------- | ------------------------------------------ | | 0 | Unspecified | Default when no kind is set | | 1 | Internal | Internal operation, no remote boundary | | 2 | Server | Inbound side of a synchronous remote call | | 3 | Client | Outbound side of a synchronous remote call | | 4 | Producer | Producer side of an async messaging system | | 5 | Consumer | Consumer side of an async messaging system |

A synchronous downstream call typically pairs a Client span on the caller with a matching Server span on the callee.

status_code enum (OpenTelemetry span status)

| Value | Label | Meaning | | ----- | ------- | --------------------------------- | | 0 | Unset | No status reported | | 1 | OK | Operation completed without error | | 2 | Error | Operation failed |

UI filter chips for status_code = OK match {0, 1}, but the underlying integer column only stores the raw value. When filtering programmatically, treat any span with status_code == 2 as the error set.

Filter property types in query-apm-spans

| type value | Filters on | | ------------------------- | ------------------------------------------------------------------------------------------------------ | | span | Built-in span fields: trace_id, span_id, duration, name, kind, status_code, is_root_span | | span_attribute | Span-level attributes (e.g. http.method, db.statement) | | span_resource_attribute | Resource-level attributes (e.g. k8s.pod.name, service.version) |

duration filters take values in nanoseconds (the column is duration_nano). The frontend translates 1000ms → 1_000_000_000 before sending.

is_root_span filters take true/false — filter true to isolate entry/request spans (e.g. request counts for RED metrics).