README

Pure-PHP OpenTelemetry instrumentation for Symfony — automatic tracing for HTTP, Console, HttpClient, Messenger, Doctrine DBAL, Cache, and Twig, plus Monolog log-trace correlation and OpenTelemetry log export. No C extension required.

Works with any OpenTelemetry-compatible backend: Traceway, Jaeger, Zipkin, Datadog, Grafana Tempo, Honeycomb, and more.

Pure PHP — no C extension required; installs on every managed Symfony host
Production-ready — stable since v1.0, PHPStan level 10 with no baseline, supports Symfony 6.4 LTS through 8.x
Correct under load — Messenger trace context propagates across async queue boundaries, Doctrine DBAL 3 and 4 both CI-tested, re-entrance guards prevent export-path recursion in HttpClient and the log handler

Quick Start

composer require traceway/opentelemetry-symfony

OTEL_PHP_AUTOLOAD_ENABLED=true
OTEL_SERVICE_NAME=my-symfony-app
OTEL_TRACES_EXPORTER=otlp
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
OTEL_EXPORTER_OTLP_PROTOCOL=http/json
# Optional: OTEL_RESOURCE_ATTRIBUTES=service.version=1.0

Use http/json unless you have ext-protobuf installed — see Performance.

That's it. Every HTTP request, console command, outgoing call, Messenger job, DB query, cache operation, and Twig render is now traced.

What Gets Traced

Component	Span Kind	What's captured
HTTP requests	SERVER	Route templates (`GET /api/items/{id}`), status codes, body sizes, client IP, exceptions, sub-requests
Console commands	SERVER	Command name, arguments, exit code, exceptions
HttpClient	CLIENT	Outgoing requests with W3C context propagation, OTLP endpoint auto-excluded, re-entrance guard
Messenger	PRODUCER/CONSUMER	Message class, transport, W3C context propagation across async boundaries
Doctrine DBAL	CLIENT	SQL queries (parameterized), transactions, db system/namespace auto-detection. DBAL 3.6+ and 4.x both CI-tested
Cache	INTERNAL	`get` (hit/miss), `delete`, `invalidateTags` with pool name. Requires `symfony/cache`
Twig	INTERNAL	Template name, nested includes. Requires `twig/twig`
Monolog: log correlation	—	Inject `trace_id` + `span_id` into every log record. Requires `monolog/monolog`
Monolog: log export	—	Export log records via the OTel Logs API with native trace correlation and per-channel instrumentation scope. Requires `symfony/monolog-bundle`. Off by default

Additional: response propagation (Server-Timing headers), Tracing helper for manual spans, full OTel semantic conventions.

Requirements

PHP >= 8.1, Symfony >= 6.4, OpenTelemetry PHP SDK >= 1.0
Doctrine DBAL >= 3.6 (optional), Twig >= 3.0 (optional)

Configuration

All options are optional — the bundle works out of the box with zero configuration. Create config/packages/open_telemetry.yaml to customize:

open_telemetry:
    traces_enabled: true
    tracer_name: 'opentelemetry-symfony'

    excluded_paths: [/health, /_profiler, /_wdt]
    record_client_ip: true           # disable for GDPR
    error_status_threshold: 500      # 400-599

    console_enabled: true
    console_excluded_commands: [cache:clear, assets:install]

    http_client_enabled: true
    http_client_excluded_hosts: []   # OTLP endpoint is auto-excluded

    messenger_enabled: true
    messenger_root_spans: false      # true = standalone traces per consumed message

    doctrine_enabled: true
    doctrine_record_statements: true # false = hide SQL from spans

    cache_enabled: true
    cache_excluded_pools: [cache.system, cache.validator, cache.serializer]

    twig_enabled: true
    twig_excluded_templates: ['@WebProfiler/', '@Debug/']

    monolog_enabled: true            # inject trace_id/span_id into log records

    log_export_enabled: false        # export logs via OTel Logs API (requires symfony/monolog-bundle)
    log_export_level: debug          # debug | info | notice | warning | error | critical | alert | emergency

Environment Variables

Variable	Example	Description
`OTEL_PHP_AUTOLOAD_ENABLED`	`true`	Enable SDK auto-initialization
`OTEL_SERVICE_NAME`	`my-symfony-app`	Service name shown in your backend
`OTEL_TRACES_EXPORTER`	`otlp`	Traces exporter (`otlp`, `zipkin`, `console`, `none`)
`OTEL_LOGS_EXPORTER`	`otlp`	Logs exporter (`otlp`, `console`, `none`) — only used when `log_export_enabled: true`
`OTEL_EXPORTER_OTLP_ENDPOINT`	`http://localhost:4318`	Collector/backend endpoint
`OTEL_EXPORTER_OTLP_PROTOCOL`	`http/json`	Protocol (`http/json`, `http/protobuf`, `grpc`)

See the OpenTelemetry SDK docs for all available options.

Manual Instrumentation

Inject TracingInterface for one-liner span creation:

use Traceway\OpenTelemetryBundle\TracingInterface;

class OrderService
{
    public function __construct(private readonly TracingInterface $tracing) {}

    public function process(int $orderId): void
    {
        $this->tracing->trace('order.validate', function () use ($orderId) {
            // validation logic...
        });

        $this->tracing->trace('order.fulfill', function () {
            $this->tracing->trace('inventory.reserve', fn () => $this->reserve());
            $this->tracing->trace('payment.charge', fn () => $this->charge());
        });
    }
}

Mock in tests with $this->createStub(TracingInterface::class) and have trace() invoke the callback directly.

Performance

Near-zero overhead when the SDK is inactive — every component short-circuits via isEnabled(). When tracing is on, almost all cost is in span export, not instrumentation. PHP-FPM has no background thread, so BatchSpanProcessor flushes during request shutdown.

Use http/json unless you have ext-protobuf installed. PHP's native json_encode() is faster than the pure-PHP protobuf encoder, which adds significant CPU overhead under load. Switch to http/protobuf only with the C extension installed.

For high-traffic apps: run a local OTel Collector at localhost:4318 (sub-ms latency) and let it forward asynchronously, enable head sampling with OTEL_TRACES_SAMPLER=parentbased_traceidratio + OTEL_TRACES_SAMPLER_ARG=0.1, and use excluded_paths / cache_excluded_pools to drop noisy spans.

Contributing

git clone https://github.com/tracewayapp/opentelemetry-symfony-bundle.git
cd opentelemetry-symfony-bundle
composer install
vendor/bin/phpunit
vendor/bin/phpstan analyse

License

MIT

traceway / opentelemetry-symfony

Maintainers

Package info

Statistics

Security