Python tracing installation

Tracing is off until you set the traces option. There's no OpenTelemetry dependency to add.

from posthog import Posthog

posthog = Posthog(
    "<ph_project_token>",
    host="https://us.i.posthog.com",
    traces={
        "service_name": "checkout-api",
        "environment": "production",
    },
)

Use your project token (the same one you use for capturing events), not a personal API key. Tracing works with the synchronous Posthog client and the module-level API, not AsyncPosthog.

See the Python SDK docs for batching, queue, and span-limit options, and before_span_send for scrubbing attributes or dropping spans before they're exported.

start_span used in a with block makes the span active for the block and ends it when the block exits. Spans started inside the block nest underneath it automatically.

with posthog.start_span("POST /checkout", kind="server") as span:
    span.set_attribute("plan", user.plan)

    with posthog.start_span("create-order"):
        order = create_order(cart)
    with posthog.start_span("charge-card"):
        stripe.charge(order)

If an exception escapes the block, the span records it, its status is set to error, and the exception propagates unchanged.

Span names should be low-cardinality operation names – GET /users/:id, not GET /users/123. Variable values belong in attributes.

For work that can't wrap a block, call start_span without with and call end() yourself. See the Python SDK docs for the full span API and for continuing a trace across services with W3C traceparent headers.

Spans created inside a PostHog context that has a distinct ID or session ID carry posthogDistinctId and sessionId attributes, which is what makes a trace reachable from a person or a Session Replay recording.

from posthog import new_context, identify_context, set_context_session

with new_context():
    identify_context(user.id)
    set_context_session(session_id)

    with posthog.start_span("POST /checkout"):
        process_order()

If you use Django, the contexts middleware sets this up for every request, and reads the X-POSTHOG-DISTINCT-ID and X-POSTHOG-SESSION-ID headers that tracing_headers sends from the browser.

Queued spans are exported on an interval, even with sync_mode on, so a short-lived process can exit before they're sent. Both flush() and shutdown() export spans that have already ended.

def handler(event, context):
    with posthog.start_span("handler"):
        do_work()
    posthog.flush()

In a serverless handler, call flush() before returning. Call shutdown() when the process is genuinely exiting.

For the complete SDK reference, see the OpenTelemetry Python docs.

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http

opentelemetry-exporter-otlp-proto-http is the OTLP HTTP/protobuf trace exporter. The -proto-grpc variant sends gRPC, so pick -proto-http to match this guide.

You'll need your PostHog project token to authenticate trace requests. This is the same token you use for capturing events with the PostHog SDK.

Important: Use your project token which starts with phc_. Do not use a personal API key (which starts with phx_).

You can find your project token in Project settings.

Set up the OpenTelemetry SDK to export spans to PostHog over OTLP HTTP.

from opentelemetry import trace
from opentelemetry.sdk.resources import Resource, SERVICE_NAME
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

resource = Resource.create({SERVICE_NAME: "my-service"})
provider = TracerProvider(resource=resource)

exporter = OTLPSpanExporter(
    endpoint="https://us.i.posthog.com/i/v1/traces",
    headers={"Authorization": "Bearer <ph_project_token>"},
)

provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)

The .http. segment in the import path is what selects the HTTP/protobuf exporter.

Alternatively, configure the exporter with environment variables:

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-service"

Note: Pass the full /i/v1/traces path to the traces endpoint. Don't use the base OTEL_EXPORTER_OTLP_ENDPOINT variable, which appends its own /v1/traces.

Wrap the operations you want to measure in spans, and attach attributes for context.

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

def checkout(order_id, amount):
    with tracer.start_as_current_span("checkout") as span:
        span.set_attribute("order.id", order_id)
        span.set_attribute("order.amount", amount)
        # ... do work ...
        return "confirmed"

To join these spans to a person or a Session Replay recording, set posthogDistinctId and sessionId attributes yourself, from the X-POSTHOG-DISTINCT-ID and X-POSTHOG-SESSION-ID headers that tracing_headers sends from the browser.

Whichever route you took:

1. Run your application and trigger the instrumented code
2. Open the PostHog Tracing interface
3. Confirm your spans and traces appear