README

UptimeX Laravel Client

The official Laravel SDK for UptimeX — full-stack APM and uptime monitoring, self-hosted or cloud.

What it does

Drop this package into a Laravel app and UptimeX automatically captures eleven kinds of telemetry — without scattering instrumentation calls across your codebase. The SDK hooks into Laravel's framework events, batches the captured data, and ships it to your UptimeX server over a gzip-compressed HTTP transport that's tightly bounded so a slow ingest never slows your application.

Everything ties together via a trace id (UUIDv7) so a single request in the dashboard shows its queries, jobs, log lines, and outgoing HTTP calls in one timeline.

Why use it

• Zero-config defaults. composer require + two env vars and you're capturing telemetry. Auto-discovers the service provider; no code changes in your app.
• Built for production. Bounded buffers (drop-oldest on overflow), fail-closed timeouts (0.5 s default), exception swallowing in every listener — a bug in the SDK can never break your application.
• Privacy-first. PII redaction for log context and request payloads out of the box, with hooks for adding your own redactors per event type. No fixed allow-list of fields; you decide what's sensitive.
• Configurable sampling. Per-event-type sample-rate gates with the rate stored on the trace, so server-side aggregations can multiply by 1/rate to keep counts honest under sampling.
• Laravel Context propagation. Whatever your app puts in Illuminate\Support\Facades\Context (request id, tenant id, feature flags) ships with each trace.
• Deployment markers. php artisan uptimex:deploy <ref> posts a release marker; the dashboard correlates issues with deploys ("regressions since v2.5.0").
• Multi-version Laravel. Tested against Laravel 10 / 11 / 12 / 13 on PHP 8.2 / 8.3 / 8.4.

Install

composer require uptimex/laravel-client

Set two env vars in your monitored app's .env:

UPTIMEX_TOKEN=utx_your_environment_token
UPTIMEX_INGEST_URL=https://ingest.your-uptimex-server.com

Smoke-test the connection:

php artisan uptimex:test

Expected output:

Sending synthetic batch to https://ingest.your-uptimex-server.com ...
Batch accepted by UptimeX.
  trace_id: 019df4c8-d721-7067-8c88-10a84081b445

That's it. Telemetry now flows to UptimeX automatically as your app serves requests, processes jobs, and runs scheduled tasks. Browse the UptimeX dashboard a few seconds later and you'll see live data.

Configuration

The defaults work out of the box. To override anything, publish the config file:

php artisan vendor:publish --tag=uptimex-config

Public API

The Uptimex facade exposes the SDK's full surface:

use Uptimex\Client\Facades\Uptimex;

// Manually start a trace (CLI scripts, custom workers, etc.)
$ctx = Uptimex::startTrace('command', ['source' => 'cron-cleanup']);

// Record a custom event
Uptimex::record('request', ['route' => '/checkout', 'duration_ms' => 42]);

// Skip recording for a block
Uptimex::ignore(function () {
    // SDK silent inside this closure
});

// Or pause/resume manually
Uptimex::pause();
// … noisy section …
Uptimex::resume();

// End the trace and flush
Uptimex::endTrace('ok');

Most apps never need to call any of this — the lifecycle hooks handle HTTP requests, Artisan commands, and scheduled tasks automatically.

Sampling, filtering, redaction

Register callbacks in a service provider:

use Uptimex\Client\Uptimex;

public function boot(Uptimex $uptimex): void
{
    // Sample-rate gate: only ship 10% of cache events
    $uptimex->sampleRate('cache', 0.10);

    // Reject events matching a predicate
    $uptimex->reject('query', fn (array $event) =>
        str_contains($event['sql'] ?? '', 'pg_stat')
    );

    // Redact / transform an event before it ships
    $uptimex->redact('log', fn (array $event) => [
        ...$event,
        'context' => array_diff_key($event['context'] ?? [], ['password' => true]),
    ]);
}

Deployment markers

Add a single command at the end of your CI deploy step:

php artisan uptimex:deploy "$(git rev-parse HEAD)" \
    --name="v$(git describe --tags --abbrev=0)" \
    --url="https://github.com/your-org/your-app/commit/$(git rev-parse HEAD)"

UptimeX:

• Records the deploy as a vertical line on every dashboard chart.
• Auto-resolves any issues marked resolve on next deploy.
• Surfaces "issues introduced since this deploy" so you spot regressions before customers do.

Testing your integration

The package ships three test suites:

composer test                # default — Unit + Feature only, hermetic
composer test:integration    # only the real-wire suite
composer test:all            # everything

Integration tests are skipped automatically unless both env vars are set:

UPTIMEX_INTEGRATION_INGEST_URL=https://ingest.your-uptimex-server.com \
UPTIMEX_INTEGRATION_TOKEN=utx_your_real_token \
composer test:integration

Performance

The SDK is designed to add negligible overhead to a request:

• Lifecycle listeners record into an in-memory buffer; they never block on network I/O.
• The HTTP flush happens on terminate() (after the response is sent to the client) on a tightly-bounded transport (default 0.5 s timeout).
• A bug in any listener is wrapped in try { … } catch (\Throwable) {} so it can never throw into your request handler.
• Buffer overflow is "drop oldest" — old events are discarded silently rather than failing the trace.

In practice you'll see <2 ms added per request, dominated by the JSON encode + gzip on flush. Sub-millisecond if your trace has few events.

Requirements

• PHP 8.2+
• Laravel 10 / 11 / 12 / 13
• A reachable UptimeX server (self-hosted or cloud)

License

MIT © Purpose Company

Built by Purpose Company

A Palestinian software development company based in the West Bank.
We build observability and developer tools used by teams across the region and beyond.

UptimeX · GitHub Org · Issues