kinetis/telemetry

OpenTelemetry tracing for Kinetis — request spans, SQL and queue decorators, a traced HTTP transport, and OTLP export over the Revolt-backed client.

v1.3.0 2026-08-16 23:52 UTC

Requires

• php: ^8.4
• kinetis/framework: ^1.11
• kinetis/revolt-http-client: ^1.1
• nyholm/psr7: ^1.8
• open-telemetry/exporter-otlp: ^1.4
• open-telemetry/sdk: ^1.15
• psr/log: ^3.0
• symfony/http-client: ^8.0
• symfony/http-client-contracts: ^3.7

Requires (Dev)

• infection/infection: ^0.34.2
• kinetis/cache-redis: ^1.0
• kinetis/persistence: ^1.10
• kinetis/queue: ^1.5
• phpstan/phpstan: ^2.2
• phpunit/phpunit: ^11.0
• vimeo/psalm: ^6.16

Suggests

• kinetis/persistence: Enables the TracingMysqlLink/TracingPostgresLink decorators, a span per SQL query.
• kinetis/queue: Enables the TracingQueue decorator — producer spans on push(), consumer spans from pop() to ack().

MIT

• Alon Noy

Published on Packagist.org on 2026-08-16 23:52 UTC

README

kinetis/telemetry
OpenTelemetry tracing for Kinetis

A span per request, per SQL query, per queue job, and per outgoing HTTP call, exported over OTLP to any tracing backend. Export goes through kinetis/revolt-http-client's Fiber-suspending transport, so flushing a span batch never blocks the worker.

The distinctive trace this produces: spans that overlap in time. A request running two queries and an HTTP call through concurrently() shows all three side by side inside the request span — what non-blocking I/O actually did for that request, visible.

Set one environment variable and requests start tracing:

OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4318

Provides

Installing this package auto-registers, via extra.kinetis:

• Global middleware RequestSpanMiddleware — one server span per request (method, url.path, status, php.memory.usage; an incoming traceparent joins the caller's trace).
• A container binding for OpenTelemetry\API\Trace\TracerProviderInterface — the OTLP-exporting provider when OTEL_EXPORTER_OTLP_ENDPOINT is set, a no-op provider otherwise, so an unconfigured install costs near nothing.
• The framework's instrumentation hooks, turned on — when the OTLP endpoint is set, the bootstrap swaps an OTel backend into core's Kinetis\Instrumentation\Telemetry holder, so the spans the framework reports from inside itself (boot phases, per-middleware timing, route match, hydration, controller, queries split at the pool boundary, transactions, concurrently() tasks, events, MCP calls, queue jobs) start exporting with no further wiring.

Nothing else. The decorators below are explicit opt-ins wired in your own bootstrap.php.

Decorators

• TracingMysqlLink / TracingPostgresLink — a span per SQL query (named by first keyword, full SQL as db.query.text, parameter values never recorded), wrapping any kinetis/persistence link while keeping its dialect marker. Transactions they begin span COMMIT and ROLLBACK too.
• TracingQueue — a producer span per push(); a consumer span from pop() to ack()/release()/fail() carrying the outcome, active while the job runs so its own queries and HTTP calls nest under it.
• TracingHttpClient — a client span per outgoing request with traceparent injection, ending when the response is consumed rather than when request() returns. Hand it to Http as its transport.
• TraceAwareLogger — wraps any PSR-3 logger, adding the active span's trace_id/span_id to every entry's context.

Configuration

Key	Default	Purpose
OTEL_EXPORTER_OTLP_ENDPOINT	—	Collector's OTLP/HTTP base URL. Unset = tracing off (no-op provider).
OTEL_SERVICE_NAME	kinetis	The service.name resource attribute.
OTEL_EXPORTER_OTLP_HEADERS	—	Export headers, key=value,key2=value2 — a hosted backend's auth.
OTEL_TRACES_SAMPLER	parentbased_always_on	Standard sampler names; traceidratio + OTEL_TRACES_SAMPLER_ARG for a rate.
OTEL_TRACES_SAMPLER_ARG	1.0	Ratio for the traceidratio samplers, 0–1.

Installation

composer require kinetis/telemetry

Requires PHP 8.4+. Full documentation: docs.kinetis.dev/telemetry.html.

License

MIT — see LICENSE.