Download the PHP package konzume/splunk-observability-sdk without Composer

Splunk Observability SDK for Laravel

A production-grade, fully asynchronous observability SDK for Laravel 13. Captures HTTP requests, database queries, exceptions, queue jobs and custom application events, batches them in-memory, and ships them to Splunk's HTTP Event Collector (HEC) from a queue worker — never on the request thread.

Designed to be a drop-in alternative to Sentry Performance / Datadog APM / New Relic / Bugsnag for teams that already operate Splunk.

Why an async pipeline

Telemetry SDKs that synchronously call out to a SaaS during a request can spike p99 latency by hundreds of milliseconds whenever the SaaS slows down or drops a packet. This package guarantees zero impact on response time by:

1. Collecting every signal in an in-memory request-scoped context.
2. Running the heavy serialization + queue dispatch in Laravel's terminate() phase — i.e. after the response has been sent to the client.
3. Doing all Splunk HTTP I/O on a separate queue worker, with retries and exponential backoff handled by Laravel's queue layer.

Features

• HTTP request lifecycle: method, URL, route, headers, payload, response status/headers/body, IP, user agent, tenant id, authenticated user, duration, memory.
• Database queries via Laravel's QueryExecuted event: SQL, optional bindings, execution time, connection, slow-query detection.
• Exceptions: stack traces, exception metadata, request + query context.
• Queue jobs: per-job lifecycle, attempts, duration, failures.
• Application logs: a splunk log channel that correlates every line to the request's trace_id.
• Outbound HTTP: every call made through Laravel's HTTP client (method, URL, status, duration, sizes).
• Mail: every email sent (subject, recipients, mailer, attachment count).
• Custom events: Splunk::event(), Splunk::metric(), Splunk::trace().
• Sampling (head-based, deterministic on trace id).
• Sanitization of passwords, tokens, authorization headers, card data.
• Configurable payload truncation, query caps, batch sizes.
• Splunk HEC client with gzip compression, batching, retry classification.
• Pluggable exporter — Splunk HEC today, swap in Datadog, Elastic, Loki, OpenTelemetry or Kafka tomorrow.
• Redis-backed queue with dedicated queue name so observability traffic is isolated from app workloads.

Installation

The package auto-discovers — no manual provider registration needed.

Publish the config:

This creates config/splunk-observability.php.

Register the middleware (required, Laravel 11+)

The SDK ships a single global middleware that owns the request lifecycle. You must register it in bootstrap/app.php — auto-discovery alone is not enough on the Laravel 11+ skeleton, and the middleware should run first so it wraps every other middleware (including auth, CORS, and exception handling). Use prepend:

Why prepend and not append?

• prepend puts the middleware first in the global stack — its handle() runs before every other middleware, so the captured duration spans the entire request (auth, body parsing, route dispatch, the controller, everything).
• append would only measure from the SDK middleware onwards and miss most of the request.

This mirrors how Sentry's tracing, Datadog APM and New Relic install their request span — first in, last out.

Environment variables

Minimum config:

For local dev, set SPLUNK_OBS_EXPORTER=null to discard everything.

Architecture

Usage

Custom events:

Setting the tenant / user context manually if you don't use auth:

Correlated logs (the splunk channel)

The SDK auto-registers a splunk log channel. Anything you write to it is buffered into the current request and shipped — correlated by trace_id — alongside the request, its queries, HTTP calls and mail. Search one trace_id in Splunk and you see the whole story.

To mirror every application log into Splunk, add splunk to your stack in config/logging.php:

Log context arrays are run through the same sanitizer as request payloads (so password, token, etc. are redacted). Levels below SPLUNK_OBS_LOG_LEVEL (default debug) are dropped.

Logs are buffered and flushed at the end of the request. A hard fatal (OOM, segfault) before terminate() loses the buffer — for guaranteed delivery of a critical line, also write it to a durable channel (file/stderr) via a stack.

Outbound HTTP capture

Every call made with Laravel's HTTP client is captured automatically — no code changes:

URLs are always sanitized (userinfo stripped, sensitive query params filtered). Headers and bodies are off by default — enable with SPLUNK_OBS_HTTP_CAPTURE_HEADERS=true / SPLUNK_OBS_HTTP_CAPTURE_BODIES=true only on trusted indexes. The SDK's own export to Splunk uses Guzzle directly, so it is never captured (no recursion).

Mail capture

Every email the app sends is captured (subject, recipients, mailer, attachment count — never the body):

Performance impact

The middleware's handle() phase only resets the context and reads request headers — measured at <0.5ms on a small Laravel API. All heavy work (sanitization, JSON serialization, queue push) happens in terminate(), after the client has the response. There is no synchronous HTTP I/O on the request thread.

Sampling

Sampling is deterministic on the trace id, so a trace that gets sampled in at the request level keeps all its child events.

Documentation

• Installation
• Configuration
• Kubernetes deployment
• Redis queue setup
• Horizon setup
• Splunk dashboards
• Splunk alerts

Testing

Suite layout:

• tests/Unit/ — sampler, sanitizer, truncator, context, HEC client framing
• tests/Feature/ — middleware lifecycle, custom events, query collection
• tests/Integration/ — Splunk downtime, retry classification
• tests/Queue/ — export job retry semantics
• tests/Performance/ — throughput smoke tests

Extending — custom exporter

Implement src/Contracts/Exporter.php and bind it:

The export pipeline is exporter-agnostic — no other code changes are needed.