Weave Code
Opentelemetry Auto Laravel Laravel Package
open-telemetry/opentelemetry-auto-laravel
Automatic OpenTelemetry instrumentation for Laravel apps. It hooks into the framework to emit traces, metrics, and logs for HTTP requests, database queries, queue jobs, and more, with no manual code changes. Add it to get distributed tracing and observability out of the box.
open-telemetry/opentelemetry-auto-laravel provides zero-code auto-instrumentation for Laravel applications using the OpenTelemetry PHP SDK. Drop it in and it automatically generates traces and metrics for your app without manual span creation—ideal for adding observability to existing Laravel projects.
- Automatic spans for HTTP requests, middleware, and routing
- Database query and Eloquent tracing
- Queue job, mail, and notification instrumentation
- Cache and event dispatching visibility
- Configured through standard OpenTelemetry environment variables
Frequently asked questions about Opentelemetry Auto Laravel
- How do I install open-telemetry/opentelemetry-auto-laravel?
- Install it with Composer alongside the OpenTelemetry PHP SDK and an exporter, but treat it as a platform runtime dependency rather than a normal Laravel package. You must also install the PECL opentelemetry extension in the runtime image, enable autoloading with OTEL_PHP_AUTOLOAD_ENABLED=true, and set OTEL_* variables in the real process environment rather than only in .env. The package is discovered through _register.php hooks, not through a Laravel service provider.
- Does this package really work without code changes?
- It provides zero-code auto-instrumentation, so you generally do not create spans manually for HTTP requests, database queries, queues, and similar framework activity. However, it is not a literal drop-in library because you still need the PHP extension, SDK, exporter, environment variables, and collector or backend configuration. Application code changes are minimal, but runtime and deployment changes are non-trivial.
- Which Laravel and PHP versions are supported?
- It is best suited to Laravel applications running PHP 8.1 or newer with the OpenTelemetry PHP SDK and an OTLP-compatible backend. The exact Laravel compatibility matrix is not guaranteed by the package description, so pin the PHP extension, SDK, exporter, auto-laravel package, Laravel version, and PHP runtime together. After Laravel upgrades, run composer why-not open-telemetry/opentelemetry-auto-laravel and inspect the _register.php hook targets against framework internals.
- What does open-telemetry/opentelemetry-auto-laravel instrument automatically?
- It automatically generates spans for HTTP requests, middleware, routing, database queries, and Eloquent activity. It also instruments queue jobs, mail, notifications, cache operations, event dispatching, console commands, and outgoing HTTP calls. The result is vendor-neutral tracing data that can be exported through OpenTelemetry tooling.
- Why am I seeing no traces or spans from my Laravel app?
- Failure is often silent, so start by checking that the PECL opentelemetry extension is installed and loaded in the runtime. Confirm OTEL_PHP_AUTOLOAD_ENABLED=true, the vendor path is correctly globbed, the package is in production dependencies rather than require-dev, and OTEL_* variables are present in the actual PHP-FPM, Docker, or systemd environment. Also verify that the exporter and collector endpoint are reachable before assuming instrumentation is broken.
- Do I need an OpenTelemetry Collector or observability backend?
- You need somewhere to send the telemetry, and the package is designed for OpenTelemetry-compatible backends via an OTLP collector. A collector preserves backend portability across tools such as Jaeger, Tempo, Honeycomb, Datadog, and New Relic. For initial validation, you can use the console exporter to prove that spans are being emitted before connecting a production backend.
- How does it handle Laravel queue jobs, Horizon, and Octane?
- Queue jobs are instrumented automatically, but you should verify parent-child trace continuity because worker spans can become orphaned. Add job middleware to inject or extract context if needed, and plan explicit SDK flushing for long-running Horizon or Octane processes rather than relying on auto-shutdown. These long-running process models are known sharp edges and should be tested carefully.
- Is this package safe for production Laravel applications?
- It can be used in production, but it is early-adopter territory with a small star count and no dependents, so expect edge cases. Run a time-boxed pilot on one non-critical service, validate span quality and latency impact, and define a kill switch and rollback path. Before wider rollout, tune sampling, batch export, PII redaction, and collector-side filtering of health or dashboard endpoints.
- How do I disable noisy instrumentation or add custom attributes?
- Use OTEL_PHP_DISABLED_INSTRUMENTATIONS to silence specific noisy instrumentation without changing application code. There is no publishable Laravel config file, so configuration is handled through standard OpenTelemetry environment variables. For business-specific context, add global middleware to attach tenant or user attributes and only create custom spans where the framework instrumentation is not enough.
- What are the alternatives to this package and how is it maintained?
- Alternatives include manual OpenTelemetry PHP SDK instrumentation, vendor APM agents such as Datadog or New Relic, or other Laravel-specific observability packages. This package is a good fit when your team is already committed to OpenTelemetry and can operate an OTLP collector, but it is a poor fit if you need turnkey APM with contractual vendor support. Treat it as contrib-tier support and assign ownership for collector configuration, sampling, redaction, and upgrade regression testing.
Weaver
How can I help you explore Laravel packages today?