Distributed Tracing and Telemetry with OpenTelemetry

Integrate OpenTelemetry into Winter Boot to capture distributed traces, metrics counters, and correlated structured logs with minimal configuration.

Winter Boot provides first-class integration with OpenTelemetry (OTel), covering all three observability pillars: distributed traces, metrics, and structured logs. The integration is delivered as an optional module (OpenTelemetryModule) so it has zero overhead when disabled. Once enabled, you can instrument web requests automatically via an interceptor, annotate individual methods for fine-grained tracing or counting, and inject telemetry beans anywhere in your application.

Prerequisites

Complete all four setup steps before enabling the module.

1. Install the PHP OpenTelemetry extension

   pecl install opentelemetry
   

   Then enable it in your php.ini:

   php.ini

   extension=opentelemetry.so
   

   If the extension is not loaded, OpenTelemetryModule will throw a MissingExtensionException at application startup.

2. Install the Composer packages

   composer require open-telemetry/sdk \
       open-telemetry/exporter-otlp \
       open-telemetry/transport-grpc
   
3. Enable the module in application.yml

   application.yml

   modules:
       -   module: 'dev\winterframework\telemetry\OpenTelemetryModule'
           enabled: true
           configFile: /path/to/opentelemetry.yaml
   
4. Create opentelemetry.yaml

   opentelemetry.yaml

   winter:
       telemetry:
           serviceName: 'my-winter-application'
           exporter:
               type: 'otlp'
               endpoint: 'http://localhost:4317'
           sampler:
               type: 'parent_based_always_on'
               ratio: 1.0
   

   Key configuration fields:

   serviceName · string · required

   Identifies this service in your observability backend (Jaeger, Tempo, etc.).

   exporter.type · string · required

   Export protocol — otlp (gRPC/HTTP), zipkin, jaeger, or console.

   exporter.endpoint · string · required

   The OTel collector or backend endpoint URL.

   sampler.type · string · default: "parent_based_always_on"

   Sampling strategy — always_on, always_off, parent_based_always_on, or traceidratio.

   sampler.ratio · float · default: "1.0"

   Sampling ratio (0.0–1.0) used when the traceidratio sampler is selected.

Web Request Tracing

Register OpenTelemetryWebInterceptor in your WebMvcConfigurer to automatically create a span for every incoming HTTP request. The interceptor extracts the W3C Trace Context from request headers (enabling distributed trace propagation from upstream services), records the HTTP method, URL, and response status code, and closes the span — including exception recording — after the response is sent.

MyWebConfigurer.php

use dev\winterframework\telemetry\web\OpenTelemetryWebInterceptor;
use dev\winterframework\stereotype\Configuration;
use dev\winterframework\web\config\WebMvcConfigurer;
use dev\winterframework\web\config\InterceptorRegistry;

#[Configuration]
class MyWebConfigurer implements WebMvcConfigurer
{
    public function addInterceptors(InterceptorRegistry $registry): void
    {
        // Trace all incoming HTTP requests
        $registry->addInterceptor(new OpenTelemetryWebInterceptor(), '.*');
    }
}

Traces, Metrics, and Logs

Traces — #[Traceable]

Annotate any public bean method with #[Traceable] to have Winter Boot automatically create an OTel span around that method’s execution. The span is named after the method by default; override the name via the name argument. Exceptions are recorded on the span and the span status is set to ERROR automatically.

OrderService.php

use dev\winterframework\telemetry\stereotype\Traceable;
use dev\winterframework\stereotype\Service;

#[Service]
class OrderService
{
    #[Traceable]
    public function processOrder(int $orderId): void
    {
        // Execution is wrapped in an OTel span named after this method.
    }

    #[Traceable(name: 'charge-customer')]
    public function chargeCustomer(int $orderId, float $amount): void
    {
        // Span will be reported as "charge-customer".
    }
}

Metrics — #[Countable]

Use #[Countable] to increment an OTel counter metric every time a method is invoked. For arbitrary numeric measurements such as latency or queue depth, inject OpenTelemetryMetrics directly.

PaymentService.php

use dev\winterframework\telemetry\metrics\Countable;
use dev\winterframework\telemetry\metrics\OpenTelemetryMetrics;
use dev\winterframework\stereotype\Autowired;
use dev\winterframework\stereotype\Service;

#[Service]
class PaymentService
{
    #[Autowired]
    private OpenTelemetryMetrics $metrics;

    // Automatically increments the "payments.processed" counter by 1 on each call.
    #[Countable(name: 'payments.processed', value: 1)]
    public function processPayment(float $amount): void
    {
        // Payment processing logic…
    }

    public function recordLatency(float $durationMs): void
    {
        // Record an arbitrary measurement with tags.
        $this->metrics->record(
            'payment.latency',
            $durationMs,
            ['currency' => 'USD']
        );
    }
}

#[Countable] options:

name · string · default: "\"method.invocations\""

The OTel counter metric name.

value · int|float · default: "1"

The amount added to the counter on each invocation.

OpenTelemetryMetrics methods:

Method	Description
add(string $name, int|float $value, array $attributes = [])	Increments a named counter by $value.
record(string $name, int|float $value, array $attributes = [])	Records a value on a named histogram (e.g. latency, queue depth).
counter(string $name, string $description = '', string $unit = '')	Returns the raw CounterInterface for the named counter.
histogram(string $name, string $description = '', string $unit = '')	Returns the raw HistogramInterface for the named histogram.

Logs — OpenTelemetryLogs

OpenTelemetryLogs is automatically registered as a bean by OpenTelemetryModule. Inject it into any service to emit structured log records through the OTel Logs API, which can be correlated with active trace spans in your observability backend.

AuditService.php

use dev\winterframework\telemetry\logs\OpenTelemetryLogs;
use dev\winterframework\stereotype\Autowired;
use dev\winterframework\stereotype\Service;

#[Service]
class AuditService
{
    #[Autowired]
    private OpenTelemetryLogs $logs;

    public function auditAction(string $userId, string $action): void
    {
        $this->logs->info('User action performed', [
            'userId' => $userId,
            'action' => $action,
        ]);
    }
}

Available methods:

Method	Severity
info(string $message, array $attributes = [])	INFO
error(string $message, array $attributes = [])	ERROR
warn(string $message, array $attributes = [])	WARN
debug(string $message, array $attributes = [])	DEBUG
emit(string $message, Severity $severity, array $attributes = [])	Custom — use any Severity constant

Both OpenTelemetryLogs and OpenTelemetryMetrics are registered as singleton beans — you can #[Autowired] them in any component without additional configuration.