Weave Code
Laravel Telemetry Laravel Package
cboxdk/laravel-telemetry
Collector-free telemetry for Laravel: Prometheus metrics aggregated in Redis or APCu, plus OTLP traces, logs and events over plain HTTP JSON. Works under FPM, auto-instruments requests, queue jobs, DB queries and commands.
cboxdk/laravel-telemetry brings collector-free observability to Laravel. Because PHP is shared-nothing, in-process metric state dies with each request—so this package aggregates metrics in Redis (or APCu) instead, letting web workers, queue workers, and nodes all write to the same series. Prometheus scrapes a route, while traces and events go straight to any OTLP backend as spec-stable HTTP JSON—no C extension, protobuf, or sidecar required.
- Prometheus metrics — counters, gauges, histograms with a secured scrape endpoint
- Real OTLP —
/v1/traces,/v1/metrics,/v1/logswithout the SDK - Auto-instrumentation — requests, queue jobs, DB queries, commands, plus W3C trace propagation
- Trace-correlated logs — a
telemetrylog channel with severity mapping - Framework detection — Horizon, Reverb, and Pennant support out of the box
Frequently asked questions about Laravel Telemetry
- How do I install cboxdk/laravel-telemetry in a Laravel application?
- Add it with composer require cboxdk/laravel-telemetry and publish its config file, then choose a shared MetricStore (Redis or APCu) and, if you want traces, an OTLP endpoint. It is a pure Composer package with no C extension, protobuf or sidecar to install, so it deploys anywhere Laravel runs. Every advanced feature, including AI cost tracking, span keep rules and usage events, stays inert until you configure it, so a bare install changes nothing.
- Why does this package need Redis or APCu instead of keeping metrics in memory?
- PHP is shared-nothing, so an in-process metric registry dies with the request and cannot aggregate across FPM workers. This package writes into a shared MetricStore contract backed by Redis or APCu, so web workers, queue workers and multiple nodes all increment the same series. Indexes are maintained explicitly, with no KEYS or SCAN calls, so lookups stay cheap on the hot path.
- Which Laravel and PHP versions does laravel-telemetry support?
- It ships as a normal Laravel package with an auto-discovered service provider, so it installs like any other Composer dependency. Check the illuminate/support and PHP constraints in composer.json on Packagist for the exact supported range rather than assuming your version is covered. Pinning to the current release and running your test suite against your Laravel version is the safest check.
- Do I need an OpenTelemetry collector, protobuf or a C extension for this package?
- No. Traces, metrics and logs are sent to any OTLP backend as spec-stable HTTP JSON on /v1/traces, /v1/metrics and /v1/logs, so there is no collector, no protobuf library and no PHP extension. Prometheus metrics are exposed through a scrape route rather than pushed. That is the main reason it works under FPM where the official SDK needs extra infrastructure.
- How do I secure the Prometheus metrics endpoint in production?
- The scrape route is closed by default outside the local and testing environments, following the same convention as Horizon and Telescope. You open it with either an IP allowlist or a bearer token, and you can apply metric filters so only the series you want are exposed. Keep the route behind your network controls as well, since a publicly reachable metrics endpoint leaks operational detail.
- What does laravel-telemetry auto-instrument out of the box?
- It hooks Laravel's lifecycle to trace requests, queue jobs, DB queries and console commands, including full W3C trace propagation into queue workers. Http::withTraceparent() adds trace context to outbound HTTP calls. When Horizon, Reverb or Pennant are installed it detects them automatically and adds supervisor state and long-wait detection, WebSocket message and channel metrics, and feature flag metrics.
- Can I send traces and logs to any OTLP-compatible backend?
- Yes, any backend that accepts OTLP over HTTP JSON works, because the payloads follow the spec rather than a vendor format. The telemetry log channel turns Laravel log entries into trace-correlated OTLP log records with mapped severity levels, and it is built to avoid feedback loops. Your existing trace IDs then line up across spans, events and logs in the backend you already use.
- How does the AI and LLM cost tracking work in laravel-telemetry?
- You supply a price table under instrument.ai_pricing.models keyed by model glob, such as anthropic/claude-sonnet-*, with per-million input, output, cache read and cache write rates. The package then derives gen_ai.usage.cost on the span and increments a gen_ai.client.cost counter labelled the same way as the token metric, with the currency taken from TELEMETRY_AI_CURRENCY (default USD). No price list ships with the package, so an unpriced model silently produces no cost rather than a wrong one. Usage events are off by default and record tokens, cost, user and context dimensions but never prompt or response content. The laravel/ai integration is opt-in, so confirm in composer.json that it is a suggested rather than required dependency if your service never calls an LLM.
- How do I control span volume and keep the detail spans I care about?
- The traces.details.keep_when and traces.details.keep_spans settings give you a declarative keep policy over attributes and span-name patterns, so you can retain, for example, spans where db.query.text matches insert * or update *. Everything not matched is trimmed according to your detail settings. Be aware these rules are evaluated per span on the request hot path, so broad patterns over high-volume spans such as DB queries add measurable CPU cost.
- Is laravel-telemetry production-ready, and how does it compare to the official OpenTelemetry SDK?
- It is a small, single-maintainer package with modest download and dependent counts, so weigh bus factor alongside the self-attested quality gates: PHPStan level 9, Pest suites with Redis, APCu and benchmark groups, ADRs and a changelog. The project has shipped repeated minor releases with opt-in defaults and no stated breaking changes, which is a reasonable maturity signal but not the same as wide production evidence. Compared with the official OpenTelemetry SDK, the trade-off is fewer moving parts and working FPM metrics versus a much larger ecosystem and support base. Test the scrape route and any AI pricing table in staging before relying on them for billing or alerting.
Weaver
How can I help you explore Laravel packages today?