Upgrade notes
Laravel 12.45 or later is required (illuminate/* ^12.45 || ^13.0). It is the first version with the CommandFailed Redis event. Composer already blocks earlier 12.x releases because of security advisories. Apps on older versions stay on 2.3.x.
Published config files need new keys. The config is merged one level deep, so a published exporters, logs or worker_mode array replaces the package one, and keys added in this release are missing. Without them the related environment variables are ignored and the defaults below apply:
| Key | Add | Without it |
|---|---|---|
exporters.otlp.connect_timeout
| (int) env('OTEL_EXPORTER_OTLP_CONNECT_TIMEOUT', 1000)
| OTEL_EXPORTER_OTLP_CONNECT_TIMEOUT is ignored, 1000 ms
|
exporters.otlp.failure_cooldown
| (int) env('OTEL_EXPORTER_OTLP_FAILURE_COOLDOWN', 30)
| OTEL_EXPORTER_OTLP_FAILURE_COOLDOWN is ignored, the cooldown is on for 30s
|
exporters.otlp.max_retries
| change the default from 3 to 1
| the published default stays 3 |
logs.level
| env('LOG_LEVEL', 'debug')
| the otlp channel keeps exporting debug and above
|
worker_mode.flush_interval
| (int) env('OTEL_WORKER_MODE_FLUSH_INTERVAL', env('OTEL_WORKER_MODE_COLLECT_INTERVAL', 60))
| metrics_collect_interval and OTEL_WORKER_MODE_COLLECT_INTERVAL are still read
|
instrumentation
| Instrumentation\ReverbInstrumentation::class => env('OTEL_INSTRUMENTATION_REVERB', true)
| no Reverb metrics |
worker_mode.detectors
| WorkerMode\Detectors\ReverbWorkerModeDetector::class
| reverb:start exports only at shutdown
|
Failed exports are much cheaper. Exports are synchronous, and every PHP process also exports at shutdown, short Artisan commands included. Before, an unreachable collector could block each export for 10s × 4 attempts.
- Over HTTP, a new connect timeout (
OTEL_EXPORTER_OTLP_CONNECT_TIMEOUT, default 1000 ms, needs Guzzle) makes an unreachable host fail fast. - Retries default to 1 instead of 3.
- gRPC exports now honour
OTEL_EXPORTER_OTLP_TIMEOUT. - After an export fails (unreachable collector, timeout or 5xx), every export to that collector is dropped for 30 seconds (
OTEL_EXPORTER_OTLP_FAILURE_COOLDOWN,0disables it). The pause is shared by every process of the application through a file instorage/framework/cache. When it expires, a single process tries again. Telemetry is lost for up to one cooldown, but under PHP-FPM or FrankenPHP requests no longer pay a failed export each. In a load test with the collector down, web throughput went from 13–32 req/s back to about 90–105 req/s.
See the new "Export Failures" section of the README. For a collector in the same host or cluster, consider OTEL_EXPORTER_OTLP_CONNECT_TIMEOUT=250 and OTEL_EXPORTER_OTLP_TIMEOUT=2000.
Worker mode flushes every signal. The periodic interval used to collect only metrics. It now also exports pending spans and log records. The interval is renamed to flush_interval / OTEL_WORKER_MODE_FLUSH_INTERVAL, and the old names still work.
Logs
- Data added with Laravel's
Contextfacade is exported as log record attributes. Hidden context is not exported. - The injected
otlpchannel followsLOG_LEVEL(opentelemetry.logs.level) instead of alwaysdebug.
Emitted telemetry changes. Update dashboards, alerts and queries that rely on the old names or values:
| Signal | Before | After |
|---|---|---|
http.server.request.duration
| server.address, server.port labels
| removed |
| HTTP server spans and metric | error.type on 3xx/4xx
| only on 5xx |
| HTTP server and client | unknown methods kept as sent | _OTHER (span name HTTP), original in http.request.method_original on spans
|
| HTTP server spans | handled report($e) set status Error
| status unchanged |
| HTTP server spans, 404 without route | http.route = "/"
| no http.route
|
| HTTP client spans | 4xx not an error | 4xx sets status Error |
| HTTP server spans | server.address could include the port
| host only |
| HTTP client spans and metric | no server.port when the URL has no port
| server.port 80 / 443
|
| All spans | status Ok set explicitly
| status left Unset
|
| DB spans | name SELECT
| name includes the database, e.g. SELECT app
|
db.client.operation.duration
| db.query.text label
| removed |
| DB spans | server.port as string
| integer, omitted for the DBMS default port |
| Redis spans | keys and values in db.query.text
| replaced by ?
|
| Redis | failed commands not recorded | span with error.type, no metric data point
|
| Redis spans and metric | no server.port
| server.port when not 6379
|
| Scout spans and metric | no error.type
| error.type on failure
|
| Scout spans without target | "<op> "
| "<op>"
|
user.id
| integer | string |
QUERY is now a known HTTP method.
New: Laravel Reverb. reverb:start exports periodically from its event loop and records laravel.reverb.messages and laravel.reverb.active_connections (Reverb 1.14+). Exports block the event loop, so keep the collector close and the timeouts low.
Metrics temporality. OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE is now case-insensitive. Unknown values fall back to cumulative.
What's Changed
- Fix CI with latest OpenTelemetry SDK and Zipkin deprecation by @cappuc in #110
- Accept metrics temporality preference in any case by @cappuc in #111
- Document metrics limitations in per-request runtimes by @cappuc in #106
- Drop db.query.text from DB metrics and sanitize Redis query text by @cappuc in #109
- Fix HTTP server error.type, metric attributes and unknown methods by @cappuc in #107
- Align span names and status with semantic conventions by @cappuc in #108
- fix(logs): forward Monolog extra (Laravel Context) to OTLP log records by @andrewbroberg in #117
- fix(logs): respect LOG_LEVEL on the injected otlp channel by @andrewbroberg in #118
- Flush all signals on the worker mode interval by @cappuc in #112
- Speed up the test suite by avoiding exports of span graphs in negated assertions by @cappuc in #119
- Normalize unknown HTTP methods on the client and add QUERY by @cappuc in #113
- Fix semantic convention correctness issues by @cappuc in #114
- Record failed Redis commands, add error.type and server.port, require Laravel 12.45 by @cappuc in #116
- Add Laravel Reverb support by @cappuc in #115
- Make failed OTLP exports cheap: connect timeout, gRPC timeout and one retry by default by @cappuc in #120
- Drop OTLP exports for a cooldown after a failed export by @cappuc in #121
Full Changelog: 2.3.0...2.4.0