Laravel Open Telemetry Laravel Package

Technical Evaluation

Architecture fit

• overtrue/laravel-open-telemetry is a Laravel service-provider package that wires the OpenTelemetry PHP SDK into framework lifecycle events (HTTP kernel, DB/Redis, queue). It is additive: it does not replace Laravel's logging or existing APM, it emits OTLP telemetry to a collector or OTLP-compatible backend.
• Fit is strongest for teams already standardizing on OpenTelemetry (Tempo/Jaeger/SigNoz/Datadog-OTLP/Grafana stack) and running standard Laravel (non-Octane or Octane) on PHP 8.1+.
• Weaker fit where the org already has a proprietary APM agent (Datadog, New Relic, Elastic) with its own auto-instrumentation — you would be running two instrumentation layers over the same hot paths.

Integration feasibility

• Low code-touch: composer require, config publish, env-driven OTLP endpoint/headers, auto-discovery. Realistically a half-day PoC, one to two weeks to production-grade configuration.
• Real effort is not in the package but in the surrounding platform: running an OpenTelemetry Collector, defining sampling policy, resource attributes (service.name, deployment.environment), and backend dashboards.
• Exporter transport (gRPC via ext-grpc vs HTTP/protobuf) is an infrastructure decision that must be made up front and affects base image and extension management.

Technical risk

• Pre-1.0 maturity: 0.0.32 with a rapid 32-patch cadence signals active development but no semver stability guarantee. Config keys, class names, and instrumentation coverage can change between minor releases. Pin exact versions (e.g. 0.0.32), never ^0.0.
• Upstream beta dependency: the OpenTelemetry PHP SDK itself is not GA; API stability risk is inherited.
• Instrumentation gaps: release 0.0.32 fixes export of monitoring information at the end of queue job execution. That this is only now being corrected implies queue-job telemetry was previously incomplete or dropped — a signal that auto-instrumentation coverage is still settling, and that other surfaces (scheduler, broadcasting, long-running workers) may have similar gaps.
• Bus factor / support model: single-maintainer community package (widely respected author, but no vendor SLA). Treat as a dependency we must be able to fork or vendor if necessary.
• Overhead in hot paths: DB query and queue instrumentation can multiply span volume; uncontrolled cardinality drives both CPU cost and observability spend.

Key questions

1. Which Laravel and PHP versions are explicitly supported and tested in CI? What is the support matrix commitment?
2. Is there a published roadmap to 1.0, and what constitutes the stability boundary?
3. What is the measured latency overhead per request at 100% sampling for a representative endpoint mix?
4. Does it propagate trace context across dispatch() → worker → nested jobs, and across scheduler-invoked jobs?
5. Which samplers are exposed (parent-based, traceidratio, custom) and can sampling be configured per-surface (HTTP vs queue)?
6. Behavior under Octane/Swoole and in long-lived queue workers — are spans flushed and memory released per job, or does state accumulate?
7. What happens when the collector is unreachable — blocking, buffered, or silently dropped? Is there a bounded queue?
8. License and contribution terms; willingness/size of internal fork budget.

Integration Approach

Stack fit

• Requires PHP 8.1+, Laravel 9/10/11 (confirm against CI matrix), Composer, and either ext-grpc + protobuf or an HTTP/protobuf exporter.
• Backend-agnostic via OTLP: run a Collector as a sidecar/DaemonSet and fan out to whichever vendor we standardize on. The Collector is the abstraction that keeps us from re-instrumenting if the backend changes.
• Cleanest fit: an existing OTel Collector already deployed for other services. Worst fit: greenfield observability stack stood up solely for this package.

Migration path

• Purely additive. No application code changes expected: enable via env, disable via env. Keep the package behind a config flag in config/telemetry.php/env so it can be turned off in one place.
• Recommended rollout as a parallel signal initially — run alongside existing logging/APM, compare trace fidelity, then decide whether the existing APM stays for errors/logs or is retired.
• Do not remove existing APM until OTel dashboards are trusted; keep a one-release overlap.

Compatibility

• Coexistence risk with other OpenTelemetry packages (duplicate root spans, double-counted DB spans) and with framework-level instrumentation in Telescope/Debugbar in non-prod.
• Verify against Octane/Swoole if used; long-running workers are the historically fragile surface and the exact area touched by 0.0.32.
• Confirm no conflict with existing laravel/framework event listeners registered on JobProcessing/JobProcessed.

Sequencing

1. Pin 0.0.32 (or later) in a sandbox app; stand up a local Collector + Jaeger/Tempo.
2. Enable HTTP-only instrumentation; baseline latency and span volume.
3. Add DB/Redis instrumentation; measure overhead delta and cardinality.
4. Enable queue instrumentation after validating the 0.0.32 fix — specifically confirm spans close and export per job rather than per worker lifetime.
5. Canary in staging with 10–25% sampling, then production at low sampling (1–10%) with error-biased sampling.
6. Tune resource attributes, collector batching/retry, and retention; publish runbook.

Operational Impact

Maintenance

• Treat as a moving target: pin exact versions, read every changelog, budget ~1–2 hours per release for review and upgrade testing during the 0.0.x line. Expect at least one breaking config change before 1.0.
• Add a dependency-health check to the observability ownership rotation; identify a named internal maintainer with authority to vendor/fork.

Support

• Community-only: GitHub issues, no SLA, no guaranteed response. Escalation path must be internal engineering, not the maintainer.
• Mixed-language issue tracker (project originates in the Chinese PHP community) — fine, but assume some self-sufficiency in reading the source.

Scaling

• Cost scales with span volume, not request volume: sampling policy is the primary cost lever and must be set before broad enablement.
• Collector becomes a critical path component; it needs its own HA/queueing (persistent queue, retry, batching) so backend outages don't propagate to app latency.
• Queue-heavy workloads are the highest-growth area: per-job spans multiply quickly on fan-out jobs. Consider suppressing spans for trivial/high-frequency jobs.
• Long-running queue workers: monitor worker RSS over multi-day runs; per-job flush semantics (the 0.0.32 change) are the thing to validate under load.

Failure modes

• Collector unreachable / slow: depending on exporter config, requests may block or spans buffer in memory. Must be tested explicitly; set aggressive timeouts and bounded buffers.
• Missing queue spans: the class of defect addressed in 0.0.32 — spans or attributes not exported at job completion, yielding silent gaps in traces. Validate post-upgrade; assume sibling gaps exist elsewhere.
• Broken trace context: jobs dispatched before instrumentation load, or through non-instrumented paths, appear as orphan root spans — traces look complete but aren't.
• Memory growth in workers: unresolved spans accumulating in long-lived processes; manifests as slow OOM rather than a clean error.
• Cardinality explosion: high-cardinality resource/attribute tagging (user IDs, URLs with parameters) inflates backend cost and slows queries.
• Silent degradation: the most dangerous mode — telemetry stops flowing and no one notices. Requires a canary/self-monitoring alert on span ingestion rate.

Ramp-up

• Team must absorb core OTel concepts (spans, context propagation, semantic conventions, sampling, Collector pipelines) — not learnable purely from this package's README. Budget ~1 sprint for a platform engineer plus ~1 sprint of team enablement.
• Deliverables for enablement: architecture diagram, sampling policy doc, dashboard from day one (not after), alerting on ingestion health, and a documented kill switch.
• Post-0.0.32, queue observability becomes a viable capability rather than a partial one — this is the right moment to scope queue-level SLOs if they were previously blocked on missing trace data.