PHPackages uptimex/laravel-client - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Logging & Monitoring](/categories/logging) 4. / 5. uptimex/laravel-client ActiveLibrary[Logging & Monitoring](/categories/logging) uptimex/laravel-client ====================== Laravel SDK that sends application telemetry (requests, queries, exceptions, jobs, logs, …) to UptimeX. v0.2.2(3w ago)0116MITPHPPHP ^8.2CI passing Since May 20Pushed 2w agoCompare [ Source](https://github.com/Purposeeco/uptimex-laravel-client-compser)[ Packagist](https://packagist.org/packages/uptimex/laravel-client)[ Docs](https://github.com/Purposeeco/uptimex-laravel-client-compser)[ RSS](/packages/uptimex-laravel-client/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (8)Versions (2)Used By (0) UptimeX Laravel Client ====================== [](#uptimex-laravel-client) **The official Laravel SDK for [UptimeX](https://uptimex.tech) — full-stack application performance monitoring.** [![Tests](https://camo.githubusercontent.com/f140b745c672fde8ec374188ed1e7d6e26dc30c8897e96263b663f66e33264b7/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f507572706f736565636f2f757074696d65782d6c61726176656c2d636c69656e742d636f6d707365722f74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/Purposeeco/uptimex-laravel-client-compser/actions)[![Latest Version](https://camo.githubusercontent.com/1536ec75fffc7064e22d1452fdc0d12ff114614c93bb0d97b9ad69582a45370c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f757074696d65782f6c61726176656c2d636c69656e742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/uptimex/laravel-client)[![PHP Version](https://camo.githubusercontent.com/71bad1b3aeb65923334cb8b85160ad625fe55d675aacef09d447ad4c905b76dd/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f757074696d65782f6c61726176656c2d636c69656e742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/uptimex/laravel-client)[![License: MIT](https://camo.githubusercontent.com/a7e65aee57b11d28e4caff8b945729a66be0bb663f7f93bd24c5aa65699f148e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d626c75652e7376673f7374796c653d666c61742d737175617265)](LICENSE) --- What it does ------------ [](#what-it-does) Add the package to a Laravel app, set one token, and UptimeX captures **eleven kinds of telemetry** automatically — with no instrumentation calls scattered through your code. The SDK hooks into Laravel's framework events, buffers what it captures in memory, and hands it to the local `uptimex:agent` daemon once the response has reached the user — so monitoring never slows a request. CapturedWhat lands in UptimeX**HTTP requests**route, method, status, response time, headers, payload (redacted)**Database queries**normalized SQL, connection, duration, slow-query detection**Exceptions**class, message, file, line, stack trace, fingerprint, occurrence groups**Background jobs**class, queue, attempts, status (queued → processing → processed / released / failed), duration**Cache events**hit / miss / write / delete / fail by key + store, hit-rate analytics**Log lines**full PSR-3 (debug → emergency), channel, message, context (redacted)**Outgoing mail**mailer, recipients, subject**Notifications**class, channel, notifiable**Artisan commands**name, arguments, exit code, duration**Scheduled tasks**expression, description, run duration, success / failure**Outgoing HTTP**URL, method, status and duration of every request your app makesEvery event carries a **trace id** (UUIDv7), so a single request in the dashboard shows its queries, jobs, log lines, and outgoing calls on one timeline. Why use it ---------- [](#why-use-it) - **Drop-in.** `composer require`, set your ingest token — done. The service provider auto-registers; no code changes in your app. - **Safe by construction.** Every listener is exception-wrapped, the request only writes to a local socket (never the network), buffers drop oldest on overflow, and with no agent running the SDK goes silently inert — a bug or an outage can never break *or* flood your application. - **Privacy-first.** Request payloads, headers, and log context are redacted against sensible defaults you can extend per event type. - **Volume control.** Per-event-type sampling and whole-category ignore switches keep telemetry — and your bill — proportionate. - **Agent-based delivery.** A local `uptimex:agent` daemon ships your telemetry out of band — the request only writes to a loopback socket, never the network. - **Multi-version.** Tested against Laravel 10 / 11 / 12 / 13 on PHP 8.2 / 8.3 / 8.4. Requirements ------------ [](#requirements) - PHP **8.2+** - Laravel **10, 11, 12, or 13** - An UptimeX workspace and an environment ingest token Installation ------------ [](#installation) ``` composer require uptimex/laravel-client ``` Set your environment's ingest token in `.env`: ``` UPTIMEX_TOKEN=utx_your_environment_token ``` Verify the connection: ``` php artisan uptimex:test ``` ``` Sending synthetic batch to https://ingest.uptimex.tech ... Batch accepted by UptimeX. trace_id: 019df4c8-d721-7067-8c88-10a84081b445 ``` Then run the agent — the daemon that delivers your telemetry — and leave it running: ``` php artisan uptimex:agent ``` That is the whole setup. With the agent running, telemetry flows automatically as your app serves requests, runs jobs, and executes scheduled tasks — visible in the UptimeX dashboard within seconds. In production the agent runs as a supervised daemon; see [Deploying to production](#deploying-to-production). Configuration ------------- [](#configuration) The defaults work out of the box. To change anything, publish the config file: ``` php artisan vendor:publish --tag=uptimex-config ``` Env varDefaultPurpose`UPTIMEX_ENABLED``true`Master switch — `false` makes the SDK a complete no-op`UPTIMEX_TOKEN`—Environment-scoped ingest token from the UptimeX dashboard`UPTIMEX_DEPLOY`—Release identifier, usually set by `uptimex:deploy``UPTIMEX_SERVER`hostnameServer label shown in the dashboard`UPTIMEX_AGENT_ADDRESS``127.0.0.1:9237`Address the `uptimex:agent` daemon listens on (`host:port` or `unix:///path.sock`)`UPTIMEX_LOG_LEVEL``debug`Minimum PSR-3 level the `uptimex` log channel capturesPrivacy, sampling, and filtering have their own env vars — see [Sampling, filtering & redaction](#sampling-filtering--redaction). Performance internals — network timeouts, buffer sizes, the agent's in-memory queue — are deliberately **not** environment variables. UptimeX manages those values so a stray setting can never degrade your app. The ingest URL is likewise **not** an env var — it ships hardcoded in the package (`https://ingest.uptimex.tech`). The host is the same for every workspace; your token, not the URL, routes data to yours. Hardcoding it also means a stray `http://` can never leak telemetry in plaintext. Delivery — the agent -------------------- [](#delivery--the-agent) Telemetry is delivered by one channel: the **`uptimex:agent`** daemon. During a request the SDK records events into an in-memory buffer; when the request ends it writes the finished batch to the agent over a local loopback socket — a microsecond-scale write, no network on the request path. The daemon ships batches to UptimeX out of band, buffering in memory and retrying through outages, and drains gracefully on `SIGTERM`so a deploy restart loses nothing. Run the agent locally while you develop: ``` php artisan uptimex:agent ``` In production it runs as a supervised daemon — see [Deploying to production](#deploying-to-production). **With no agent running, the SDK is inert.** It detects the absence — a cached health check, re-probed every ~30 s — starts no trace, buffers nothing, and writes no log line: it behaves exactly as if `UPTIMEX_ENABLED=false`. The moment the agent is back, capture resumes on its own. So a forgotten or crashed agent costs a gap in telemetry, never an error or a slowdown. Check the agent's reachability any time with `php artisan uptimex:status`. Deploying to production ----------------------- [](#deploying-to-production) The `uptimex:agent` daemon must run as a supervised, long-lived process — exactly as you would run Horizon or a queue worker. Keep `php artisan uptimex:agent` alive; running the command by hand is not enough, it must survive reboots and crashes. `php artisan uptimex:install` generates the supervision config for you: - **Laravel Forge** — add it under Server → Daemons → New Daemon, using the command, directory, and user the installer prints. Forge keeps it alive. - **Plain VPS** — copy the generated Supervisor program (or `systemd`unit) into place and enable it. - **Docker** — run `php artisan uptimex:agent` as its own service. Serverless runtimes (Vapor / Lambda) cannot host a persistent daemon, so the SDK is inert there — no errors, just no telemetry. Capturing logs -------------- [](#capturing-logs) The SDK registers a `uptimex` log channel **automatically** — no `config/logging.php` edit needed. To capture your application's logs as telemetry, add `uptimex` to your log stack in `.env`: ``` LOG_CHANNEL=stack LOG_STACK=single,uptimex ``` Every `Log::info()`, `Log::error()`, etc. written during a traced request, command, or job now ships to UptimeX as a `log` event on that trace — channel, level, message, and context included (with PII redaction). Logs fired outside a trace are skipped by design. Tune the minimum level captured with `UPTIMEX_LOG_LEVEL` (default `debug`): ``` UPTIMEX_LOG_LEVEL=warning ``` Already have a `uptimex` channel defined in `config/logging.php`? The SDK detects it and leaves yours untouched. Sampling, filtering & redaction ----------------------------------- [](#sampling-filtering--redaction) ### Sampling [](#sampling) Control telemetry volume per event-root type. The decision is made once at trace start, and child events inherit it: Env varDefault`UPTIMEX_REQUEST_SAMPLE_RATE``1.0``UPTIMEX_COMMAND_SAMPLE_RATE``1.0``UPTIMEX_SCHEDULED_TASK_SAMPLE_RATE``1.0``UPTIMEX_EXCEPTION_SAMPLE_RATE``1.0`High-traffic apps usually lower `UPTIMEX_REQUEST_SAMPLE_RATE` (e.g. `0.1`); keep exception sampling at `1.0` unless you are sure. Server-side aggregations multiply by `1/rate`, so dashboard counts stay true to real volume. To force-capture a specific request at runtime: ``` use Uptimex\Client\Facades\Uptimex; Uptimex::sample(1.0); // capture this whole trace regardless of the rate ``` ### Ignoring whole categories [](#ignoring-whole-categories) Set any of these to `true` to drop an event type entirely — no buffer entry, no network call: `UPTIMEX_IGNORE_QUERIES` · `UPTIMEX_IGNORE_CACHE_EVENTS` · `UPTIMEX_IGNORE_MAIL` · `UPTIMEX_IGNORE_NOTIFICATIONS` · `UPTIMEX_IGNORE_OUTGOING_REQUESTS` ### Filtering individual events [](#filtering-individual-events) Register predicates in a service provider's `boot()` — return `true` to drop the event: ``` use Uptimex\Client\Facades\Uptimex; public function boot(): void { Uptimex::rejectQueries(fn (array $q) => str_contains($q['sql_normalized'] ?? '', 'telescope_') ); Uptimex::rejectCacheKeys(fn (array $c) => str_starts_with($c['key'] ?? '', 'framework/') ); } ``` Also available: `rejectQueuedJobs`, `rejectMail`, `rejectNotifications`, `rejectOutgoingRequests`, and the generic `reject(string $type, Closure)`. ### Redaction [](#redaction) Header names, request-payload fields, and log-context keys are redacted against built-in defaults. Override them with comma-separated env vars: Env varRedacts`UPTIMEX_REDACT_HEADERS`request / response header names`UPTIMEX_REDACT_PAYLOAD_FIELDS`top-level request-payload keys`UPTIMEX_REDACT_LOG_KEYS`keys inside captured log contextTwo capture toggles govern potentially-sensitive data: Env varDefaultNotes`UPTIMEX_CAPTURE_REQUEST_PAYLOAD``false`opt-in — request bodies can hold PII`UPTIMEX_CAPTURE_EXCEPTION_SOURCE_CODE``true`±5 source lines around the throw siteFor anything the defaults don't cover, register a transformer in `boot()`: ``` Uptimex::redactLogs(function (array $context) { unset($context['ssn'], $context['card_number']); return $context; }); ``` Also available: `redactHeaders`, `redactPayload`, `redactQueries`, `redactMail`, `redactCacheKeys`, `redactOutgoingRequests`, and the generic `redact(string $type, Closure)`. Deployment markers ------------------ [](#deployment-markers) Add one command to 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 then: - draws the deploy as a vertical marker on every dashboard chart, - auto-resolves issues marked **resolve on next deploy**, and - surfaces "issues introduced since this deploy" so you catch regressions before your customers do. Artisan commands ---------------- [](#artisan-commands) CommandWhat it does`php artisan uptimex:test`Send a synthetic batch and print the result — a real round-trip that verifies token and connectivity.`php artisan uptimex:status`Print the resolved SDK config and report whether the agent is reachable.`php artisan uptimex:deploy `Post a deployment marker — see [Deployment markers](#deployment-markers).`php artisan uptimex:agent`Run the telemetry agent daemon — the SDK's delivery process; run it locally and as a supervised daemon in production.`php artisan uptimex:install`Generate Supervisor / systemd config to run `uptimex:agent` as a supervised daemon in production.The `Uptimex` facade -------------------- [](#the-uptimex-facade) Most apps never call the SDK directly — the lifecycle hooks handle HTTP requests, Artisan commands, and scheduled tasks automatically. For custom workers or CLI scripts, the facade exposes the full surface: ``` use Uptimex\Client\Facades\Uptimex; // Start a trace manually (custom long-running scripts, workers, …) Uptimex::startTrace('command', ['source' => 'cron-cleanup']); // Record a custom event under the active trace Uptimex::record('request', ['route' => '/checkout', 'duration_ms' => 42]); // Run a block with capture paused Uptimex::ignore(function () { // the SDK is silent inside this closure }); // …or pause / resume manually Uptimex::pause(); // noisy section Uptimex::resume(); // End the trace and flush its batch Uptimex::endTrace('ok'); ``` Performance ----------- [](#performance) The SDK is built to add **negligible** overhead to a request: - Lifecycle listeners record into an in-memory buffer; they never block on network I/O. - The request only writes the finished batch to a local loopback socket (a microsecond-scale write); the `uptimex:agent` daemon owns all network I/O and retries — the request process never touches the network. - Every listener is wrapped in `try { … } catch (\Throwable) {}`, so a bug in the SDK can never throw into your request handler. - Buffer overflow is "drop oldest", and failure logging is throttled — the SDK can neither exhaust memory nor flood your log. Testing ------- [](#testing) The package ships three test suites: SuiteCoversExternal deps`Unit` + `Feature`SDK internals against a Testbench-faked Laravel; no socketsnone`Integration`Real HTTP calls to a live UptimeX ingest endpointa reachable UptimeX server + a valid token``` composer test # default — Unit + Feature, hermetic composer test:integration # only the real-wire suite composer test:all # everything ``` `Integration` tests skip automatically unless both env vars are set: ``` UPTIMEX_INTEGRATION_INGEST_URL=https://ingest.uptimex.tech \ UPTIMEX_INTEGRATION_TOKEN=utx_your_real_token \ composer test:integration ``` License ------- [](#license) [MIT](LICENSE) © Purpose Company --- ### Built by [Purpose Company](https://github.com/Purposeeco) [](#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**](https://uptimex.tech) · [**GitHub**](https://github.com/Purposeeco) · [**Issues**](https://github.com/Purposeeco/uptimex-laravel-client-compser/issues) ### Health Score 40 — FairBetter than 86% of packages Maintenance96 Actively maintained with recent releases Popularity14 Limited adoption so far Community6 Small or concentrated contributor base Maturity36 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 21d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/7938999804495a5bda76fc2a1e44b746c9a66f4651ecc0c5cb3a50c0c56dac9a?d=identicon)[purpose](/maintainers/purpose) --- Top Contributors [![momen-sisalem92](https://avatars.githubusercontent.com/u/16369528?v=4)](https://github.com/momen-sisalem92 "momen-sisalem92 (24 commits)") --- Tags laravelmonitoringapmtelemetryobservabilityuptimex ### Code Quality TestsPest ### Embed Badge ![Health badge](/badges/uptimex-laravel-client/health.svg) ``` [![Health](https://phpackages.com/badges/uptimex-laravel-client/health.svg)](https://phpackages.com/packages/uptimex-laravel-client) ``` ### Alternatives [spatie/laravel-health Monitor the health of a Laravel application 87311.3M149](/packages/spatie-laravel-health)[larastan/larastan Larastan - Discover bugs in your code without running it. A phpstan/phpstan extension for Laravel 6.4k51.0M7.4k](/packages/larastan-larastan)[psalm/plugin-laravel Psalm plugin for Laravel 3325.1M337](/packages/psalm-plugin-laravel)[laravel/mcp Rapidly build MCP servers for your Laravel applications. 76318.2M110](/packages/laravel-mcp)[spatie/laravel-export Create a static site bundle from a Laravel app 670139.5k6](/packages/spatie-laravel-export)[simplestats-io/laravel-client Analytics for Laravel. Track visitors, registrations, and payments. Discover which channels actually drive revenue, not just traffic. Server-side, GDPR compliant, ad-blocker proof. 5019.3k](/packages/simplestats-io-laravel-client) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)