README

Collector-free telemetry for Laravel: Prometheus metrics, OTLP traces and events. No C extension, no protobuf, no sidecar — metrics that actually work under FPM.

Telemetry::counter('orders.created')->inc();
Telemetry::gauge('queue.depth', fn () => Queue::size());
Telemetry::histogram('checkout.duration', unit: 'ms')->record($ms);

Telemetry::span('import.customers', function () {
    // traced work — exceptions recorded, duration measured
});

Telemetry::event('autoscale.decision', ['workers' => 7]);

Why

PHP is shared-nothing: in-process metric state dies with the request, which is why the official OTel SDK's metrics don't work under FPM without a collector. This package aggregates metrics in Redis (or APCu) instead — web workers, queue workers and nodes all write to the same series. Prometheus scrapes a route; traces and events go straight to any OTLP backend as spec-stable HTTP JSON.

• ✅ Pure Composer package — deploys anywhere Laravel runs
• ✅ Prometheus scrape endpoint(s) with IP allowlisting and metric filters
• ✅ Real OTLP (/v1/traces, /v1/metrics, /v1/logs) without the SDK
• ✅ telemetry log channel: Laravel logs become trace-correlated OTLP log records (severity-mapped, feedback-loop safe)
• ✅ Auto-instrumentation: requests, queue jobs (full W3C trace propagation into workers), DB queries, commands — plus Http::withTraceparent() for outbound calls
• ✅ Telemetry::fake() with assertions for counters, gauges, histograms, spans and events
• ✅ Provider contract so packages publish telemetry without coupling
• ✅ Host CPU/memory/load via cboxdk/system-metrics — just install it
• ✅ Zero cost when disabled; telemetry never throws into your app
• ✅ Resource attribution: peak memory + CPU per request/job/task, per-span CPU & memory deltas, real RSS via cboxdk/system-metrics
• ✅ Ships four Grafana dashboards (telemetry:dashboards) — overview, requests, queue & schedule, drill-down — service-scoped, LGTM-ready
• ✅ AI-ready: ships Laravel Boost guidelines, llms.txt and an agent guide — your AI assistant follows the conventions out of the box

Installation

composer require cboxdk/laravel-telemetry

TELEMETRY_STORE=redis            # redis | apcu | array
TELEMETRY_EXPORTERS=otlp         # optional; Prometheus endpoint is on by default
OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.example.com:4318

Scrape GET /telemetry/metrics, and for OTLP metrics schedule the flush:

Schedule::command('telemetry:flush')->everyMinute()->onOneServer();

Documentation

Full documentation lives in docs/:

• Getting started — quickstart, testing, API reference, AI assistants
• Core concepts — metrics, traces, events, logs, naming
• Cookbook — multi-tenant SaaS, queue monitoring, external services
• Configuration reference
• Extension points — custom exporters
• Production — OTLP, the recommended Grafana stack, performance, security

Design decisions (and the prior-art survey behind them) are recorded in docs/adr/.

Publishing telemetry from your package

if (class_exists(\Cbox\Telemetry\Facades\Telemetry::class)) {
    Telemetry::provider(new QueueMetricsProvider);
}

Telemetry never knows about your package — your package publishes telemetry if telemetry exists. See providers.

Development

composer check   # pint --test, phpstan (level 8), pest

License

MIT. See LICENSE.md.