spiral / otel-bridge

1.3.0 2026-10-16 14:21 UTC

Requires

• php: >=8.2
• open-telemetry/api: ^1.1
• open-telemetry/sdk: ^1.3
• spiral/boot: ^3.17.2
• spiral/core: ^3.17.2
• spiral/events: ^3.17.2
• spiral/exceptions: ^3.17.2
• spiral/telemetry: ^3.17.2

Requires (Dev)

• bamarni/composer-bin-plugin: ^1.8
• buggregator/trap: ^1.17
• jasonmccreary/double: ^1.0.1
• llm/skills: ^1.14
• nyholm/psr7: ^1.8
• open-telemetry/exporter-otlp: ^1.4
• roxblnfk/unpoly: ^1.8
• spiral/dumper: ^3.3
• spiral/testing: 4.x-dev as 4.0.0
• symfony/http-client: ^6.4 || ^7.0 || ^8.0
• testo/bridge-double: ^0.1.1
• testo/bridge-infection: ^0.1.9
• testo/testo: ^0.10.54

Conflicts

• open-telemetry/sem-conv: <1.22

MIT

• butschster
• Aleksei Gagarin

• telemetry
• spiral
• opentelemetry
• otel
• spiral framework

Published on Packagist.org on 2026-10-16 14:21 UTC

README

OpenTelemetry tracing for Spiral Framework

This package plugs the OpenTelemetry PHP SDK into the Spiral telemetry component as the otel tracer driver, so the spans of your application are exported to any OpenTelemetry-compatible backend and the trace context is propagated between services with W3C traceparent headers.

Get Started

Installation

composer require spiral/otel-bridge

Install an exporter as well, for example OTLP:

composer require open-telemetry/exporter-otlp

Then add the bootloader to your application kernel:

public function defineBootloaders(): array
{
    return [
        // ...
        \Spiral\OpenTelemetry\Bootloader\OpenTelemetryBootloader::class,
        // ...
    ];
}

Configuration

Select the otel driver and configure the SDK with the standard OTEL_* environment variables:

# Telemetry driver [log, null, otel]
TELEMETRY_DRIVER=otel

OTEL_SERVICE_NAME=php # Your application name
OTEL_TRACES_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318
OTEL_PHP_TRACES_PROCESSOR=simple

The exporter is created lazily, on the first export. The full list of variables is in the OpenTelemetry SDK configuration.

With OTEL_PHP_TRACES_PROCESSOR=batch (the SDK default) spans are queued and flushed after every request or job, and on application shutdown, through the Spiral finalizer. Spans still queued are lost when the worker is killed hard, e.g. by SIGKILL or the RoadRunner stop timeout.