Configuration reference

Publish with php artisan vendor:publish --tag=telemetry-config.

Env-var convention: every variable is prefixed TELEMETRY_ and mirrors its config path (otlp.spool.key → TELEMETRY_OTLP_SPOOL_KEY). The package additionally honors the OpenTelemetry-standard variables (OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES) as fallbacks for interop — TELEMETRY_* wins when both are set.

Master switch

Disabled: no-op instruments, no listeners, no routes, no providers.

Service resource

Attached to every exported signal (OTel resource conventions).

Container / Kubernetes / cloud detection

With resource_detection on, every signal carries where it ran:

• From cgroups (via cboxdk/system-metrics): container.id, container.runtime.
• From env vars (the common downward-API injections): k8s.pod.name (K8S_POD_NAME/POD_NAME, or the pod's HOSTNAME), k8s.namespace.name, k8s.node.name, cloud.region (AWS_REGION/GOOGLE_CLOUD_REGION/…), and more.
• From OTEL_RESOURCE_ATTRIBUTES — the OpenTelemetry standard (key1=val1,key2=val2, percent-decoded). Operator-explicit, overrides the env-var conventions. This is the cleanest way to inject arbitrary attributes; k8s operators set it automatically.
• From AWS Lambda's own runtime env vars (Vapor included — it deploys on Bref's PHP-FPM Lambda layer, so the same vars are always present): cloud.provider=aws, cloud.platform=aws_lambda, faas.name/.version/.instance/.max_memory, and a per-invocation faas.coldstart (true only on the first request served by a given execution environment — the PHP-FPM worker is reused across warm invocations, so this is re-evaluated on every call, unlike the rest of the detected resource which is memoized for the process). Vapor itself is flagged with vapor.detected (from VAPOR_SSM_PATH) — there's no standardized OTel value for "which PaaS wraps this Lambda".

Precedence: the package's own service.* config is authoritative; OTEL_RESOURCE_ATTRIBUTES beats the env-var conventions; both fill in around the config. Filter any of these in Tempo: { resource.k8s.namespace.name = "production" }, { resource.faas.name = "my-app-production-http" }.

Self-observability metrics

With self_metrics on, the package reports on itself (bounded labels):

The bundled System dashboard renders these under a "Telemetry health" row — alert on a sustained open circuit or a climbing spool.

Metric store

Exporters

Valid entries: otlp, null, or a fully-qualified class name implementing Cbox\Telemetry\Contracts\Exporter (resolved from the container).

OTLP

| otlp.spool.enabled | TELEMETRY_OTLP_SPOOL | false — spans/events go to a Redis list instead of POSTing at terminate; telemetry:flush (cron or --daemon) ships merged batches | | otlp.spool.connection | TELEMETRY_OTLP_SPOOL_CONNECTION | default | | otlp.spool.key | TELEMETRY_OTLP_SPOOL_KEY | telemetry:spool | | otlp.spool.max_items | TELEMETRY_OTLP_SPOOL_MAX_ITEMS | 20000 (drop-oldest above) |

Daemon mode for high traffic: telemetry:flush --daemon --interval=1 --metrics-interval=15 --max-batch=200 (one process under supervisor; graceful SIGTERM drain).

After a retryable transport failure (429/5xx, network), an in-process circuit breaker skips exports for 30 s (or the server's Retry-After).

Prometheus

AllowIps (the default endpoint middleware) is closed outside local/testing unless allowed_ips or token is set — the same convention as Horizon/Telescope/Pulse.

Multiple named endpoints are supported — e.g. an internal endpoint with everything and a public endpoint filtered to a prefix list:

'endpoints' => [
    'internal' => ['path' => 'internal/metrics', 'middleware' => [AllowIps::class]],
    'public' => ['path' => 'metrics', 'middleware' => ['auth:metrics'], 'only' => ['http', 'queue']],
],

Exemplars

Every histogram observation made inside a sampled trace carries that trace's id as an exemplar — click a slow bucket in Grafana, land on the actual trace that landed in it. No config toggle: it follows traces.sample_rate automatically, and costs nothing when a trace isn't sampled (the exemplar is simply omitted).

Exemplars have no grammar in the classic Prometheus text format (text/plain; version=0.0.4), so they only render when the scraper negotiates OpenMetrics via its Accept header — content negotiation, not a setting. Prometheus does this itself when --enable-feature=exemplar-storage is set; scraping with curl always gets the classic format unless you pass -H 'Accept: application/openmetrics-text'.

Traces

Redaction engine

Applied to span attributes, span events, telemetry events AND log records (message + context) at flush. Custom last-pass hook: Telemetry::redactUsing(fn ($key, $value) => ...) — log messages arrive with the key log.message.

Events

Histograms

Analytics (optional)

An additive layer on top of the telemetry already collected — a shared session.id across browser + server so a whole visit, not just one trace, can be analysed. Off by default; changes nothing when disabled. See Analytics.

Browser span ingest (optional)

Add @telemetryBrowser to your layout for turnkey RUM (or @telemetryTraceparent + your own script). See Browser tracing.

Source map upload (optional)

A POST endpoint the build pipeline uploads source maps to (via the @cboxdk/telemetry-browser uploader / Vite plugin), keyed by release, so minified browser stacks can be symbolicated back to original source. Uploads come from CI — which can hold a secret — so unlike the browser span ingest this endpoint is bearer-token gated: without a configured token every upload is rejected (403), so it is never accidentally open. Only valid v3 source maps within the size limit are stored. See Browser tracing.

Automatic instrumentation

Host & process monitor

telemetry:monitor --once from the scheduler (cron mode) or without --once under supervisor (daemon mode). Queue workers additionally self-report worker.memory.{php,rss}{queue,pid} (By) after every job — no monitor required for worker leak tracking.

Profiling (ext-excimer)

Requires the PECL excimer extension (pecl install excimer or your distro's php-excimer package) — a statistical sampling profiler, not bundled, extension_loaded()-guarded everywhere. Without it, instrument.profiling is a silent no-op; telemetry:doctor reports whether it's active. Profiling always runs on a sampled trace (excimer's own sampling keeps the overhead low), but the result — a bounded "top functions by sample count" profile.captured event — is only kept for requests/jobs slower than min_duration_ms. This is not a full pprof export; the package has no opinion on a profiling backend.

Built-in providers

The system provider only activates when cboxdk/system-metrics is installed.