spiral / otel-bridge
OpenTelemetry bridge for Spiral Framework
Fund package maintenance!
Requires
- php: >=8.2
- open-telemetry/api: ^1.7
- open-telemetry/context: ^1.4
- open-telemetry/sdk: ^1.9
- spiral/boot: ^3.18
- spiral/core: ^3.18
- spiral/events: ^3.18
- spiral/exceptions: ^3.18
- spiral/telemetry: ^3.18
- tbachert/spi: ^1.0.5
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/http: ^3.18
- 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
Suggests
- ext-opentelemetry: To add the spans of auto-instrumentation packages to the Spiral traces
Provides
None
Conflicts
- open-telemetry/opentelemetry-auto-psr15: <1.0.6 || >=1.4
- open-telemetry/sdk: >=1.16
- open-telemetry/sem-conv: <1.22
Replaces
None
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
The exporter is created lazily, on the first export. The full list of variables is in the OpenTelemetry SDK configuration.
The trace context is read from and written to headers with the propagators of OTEL_PROPAGATORS, by default W3C Trace Context and Baggage. Other propagators need their package, for example b3 needs open-telemetry/extension-propagator-b3: a name the SDK does not know is skipped with a warning, and with none left the propagator is a no-op one.
getContext() depends on where it is called:
- before the tracer has started any trace, it returns the incoming headers the tracer was made with, baggage included, limited to the fields of the propagator;
- while a trace runs, the context of the span running there, with the baggage current there, or the incoming baggage when no baggage is current;
- once the traces of the tracer have ended, as when
Spiral\Http\Httpadds the context to the response, the trace context of the last finished outermost trace, without baggage.
The incoming baggage is current inside a scoped trace that takes the incoming parent, so code reads it with Baggage::getCurrent() and can extend it.
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.
The names, attributes and status of the spans of Spiral components, like the SERVER span of a request and its HTTP attributes, are set by those components, spiral/http among them; the bridge exports them as they are.
Span status
A status set on a Spiral span is exported as the OpenTelemetry span status:
- the strings
okanderror, in any case, giveOkandError; any other string leaves the statusUnset; - the integers
0,1and2are the OTLP values ofUnset,OkandError; - any other integer is taken for an HTTP status code: 1xx–3xx leave the status
Unset, 4xx isErrorexcept on aSERVERspan, 5xx isError, and a number out of the HTTP range isError.
When the traced callback throws, the span keeps its name and attributes and gets status Error with the exception message, unless the callback set Ok or Error.
Auto-instrumentation with ext-opentelemetry
The bridge works with and without the opentelemetry extension. With it, auto-instrumentation packages (open-telemetry/opentelemetry-auto-*) add spans for code Spiral does not trace: database drivers, HTTP clients, caches.
The spans of those hooks and the Spiral spans form one trace and go through one SDK pipeline:
- When the app boots, the bridge registers its tracer provider and propagator as the global ones that auto-instrumentation takes from
OpenTelemetry\API\Globals. The provider is still built on first use. Spans of hooks are flushed together with the Spiral spans at the end of each request or job, so under RoadRunner they are not held until the worker exits. - With
OTEL_PHP_AUTOLOAD_ENABLED=truethe SDK autoloader configures the global provider and propagator, from the env or from the file ofOTEL_CONFIG_FILE(OTEL_EXPERIMENTAL_CONFIG_FILEbefore SDK 1.14), which needsopen-telemetry/sdk-configuration, and the bridge takes them fromGlobals. The bridge flushes that provider after every request or job, while shutting it down is left to the SDK at process exit. The autoloader decides when Composer loads, so the variable has to be in the process environment orphp.ini: set only in.env, it is reported and the bridge builds its own provider. - Spans that hooks start while the exporter sends a batch, like the PSR-18 or curl request of the OTLP exporter itself, are not recorded, so that every flush does not send a new trace of its own.
Packages
Most packages register their hooks on classes, interfaces and functions when Composer loads their autoload.files entry, _register.php. For them installing the package is all it takes: nothing has to be turned on, and OTEL_PHP_AUTOLOAD_ENABLED is not needed, since the hooks take the tracer and propagator from Globals, where the bridge puts its own. The packages require ext-opentelemetry; where the extension is not loaded at runtime, _register.php triggers a warning and registers nothing.
pie install open-telemetry/ext-opentelemetry composer require open-telemetry/opentelemetry-auto-guzzle
PIE enables the extension; if php -m does not list opentelemetry, add extension=opentelemetry to php.ini.
Packages moved to SPI register through the SDK autoloader only, which runs with OTEL_PHP_AUTOLOAD_ENABLED=true in the process environment or php.ini and needs the tbachert/spi Composer plugin allowed in config.allow-plugins. With it, the bridge takes the provider of the SDK, with the consequences described above. psr18 registers this way from the release after 1.4.0.
Packages useful in a Spiral app, all open-telemetry/opentelemetry-auto-*:
| Package | Name | Hooks |
|---|---|---|
psr18 |
psr18 |
sendRequest() of any PSR-18 client |
guzzle |
guzzle |
every Guzzle request: send(), request(), get() and the like, sync and async |
symfony |
symfony |
request() of Symfony HttpClient, together with HttpKernel and Messenger; requires symfony/http-kernel |
curl |
curl |
curl_exec() and curl_multi_* |
pdo |
pdo |
PDO and PDOStatement: connect, query, exec, prepare, execute, transactions |
mysqli |
mysqli |
mysqli functions and methods |
postgresql |
postgresql |
pg_* functions of ext-pgsql |
psr16 |
psr16 |
PSR-16 CacheInterface, which the spiral/cache storages implement; CacheManager::storage() returns a CacheRepository, itself a CacheInterface that calls the storage, so each cache call through Spiral gives two nested spans |
ext-amqp |
ext_amqp |
AMQPExchange::publish() and AMQPQueue ack, nack, reject of ext-amqp |
The HTTP client packages add the propagator headers, traceparent among them, to the request. psr18 sees only sendRequest(): Guzzle's request() or Symfony's request() need their own package. A client called through sendRequest() with both psr18 and its own package installed gives two nested CLIENT spans, and curl adds one more under clients that use curl, like the curl handler of Guzzle or CurlHttpClient of Symfony. Disable the outer package, or set OTEL_EXPERIMENTAL_SPAN_SUPPRESSION_STRATEGY=spankind (see PSR-15). Disabling psr18 also drops the spans of PSR-18 clients that have no package of their own.
Disabling
OTEL_PHP_DISABLED_INSTRUMENTATIONS takes a comma-separated list of the names from the table, or all:
export OTEL_PHP_DISABLED_INSTRUMENTATIONS=guzzle,psr18
It is read while Composer autoloads, by each _register.php or by the SDK autoloader, before Spiral loads .env, so, as with OTEL_PHP_AUTOLOAD_ENABLED, it has to be in the process environment or php.ini: the SDK reads getenv(), then $_SERVER, then get_cfg_var(). Set only in .env, it has no effect. For example:
-
RoadRunner:
server.envin.rr.yaml, or the environment of therrprocess (Docker, systemd):server: env: OTEL_PHP_DISABLED_INSTRUMENTATIONS: guzzle
-
php-fpm:
env[OTEL_PHP_DISABLED_INSTRUMENTATIONS] = guzzlein the pool; -
php.ini:OTEL_PHP_DISABLED_INSTRUMENTATIONS = guzzle.
Under RoadRunner the hooks are registered once per worker, when it starts, so a new value applies to new workers only: a php.ini change takes effect on rr reset; a change in .rr.yaml or in the environment of rr, on a restart of rr.
OTEL_SDK_DISABLED=true does not remove the hooks, as the _register.php files do not check it. The bridge then builds a no-op provider, so nothing is exported, but the hooks still run on every call. To drop them, list them in OTEL_PHP_DISABLED_INSTRUMENTATIONS.
PSR-15
The HTTP stack of Spiral is PSR-15, so open-telemetry/opentelemetry-auto-psr15 hooks into it. With the provider built by the bridge, the spans in which it doubles Spiral are suppressed, and the tree of a request is the same as without the extension:
- its
SERVERspan ofSpiral\Http\Http::handle()is suppressed, and theSERVERspan of Spiral stays the root of the request, under the incoming parent; - its
INTERNALspans of every request handler and middleware are suppressed, as Spiral traces its middleware pipeline itself.
Disabling that instrumentation with OTEL_PHP_DISABLED_INSTRUMENTATIONS=psr15 (see Disabling) gives the same tree.
Nothing else is suppressed: a request handled inside a request or a job run inside a job keeps both spans. Suppression by span kind or by semantic conventions is opt-in, with OTEL_EXPERIMENTAL_SPAN_SUPPRESSION_STRATEGY=spankind or semconv, as the SDK reads it.
With OTEL_PHP_AUTOLOAD_ENABLED=true the provider comes from the SDK, so the bridge cannot suppress anything: disable psr15 or configure suppression in the SDK.
A span left active when a request or job ends would become the parent of every later span of the worker and hide the incoming trace context; the bridge writes a warning to the SDK log when it sees one.
Spans of hooks nest under the active span. A Spiral trace that is not scoped, like Routing or Job push, is never active, so database or HTTP client spans made inside it hang on the enclosing scoped span.
Upgrading to 2.0
- The instrumentation scope of the Spiral spans is
spiral/otel-bridgewith the package version, notOTEL_SERVICE_NAME. The service name stays a resource attribute. The version comes fromresources/version.json, the release manifest, which moved there from.github/. - The propagator is built from
OTEL_PROPAGATORS, by defaulttracecontext,baggage, and is a singleton. - The tracer provider and propagator are registered in
Globalsfrom boot until the app terminates; withOTEL_PHP_AUTOLOAD_ENABLED=truein the process environment they are taken from there instead. - Status codes: integers and unknown strings no longer give
Ok, see Span status. - A callback that throws makes the span
Errorwith the exception message and keeps the name and attributes set in it. getContext()returns the context of the span running where it is called, with the baggage; after all traces have ended, the trace context of the last finished outermost one, without baggage.- With
opentelemetry-auto-psr15, its spans that double Spiral ones are suppressed. OpenTelemetryBootloader::initTraceProvider()takes the span processor from the container instead of a parameter.- Dependencies: Spiral packages
^3.18,open-telemetry/sdk>=1.9 <1.16,open-telemetry/api^1.7,open-telemetry/context^1.4;open-telemetry/opentelemetry-auto-psr15conflicts outside>=1.0.6 <1.4,open-telemetry/sem-convbelow1.22.