What is OpenTelemetry?
OpenTelemetry is a vendor-neutral, open-source observability framework that provides a unified set of APIs, SDKs, and tools for generating, collecting, and exporting telemetry data. It is maintained by the Cloud Native Computing Foundation (CNCF) and is the industry standard for instrumenting cloud-native applications. Telemetry data comes in three signals:- Traces — distributed call graphs that show exactly what happened during a request, including cross-service hops.
- Metrics — numerical measurements over time (request counts, latency histograms, error rates, etc.).
- Logs — structured log records correlated with the active trace context.
What this package does
keepsuit/laravel-opentelemetry integrates the OpenTelemetry PHP SDK into Laravel with zero boilerplate. After installing the package and setting a couple of environment variables, your application automatically emits traces, metrics, and logs for the most common Laravel operations.
The package handles the full SDK lifecycle — building providers, registering propagators, managing exporters, and flushing telemetry on shutdown — so you can focus on your application.
Supported instrumentations
All instrumentations are enabled by default and configurable via environment variables orconfig/opentelemetry.php.
| Instrumentation | What it traces | Env variable |
|---|---|---|
| HTTP Server | Incoming HTTP requests via middleware | OTEL_INSTRUMENTATION_HTTP_SERVER |
| HTTP Client | Outgoing HTTP requests via Laravel’s Http facade | OTEL_INSTRUMENTATION_HTTP_CLIENT |
| Database | SQL queries via Laravel’s query listener | OTEL_INSTRUMENTATION_QUERY |
| Queue Jobs | Dispatched and executed queue jobs | OTEL_INSTRUMENTATION_QUEUE |
| Redis | Redis commands | OTEL_INSTRUMENTATION_REDIS |
| Cache | Cache hits, misses, and writes as span events | OTEL_INSTRUMENTATION_CACHE |
| Events | Laravel events as span events | OTEL_INSTRUMENTATION_EVENT |
| Views | Blade view rendering | OTEL_INSTRUMENTATION_VIEW |
| Livewire | Livewire component rendering | OTEL_INSTRUMENTATION_LIVEWIRE |
| Console Commands | Artisan commands (opt-in per command) | OTEL_INSTRUMENTATION_CONSOLE |
| Laravel Scout | Search, update, and delete operations | OTEL_INSTRUMENTATION_SCOUT |
Signals
Traces
Distributed traces are the primary signal. Every instrumented operation creates a span inside the active trace. Spans are exported via OTLP to any compatible backend — Jaeger, Grafana Tempo, Honeycomb, Datadog, and others. TheTracer facade lets you create custom spans and access the active trace ID.
Metrics
The package collects HTTP server and client request durations, database and Redis operation durations, and any custom metrics you define with theMeter facade. Metrics are exported via OTLP.
Logs
Anotlp log channel is automatically injected into Laravel’s logging system. When you log through this channel, log records are exported via OTLP with the active trace ID attached, correlating logs directly with traces.
Key features
Auto-instrumentation
Covers HTTP, database, queues, Redis, cache, events, views, Livewire, Scout, and console commands out of the box — no code changes required.
Manual tracing
Use the
Tracer facade and its fluent SpanBuilder API when you need custom spans for business-level operations.Tail sampling
Keep only meaningful traces. Built-in rules for errors and slow traces. Custom rules are supported via a simple interface.
Worker mode
Automatic detection and optimized flushing for long-running processes: Laravel Octane, Horizon, and queue workers.
User context
Automatically attaches the authenticated user ID to traces and logs. Customizable via a resolver callback.
Multiple exporters
OTLP over HTTP (protobuf or JSON) or gRPC, Zipkin, console output, or in-memory. Configure separate exporters per signal.
Requirements
- PHP 8.2 or higher
- Laravel 11, 12, or 13
- An OpenTelemetry Collector or compatible backend (Jaeger, Grafana Tempo, Honeycomb, Datadog, etc.)
Get started
Installation
Install the package and publish the config file.
Quickstart
Emit your first traces in under five minutes.
HTTP server instrumentation
Learn how incoming requests are automatically traced.
Tracer facade
Full API reference for manual tracing.