traceway/opentelemetry-symfony

Pure-PHP OpenTelemetry instrumentation for Symfony — automatic HTTP, Console, HttpClient, Messenger, Doctrine DBAL, Cache, Twig tracing and Monolog log-trace correlation with response propagation, a lightweight Tracing helper, route templates, and semantic conventions. No C extension required (ext-p

v3.1.0 2026-07-14 18:24 UTC

Requires

• php: >=8.1
• open-telemetry/api: ^1.9
• open-telemetry/context: ^1.5
• open-telemetry/sdk: ^1.14
• open-telemetry/sem-conv: ^1.38
• symfony/config: ^6.4 || ^7.0 || ^8.0
• symfony/console: ^6.4 || ^7.0 || ^8.0
• symfony/dependency-injection: ^6.4 || ^7.0 || ^8.0
• symfony/event-dispatcher: ^6.4 || ^7.0 || ^8.0
• symfony/http-foundation: ^6.4 || ^7.0 || ^8.0
• symfony/http-kernel: ^6.4 || ^7.0 || ^8.0
• symfony/yaml: ^6.4 || ^7.0 || ^8.0

Requires (Dev)

• doctrine/dbal: ^4.0
• monolog/monolog: ^3.0
• open-telemetry/contrib-aws: ^1.2
• php-cs-fixer/shim: ^3.0
• phpstan/phpstan: ^2.0
• phpunit/phpunit: ^10.0 || ^11.0 || ^12.0 || ^13.0
• symfony/cache: ^6.4 || ^7.0 || ^8.0
• symfony/framework-bundle: ^6.4 || ^7.0 || ^8.0
• symfony/http-client: ^6.4 || ^7.0 || ^8.0
• symfony/mailer: ^6.4 || ^7.0 || ^8.0
• symfony/messenger: ^6.4 || ^7.0 || ^8.0
• symfony/monolog-bundle: ^3.10 || ^4.0
• symfony/phpunit-bridge: ^7.2 || ^8.0
• symfony/scheduler: ^6.4 || ^7.0 || ^8.0
• twig/twig: ^3.0 || ^4.0

Suggests

• ext-grpc: Required for the gRPC OTLP transport (use with OTEL_EXPORTER_OTLP_PROTOCOL=grpc)
• ext-protobuf: Significantly faster protobuf serialization for OTLP export (use with OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf)
• doctrine/dbal: Required for automatic Doctrine DBAL query tracing (^3.6 || ^4.0)
• monolog/monolog: Required for log-trace correlation and OTel log export (trace_id/span_id injection + OTLP log shipping)
• open-telemetry/contrib-aws: Required for native AWS X-Ray support (open_telemetry.propagator: xray and open_telemetry.id_generator: xray)
• open-telemetry/exporter-otlp: Required to export traces via OTLP (the most common protocol for OpenTelemetry backends)
• open-telemetry/transport-grpc: Required for the gRPC OTLP transport (use with OTEL_EXPORTER_OTLP_PROTOCOL=grpc); also requires ext-grpc
• php-http/guzzle7-adapter: HTTP transport for the OTLP exporter (or use any PSR-18 client)
• symfony/cache: Required for automatic cache pool tracing (get/delete/invalidateTags)
• symfony/http-client: Required for automatic HttpClient outgoing request tracing
• symfony/mailer: Required for automatic Mailer instrumentation (PRODUCER spans around MailerInterface::send and CLIENT spans around the transport)
• symfony/messenger: Required for automatic Messenger job/task tracing
• symfony/monolog-bundle: Required when log_export_enabled is true — wires OtelLogHandler into Monolog's handler stack
• symfony/scheduler: Required for automatic Scheduler tracing (CONSUMER spans around RecurringMessage execution, with trigger metadata)
• twig/twig: Required for automatic Twig template rendering tracing

Conflicts

• open-telemetry/api: <1.0
• open-telemetry/sdk: <1.0

MIT

• Traceway

• logging
• symfony
• twig
• cache
• monolog
• console
• doctrine
• instrumentation
• tracing
• observability
• opentelemetry
• otel

Published on Packagist.org on 2026-07-14 18:25 UTC

README

OpenTelemetry Symfony Bundle

Pure-PHP OpenTelemetry instrumentation for Symfony. Automatic tracing for HTTP, Console, HttpClient, Messenger, Mailer, Scheduler, Doctrine DBAL, Cache, and Twig — plus Monolog log-trace correlation, OTel log export, and opt-in metrics. No C extension required.

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

• Pure PHP — installs on every managed Symfony host
• Production-ready — stable since v1.0, PHPStan level 10 with no baseline, Symfony 6.4 LTS through 8.x
• Correct under load — Messenger context propagates across async boundaries, DBAL 3 and 4 CI-tested, re-entrance guards on HttpClient and the log handler

Installation

composer require traceway/opentelemetry-symfony

Symfony Flex registers the bundle automatically. Without Flex, add it to config/bundles.php:

return [
    // ...
    Traceway\OpenTelemetryBundle\OpenTelemetryBundle::class => ['all' => true],
];

Quick Start

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

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

Prefer configuring the SDK via the bundle instead of raw env vars (works with DotEnv and Symfony Secrets)? See the open_telemetry.sdk section in docs/configuration.md.

Verify the wiring:

bin/console traceway:doctor

What Gets Traced

HTTP requests (with route templates), Console commands, HttpClient, Messenger, Scheduler, Mailer, Doctrine DBAL, Cache, and Twig — plus Monolog trace_id/span_id correlation and opt-in OTel log export. Each subsystem is individually toggleable. See docs/index.md for the per-component span breakdown.

Semantic Conventions

Audited against the current OTel semantic conventions: every stable MUST/Required/Conditionally-Required rule is implemented, Recommended attributes are emitted wherever the data exists, and all deviations are deliberate and spec-permitted. See docs/semantic-conventions.md for the conformance statement, deviations, and known limitations.

Configuration

All options are optional — the bundle works out of the box. A minimal config/packages/open_telemetry.yaml:

open_telemetry:
    traces:
        excluded_paths: [/health, /_profiler, /_wdt]
    metrics:
        enabled: true
    logs:
        correlation:
            enabled: true

See docs/configuration.md for the full reference and environment variables.

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', fn () => $this->validate($orderId));
        $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.

Metrics

Opt-in OpenTelemetry metrics — Messenger, Doctrine DBAL, HTTP server/client, and Mailer — alongside a MeterRegistryInterface for custom counters/histograms/gauges. See docs/metrics.md.

Doctor

bin/console traceway:doctor runs diagnostic checks against the bundle's wiring, SDK environment variables, and OTLP endpoint reachability — text or JSON, scriptable in CI. See docs/doctor.md for flags, JSON envelope schema, and custom checks.

Documentation

Configuration	Full config reference and environment variables
Metrics	Instrument list, manual metrics, exemplars
AWS X-Ray	Native propagator / id_generator keys
Doctor	traceway:doctor flags, JSON output, custom checks
Performance	Overhead, sampling, exporter choice
Upgrade from v1.x	Flat → nested config migration
Changelog	Release history

Contributing

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

See CONTRIBUTING.md. Join the conversation on Discord.

License

MIT