Weave Code
Laravel Opentelemetry Laravel Package
keepsuit/laravel-opentelemetry
OpenTelemetry integration for Laravel: automatically instrument HTTP requests, database queries, queues, Redis, and more, then export traces and metrics via OTLP to your observability backend. Simple configuration and Laravel-native APIs.
OpenTelemetry integration for laravel
Frequently asked questions about Laravel Opentelemetry
- How do I install keepsuit/laravel-opentelemetry in a Laravel application?
- Install it with Composer via keepsuit/laravel-opentelemetry; the package registers its own Laravel service provider, so no manual provider registration is normally required. Publish the config file with the vendor:publish command and set your OTEL_* environment variables, including the service name and the OTLP endpoint. No application code changes are needed to get baseline tracing, because instrumentation hooks into framework seams such as the HTTP kernel, database layer, queue worker, and Redis.
- What does Laravel OpenTelemetry automatically instrument?
- The package instruments framework-level seams: incoming HTTP requests, Eloquent and database queries, queued jobs, Redis and cache operations, console commands, and outbound Guzzle HTTP client calls. Because the instrumentation lives in the framework integration rather than your application code, you get spans across a typical Laravel monolith without touching controllers or models. Anything beyond that, such as pricing logic or multi-step orchestration, is not automatically spanned and needs manual instrumentation.
- Do I need an OpenTelemetry Collector to export traces from Laravel?
- You need an OTLP-capable destination, and running an OpenTelemetry Collector in front of your backend is the recommended pattern. The package emits standard OTLP rather than a vendor agent protocol, so the instrumentation choice and the observability vendor choice stay decoupled and you can change backends later without rewriting code. Point the exporter at the collector endpoint via environment variables and let the collector handle routing, sampling, and redaction.
- Does it collect metrics as well as traces?
- Yes. The package exports both traces and metrics over OTLP, so you can ship request latency and error signals alongside distributed traces to the same backend. In practice, start with traces to validate your collector tier and sampling policy, then enable metrics once the pipeline is stable. Both signals share the same OTLP exporter configuration.
- Can I create custom spans for my own application code?
- Yes. The package exposes Laravel-native APIs for creating spans around your own logic, so you can instrument domain operations like pricing calculations, saga steps, or third-party calls that auto-instrumentation cannot see. Treat manual spans as a team convention with naming and attribute standards, not an afterthought, or you will end up with inconsistent trace data. Plan some developer training and documentation time for this.
- What is the performance overhead and how do I avoid adding latency?
- Per-request overhead is modest but real, and it grows with span volume and attribute payload size. The classic mistake is a synchronous exporter, which adds tail latency precisely when your collector tier is degraded or unreachable. Use a batch or async exporter, keep sampling sensible, and avoid attaching large payloads to span attributes.
- Does it work with Laravel Octane or Swoole long-lived workers?
- It can, but long-lived worker runtimes are one of the things you must validate explicitly in your own environment rather than assume. Because workers persist between requests, resource attributes, service naming, and any per-request state need to behave correctly across many requests in the same process. Test your container base image and PHP extension availability at the same time, since the OpenTelemetry PHP SDK depends on them.
- How do I stop SQL text, bindings, and headers from leaking secrets into spans?
- Database statements and bindings, URLs, and request or response headers can all carry PII or credentials into span attributes, so define a redaction policy before going to production. Enforce it at the collector where possible, and disable or trim sensitive attributes in the package config where the collector cannot help. Retention and access rules for trace data should be signed off by whoever owns data governance, not decided ad hoc during an incident.
- Is keepsuit/laravel-opentelemetry production-ready, and what are the alternatives?
- It is MIT licensed with a small dependency footprint and a clean architecture, but it has weak adoption signals: roughly 190 GitHub stars and effectively no Packagist dependents, with a single maintainer. That means you would be an early adopter absorbing discovery cost, so only adopt it with a fork-and-vendor contingency and a named internal owner. The main alternative is a vendor APM SDK with its own auto-instrumentation, but running both creates two overlapping instrumentation layers, so pick one.
- Which version should I start with, and how should I handle upgrades?
- Set a minimum of 2.2.7 for any pilot, because earlier releases under-instrumented failed outbound HTTP client calls, which would make trace-derived error rates understate reality. Treat any traces collected on 2.2.6 or below as unreliable for outbound error analysis. Pin the package and the OpenTelemetry PHP SDK together and upgrade them as a unit, since the SDK and semantic conventions are still changing, and assign someone to read the changelog before every bump.
Weaver
How can I help you explore Laravel packages today?