README

Waffle Commons — Telemetry (OpenTelemetry Bridge)

OpenTelemetry SDK bridge for the Waffle Commons framework. It implements Waffle\Commons\Contracts\Telemetry\TracerInterface on top of the audited OpenTelemetry PHP SDK and propagates W3C Trace Context on outbound HTTP calls — isolating the vendor SDK in this adapter so the core packages stay vendor-free.

Status: shipped in Beta 5 / AXE 5 (RFC-005). The SDK-free defaults, the Prometheus endpoint and the metric collectors live in waffle-commons/telemetry.

What's inside

• Tracer adapters — Trace\OtelTracer, Trace\OtelSpan and Trace\OtelSpanContext adapt the OpenTelemetry SDK to the framework's Contracts\Telemetry\TracerInterface / SpanInterface / SpanContextInterface. The SDK owns the active-context stack, so the adapters hold no per-request worker state.
• W3C propagation — Propagation\W3CTraceContextPropagator injects / extracts traceparent + tracestate, enabling transparent distributed tracing across services.
• Factory — Factory\OtelTracerFactory assembles a tracer from any SpanExporterInterface (or a console JSON exporter for local docker logs inspection), keeping every OpenTelemetry\SDK\* symbol out of the core perimeter.

Perimeter

The only Waffle package permitted to require the OpenTelemetry SDK (open-telemetry/*). Depends on waffle-commons/contracts plus the OTel SDK; mago guard is configured to allow the SDK here and nowhere else. The request-scoped trace-context holder implements ResettableInterface (wfl igor 0 KO).

Development

composer install
composer mago     # fmt + lint + analyze + guard — must be ZERO output
composer tests    # PHPUnit 12.5, >=95% coverage
composer igor     # worker-safety audit — 0 KO

License

MIT — see LICENSE.md.