/instrument-tracing

name: instrument-tracing
description: >-
  Add PostHog distributed tracing to see how requests flow through services and
  where time goes. Use after implementing features or reviewing PRs to ensure
  request entry points, outbound calls, and background jobs produce spans, or
  when asked to add tracing or spans. Also handles pointing existing
  OpenTelemetry tracing at PostHog and initial OTLP exporter setup.
metadata:
  author: PostHog

Add PostHog distributed tracing

Use this skill to add PostHog distributed tracing for new or changed code. Use it after implementing features or reviewing PRs to ensure request entry points, outbound calls, and background jobs produce spans, when the user asks to add tracing or spans, or to point existing OpenTelemetry tracing at PostHog. Supports any platform or language.

Supported platforms: Node.js, Next.js, Python (including Django, FastAPI, and Flask), Go, Java, .NET, PHP, Ruby, and any language via OpenTelemetry (OTLP).

PostHog tracing uses the standard OpenTelemetry SDK and an OTLP HTTP trace exporter. It does not need a PostHog SDK.

Instructions

Follow these steps IN ORDER:

STEP 1: Analyze the codebase and detect the platform.

• Detect the language, framework, and existing tracing setup.
• Look for dependency files and project files (package.json, requirements.txt, pyproject.toml, go.mod, pom.xml, build.gradle, *.csproj, Gemfile, composer.json, etc.).
• Look for lockfiles (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb, poetry.lock, uv.lock, go.sum, Gemfile.lock, composer.lock, etc.) to determine the package manager.
• Look for existing tracing: an OpenTelemetry tracer provider, an `instrumentation.ts` file, an `opentelemetry-instrument` launch command, an OpenTelemetry Collector config, a Java agent flag, or another vendor's tracing agent.
• Check whether a PostHog SDK (posthog-js, posthog-node, posthog-python) is already installed. You need this only for STEP 6.

STEP 2: Choose the capture path.

• If the codebase already exports OpenTelemetry traces, point the existing OTLP trace exporter (or Collector) at PostHog. Reuse the existing tracer provider. If it exports to another tracing backend, ask the user before you add PostHog as a second destination.
• Otherwise, add the OpenTelemetry SDK with an OTLP HTTP trace exporter and auto-instrumentation. Auto-instrumentation creates spans for HTTP servers, frameworks, and database drivers without code changes.
• Read the platform reference that matches the detected stack now. Use its "With OpenTelemetry" section. If no reference matches, use the general installation reference.

STEP 3: Install dependencies. (Skip if the codebase already exports OpenTelemetry traces.)

• Install the OpenTelemetry SDK, the OTLP HTTP/protobuf trace exporter, and the auto-instrumentation for the detected stack:
• Node.js and Next.js: the packages from the platform reference, plus `@opentelemetry/auto-instrumentations-node`.
• Python: `opentelemetry-distro` and `opentelemetry-exporter-otlp-proto-http`, then run `opentelemetry-bootstrap -a install`. It installs the instrumentation packages for the libraries the app already uses. Do not install `opentelemetry-instrumentation-all`.
• Go: the packages from the platform reference, plus the contrib instrumentation for each library, such as `go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp`.
• Java: the zero-code `opentelemetry-javaagent.jar`. It needs no dependency changes.
• .NET: `OpenTelemetry`, `OpenTelemetry.Exporter.OpenTelemetryProtocol`, and `OpenTelemetry.Extensions.Hosting`, plus `OpenTelemetry.Instrumentation.AspNetCore` and `OpenTelemetry.Instrumentation.Http`.
• PHP: the packages from the platform reference. For auto-instrumentation, the `opentelemetry` PHP extension (from PECL) and the `open-telemetry/opentelemetry-auto-*` package for the framework, such as `open-telemetry/opentelemetry-auto-slim`.
• Ruby: `opentelemetry-sdk`, `opentelemetry-exporter-otlp`, and `opentelemetry-instrumentation-all`, enabled with `c.use_all`.
• Do not manually edit dependency files — use the package manager's install command.

STEP 4: Configure the OTLP trace exporter.

• Send spans over OTLP HTTP/protobuf to `/i/v1/traces` on the PostHog host, with the project token in an `Authorization: Bearer` header. Do not use `/i/v0/ai/otel`. That endpoint accepts only LLM spans.
• With environment variables, set the full path in `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` and the header in `OTEL_EXPORTER_OTLP_TRACES_HEADERS` (`Authorization=Bearer <token>`). Do not set the base `OTEL_EXPORTER_OTLP_ENDPOINT` for PostHog. It appends its own `/v1/traces` path.
• Set `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf` where the SDK or agent defaults to gRPC. This applies to the Java agent, .NET, and Python with `opentelemetry-distro`.
• Python with `opentelemetry-distro`: start the app with `opentelemetry-instrument` (for example, `opentelemetry-instrument python app.py`). It builds the tracer provider from the environment variables, so do not also build a provider in code. The distro also turns on OTLP metric and log export. Set `OTEL_METRICS_EXPORTER=none` and `OTEL_LOGS_EXPORTER=none` unless the app already sends those signals somewhere.
• Set a service name (`service.name`, or `OTEL_SERVICE_NAME`) so spans are easy to find in the Tracing UI.
• Start the provider before the application loads its frameworks, so auto-instrumentation can patch them. In Next.js, register the provider in `instrumentation.ts` behind the `NEXT_RUNTIME === 'nodejs'` check.
• Follow the platform-specific reference for the exact configuration.
• You must read a file immediately before attempting to write it.

STEP 5: Add spans where they belong.

• Auto-instrumentation covers request entry points and most outbound calls. Add manual spans with the OpenTelemetry tracer API only where it has no coverage: background job handlers,