Opentelemetry Auto Laravel Laravel Package

Technical Evaluation

• Architecture fit: Strong fit for Laravel services already committed to OpenTelemetry and an OTLP collector/backend. The package auto-instruments the HTTP kernel, router, middleware, database queries, queues, console commands, and outgoing HTTP calls, producing vendor-neutral traces. It is not a Laravel service provider and has no publishable config; it is a set of _register.php hooks discovered by the native opentelemetry PHP extension. That makes it a platform-level runtime dependency, not a normal composer package.
• Integration feasibility: Moderate. Application code changes are minimal, but runtime changes are non-trivial: PECL opentelemetry extension in the base image, SDK/exporter/auto-laravel packages, OTEL_PHP_AUTOLOAD_ENABLED=true, and OTEL_* variables set in the real process environment rather than .env. A TPM should treat this as a small platform integration project, not a drop-in library. A time-boxed pilot on one non-critical service is appropriate.
• Technical risk: Adoption risk is the main concern: ~63 stars and zero dependents means early-adopter territory, and the team will likely discover edge cases. Version compatibility is the top breakage source after Laravel/PHP upgrades. Failure is often silent: missing extension, disabled autoload, unglobbed vendor path, or moving the package to require-dev produces zero spans and zero errors. Octane/Horizon long-running processes, queue trace propagation, PII/cardinality, and double instrumentation are known sharp edges.
• Key questions: Is an OTel collector and OTLP backend already funded and owned? Which Laravel/PHP versions must be supported, and can the PHP extension be baked into every runtime? Who owns collector config, sampling, redaction, and upgrade regression testing? What decisions will traces drive: SLOs, canary gating, queue reliability, or monolith decomposition? What is the kill switch and rollback path? Can the organization accept contrib-tier support instead of a vendor SLA? Which service is the pilot, and what span schema must remain stable?

Integration Approach

• Stack fit: Best suited to Laravel PHP 8.1+ services using the OpenTelemetry PHP SDK and an OTLP-compatible backend via a collector. It preserves backend portability across Jaeger, Tempo, Honeycomb, Datadog, New Relic, etc. Poor fit where the organization needs turnkey APM with contractual support, cannot add a PHP extension, or has no appetite to operate a collector.
• Migration path: Start with one non-critical service. Add the extension to the base image, require SDK/exporter/auto-laravel in production dependencies, set OTEL_* variables in php-fpm/Docker/systemd, and validate with the console exporter before connecting a backend. Prove one request trace with HTTP and database child spans. Then add a global middleware for tenant/user attributes and only add custom spans where business logic needs them. For queued jobs, verify parent-child trace continuity; add job middleware to inject/extract context if worker spans are orphaned.
• Compatibility: Pin the PHP extension, SDK/exporter versions, auto-laravel version, Laravel version, and PHP runtime together. After Laravel upgrades, run composer why-not open-telemetry/opentelemetry-auto-laravel and inspect _register.php hook targets against framework internals. Add CI tests using an in-memory exporter to assert expected span names/attributes. Use OTEL_PHP_DISABLED_INSTRUMENTATIONS to silence noisy instrumentation without code changes. For Octane/Horizon, plan explicit SDK flush rather than relying on auto-shutdown.
• Sequencing: Phase 0: collector/backend ownership and success criteria. Phase 1: one-service pilot with console exporter, then OTLP; verify span quality, latency impact, and rollback. Phase 2: tune sampling, batch export, PII redaction, and collector-side filtering of health/dashboard endpoints. Phase 3: standardize base image, env templates, and version matrix; roll to the next services. Phase 4: wire traces into SLOs, incident response, and canary/progressive-delivery decisions. Gate each phase with a documented kill switch.

Operational Impact

• Maintenance: The TPM must budget an owner for collector operation, sampling policy, redaction, dependency pinning, and upgrade regression testing. The package itself is small; the surrounding OTel pipeline is the durable platform asset. Keep the package in production dependencies and never move it to require-dev; otherwise composer install --no-dev silently removes all traces.
• Support: No vendor SLA. Support is community/contrib-tier, so escalation is internal platform engineering plus the OTel community. If the organization requires audited, maintained dependencies with contractual support, a commercial APM agent or Laravel Nightwatch is the lower-risk alternative. Document a known-good version matrix and runbooks for “no spans arriving” versus “spans not exported.”
• Scaling: Cost and operational load scale with collector capacity, span volume, and cardinality, not with the package. Use parent-based ratio sampling, batch processing, collector-side filtering of health/dashboard endpoints, and redaction of SQL statements and URLs containing IDs. The payoff is portfolio-level consistency: instrument once against OTel and route to the backend of choice, including across multiple Laravel services.
• Failure modes: Silent no-span behavior from missing extension, disabled autoload, unglobbed vendor path, or package removal. Collector/backend outages should not break the app, but export backpressure and retry behavior must be tested. Watch for orphaned queue traces, Octane/Horizon flush gaps and state bleed, duplicate spans from overlapping auto-instrumentation, high-cardinality/PII leakage, and version breakage after framework upgrades. Use console exporter smoke tests, OTEL_LOG_LEVEL=debug, and collector logs to separate “not instrumented” from “not exported.”
• Ramp-up: Expect roughly 1–2 engineer-weeks for the pilot, mostly collector setup, sampling, environment plumbing, and span validation. A TPM should leverage the pilot to decide whether this becomes a platform standard or remains a one-off. Define success criteria around useful HTTP/DB/queue breakdowns, no measurable latency regression, and evidence that traces support SLO, incident, or release decisions. Avoid platform-wide commitment until operability and maintainability are proven.