references/php.md
AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
PHP tracing installation
Canonical URL: https://posthog.com/docs/distributed-tracing/installation/php
Cloud region: This page uses US Cloud hosts. For an EU Cloud project, use
https://eu.i.posthog.cominstead ofhttps://us.i.posthog.com(ingestion host), and usehttps://eu.posthog.cominstead ofhttps://app.posthog.com(app host for links).
On this page
- Install OpenTelemetry packages
- Get your project token
- Configure the SDK
- Create spans
- Test your setup
- Next steps
-
1
Install OpenTelemetry packages
Required
For the complete SDK reference, see the OpenTelemetry PHP docs.
composer require open-telemetry/api open-telemetry/sdk open-telemetry/exporter-otlp composer require guzzlehttp/guzzle php-http/guzzle7-adapterThe OTLP HTTP transport needs a PSR-18 HTTP client and PSR-17 factories, which
php-http/discoveryfinds at runtime. Guzzle (above) orsymfony/http-clientwithnyholm/psr7both work. For production, install the native protobuf extension (pecl install protobuf) – the pure-PHP fallback is slower. -
2
Get your project token
Required
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 withphx_).You can find your project token in Project settings.
-
3
Configure the SDK
Required
Set up the OpenTelemetry SDK to export spans to PostHog over OTLP HTTP.
<?php use OpenTelemetry\Contrib\Otlp\OtlpHttpTransportFactory; use OpenTelemetry\Contrib\Otlp\SpanExporter; use OpenTelemetry\SDK\Common\Attribute\Attributes; use OpenTelemetry\SDK\Resource\ResourceInfo; use OpenTelemetry\SDK\Resource\ResourceInfoFactory; use OpenTelemetry\SDK\Trace\SpanProcessor\BatchSpanProcessor; use OpenTelemetry\SDK\Trace\TracerProvider; $resource = ResourceInfoFactory::defaultResource()->merge( ResourceInfo::create(Attributes::create([ 'service.name' => 'my-service', ])) ); $transport = (new OtlpHttpTransportFactory())->create( 'https://us.i.posthog.com/i/v1/traces', 'application/x-protobuf', ['Authorization' => 'Bearer <ph_project_token>'], ); $tracerProvider = TracerProvider::builder() ->addSpanProcessor(new BatchSpanProcessor(new SpanExporter($transport))) ->setResource($resource) ->build();Alternatively, configure the SDK with environment variables and let it autoconfigure:
OTEL_PHP_AUTOLOAD_ENABLED=true OTEL_SERVICE_NAME=my-service OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://us.i.posthog.com/i/v1/traces" OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer <ph_project_token>"Note: Pass the full
/i/v1/tracespath to the traces endpoint. Don't use the baseOTEL_EXPORTER_OTLP_ENDPOINTvariable, which appends its own/v1/traces. -
4
Create spans
Required
Wrap the operations you want to measure in spans, and attach attributes for context.
$tracer = $tracerProvider->getTracer('my-service'); $span = $tracer->spanBuilder('process-order')->startSpan(); $scope = $span->activate(); try { $span->setAttribute('order.id', $orderId); // ... do work ... } finally { $scope->detach(); $span->end(); } -
5
Test your setup
Recommended
Once everything is configured, confirm spans are reaching PostHog:
- Run your application and trigger the instrumented code
- Open the PostHog Tracing interface
- Confirm your spans and traces appear
-
Next steps
Checkpoint
What you can do with your traces
| Action | Description | | --- | --- | | Why you need distributed tracing | What a trace shows you that nothing else does | | Explore traces | Read a trace as a waterfall to see where time goes | | Filter spans | Narrow down by service, status, duration, and attributes | | Propagate context | Pass trace context across services so spans join the same trace |