skills.rest
PostHog
PostHogOFFICIAL
Explore all skills by this author →
Website𝕏@PostHogGitHub

exploring-apm-traces

Investigates distributed OpenTelemetry traces and spans in PostHog APM via MCP tools.

713|118|Updated Aug 11, 2020
Search Tags:#mcp#distributed tracing#spans#apm#PostHog#openTelemetry#latency analysis
One-click install
npx skills add https://github.com/PostHog/posthog-foss --skill exploring-apm-traces
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: exploring-apm-traces
Source: https://github.com/PostHog/posthog-foss/tree/main/products/tracing/skills/exploring-apm-traces
Command: npx skills add https://github.com/PostHog/posthog-foss --skill exploring-apm-traces

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

Debugging slow requests and errors across distributed services requires digging through large OpenTelemetry trace payloads, which are hard to navigate manually. This Skill provides a structured workflow for querying PostHog APM span data, reconstructing trace trees, and pinpointing latency bottlenecks and error spans.

Core Features & Use Cases

  • Trace retrieval and tree reconstruction: Fetch a full trace by hex trace ID and rebuild the parent-child span tree with DFS-indented timeline scripts.
  • Latency and error analysis: Sort spans by self_time_nano to find where wall-clock time went, list error spans with status_code 2, and read exception details from span attributes.
  • Trend and distribution queries: Use sparkline, duration histogram, and attribute breakdown MCP tools to detect error-rate spikes and slow trace populations.
  • Use Case: A user reports the checkout API is slow. Query spans filtered to the checkout service, fetch the slowest trace, run print_summary.py to see the top-5 slowest spans, and surface the _posthogUrl deep link so the team can inspect the trace in the PostHog UI.

Quick Start

Ask the assistant to fetch and summarize the PostHog APM trace for a given trace ID and identify its slowest and error spans.

Frequently Asked Questions about exploring-apm-traces

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug a slow distributed trace in PostHog?▼

Fetch the trace with posthog:apm-trace-get using its hex trace ID, then run print_summary.py to see the top-5 slowest spans. Sort by self_time_nano to find where wall-clock time actually went, and use extract_span.py to drill into a specific span.

How do I find error spans in an OpenTelemetry trace?▼

Error spans have status_code equal to 2. Run print_summary.py on the trace payload to list every error span with its service and parent context, then read exception.message and exception.type directly from that span's attributes map.

Does this skill cover AI observability traces or logs?▼

No. This skill is strictly for APM and OpenTelemetry distributed traces. AI observability traces using $ai_* events and product logs queried via posthog:query-logs are separate domains with their own tools.

Why is my query-apm-spans query slow or returning nothing?▼

Always set a dateRange, since queries without a time range are slow; the default is -1h. Before filtering, call apm-services-list and apm-attributes-list to confirm the services and attribute keys actually exist in the project.

What units are span durations in PostHog APM?▼

Durations are stored in nanoseconds in the duration_nano field, so one second equals 1,000,000,000. Duration filters in query-apm-spans also take nanosecond values.

How do I link a trace found via span search to the PostHog UI?▼

query-apm-spans does not return a UI link. Take the trace_id from its results and call apm-trace-get, which returns a _posthogUrl deep link to the trace in the tracing UI. Never hand-construct PostHog URLs.

Related Skills

Explore More Software Engineering Skills→
AgentientAgentient
2

python-backend-opentelemetry-instrumentation

Instrument Python backend services with OpenTelemetry for distributed tracing.

Official
Advanced
webrix-aiwebrix-ai
1

incident-alerting

Configure incident alerting workflows with Slack and Grafana integrations.

Official
Intermediate
PostHogPostHog
58

user-deep-dive

Aggregate PostHog and Vitally data into a user activity profile with outreach angles.

Official
Advanced
opensearch-projectopensearch-project
40

trace-analytics

Analyze OpenSearch distributed traces and spans to identify bottlenecks and failures.

Official
Advanced