Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tracewayapp/opentelemetry-symfony-bundle/llms.txt

Use this file to discover all available pages before exploring further.

The OpenTelemetry Symfony Bundle is distributed as a standard Composer package and registered automatically when Symfony Flex is present. The core bundle has no optional runtime dependencies beyond the OpenTelemetry PHP SDK — additional packages unlock specific exporters and transports. Follow the steps below to go from a fresh Symfony project to a fully wired OTel setup.

​
Installation Steps

1

Require the package via Composer

Run the following command in your project root:
composer require traceway/opentelemetry-symfony
This installs the bundle along with its required dependencies: the OpenTelemetry PHP SDK (open-telemetry/sdk), the OTel API, context propagation, and semantic conventions packages.
2

Register the bundle

If your project uses Symfony Flex, the bundle is registered in config/bundles.php automatically — no further action needed.Without Flex, add the bundle to config/bundles.php manually:
<?php

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

Install the OTLP exporter

The OTLP exporter is the standard way to ship traces to any OpenTelemetry-compatible backend. Install it alongside a PSR-18 HTTP client:
composer require open-telemetry/exporter-otlp php-http/guzzle7-adapter
The open-telemetry/exporter-otlp package is listed as a suggestion in composer.json because the bundle supports multiple exporter backends. You only need this package if you are exporting via OTLP (the most common and recommended option).

​
Optional Dependencies

The bundle activates additional instrumentation automatically when optional packages are detected. None of these are required for the core tracing pipeline.
PackagePurpose
open-telemetry/contrib-awsNative AWS X-Ray support (propagator: xray and id_generator: xray config keys)
open-telemetry/exporter-otlpExport traces, metrics, and logs via OTLP (most common backend protocol)
php-http/guzzle7-adapterHTTP transport for the OTLP exporter (or use any PSR-18 client)
ext-protobufSignificantly faster protobuf serialization for OTLP export
ext-grpcRequired for the gRPC OTLP transport
open-telemetry/transport-grpcPHP-side gRPC transport layer (also requires ext-grpc)
doctrine/dbalAutomatic Doctrine DBAL query tracing (^3.6 or ^4.0)
symfony/cacheAutomatic cache pool tracing (get / delete / invalidateTags)
symfony/http-clientAutomatic outgoing HttpClient request tracing
symfony/mailerAutomatic Mailer instrumentation with PRODUCER and CLIENT spans
symfony/messengerAutomatic Messenger job tracing with async context propagation
symfony/schedulerAutomatic Scheduler tracing for RecurringMessage execution
twig/twigAutomatic Twig template rendering tracing
monolog/monologLog-trace correlation and OTel Logs API export
symfony/monolog-bundleRequired when log_export_enabled: true — wires OtelLogHandler into Monolog

​
PHP and Symfony Version Requirements

The bundle’s composer.json specifies the following minimum versions:
DependencySupported Versions
PHP>= 8.1
Symfony components^6.4 || ^7.0 || ^8.0
open-telemetry/sdk^1.14
open-telemetry/api^1.9
Doctrine DBAL (optional)^3.6 || ^4.0

​
gRPC Transport

The gRPC OTLP transport is an alternative to HTTP/JSON and HTTP/Protobuf that can offer lower overhead in high-throughput environments. It requires both a PHP extension and a Composer package.
1

Install the PHP extension

The ext-grpc extension must be installed and enabled in your PHP environment:
# On Ubuntu/Debian
sudo apt-get install php-grpc

# Via PECL
pecl install grpc
2

Install the gRPC transport package

composer require open-telemetry/transport-grpc
3

Set the protocol environment variable

OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
gRPC uses port 4317 by default, while HTTP/JSON and HTTP/Protobuf use port 4318. Make sure your OTLP collector or backend is listening on the correct port for the protocol you choose.

​
A Note on ext-protobuf

The ext-protobuf C extension is not required for the bundle to work, but it is strongly recommended for production deployments when using OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf. Without it, the PHP-native protobuf implementation is used, which is significantly slower under load.
If you cannot install C extensions (for example, on a managed shared host), use OTEL_EXPORTER_OTLP_PROTOCOL=http/json instead. This is the best default for pure-PHP environments and is fully supported by all major OTel backends.

Build docs developers (and LLMs) love

Get started for freeTalk to us