Packages

crystoline/xpsr-telemetry

Distributed tracing for XPSR applications, on the OpenTelemetry PHP SDK. A request through the application shows up in Jaeger, Grafana Tempo, Honeycomb, Datadog, or any other OTLP collector as one trace: the request, its database queries, the HTTP calls it made, the jobs it queued (even when a worker runs them later), with the console commands and scheduled tasks of the application as traces of their own. Log lines carry the trace and span IDs, so a log line, a trace, and a support ticket meet.

composer require crystoline/xpsr-telemetry

Composer asks whether to allow the tbachert/spi plugin the SDK ships with. Answer no: XPSR builds the SDK's components itself and needs none of the plugin's autoloading. To stop the question, add "tbachert/spi": false under config.allow-plugins in composer.json.

Add the provider to app.registry in config/app.php, after the providers of the packages it traces (database, HTTP client, queue, scheduler, Monolog), and the middleware first in app.middleware, so every other middleware is inside the request's span:

'registry' => [
    // ...
    Crystoline\Xpsr\Telemetry\TelemetryServiceRegistry::class,
],
'middleware' => [
    Crystoline\Xpsr\Telemetry\Http\TraceRequestsMiddleware::class,
    // ...
],

Installing the package changes nothing until telemetry is turned on. Then the only setting most collectors need is where they listen:

OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318

Configuration

Set environment variables, or override them in config/telemetry.php:

// config/telemetry.php
return [
    'enabled' => env('APP_ENV') === 'production',
    'service_name' => 'shop-api',
    'service_version' => env('APP_RELEASE'),
    'endpoint' => 'https://api.honeycomb.io',
    'headers' => ['x-honeycomb-team' => env('HONEYCOMB_KEY')],
    'sample' => 0.1,
];

Invalid values fail when telemetry is first used, with the setting's name. The configuration wins over the environment variables.

What is traced

Each span carries the attributes of the OpenTelemetry semantic conventions, named in Crystoline\Xpsr\Telemetry\Attributes, plus a few of XPSR's own under xpsr..

A span fails, with the exception recorded as an event, when a request answers 5xx or an exception reaches the kernel, when an outgoing request answers 4xx or 5xx or cannot be sent, when a job throws, when a command throws or exits with a code other than 0, and when a task fails. A 4xx answer of the application is not a failure, and the span of a request that matched no route stays named by its method.

Your own spans

Crystoline\Xpsr\Telemetry\Tracer wraps the SDK's tracer, so application code does not depend on OpenTelemetry's API. A span is a child of the current one (the request, job, or command), is current while the closure runs, records an exception the closure throws and rethrows it, and ends when the closure returns:

use Crystoline\Xpsr\Telemetry\Span;
use Crystoline\Xpsr\Telemetry\Tracer;

final class ChargeController
{
    public function __construct(private readonly Tracer $tracer, private readonly Gateway $gateway) {}

    public function capture(ServerRequestInterface $request): ResponseInterface
    {
        $charge = $this->tracer->span('charge.capture', function (Span $span) use ($request): Charge {
            $span->setAttribute('charge.id', $request->getAttribute('id'));
            $charge = $this->gateway->capture($request->getAttribute('id'));
            $span->addEvent('gateway.answered', ['reference' => $charge->reference]);

            return $charge;
        });
        // ...
    }
}

start($name, $attributes) gives a span to end() by hand; current() is the span in progress, with traceId() and spanId() to show a user or write somewhere; inject($headers) writes the trace context into an array of headers for a message that continues the trace elsewhere, and extract($headers) reads one back. Attributes are strings, numbers, booleans, or lists of one of them; enums and Stringable objects become strings. With telemetry off, closures still run and spans do nothing.

The SDK's own API works too: the tracer provider is registered with OpenTelemetry\API\Globals, so a library instrumented with OpenTelemetry joins the same traces.

Logs

With crystoline/xpsr-log-monolog, every log line written inside a span carries trace_id and span_id in its extra data, next to request_id. Search the collector for the trace ID of a log line, or the logs for the trace ID of a slow span. List the telemetry provider after the Monolog one.

Exporting

Spans are kept until the request or command ends, then sent in one batch from a shutdown function, so a request never waits on the collector; a worker sends a batch every few seconds or every 512 spans. Telemetry::flush() sends what is finished now. The export goes through the HTTP client package's client (or the one telemetry.client names), without being traced itself.

The console exporter prints each span as JSON on standard output: OTEL_TRACES_EXPORTER=console php xpsr migrate shows what a command would send. The SDK's other OTEL_* variables are not read: XPSR configures the SDK from the settings above.

Testing

Turn telemetry on with the memory exporter in the test environment, in phpunit.xml:

<env name="OTEL_ENABLED" value="true"/>
<env name="OTEL_TRACES_EXPORTER" value="memory"/>

Crystoline\Xpsr\Telemetry\Testing\FakeTelemetry then has the spans the application finished:

use Crystoline\Xpsr\Telemetry\Testing\FakeTelemetry;
use Crystoline\Xpsr\Telemetry\Testing\FinishedSpan;

$this->postJson('/payments', ['amount' => 500]);

$spans = $this->application()->get(FakeTelemetry::class);
$request = $spans->assertSpan('POST /payments', static fn(FinishedSpan $span): bool => $span->attribute('http.response.status_code') === 201);
$spans->assertSpan('job App\Jobs\SendReceipt', static fn(FinishedSpan $span): bool => $span->traceId() === $request->traceId());
$spans->assertSpan('charge.capture', null, 1);                   // exactly once
$spans->assertNoSpan('SELECT payments', static fn(FinishedSpan $span): bool => $span->isError());
$spans->assertNothingTraced();

A FinishedSpan has name(), kind(), attribute($name), attributes(), isError(), error(), exception(), events(), traceId(), spanId(), parentSpanId(), isRoot(), and durationNanos(). spans() lists them in the order they ended, find($name) those with a name, and clear() forgets them. A failed assertion names the spans that finished.

Services

Not provided: metrics and OpenTelemetry logs (traces first; metrics can follow once there is a use for them), the gRPC transport (the OTLP/HTTP one serves every collector), and spans for views or cache calls.

Requires PHP 8.4+, open-telemetry/sdk 1.15+, and open-telemetry/exporter-otlp 1.4+. The database, HTTP client, queue, scheduler, and Monolog packages are optional and detected.