Getting started with distributed tracing

Note: Distributed tracing is in alpha. Setup details, including the ingestion endpoint, may change before general availability.

Install an OpenTelemetry trace exporter

PostHog Distributed Tracing works with any OpenTelemetry client. No PostHog-specific packages are required. Use the OTel SDKs you already have, point your trace exporter at PostHog's HTTP endpoint, and add your project token.

Set these on your OpenTelemetry SDK:

Terminal
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://us.i.posthog.com/i/v1/traces"
OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer <ph_project_token>"
OTEL_SERVICE_NAME="my-app"

<ph_client_api_host> and <ph_project_token> are filled in with your project's values when you're logged in. Use your project token (the same one you use for capturing events), not a personal API key.

This is a different endpoint from PostHog's AI/LLM tracing (/i/v0/ai/otel), which only accepts generative-AI spans. For general application traces, use /i/v1/traces.

Send context-rich spans

PostHog ingests spans using OpenTelemetry's standard model: a trace is a tree of spans, each with a trace_id, span_id, and parent_span_id, plus timing, a service name, and attributes.

Wrap the operations you care about – incoming requests, outgoing calls, database queries – in spans, and enrich them with attributes for business context.

Python
from opentelemetry import trace

tracer = trace.get_tracer("my-app")

with tracer.start_as_current_span("checkout") as span:
    span.set_attribute("user.id", "123")
    span.set_attribute("cart.value", 4200)
    # ... your code ...

Explore your traces

Once spans are flowing into PostHog, you can:

Search and filter spans by service, status, duration, and attributes
Follow a trace end to end as a waterfall to see where time goes
Spot slow and failing operations across your services

Part of PostHog's observability suite

Distributed tracing uses the same OpenTelemetry-based ingestion as Logs, so a single OTel setup covers both. Your traces also live in the same PostHog project as Session Replay, Error Tracking, and Product Analytics – one platform instead of another observability vendor to run.