Exploring APM traces (OpenTelemetry spans)

PostHog captures distributed traces from OpenTelemetry. Each trace is a tree of spans representing a request’s path through services.

Disambiguation: This skill is for APM / OpenTelemetry traces. Do not confuse with LLM analytics traces (agent/model $ai_* events and LLM observability tools) or logs (posthog:query-logs, posthog:logs-*).

MCP tools

For aggregates or joins not covered by these tools, posthog:execute-sql may be appropriate once the span schema is confirmed for the project.

Span data model

Property filter types (query.filterGroup)

• span — built-in fields: trace_id, span_id, duration, name, kind, status_code
• span_attribute — span-level attributes (e.g. http.method)
• span_resource_attribute — resource attributes (e.g. Kubernetes labels)

Workflow: investigate slow requests

1. Discover services: call posthog:apm-services-list with {} (or applicable filters per tool schema).
2. Find slow spans: posthog:query-apm-spans with a query that filters by service and duration (remember nanoseconds: 1s = 1_000_000_000).
3. Drill in: posthog:apm-trace-get with { "trace_id": "<hex from step 2>" }.

Workflow: find error traces

Use posthog:query-apm-spans with query.filterGroup on status_code exact / numeric operators as appropriate — OpenTelemetry status 2 means error.

Workflow: explore unknown attributes

1. posthog:apm-attributes-list — narrow keys (e.g. search "http").
2. posthog:apm-attribute-values-list — inspect values for a chosen key.
3. Build filters in posthog:query-apm-spans using the discovered keys.

Reminders

• Prefer discovering attribute keys and services before guessing filters.
• Durations in filters are in nanoseconds.
• query-apm-spans expects a query wrapper object; defaults often assume a recent time window — tighten query.dateRange when the question implies it.