README

Vendor-neutral tracing core for Yii3. One ergonomic call — trace(name, callback) — opens a span, runs your code, and closes the span, instead of the verbose OpenTelemetry span-builder. The exporter is a swappable backend.

Using an AI coding assistant? llms.txt has a compact API reference you can pass as context.

Requirements

• PHP 8.3+ (64-bit — epoch nanoseconds exceed PHP_INT_MAX on 32-bit builds)
• open-telemetry/api ^1.5 (thin: interfaces + NoopTracer, no SDK)
• PSR-20 clock, PSR-3 log, PSR-7 http-message interfaces

Installation

composer require rasuvaeff/yii3-telemetry

For real span export, add a backend (Sprint 2): rasuvaeff/yii3-telemetry-otel. Without one, bind the no-op provider (see Wiring).

Usage

Trace a block of work

use Rasuvaeff\Yii3Telemetry\SpanInterface;
use Rasuvaeff\Yii3Telemetry\TraceKind;
use Rasuvaeff\Yii3Telemetry\Tracer;

/** @var Tracer $tracer (injected) */
$order = $tracer->trace(
    name: 'checkout.process',
    callback: static function (SpanInterface $span) use ($cart): Order {
        $order = $cart->checkout();
        $span->setAttribute('order.id', $order->getId());

        return $order;
    },
    attributes: ['user.id' => $userId],
    scoped: true,
    traceKind: TraceKind::Internal,
);

The callback receives the active SpanInterface and its return value becomes the trace() return value.

trace() contract (frozen at 1.0.0)

end() is idempotent.

Span

SpanInterface is what the callback receives:

The concrete Span (recorded by LogTracer) additionally exposes getters: getName(), getKind(), getStatus(): SpanStatus (a value object pairing a SpanStatusCode with an optional description), getAttributes(), getEvents(): list<SpanEvent>, getRecordedExceptions(), getDurationNanos(), hasEnded().

Tracers

use Rasuvaeff\Yii3Telemetry\LogTracer;

$tracer = new LogTracer($psrLogger); // logs every finished span, no backend

Context propagation (W3C Trace Context)

use Rasuvaeff\Yii3Telemetry\TraceContextPropagator;

$propagator = new TraceContextPropagator();

// Incoming server request → context.
$context = $propagator->extract($serverRequest);

// Context → outgoing client request (adds the `traceparent` header).
$request = $propagator->inject($context, $clientRequest);

extract reads a ServerRequestInterface; inject writes an outgoing RequestInterface. A missing/malformed header yields TraceContext::invalid().

For non-HTTP transports use the carrier-agnostic pair — a plain header map you can put into any envelope (queue message, AMQP header table, gRPC metadata):

// Producer: attach the current context to the message envelope.
$envelope['headers'] = $propagator->toHeaders($tracer->getContext());

// Consumer: restore it and open a Consumer span.
$context = $propagator->fromHeaders($message['headers'] ?? []);

fromHeaders matches names case-insensitively; an invalid context yields an empty map from toHeaders, so the round trip is always safe.

Queue instrumentation roadmap. A ready-made yiisoft/queue middleware (Producer inject + Consumer span) is deferred until yiisoft/queue has a stable release — the carrier API above is the supported way to propagate a trace through any queue today.

Clock

ClockInterface extends PSR-20 with a monotonic reading — two clocks that must not be mixed:

• now(): \DateTimeImmutable — the wall clock (span start timestamp);
• monotonicNanos(): int — hrtime, for measuring durations.

SystemClock is the default (and is a valid PSR-20 clock).

Wiring (yiisoft/config)

The core config/di.php binds only the facade (Tracer, TracerInterface). It never binds TracerProviderInterface — that swappable key is owned by exactly one source. With no backend installed, bind the no-op provider in your app:

// config/common/di.php
use Rasuvaeff\Yii3Telemetry\NullTracerProvider;
use Rasuvaeff\Yii3Telemetry\TracerProviderInterface;

return [
    TracerProviderInterface::class => NullTracerProvider::class,
];

Installing yii3-telemetry-otel provides the real binding instead — binding it in two vendor packages is a deliberate yiisoft/config Duplicate key error.

Instrumentation

Backend-agnostic instrumentation that records spans through the facade. Wire it app-side — never unconditionally in a package di.php, or the container would fatal when the subsystem isn't installed.

// HTTP client (PSR-18) — inner client is wrapped
$client = new HttpClientSpanDecorator($innerClient, $tracer);

// Cache (PSR-16)
$cache = new TracingCacheDecorator($innerCache, $tracer);

// DB (yiisoft/db) — pass the semconv db.system for your driver (default 'sql')
$connection->setProfiler(new DbQueryProfiler($tracer, dbSystem: 'postgresql'));

// View (yiisoft/view) — register in config/events.php
BeforeRender::class => [[ViewRenderSpanListener::class, 'beforeRender']],
AfterRender::class  => [[ViewRenderSpanListener::class, 'afterRender']],

DbQueryProfiler and ViewRenderSpanListener bracket a subsystem's split begin/end hooks with Tracer::startSpan() (a manual span the caller ends). yiisoft/db and yiisoft/view are optional (suggest); their symbols are declared in composer-require-checker.json.

Log correlation & exposing the trace id

// Wrap the application logger — every record inside an active trace gets
// trace_id / span_id in its context (existing keys are never overwritten):
$logger = new TraceContextLogger($innerLogger, $tracer);

// Opt-in: return the trace id to the client for support tickets. Place it
// AFTER the tracing middleware (inside the root span):
$middleware = new TraceIdResponseHeaderMiddleware($tracer);              // X-Trace-Id
$middleware = new TraceIdResponseHeaderMiddleware($tracer, 'Trace-Ref'); // custom name

Without an active valid trace context both are transparent: the log record and the response pass through unchanged.

Security

• SQL safety: DbQueryProfiler puts only the parameterized SQL into db.statement — parameter values are never attached to a span. A debug opt-in for parameter values and a slow-query threshold are deliberately not implemented; if they land later, they will be off by default.
• TraceContext validates ids (hex32 / hex16) and flags (0..255) in its constructor; malformed propagation headers are rejected, not trusted.
• trace() never swallows exceptions — failures stay visible.

Examples

Runnable, server-independent scripts live in examples/: 01_basic_trace.php, 02_nested_trace.php, 03_propagation.php. See examples/README.md.

Development

docker run --rm -v "$PWD":/app -w /app composer:2 composer build

Runs validate → normalize → require-checker → cs → psalm → tests (incl. property tests). make build, make test, make mutation, make release-check are also available.

License

BSD-3-Clause. See LICENSE.md.