Search by

danilovl / open-telemetry-bundle

danilovl

OpenTelemetry bundle for Symfony

Package info

github.com/danilovl/open-telemetry-bundle

Type:symfony-bundle

pkg:composer/danilovl/open-telemetry-bundle

Statistics

Installs: 14

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v1.0.0 2026-11-16 10:46 UTC

This package is auto-updated.

Last update: 2026-11-16 10:48:15 UTC


README

phpunit downloads latest Stable Version license

OpenTelemetryBundle

danilovl/open-telemetry-bundle is a configurable Symfony bundle that integrates OpenTelemetry tracing and metrics into common Symfony and infrastructure flows.

You can:

  • enable only the instrumentation you need
  • replace any default implementation with your own
  • configure each instrumentation independently
  • extend spans with custom attributes via provider interfaces
  • override span names and skip spans entirely via ignore interfaces

Kibana

Alt text

Metrics

Alt text

Alt text

Requirements

From composer.json:

  • PHP ^8.5
  • ext-opentelemetry: *
  • symfony/framework-bundle: ^8.0
  • open-telemetry/api: ^1.8
  • open-telemetry/sdk: ^1.8
  • open-telemetry/exporter-otlp: ^1.4
  • open-telemetry/sem-conv: ^1.38
  • nyholm/psr7: ^1.8

Installation

composer require danilovl/open-telemetry-bundle

If Symfony Flex does not register the bundle automatically, add it manually:

// config/bundles.php
return [
    Danilovl\OpenTelemetryBundle\OpenTelemetryBundle::class => ['all' => true],
];

Important: disable OpenTelemetry PHP extension auto-loading

The bundle initializes OpenTelemetry providers manually. If the PHP extension auto-loading is also active, it will conflict with the bundle initialization. You must disable it:

# .env or server environment
OTEL_PHP_AUTOLOAD_ENABLED=false

Environment variables

The providers are built with the OpenTelemetry SDK factories, so the standard environment variables apply:

OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_SERVICE_NAME=my-app
Variable Default Effect
OTEL_SDK_DISABLED false true → no-op providers, nothing is exported
OTEL_TRACES_EXPORTER / OTEL_METRICS_EXPORTER / OTEL_LOGS_EXPORTER otlp none disables the default exporter (e.g. in dev/CI without a collector), console prints to stdout
OTEL_TRACES_SAMPLER / OTEL_TRACES_SAMPLER_ARG parentbased_always_on e.g. parentbased_traceidratio + 0.1 to sample 10 % of traces in production
OTEL_PHP_TRACES_PROCESSOR / OTEL_PHP_LOGS_PROCESSOR batch simple exports synchronously (only useful for debugging)
OTEL_PROPAGATORS tracecontext,baggage propagation format used for incoming/outgoing HTTP and Messenger
OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE cumulative delta is recommended for PHP-FPM (every request is a new short-lived meter provider)

Redis instrumentation requires ext-opentelemetry

Redis (ext-redis) and Predis are instrumented with the hook() API of the opentelemetry PHP extension. Hooks do not replace your Redis client objects, so services type-hinting \Redis, \RedisCluster, \Predis\Client, RedisSessionHandler, cache adapters, … keep working, and every Redis call is traced. Without the extension the Redis/Predis instrumentation is simply not enabled (unless enabled explicitly, which fails with a clear message).

Minimal configuration

No configuration is required: every instrumentation is enabled automatically when the package or PHP extension it needs is installed (enabled: ~, the default). Set enabled: true to require an instrumentation (the container fails to compile if its dependency is missing) or enabled: false to disable it.

Create config/packages/open_telemetry.yaml:

danilovl_open_telemetry:
    service:
        name: 'my-app'
        environment: '%kernel.environment%'
    instrumentation:
        http_server:
            enabled: true
            tracing:
                enabled: true

Full configuration example

danilovl_open_telemetry:
    service:
        namespace: 'MyOrganization'         # maps to service.namespace OTEL resource attribute
        name: 'my-app'                      # maps to service.name OTEL resource attribute
        version: '1.0.0'                    # maps to service.version OTEL resource attribute
        environment: '%kernel.environment%' # maps to deployment.environment.name OTEL resource attribute

    privacy:
        # values of these query parameters are replaced by "REDACTED" in url.full (case-insensitive);
        # the default list covers tokens, API keys, passwords, OAuth codes and presigned URL signatures
        sensitive_query_parameters: ['token', 'access_token', 'api_key', 'password', 'Signature', 'sig']
        # replace literals of non-prepared SQL (Connection::query()/exec()) with "?" in db.query.text
        sanitize_sql: true

    instrumentation:
        # enabled: ~ (default) = auto-detect, true = required, false = disabled
        # tracing.enabled: false + metering.enabled: true = metrics only (spans are not created)
        http_server:
            enabled: true
            default_trace_ignore_enabled: true  # enables DefaultHttpRequestTraceIgnore
            tracing:
                enabled: true
            metering:
                enabled: false

        http_client:
            enabled: true
            tracing:
                enabled: true
            metering:
                enabled: false

        messenger:
            enabled: true
            long_running_command_enabled: true  # enables MessengerFlushSubscriber for messenger:consume
            tracing:
                enabled: true
            metering:
                enabled: false

        console:
            enabled: true
            tracing:
                enabled: true
            metering:
                enabled: false

        traceable:
            enabled: true
            tracing:
                enabled: true
            metering:
                enabled: false

        twig:
            enabled: true
            tracing:
                enabled: true

        cache:
            enabled: true
            tracing:
                enabled: true
            metering:
                enabled: true

        doctrine:
            enabled: true
            default_trace_ignore_enabled: true   # enables DefaultDoctrineTraceIgnore
            default_span_name_handler_enabled: true # enables DefaultDoctrineSpanNameHandler
            tracing:
                enabled: true
            metering:
                enabled: false

        redis:
            enabled: true
            tracing:
                enabled: true
            metering:
                enabled: false

        predis:
            enabled: true
            tracing:
                enabled: true
            metering:
                enabled: false

        mailer:
            enabled: true
            tracing:
                enabled: true
            metering:
                enabled: false

        events:
            enabled: true
            default_trace_ignore_enabled: true   # enables DefaultEventTraceIgnore (ignores vendor events)
            default_span_name_handler_enabled: true # enables DefaultEventSpanNameHandler
            tracing:
                enabled: true
            metering:
                enabled: false

        async:
            enabled: true
            tracing:
                enabled: true
            metering:
                enabled: false

Bundle initialization flow

This section describes how the bundle boots, how services are registered during container compilation, and how user-defined implementations automatically override bundle defaults.

Phase 1 — Container compilation (OpenTelemetryExtension)

When Symfony compiles the container it calls OpenTelemetryExtension::load(). The extension performs the following steps in order:

OpenTelemetryExtension::load()
│
├── processConfiguration()          parse & validate the danilovl_open_telemetry config
│
├── resolveEnabledFlags()
│   └── enabled: ~ → true when the package / PHP extension is installed, false otherwise
│       enabled: true with a missing dependency → LogicException
│
├── privacy parameters
│   ├── danilovl.open_telemetry.privacy.sensitive_query_parameters
│   └── danilovl.open_telemetry.privacy.sanitize_sql
│
├── YamlFileLoader → services.yaml  register all base bundle services
│
├── DefaultResourceInfoFactory      inject service.name / namespace / version / environment
│   └── danilovl.open_telemetry.resource_info   factory-backed: createResource() called at runtime
│
├── registerScopedInstrumentation()
│   └── one ScopedInstrumentation per area (instrumentation scope name + tracing.enabled flag)
│
├── registerInstrumentationServices()
│   └── for each enabled instrumentation block (http_server, doctrine, redis …)
│       └── register instrumentation-specific services (subscribers, middleware, decorators, hooks)
│
├── setInstrumentationMetricsArgument() (×N)
│   └── default metrics service + interface alias, MetricsRecorder created lazily
│
├── Provider registrations (factory-backed definitions)
│   ├── TracerProviderInterface   → DefaultTracerProviderFactory::create()
│   ├── MeterProviderInterface    → DefaultMeterProviderFactory::create()
│   └── LoggerProviderInterface   → DefaultLoggerProviderFactory::create()
│
├── ContextStorageInterface       → Context::storage()
├── TracingSpanServiceInterface   → TracingSpanService  (autowired)
│
└── registerProviderAutoconfiguration()
    ├── TraceSpanProcessorInterface  → tag: otel.span_processor
    ├── TraceSpanExporterInterface   → tag: otel.span_exporter
    ├── LogRecordProcessorInterface  → tag: otel.log_processor
    ├── LogRecordExporterInterface   → tag: otel.log_exporter
    ├── MetricExporterInterface      → tag: otel.metric_exporter
    └── MetricReaderInterface        → tag: otel.metric_reader

Phase 2 — Container compilation (OpenTelemetryCompilerPass)

After all extensions have loaded, Symfony runs compiler passes. OpenTelemetryCompilerPass::process() wires the fully-built container:

OpenTelemetryCompilerPass::process()
│
├── registerMessengerMiddleware()
│   ├── prepend MessageBusTracingMiddleware to messenger.bus.default.middleware (parameter)
│   └── prepend it to every service tagged messenger.bus (IteratorArgument or array)
│
├── registerHttpClientDecorator()
│   └── clone HttpTracingMiddleware for each http_client.client tagged service
│       └── setDecoratedService($id, priority: 1000)
│
├── registerEventDispatcherDecorator()
│   └── TracingEventDispatcher decorates event_dispatcher
│
├── registerCacheDecorator()
│   └── TracingCachePool decorates cache.app
│
├── overrideInterfaceAliasesByUserImplementations()  ← see Phase 2.1 below
│
├── registerTracerProviderProcessors()
│   ├── collect services tagged otel.span_processor  → setArgument('$processors')
│   └── collect services tagged otel.span_exporter   → setArgument('$exporters')
│
├── registerLoggerProviderProcessors()
│   ├── collect services tagged otel.log_processor   → setArgument('$processors')
│   └── collect services tagged otel.log_exporter    → setArgument('$exporters')
│
└── registerMeterProviderReaders()
    ├── collect services tagged otel.metric_exporter → setArgument('$exporters')
    └── collect services tagged otel.metric_reader   → setArgument('$readers')

Phase 2.1 — Automatic metrics interface alias override

For each instrumentation metrics interface the bundle registers a default alias:

Interface                        Default alias (bundle service)
──────────────────────────────────────────────────────────────────────
HttpServerMetricsInterface    →  danilovl.open_telemetry.metrics.http_server.default
DoctrineMetricsInterface      →  danilovl.open_telemetry.metrics.doctrine.default
RedisMetricsInterface         →  danilovl.open_telemetry.metrics.redis.default
                                 danilovl.open_telemetry.metrics.predis.default (predis)
CacheMetricsInterface         →  danilovl.open_telemetry.metrics.cache.default
ConsoleMetricsInterface       →  danilovl.open_telemetry.metrics.console.default
MessengerMetricsInterface     →  danilovl.open_telemetry.metrics.messenger.default
AsyncMetricsInterface         →  danilovl.open_telemetry.metrics.async.default
HttpClientMetricsInterface    →  danilovl.open_telemetry.metrics.http_client.default
MailerMetricsInterface        →  danilovl.open_telemetry.metrics.mailer.default
EventDispatcherMetricsInterface → danilovl.open_telemetry.metrics.events.default
TraceableMetricsInterface     →  danilovl.open_telemetry.metrics.traceable.default

At compile time overrideInterfaceAliasesByUserImplementations() scans every container definition. If it finds exactly one user-defined service that implements an interface, it automatically re-points the alias to that service — no explicit YAML configuration needed. If more than one custom implementation is found, a LogicException is thrown asking the developer to declare the alias explicitly. An alias the developer already changed is left untouched.

User registers MyDoctrineMetrics implements DoctrineMetricsInterface
        │
        ▼
CompilerPass detects 1 custom implementation
        │
        ▼
setAlias(DoctrineMetricsInterface, MyDoctrineMetrics)
        │
        ▼
All instrumentation services now inject MyDoctrineMetrics automatically

This automatic override applies only to the metrics interfaces above. Provider factories are replaced differently — see Replacing the provider factory.

Phase 2.2 — TraceableHookCompilerPass

A second compiler pass registered in OpenTelemetryBundle::build() (default PassConfig::TYPE_BEFORE_OPTIMIZATION).

It scans every container definition for classes that carry the #[Traceable] attribute (at class or method level) and builds a static hook map for TraceableHookSubscriber:

TraceableHookCompilerPass::process()
│
├── iterate all container definitions
│   ├── skip abstract / synthetic definitions and classes that are unresolved (%param%) or do not exist
│   └── reflect each class with #[Traceable] on the class or on any public method
│       └── for every public method (constructor, destructor, abstract and magic methods
│           except __invoke are skipped):
│           ├── method-level #[Traceable] wins over class-level
│           ├── handler = HOOK (default) → register hook
│           └── handler = CONTROLLER or COMMAND → skip (TraceableSubscriber handles it)
│
├── deduplicate hooks by key "ClassName::methodName"
│
└── setArgument('$hooks', $hooks) → TraceableHookSubscriber
        └── subscriber wraps every listed method with a tracing span at runtime

Phase 3 — Runtime initialization

The OpenTelemetry SDK is not initialized during container compilation. It is initialized lazily on the first main request / console command, followed by the hook registration:

HTTP request arrives (main request)          Console command (CLI)
        │                                            │
        ▼                                            ▼
KernelEvents::REQUEST                        ConsoleEvents::COMMAND
        │
        ├── PHP_INT_MAX  OpenTelemetryInitializer   (first, once per process)
        │       └── OpenTelemetryFactory::initializeSdk()
        │               ├── TracerProvider / MeterProvider / LoggerProvider
        │               │     (built by the Default*ProviderFactory, with the ResourceInfo)
        │               ├── PropagatorFactoryInterface::create()  → TextMapPropagator
        │               │     (EnvPropagatorFactory: OTEL_PROPAGATORS)
        │               └── register providers in OpenTelemetry Globals, auto-shutdown on exit
        │
        ├── 4096  RedisHookSubscriber        register phpredis / predis hooks (once per process)
        ├── 2048  TraceableHookSubscriber    register #[Traceable] HOOK methods (once per process)
        │
        └── 64    HttpRequestTracingSubscriber  start the server span (HTTP only)

Hooks need the opentelemetry PHP extension. They cannot be removed, so every method is hooked once per process and the hook calls go to the services of the current container (no duplicate spans after a kernel reboot).

Phase 4 — Flush (TelemetryFlushSubscriber)

At the end of every request / command the buffered telemetry is flushed, never shut down: in long-running runtimes (FrankenPHP worker mode, RoadRunner, Swoole, messenger:consume) the same providers serve many requests. The final shutdown happens on process exit through the SDK auto-shutdown handler.

KernelEvents::TERMINATE (main request) / ConsoleEvents::TERMINATE (priority -PHP_INT_MAX + 2 — runs last)
        │
        ▼
TelemetryFlushSubscriber → TelemetryFlusher::flush()
        ├── TracerProvider::forceFlush()
        ├── MeterProvider::forceFlush()
        └── LoggerProvider::forceFlush()

With instrumentation.messenger.long_running_command_enabled: true (default) MessengerFlushSubscriber uses the same flusher after every message handled or failed by a long-running command (messenger:consume by default, extendable through LongRunningCommandInterface).

Service configuration

The service block maps to OpenTelemetry resource attributes attached to all spans and metrics:

Key OTEL attribute Description
namespace service.namespace Logical grouping of services
name service.name Service identifier
version service.version Deployed version
environment deployment.environment.name e.g. prod, dev

Tracing setup

The bundle creates TracerProvider, MeterProvider, and LoggerProvider using factory classes that delegate to the OpenTelemetry SDK.

DefaultTracerProviderFactory

Creates a TracerProvider from the environment (see Environment variables):

  • OTEL_SDK_DISABLED=true → NoopTracerProvider
  • sampler from OTEL_TRACES_SAMPLER (default parentbased_always_on)
  • default exporter from OTEL_TRACES_EXPORTER (none disables it) with the processor from OTEL_PHP_TRACES_PROCESSOR (default batch)
  • plus the processors / exporters registered in the container

DefaultMeterProviderFactory

Creates a MeterProvider with an ExportingReader for the exporter selected by OTEL_METRICS_EXPORTER (none disables it), plus registered exporters/readers.

DefaultLoggerProviderFactory

Creates a LoggerProvider with the exporter selected by OTEL_LOGS_EXPORTER and the processor from OTEL_PHP_LOGS_PROCESSOR (default batch — a synchronous export per log record would add an HTTP round-trip to every log call).

Propagation

EnvPropagatorFactory (alias of PropagatorFactoryInterface) builds the propagator from OTEL_PROPAGATORS (default tracecontext,baggage). It is used to:

  • extract the incoming traceparent / tracestate / baggage headers of HTTP requests — the server span continues the caller's trace,
  • inject them into outgoing Symfony HttpClient requests,
  • carry the context through Messenger transports (TraceContextStamp) — the consumer span continues the producer's trace.

Replacing the provider factory

The providers are built by the services DefaultTracerProviderFactory, DefaultMeterProviderFactory and DefaultLoggerProviderFactory (referenced directly, not through the interfaces). Implementing TracerProviderFactoryInterface / MeterProviderFactoryInterface / LoggerProviderFactoryInterface alone is not picked up automatically: override the class of the default factory service in your services.yaml.

services:
    Danilovl\OpenTelemetryBundle\OpenTelemetry\Trace\DefaultTracerProviderFactory:
        class: App\Tracing\MyTracerProviderFactory
use Danilovl\OpenTelemetryBundle\OpenTelemetry\Interfaces\TracerProviderFactoryInterface;
use OpenTelemetry\SDK\Trace\TracerProviderInterface;

class MyTracerProviderFactory implements TracerProviderFactoryInterface
{
    public function create(iterable $processors = [], iterable $exporters = []): TracerProviderInterface
    {
        // build and return your TracerProvider
        // $processors / $exporters are the services tagged otel.span_processor / otel.span_exporter
    }
}

Custom Processors and Exporters

The bundle allows you to easily register custom OpenTelemetry processors and exporters. By implementing the provided interfaces, your services will be automatically discovered and injected into the corresponding providers via Symfony's DI autoconfiguration.

Supported interfaces

Tracing

  • TraceSpanProcessorInterface: For custom span processors. For convenience, you can extend AbstractFilteringSpanProcessor.
  • TraceSpanExporterInterface: For custom span exporters. Automatically wrapped in a BatchSpanProcessor.

Logging

  • LogRecordProcessorInterface: For custom log record processors. For convenience, you can extend AbstractFilteringLogRecordProcessor.
  • LogRecordExporterInterface: For custom log record exporters. Automatically wrapped in a BatchLogRecordProcessor.

Metrics

  • MetricExporterInterface: For custom metric exporters. Automatically wrapped in an ExportingReader.
  • MetricReaderInterface: For custom metric readers.

Instrumentation scope filtering

Each interface includes a getSupportedInstrumentation() method. This allows you to restrict which instrumentation scopes the processor or exporter handles.

  • Return an empty array to receive data from all scopes.
  • Return an array of scope names (e.g. ['danilovl/open-telemetry/doctrine']) to receive data only from specific instrumentations.

Priority

The getPriority() method controls the order in which processors or readers are added to the provider. Higher values mean earlier registration.

Cached Instrumentation

The bundle registers CachedInstrumentation services for all its components. This simplifies creating spans and metrics in your own services.

Injecting CachedInstrumentation

You can inject the OpenTelemetry\API\Instrumentation\CachedInstrumentation service. By default, it uses the danilovl/open-telemetry instrumentation scope.

use OpenTelemetry\API\Instrumentation\CachedInstrumentation;

class MyService
{
    public function __construct(
        private CachedInstrumentation $cachedInstrumentation
    ) {}

    public function doSomething(): void
    {
        $span = $this->cachedInstrumentation->tracer()->spanBuilder('my_action')->startSpan();
        // ...
        $span->end();
    }
}

Component-specific instrumentation

The bundle also provides a ScopedInstrumentation service for each component (instrumentation scope name + the tracing.enabled flag of the component: when tracing is disabled its tracer is a no-op tracer that still propagates the parent context). You can inject them by their service IDs:

  • danilovl.open_telemetry.instrumentation.async
  • danilovl.open_telemetry.instrumentation.cache
  • danilovl.open_telemetry.instrumentation.console
  • danilovl.open_telemetry.instrumentation.doctrine
  • danilovl.open_telemetry.instrumentation.events
  • danilovl.open_telemetry.instrumentation.http_client
  • danilovl.open_telemetry.instrumentation.http_server
  • danilovl.open_telemetry.instrumentation.mailer
  • danilovl.open_telemetry.instrumentation.messenger
  • danilovl.open_telemetry.instrumentation.redis
  • danilovl.open_telemetry.instrumentation.predis
  • danilovl.open_telemetry.instrumentation.traceable
  • danilovl.open_telemetry.instrumentation.twig

Instrumentation: http_server

What it does

Listens to KernelEvents::REQUEST, KernelEvents::EXCEPTION, KernelEvents::RESPONSE, KernelEvents::TERMINATE. Creates one SERVER span per HTTP request.

  • The incoming trace context (traceparent, …) is extracted: the span is a child of the caller's span.
  • The span name is {METHOD} and becomes {METHOD} {route template} (e.g. GET /users/{id}) once the route is matched. The raw path is never used in the name (unbounded cardinality, may contain secrets).
  • Metrics are recorded once per request.

Configuration

instrumentation:
    http_server:
        enabled: true
        default_trace_ignore_enabled: true   # registers DefaultHttpRequestTraceIgnore
        tracing:
            enabled: true
        metering:
            enabled: false

Span attributes

Attribute Source
url.full full URL, credentials and sensitive query parameters redacted
http.request.method HTTP method
http.request.body.size Content-Length header
url.scheme request scheme
url.path path info
user_agent.original User-Agent header
server.address host
server.port port
network.protocol.version HTTP version (e.g. 1.1)
client.address client IP (Request::getClientIp(), honours trusted proxies)
network.peer.address REMOTE_ADDR
network.peer.port REMOTE_PORT
http.route matched route template, e.g. /users/{id}
symfony.route.name matched route name
http.response.status_code response status
error.type exception class or status code on error

Interfaces

HttpRequestAttributeProviderInterface

Adds custom attributes to the request span.

Service tag: danilovl.open_telemetry.http_request.attribute_provider

use Danilovl\OpenTelemetryBundle\Instrumentation\Symfony\HttpKernel\Interfaces\HttpRequestAttributeProviderInterface;

class MyHttpRequestAttributeProvider implements HttpRequestAttributeProviderInterface
{
    public function provide(array $context): array
    {
        // $context['request'] is Symfony\Component\HttpFoundation\Request
        // $context['event'] is RequestEvent
        return [
            'app.tenant' => $context['request']->headers->get('X-Tenant-Id'),
        ];
    }
}

HttpRequestSpanNameHandlerInterface

Overrides the span name.

Service tag: danilovl.open_telemetry.http_request.span_name_handler

use Danilovl\OpenTelemetryBundle\Instrumentation\Symfony\HttpKernel\Interfaces\HttpRequestSpanNameHandlerInterface;
use Symfony\Component\HttpKernel\Event\RequestEvent;

class MyHttpRequestSpanNameHandler implements HttpRequestSpanNameHandlerInterface
{
    public function process(string $spanName, RequestEvent $event): string
    {
        return 'custom ' . $spanName;
    }
}

HttpRequestTraceIgnoreInterface

Skips tracing for matching requests.

Service tag: danilovl.open_telemetry.http_request.trace_ignore

use Danilovl\OpenTelemetryBundle\Instrumentation\Symfony\HttpKernel\Interfaces\HttpRequestTraceIgnoreInterface;
use Symfony\Component\HttpKernel\Event\RequestEvent;

class MyHttpRequestTraceIgnore implements HttpRequestTraceIgnoreInterface
{
    public function shouldIgnore(string $spanName, RequestEvent $event): bool
    {
        return str_starts_with($event->getRequest()->getPathInfo(), '/health');
    }
}

HttpServerMetricsInterface

Records metrics for HTTP server requests.

use Danilovl\OpenTelemetryBundle\Instrumentation\Symfony\HttpKernel\Interfaces\HttpServerMetricsInterface;
use Symfony\Component\HttpFoundation\Request;

class MyHttpServerMetrics implements HttpServerMetricsInterface
{
    public function recordRequest(Request $request, int $statusCode, float $durationMs): void { }
    public function recordError(Request $request, Throwable $exception): void { }
}

Default implementations

Class Description
DefaultHttpRequestTraceIgnore Ignores requests to /_wdt/ (Symfony web debug toolbar)
DefaultHttpServerMetrics Records http.server.request.duration (histogram, seconds, semantic conventions), http.server.requests_total, http.server.memory_usage, http.server.errors_total with http.request.method, http.response.status_code, http.route (template), error.type

Instrumentation: http_client

What it does

Decorates HttpClientInterface (priority 1000) using AsyncDecoratorTrait. Creates one CLIENT span per outgoing HTTP request, named {METHOD} (semantic conventions; use an HttpClientSpanNameHandlerInterface to customise). Injects trace context headers into the request automatically. Transport errors (timeouts, DNS, connection refused) end the span with an error status.

Configuration

instrumentation:
    http_client:
        enabled: true
        tracing:
            enabled: true
        metering:
            enabled: false

Span attributes

Attribute Source
http.request.method HTTP method
url.full request URL, credentials and sensitive query parameters redacted
server.address hostname from URL
server.port port (or 80/443 by scheme)
http.response.status_code response status
error.type exception class or status code on error

Interfaces

HttpClientAttributeProviderInterface

Service tag: danilovl.open_telemetry.http_client.attribute_provider

use Danilovl\OpenTelemetryBundle\Instrumentation\Symfony\HttpClient\Interfaces\HttpClientAttributeProviderInterface;

class MyHttpClientAttributeProvider implements HttpClientAttributeProviderInterface
{
    public function provide(array $context): array
    {
        // $context['method'], $context['url'], $context['options']
        return ['app.service' => 'payment-api'];
    }
}

HttpClientSpanNameHandlerInterface

Service tag: danilovl.open_telemetry.http_client.span_name_handler

use Danilovl\OpenTelemetryBundle\Instrumentation\Symfony\HttpClient\Interfaces\HttpClientSpanNameHandlerInterface;

class MyHttpClientSpanNameHandler implements HttpClientSpanNameHandlerInterface
{
    public function process(string $spanName, string $method, string $url, array $options): string
    {
        return $spanName;
    }
}

HttpClientTraceIgnoreInterface

Service tag: danilovl.open_telemetry.http_client.trace_ignore

use Danilovl\OpenTelemetryBundle\Instrumentation\Symfony\HttpClient\Interfaces\HttpClientTraceIgnoreInterface;

class MyHttpClientTraceIgnore implements HttpClientTraceIgnoreInterface
{
    public function shouldIgnore(string $spanName, string $method, string $url, array $options): bool
    {
        return str_contains($url, 'internal-health-check');
    }
}

HttpClientMetricsInterface

interface HttpClientMetricsInterface
{
    public function recordRequest(string $method, string $url, array $options, array $info, float $durationMs): void;
    public function recordError(string $method, string $url, array $options, Throwable $exception, float $durationMs): void;
}

Default implementations

Class Description
DefaultHttpClientMetrics Records http.client.request.duration (histogram, seconds, semantic conventions), http.client.requests_total, http.client.memory_usage, http.client.errors_total with http.request.method, server.address, http.response.status_code, error.type

Instrumentation: doctrine

What it does

Registers a Doctrine DBAL middleware (doctrine.middleware tag). Wraps the Driver with TraceableDriver → TraceableConnection / TraceableStatement. Creates one CLIENT span per SQL operation.

Configuration

instrumentation:
    doctrine:
        enabled: true
        default_trace_ignore_enabled: true    # registers DefaultDoctrineTraceIgnore
        default_span_name_handler_enabled: true # registers DefaultDoctrineSpanNameHandler
        tracing:
            enabled: true
        metering:
            enabled: false

Span attributes

Attribute Source
db.system.name database system (e.g. mysql, postgresql)
db.operation.name SQL operation (e.g. SELECT, INSERT, BEGIN, COMMIT)
db.query.text SQL query; literals of non-prepared queries are replaced by ? (privacy.sanitize_sql)
db.namespace, server.address, server.port connection parameters (the user name and password are never recorded)
error.type exception class on error

Interfaces

DoctrineSpanNameHandlerInterface

Service tag: danilovl.open_telemetry.doctrine.span_name_handler

Context keys available: db.operation, db.system, db.name, db.sql, db.params, db.user

use Danilovl\OpenTelemetryBundle\Instrumentation\Doctrine\Interfaces\DoctrineSpanNameHandlerInterface;

class MyDoctrineSpanNameHandler implements DoctrineSpanNameHandlerInterface
{
    public function process(string $spanName, array $context): string
    {
        return $spanName;
    }
}

DoctrineTraceIgnoreInterface

Service tag: danilovl.open_telemetry.doctrine.trace_ignore

use Danilovl\OpenTelemetryBundle\Instrumentation\Doctrine\Interfaces\DoctrineTraceIgnoreInterface;

class MyDoctrineTraceIgnore implements DoctrineTraceIgnoreInterface
{
    public function shouldIgnore(string $spanName, array $context): bool
    {
        return str_contains((string) ($context['db.sql'] ?? ''), 'migration_versions');
    }
}

DoctrineMetricsInterface

interface DoctrineMetricsInterface
{
    public function recordCall(string $dbSystem, string $operation, float $durationMs): void;
    public function recordError(string $dbSystem, string $operation, Throwable $exception, float $durationMs): void;
}

Default implementations

Class Description
DefaultDoctrineSpanNameHandler Builds span name from SQL using SqlHelper::buildSpanName()
DefaultDoctrineTraceIgnore Ignores: db.connection/begin/prepare/commit/rollback, system databases (information_schema, mysql, pg_catalog, etc.), schema queries, and SQL not referencing ORM-managed tables
DefaultDoctrineMetrics Records db.client.requests_total, db.client.duration_ms, db.client.memory_usage, db.client.errors_total

Instrumentation: redis

What it does

Hooks the methods of \Redis and \RedisCluster (ext-redis) with the ext-opentelemetry hook API. Creates one CLIENT span per Redis command, wherever the client is used (your services, RedisSessionHandler, cache adapters, Messenger Redis transport). Your Redis services are not decorated, so their type does not change.

Traced commands: strings, keys, hashes, lists, sets, sorted sets, streams, scripting and transactions (see PhpRedisHookInstrumentation::COMMANDS). Arguments of AUTH, EVAL, HELLO, … are never recorded.

Requires ext-redis and ext-opentelemetry.

Configuration

instrumentation:
    redis:
        enabled: true
        tracing:
            enabled: true
        metering:
            enabled: false

Span attributes

Attribute Source
db.system.name redis
db.operation.name command name (e.g. GET, SET)
db.redis.key first key of the command
db.redis.client phpredis
error.type exception class on error

Interfaces

RedisSpanNameHandlerInterface

Service tag: danilovl.open_telemetry.redis.span_name_handler

use Danilovl\OpenTelemetryBundle\Instrumentation\Redis\Interfaces\RedisSpanNameHandlerInterface;

class MyRedisSpanNameHandler implements RedisSpanNameHandlerInterface
{
    public function process(string $spanName, string $command, string $key): string
    {
        return sprintf('redis.%s %s', strtolower($command), $key);
    }
}

RedisTraceIgnoreInterface

Service tag: danilovl.open_telemetry.redis.trace_ignore

use Danilovl\OpenTelemetryBundle\Instrumentation\Redis\Interfaces\RedisTraceIgnoreInterface;

class MyRedisTraceIgnore implements RedisTraceIgnoreInterface
{
    public function shouldIgnore(string $spanName, string $command, string $key): bool
    {
        return $command === 'PING';
    }
}

RedisAttributeProviderInterface

Service tag: danilovl.open_telemetry.redis.attribute_provider

use Danilovl\OpenTelemetryBundle\Instrumentation\Redis\Interfaces\RedisAttributeProviderInterface;

class MyRedisAttributeProvider implements RedisAttributeProviderInterface
{
    public function provide(array $context): array
    {
        // $context['command'], $context['key']
        return ['app.cache.prefix' => 'session'];
    }
}

RedisMetricsInterface

interface RedisMetricsInterface
{
    public function recordCommand(string $command, float $durationMs): void;
    public function recordError(string $command, Throwable $exception, float $durationMs): void;
}

Default implementations

Class Description
DefaultRedisMetrics Records redis.client.requests_total, redis.client.duration_ms, redis.client.memory_usage, redis.client.errors_total; db.system attribute is set to redis

Instrumentation: predis

What it does

Hooks Predis\ClientInterface::executeCommand() with the ext-opentelemetry hook API, which every command (including magic methods) goes through. Creates one CLIENT span per Redis command. Clients are not decorated, so Predis\Client type hints keep working.

Requires predis/predis and ext-opentelemetry. Redis and Predis have independent metering flags.

Configuration

instrumentation:
    predis:
        enabled: true
        tracing:
            enabled: true
        metering:
            enabled: false

Span attributes

Attribute Source
db.system.name redis
db.operation.name command name (e.g. GET, SET)
db.redis.key first key of the command
db.redis.client predis
error.type exception class on error

Interfaces

RedisSpanNameHandlerInterface

Service tag: danilovl.open_telemetry.redis.span_name_handler

use Danilovl\OpenTelemetryBundle\Instrumentation\Redis\Interfaces\RedisSpanNameHandlerInterface;

class MyPredisSpanNameHandler implements RedisSpanNameHandlerInterface
{
    public function process(string $spanName, string $command, string $key): string
    {
        return sprintf('predis.%s %s', strtolower($command), $key);
    }
}

RedisTraceIgnoreInterface

Service tag: danilovl.open_telemetry.redis.trace_ignore

use Danilovl\OpenTelemetryBundle\Instrumentation\Redis\Interfaces\RedisTraceIgnoreInterface;

class MyPredisTraceIgnore implements RedisTraceIgnoreInterface
{
    public function shouldIgnore(string $spanName, string $command, string $key): bool
    {
        return $command === 'PING';
    }
}

RedisAttributeProviderInterface

Service tag: danilovl.open_telemetry.redis.attribute_provider

use Danilovl\OpenTelemetryBundle\Instrumentation\Redis\Interfaces\RedisAttributeProviderInterface;

class MyPredisAttributeProvider implements RedisAttributeProviderInterface
{
    public function provide(array $context): array
    {
        // $context['command'], $context['key']
        return ['app.cache.prefix' => 'session'];
    }
}

RedisMetricsInterface

interface RedisMetricsInterface
{
    public function recordCommand(string $command, float $durationMs): void;
    public function recordError(string $command, Throwable $exception, float $durationMs): void;
}

Default implementations

Class Description
DefaultRedisMetrics Records redis.client.requests_total, redis.client.duration_ms, redis.client.memory_usage, redis.client.errors_total; db.system attribute is set to redis

Instrumentation: cache

What it does

Decorates cache.app. The decorator implements the same interfaces as Symfony pools (CacheInterface, AdapterInterface / PSR-6, NamespacedPoolInterface, PruneableInterface, ResettableInterface), so every way of injecting cache.app keeps working. Creates one INTERNAL span per cache operation (get, getItem(s), hasItem, save, delete*, clear, commit). Metering is enabled by default; the cache key is not a metric attribute (unbounded cardinality).

Configuration

instrumentation:
    cache:
        enabled: true
        tracing:
            enabled: true
        metering:
            enabled: true   # enabled by default

Span attributes

Attribute Source
cache.system symfony
cache.pool cache.app
cache.operation get, get_multiple, has, save, delete, delete_multiple, clear, commit
cache.key cache item key
cache.hit true / false (get operations)
error.type exception class on error

Interfaces

CacheSpanNameHandlerInterface

Service tag: danilovl.open_telemetry.cache.span_name_handler

use Danilovl\OpenTelemetryBundle\Instrumentation\Symfony\Cache\Interfaces\CacheSpanNameHandlerInterface;

class MyCacheSpanNameHandler implements CacheSpanNameHandlerInterface
{
    public function process(string $spanName, string $key): string
    {
        return $spanName;
    }
}

CacheTraceIgnoreInterface

Service tag: danilovl.open_telemetry.cache.trace_ignore

use Danilovl\OpenTelemetryBundle\Instrumentation\Symfony\Cache\Interfaces\CacheTraceIgnoreInterface;

class MyCacheTraceIgnore implements CacheTraceIgnoreInterface
{
    public function shouldIgnore(string $spanName, string $key): bool
    {
        return str_starts_with($key, 'sf_meta_');
    }
}

CacheAttributeProviderInterface

Service tag: danilovl.open_telemetry.cache.attribute_provider

use Danilovl\OpenTelemetryBundle\Instrumentation\Symfony\Cache\Interfaces\CacheAttributeProviderInterface;

class MyCacheAttributeProvider implements CacheAttributeProviderInterface
{
    public function provide(array $context): array
    {
        // $context['key']
        return ['app.cache.pool' => 'app'];
    }
}

CacheMetricsInterface

interface CacheMetricsInterface
{
    public function recordGet(string $key, bool $hit, float $durationMs): void;
    public function recordError(string $key, Throwable $exception): void;
}

Default implementations

Class Description
DefaultCacheMetrics Records cache.requests_total, cache.duration_ms, cache.hits_total, cache.misses_total, cache.memory_usage, cache.errors_total

Instrumentation: console

What it does

Listens to ConsoleEvents::COMMAND, ConsoleEvents::ERROR, ConsoleEvents::TERMINATE. Creates one SERVER span per console command execution.

Configuration

instrumentation:
    console:
        enabled: true
        tracing:
            enabled: true
        metering:
            enabled: false

Span attributes

Attribute Source
console.system console
console.command command name
console.command.name command name
console.command.class command class
console.command.exit_code exit code on terminate
error.type exception class on error

Interfaces

ConsoleSpanNameHandlerInterface

Service tag: danilovl.open_telemetry.console.span_name_handler

use Danilovl\OpenTelemetryBundle\Instrumentation\Symfony\Console\Interfaces\ConsoleSpanNameHandlerInterface;
use Symfony\Component\Console\Event\ConsoleCommandEvent;

class MyConsoleSpanNameHandler implements ConsoleSpanNameHandlerInterface
{
    public function process(string $spanName, ConsoleCommandEvent $event): string
    {
        return $spanName;
    }
}

ConsoleTraceIgnoreInterface

Service tag: danilovl.open_telemetry.console.trace_ignore

use Danilovl\OpenTelemetryBundle\Instrumentation\Symfony\Console\Interfaces\ConsoleTraceIgnoreInterface;
use Symfony\Component\Console\Event\ConsoleCommandEvent;

class MyConsoleTraceIgnore implements ConsoleTraceIgnoreInterface
{
    public function shouldIgnore(string $spanName, ConsoleCommandEvent $event): bool
    {
        return $event->getCommand()?->getName() === 'cache:warmup';
    }
}

ConsoleAttributeProviderInterface

Service tag: danilovl.open_telemetry.console.attribute_provider

use Danilovl\OpenTelemetryBundle\Instrumentation\Symfony\Console\Interfaces\ConsoleAttributeProviderInterface;

class MyConsoleAttributeProvider implements ConsoleAttributeProviderInterface
{
    public function provide(array $context): array
    {
        // $context['event'], $context['command']
        return ['app.worker' => 'node-1'];
    }
}

ConsoleMetricsInterface

interface ConsoleMetricsInterface
{
    public function recordError(ConsoleErrorEvent $event): void;
    public function recordCommand(ConsoleTerminateEvent $event, string $commandName, float $durationMs): void;
    public function recordExitError(ConsoleTerminateEvent $event, string $commandName): void;
}

Default implementations

Class Description
MessengerConsumeTraceIgnore Ignores messenger:consume and messenger:consume-messages commands
DefaultConsoleMetrics Records console.command.requests_total, console.command.duration_ms, console.command.memory_usage, console.command.errors_total

Instrumentation: events

What it does

Decorates event_dispatcher. Creates one INTERNAL span per dispatched event — only when a parent span already exists.

Configuration

instrumentation:
    events:
        enabled: true
        default_trace_ignore_enabled: true    # registers DefaultEventTraceIgnore
        default_span_name_handler_enabled: true # registers DefaultEventSpanNameHandler
        tracing:
            enabled: true
        metering:
            enabled: false

Span attributes

Attribute Source
event.class fully qualified event class name
error.type exception class on error

Interfaces

EventSpanNameHandlerInterface

Service tag: danilovl.open_telemetry.event.span_name_handler

use Danilovl\OpenTelemetryBundle\Instrumentation\Symfony\EventDispatcher\Interfaces\EventSpanNameHandlerInterface;

class MyEventSpanNameHandler implements EventSpanNameHandlerInterface
{
    public function process(string $spanName, object $event, ?string $eventName = null): string
    {
        return $spanName;
    }
}

EventTraceIgnoreInterface

Service tag: danilovl.open_telemetry.event.trace_ignore

use Danilovl\OpenTelemetryBundle\Instrumentation\Symfony\EventDispatcher\Interfaces\EventTraceIgnoreInterface;

class MyEventTraceIgnore implements EventTraceIgnoreInterface
{
    public function shouldIgnore(string $spanName, object $event, ?string $eventName = null): bool
    {
        return $event instanceof SomeNoisyEvent;
    }
}

EventAttributeProviderInterface

Service tag: danilovl.open_telemetry.event.attribute_provider

use Danilovl\OpenTelemetryBundle\Instrumentation\Symfony\EventDispatcher\Interfaces\EventAttributeProviderInterface;

class MyEventAttributeProvider implements EventAttributeProviderInterface
{
    public function provide(array $context): array
    {
        // $context['event'], $context['eventName']
        return [];
    }
}

EventDispatcherMetricsInterface

interface EventDispatcherMetricsInterface
{
    public function recordDispatch(object $event, ?string $eventName, float $durationMs): void;
    public function recordError(object $event, ?string $eventName, Throwable $throwable, float $durationMs): void;
}

Default implementations

Class Description
DefaultEventSpanNameHandler Uses short class name: event.dispatch {ShortClassName}
DefaultEventTraceIgnore Ignores all events whose class file is inside the vendor/ directory
DefaultEventDispatcherMetrics Records event.dispatch.requests_total, event.dispatch.duration_ms, event.dispatch.memory_usage, event.dispatch.errors_total

Instrumentation: messenger

What it does

Registers a Messenger middleware (messenger_tracing). Creates one span per message:

  • PRODUCER span when the message is dispatched (no ReceivedStamp)
  • CONSUMER span when the message is consumed (has ReceivedStamp)

Automatically detects RabbitMQ/AMQP transport from stamps.

The producer adds a TraceContextStamp with the propagation headers to the envelope; the consumer span (in the worker) continues the producer's trace. The stamp contains only scalar data and works with every serializer. Re-dispatched messages (retries, failure transport) keep their original stamp.

When long_running_command_enabled: true, MessengerFlushSubscriber forces forceFlush() on all providers after each message is processed in messenger:consume.

Configuration

instrumentation:
    messenger:
        enabled: true
        long_running_command_enabled: true
        tracing:
            enabled: true
        metering:
            enabled: false

Span attributes

Attribute Source
messaging.message.type message class
messaging.system rabbitmq or symfony.messenger
messaging.operation.name publish or process
messaging.destination.name transport name
error.type exception class on error

Interfaces

MessengerSpanNameHandlerInterface

Service tag: danilovl.open_telemetry.messenger.span_name_handler

use Danilovl\OpenTelemetryBundle\Instrumentation\Symfony\Messenger\Interfaces\MessengerSpanNameHandlerInterface;
use Symfony\Component\Messenger\Envelope;

class MyMessengerSpanNameHandler implements MessengerSpanNameHandlerInterface
{
    public function process(string $spanName, Envelope $envelope): string
    {
        return $spanName;
    }
}

MessengerTraceIgnoreInterface

Service tag: danilovl.open_telemetry.messenger.trace_ignore

use Danilovl\OpenTelemetryBundle\Instrumentation\Symfony\Messenger\Interfaces\MessengerTraceIgnoreInterface;
use Symfony\Component\Messenger\Envelope;

class MyMessengerTraceIgnore implements MessengerTraceIgnoreInterface
{
    public function shouldIgnore(string $spanName, Envelope $envelope): bool
    {
        return $envelope->getMessage() instanceof SomeNoisyMessage;
    }
}

MessengerAttributeProviderInterface

Service tag: danilovl.open_telemetry.messenger.attribute_provider

use Danilovl\OpenTelemetryBundle\Instrumentation\Symfony\Messenger\Interfaces\MessengerAttributeProviderInterface;

class MyMessengerAttributeProvider implements MessengerAttributeProviderInterface
{
    public function provide(array $context): array
    {
        // $context['envelope'], $context['message']
        return [];
    }
}

MessengerMetricsInterface

interface MessengerMetricsInterface
{
    public function recordMessage(object $message, string $operation, array $messagingAttributes, float $durationMs): void;
    public function recordError(object $message, string $operation, array $messagingAttributes, Throwable $exception, float $durationMs): void;
}

LongRunningCommandInterface

Identifies whether a console command is long-running (e.g. messenger:consume). Used to trigger forceFlush() after each message.

Service tag: danilovl.open_telemetry.messenger.long_running_command

use Danilovl\OpenTelemetryBundle\Instrumentation\Symfony\Messenger\Interfaces\LongRunningCommandInterface;

class MyLongRunningCommand implements LongRunningCommandInterface
{
    public function isLongRunning(string $commandName): bool
    {
        return in_array($commandName, ['messenger:consume', 'my:worker'], true);
    }
}

Default implementations

Class Description
DefaultLongRunningCommand Recognizes messenger:consume and messenger:consume-messages
DefaultMessengerMetrics Records messenger.message.requests_total, messenger.message.duration_ms, messenger.message.memory_usage, messenger.message.errors_total

Instrumentation: mailer

What it does

Listens to MessageEvent, SentMessageEvent, FailedMessageEvent. Creates one PRODUCER span per email send attempt.

Configuration

instrumentation:
    mailer:
        enabled: true
        tracing:
            enabled: true
        metering:
            enabled: false

Span attributes

Attribute Source
mailer.system mailer
email.class message class
email.transport transport name
email.message_id message ID (on success)
error.type exception class on error

Interfaces

MailerSpanNameHandlerInterface

Service tag: danilovl.open_telemetry.mailer.span_name_handler

use Danilovl\OpenTelemetryBundle\Instrumentation\Symfony\Mailer\Interfaces\MailerSpanNameHandlerInterface;
use Symfony\Component\Mailer\Event\MessageEvent;

class MyMailerSpanNameHandler implements MailerSpanNameHandlerInterface
{
    public function process(string $spanName, MessageEvent $event): string
    {
        return $spanName;
    }
}

MailerTraceIgnoreInterface

Service tag: danilovl.open_telemetry.mailer.trace_ignore

use Danilovl\OpenTelemetryBundle\Instrumentation\Symfony\Mailer\Interfaces\MailerTraceIgnoreInterface;
use Symfony\Component\Mailer\Event\MessageEvent;

class MyMailerTraceIgnore implements MailerTraceIgnoreInterface
{
    public function shouldIgnore(string $spanName, MessageEvent $event): bool
    {
        return false;
    }
}

MailerMetricsInterface

interface MailerMetricsInterface
{
    public function recordSent(object $message, string $transport, float $durationMs): void;
    public function recordFailed(object $message, string $transport, Throwable $error, float $durationMs): void;
}

Default implementations

Class Description
DefaultMailerMetrics Records mailer.message.requests_total, mailer.message.duration_ms, mailer.message.memory_usage, mailer.message.errors_total

Instrumentation: twig

What it does

Extends Twig using ProfilerNodeVisitor. Creates one INTERNAL span per template render, block, and macro call.

Requires twig/twig package.

Configuration

instrumentation:
    twig:
        enabled: true
        tracing:
            enabled: true

Span attributes

Attribute Source
twig.system twig

Span name pattern:

  • Root profile: twig {name}
  • Template: twig {template}
  • Block/macro: twig {template}::{type}({name})

Interfaces

TwigSpanNameHandlerInterface

Service tag: danilovl.open_telemetry.twig.span_name_handler

Implement processProfile(string $spanName, Profile $profile): string in your class (duck-typed, called via method_exists).

TwigTraceIgnoreInterface

Service tag: danilovl.open_telemetry.twig.trace_ignore

Implement shouldIgnoreProfile(string $spanName, Profile $profile): bool in your class (duck-typed, called via method_exists).

TwigAttributeProviderInterface

Service tag: danilovl.open_telemetry.twig.attribute_provider

use Danilovl\OpenTelemetryBundle\Instrumentation\Symfony\Twig\Interfaces\TwigAttributeProviderInterface;

class MyTwigAttributeProvider implements TwigAttributeProviderInterface
{
    public function provide(array $context): array
    {
        // $context['profile'] is Twig\Profiler\Profile
        return [];
    }
}

Instrumentation: async

What it does

Listens to AsyncPreCallEvent and AsyncPostCallEvent from danilovl/async-bundle. Creates one SERVER span per async call.

Requires danilovl/async-bundle package.

Configuration

instrumentation:
    async:
        enabled: true
        tracing:
            enabled: true
        metering:
            enabled: false

Span attributes

Attribute Source
async.system async

Interfaces

AsyncMetricsInterface

interface AsyncMetricsInterface
{
    public function recordCall(float $durationMs): void;
}

Default implementations

Class Description
DefaultAsyncMetrics Records async.requests_total, async.duration_ms, async.memory_usage

Instrumentation: traceable

What it does

The traceable instrumentation has two modes:

1. TraceableSubscriber — PHP attribute on controllers and console commands

Reads the #[Traceable] PHP attribute from controller classes/methods or console command classes. Creates one INTERNAL span when the annotated controller or command runs.

2. TraceableHookSubscriber — OpenTelemetry hook on any service method

At container compile time (TraceableHookCompilerPass), scans all registered services for the #[Traceable] attribute on class or method level. Registers an OpenTelemetry hook() for each matching public method. This uses the ext-opentelemetry hook API and does not require any event listener.

The #[Traceable] attribute

Parameters

Parameter Type Default Description
name string|null null Custom span name. Defaults to class::method, traceable.controller, or traceable.console depending on context.
attributes array<string, mixed> [] Custom key-value pairs added as span attributes.
handler TraceableHandler TraceableHandler::HOOK Selects which subscriber processes this attribute. See values below.

TraceableHandler values

Value Handled by Span lifecycle Use when
TraceableHandler::HOOK (default) TraceableHookSubscriber method entry → method exit Regular services
TraceableHandler::CONTROLLER TraceableSubscriber::onController KernelEvents::CONTROLLER → KernelEvents::TERMINATE Controllers (all routes configs)
TraceableHandler::COMMAND TraceableSubscriber::onConsoleCommand ConsoleEvents::COMMAND → ConsoleEvents::TERMINATE + exit code Console commands

Rule: #[Traceable] without handler defaults to TraceableHandler::HOOK — processed by TraceableHookSubscriber. For controllers use handler: TraceableHandler::CONTROLLER, for console commands use handler: TraceableHandler::COMMAND.

Examples

use Danilovl\OpenTelemetryBundle\Instrumentation\Attribute\{Traceable, TraceableHandler};

// Controller — always set handler: CONTROLLER
#[Traceable(name: 'orders.controller', handler: TraceableHandler::CONTROLLER, attributes: ['app.module' => 'orders'])]
class OrderController
{
    #[Route('/orders')]
    public function index(): Response { ... }
}

// Controller with routes in YAML/XML
#[Traceable(name: 'conversation.controller', handler: TraceableHandler::CONTROLLER)]
class ConversationController
{
    public function list(Request $request): Response { ... }
}

// Specific controller action only
class ProductController
{
    #[Traceable(name: 'product.show', handler: TraceableHandler::CONTROLLER)]
    public function show(int $id): Response { ... }
}

// Regular service — default handler is HOOK, no need to specify
class PaymentService
{
    #[Traceable(name: 'payment.process', attributes: ['app.domain' => 'billing'])]
    public function process(Payment $payment): void { ... }
}

// Whole service class traced via hook
#[Traceable(name: 'order.service')]
class OrderService
{
    public function create(array $data): Order { ... }
    public function cancel(int $id): void { ... }
}

// Console command — always set handler: COMMAND
#[Traceable(name: 'import.command', handler: TraceableHandler::COMMAND)]
class ImportDataCommand extends Command
{
    protected function execute(InputInterface $input, OutputInterface $output): int { ... }
}

Configuration

instrumentation:
    traceable:
        enabled: true
        tracing:
            enabled: true
        metering:
            enabled: false

Span attributes

Attribute Source
traceable.type controller, console_command, or service_method
traceable.class class name (for console_command and service_method)
traceable.method method name (for service_method)
traceable.exit_code exit code (for console_command)
custom attributes from #[Traceable(attributes: [...])]
error.type exception class on error

Interfaces

TraceableSpanNameHandlerInterface

Service tag: danilovl.open_telemetry.traceable.span_name_handler

use Danilovl\OpenTelemetryBundle\Instrumentation\Symfony\Traceable\Interfaces\TraceableSpanNameHandlerInterface;

class MyTraceableSpanNameHandler implements TraceableSpanNameHandlerInterface
{
    public function process(string $spanName, array $context): string
    {
        // $context keys: operation, event/command/class/method, traceable, arguments
        return $spanName;
    }
}

TraceableTraceIgnoreInterface

Service tag: danilovl.open_telemetry.traceable.trace_ignore

use Danilovl\OpenTelemetryBundle\Instrumentation\Symfony\Traceable\Interfaces\TraceableTraceIgnoreInterface;

class MyTraceableTraceIgnore implements TraceableTraceIgnoreInterface
{
    public function shouldIgnore(string $spanName, array $context): bool
    {
        return false;
    }
}

TraceableAttributeProviderInterface

Service tag: danilovl.open_telemetry.traceable.attribute_provider

use Danilovl\OpenTelemetryBundle\Instrumentation\Symfony\Traceable\Interfaces\TraceableAttributeProviderInterface;

class MyTraceableAttributeProvider implements TraceableAttributeProviderInterface
{
    public function provide(array $context): array
    {
        return ['app.user' => 'system'];
    }
}

TraceableMetricsInterface

Only used by TraceableHookSubscriber (service method hooks).

interface TraceableMetricsInterface
{
    public function recordServiceMethod(string $className, string $methodName, float $durationMs): void;
    public function recordServiceMethodError(string $className, string $methodName, Throwable $throwable): void;
}

Default implementations

Class Description
DefaultTraceableMetrics Records traceable.service_method.requests_total, traceable.service_method.duration_ms, traceable.service_method.memory_usage, traceable.service_method.errors_total

Metrics

All instrumentation sections support a metering block:

instrumentation:
    http_server:
        metering:
            enabled: true

When metering is enabled, each instrumentation's default metrics class is activated automatically. All metrics use the shared MetricsRecorder service which wraps the OpenTelemetry MeterProvider.

MetricsRecorderInterface

The MetricsRecorderInterface provides the following methods:

interface MetricsRecorderInterface
{
    public function addCounter(string $name, float|int $amount = 1, array $attributes = [], ?string $unit = null, ?string $description = null): void;
    public function addUpDownCounter(string $name, float|int $amount = 1, array $attributes = [], ?string $unit = null, ?string $description = null): void;
    public function recordHistogram(string $name, float|int $amount, array $attributes = [], ?string $unit = null, ?string $description = null): void;
    public function recordGauge(string $name, float|int $amount, array $attributes = [], ?string $unit = null, ?string $description = null): void;
    public function createObservableCounter(string $name, ...): ObservableCounterInterface;
    public function createObservableGauge(string $name, ...): ObservableGaugeInterface;
    public function createObservableUpDownCounter(string $name, ...): ObservableUpDownCounterInterface;
    public function batchObserve(callable $callback, AsynchronousInstrument $instrument, ...): ObservableCallbackInterface;
}

You can inject MetricsRecorderInterface into your own services to record custom metrics.

Metrics reference by instrumentation

Instrumentation Metric Type Attributes
http_server http.server.requests_total counter http.method, http.route, http.status_code
http_server http.server.duration_ms histogram same
http_server http.server.memory_usage gauge same
http_server http.server.errors_total counter http.method, http.route, error.type
http_client http.client.requests_total counter http.method, http.host, http.status_code
http_client http.client.duration_ms histogram same
http_client http.client.memory_usage gauge same
http_client http.client.errors_total counter http.method, http.host, error.type
doctrine db.client.requests_total counter db.system, db.operation
doctrine db.client.duration_ms histogram same
doctrine db.client.memory_usage gauge same
doctrine db.client.errors_total counter db.system, db.operation, error.type
redis redis.client.requests_total counter db.system (redis), db.redis.command
redis redis.client.duration_ms histogram same
redis redis.client.memory_usage gauge same
redis redis.client.errors_total counter db.system (redis), db.redis.command, error.type
predis redis.client.requests_total counter db.system (predis), db.redis.command
predis redis.client.duration_ms histogram same
predis redis.client.memory_usage gauge same
predis redis.client.errors_total counter db.system (predis), db.redis.command, error.type
cache cache.requests_total counter cache.operation, cache.key, cache.hit
cache cache.duration_ms histogram same
cache cache.hits_total counter same
cache cache.misses_total counter same
cache cache.memory_usage gauge same
cache cache.errors_total counter cache.operation, cache.key, error.type
console console.command.requests_total counter console.command.name, console.command.exit_code
console console.command.duration_ms histogram same
console console.command.memory_usage gauge same
console console.command.errors_total counter console.command.name, error.type
events event.dispatch.requests_total counter event.class, event.name
events event.dispatch.duration_ms histogram same
events event.dispatch.memory_usage gauge same
events event.dispatch.errors_total counter event.class, event.name, error.type
messenger messenger.message.requests_total counter messaging.message.type, messaging.operation.name, messaging.system, messaging.destination.name
messenger messenger.message.duration_ms histogram same
messenger messenger.message.memory_usage gauge same
messenger messenger.message.errors_total counter same + error.type
mailer mailer.message.requests_total counter email.class, email.transport
mailer mailer.message.duration_ms histogram same
mailer mailer.message.memory_usage gauge same
mailer mailer.message.errors_total counter same + error.type
async async.requests_total counter async.operation
async async.duration_ms histogram same
async async.memory_usage gauge same
traceable traceable.service_method.requests_total counter traceable.class, traceable.method
traceable traceable.service_method.duration_ms histogram same
traceable traceable.service_method.memory_usage gauge same
traceable traceable.service_method.errors_total counter same + error.type

Replacing a metrics implementation

Each instrumentation binds its metrics interface to a default implementation. You can replace it by registering your own class implementing the interface. The container alias will be updated automatically.

Example for http_server:

use Danilovl\OpenTelemetryBundle\Instrumentation\Symfony\HttpKernel\Interfaces\HttpServerMetricsInterface;
use Symfony\Component\HttpFoundation\Request;

class MyHttpServerMetrics implements HttpServerMetricsInterface
{
    public function recordRequest(Request $request, int $statusCode, float $durationMs): void
    {
        // custom metrics logic
    }

    public function recordError(Request $request, Throwable $exception): void
    {
        // custom error metrics logic
    }
}

Register it as a service in your services.yaml:

services:
    App\Metrics\MyHttpServerMetrics:
        autowire: true
        autoconfigure: true

The bundle will detect it and use it instead of DefaultHttpServerMetrics.

Planned changes

Switch messaging.system to messaging.system.name

Semantic conventions 1.44 renamed the messaging attribute messaging.system to messaging.system.name. The bundle supports open-telemetry/sem-conv ^1.38, and no constant exists in both ranges (MessagingIncubatingAttributes::MESSAGING_SYSTEM is only in < 1.44, MESSAGING_SYSTEM_NAME only in >= 1.44). So MessageBusTracingMiddleware::ATTRIBUTE_MESSAGING_SYSTEM currently uses the literal messaging.system.

When the new name is wanted:

  1. Raise the requirement in composer.json to "open-telemetry/sem-conv": "^1.44".
  2. In MessageBusTracingMiddleware replace self::ATTRIBUTE_MESSAGING_SYSTEM with MessagingIncubatingAttributes::MESSAGING_SYSTEM_NAME and remove the literal constant.
  3. Update the span attribute and the messenger metrics tables in this README, and the tests that assert messaging.system.
  4. Mention the breaking change in the release notes: dashboards and queries filtering on messaging.system must use messaging.system.name, and applications must update open-telemetry/sem-conv to 1.44+.

License

The OpenTelemetryBundle is open-sourced software licensed under the MIT license.