Download the PHP package cosmos-observe/laravel-monitor without Composer

Cosmos Laravel Monitor

Production-safe, ClickHouse-first monitoring APIs for Laravel 10, 11, 12, and 13.

Cosmos Monitor gives you Telescope-style operational visibility without shipping a Blade UI and without storing high-volume telemetry in the host application's OLTP database. Runtime telemetry lives in ClickHouse with typed filter columns, JSON payloads, materialized rollups, cursor pagination, sampling, redaction, fail-open writes, and TTL-based retention. Durable low-volume settings, exception workflow state, and external service definitions stay in the host application's database.

The official package and dashboard logo is the Laravel Cosmos heartbeat mark shown above.

What It Captures

• HTTP RPS, status counts, latency, slow requests, and performance events.
• Queue depth, processed/failed job counts, job runtime, failed-job summaries, and oldest pending age where the host queue driver supports it.
• Sanitized Monolog records through an opt-in Laravel log tap.
• Sanitized exceptions with bounded stack traces and stable grouping hashes.
• Scheduler start, finish, failure, missed, skipped, and heartbeat telemetry.
• Database query latency, slow queries, SQL hashes, and aggregate rollups.
• Cache hit, miss, write, and forget events where Laravel emits cache events.
• Storage disk snapshots: selected disk file counts, file-count deltas, byte totals, local disk pressure, and remote disk listability checks.
• External HTTP dependency checks: user-registered service name/URL probes with latest status, latency, status code, and transition alerts.
• Outbound external HTTP requests: Laravel Http:: traffic automatically, plus an opt-in Guzzle middleware for direct Guzzle clients.
• Mail sends: metadata-only send/failure telemetry with mailer, transport, duration, recipient count, domains, and salted recipient hashes.
• Runtime health: app identity, PHP/Laravel/package versions, ClickHouse ping, DB ping latency, queue config, and memory peak.

Install

Install and start ClickHouse before enabling live telemetry. A local install should answer with Ok.:

Minimal Configuration

Default base path:

All responses use a stable API envelope:

Security Model

Use your Laravel app middleware as the primary protection layer:

For dashboards, service-to-service calls, or staging E2E apps, you can also set:

When the token is set, requests must include:

Scheduler

Register these commands in your host app scheduler:

sample-queues records queue depth, failed job count, and oldest pending age where supported. ClickHouse TTL deletes expired telemetry during table merges; prune reports retention status and does not force OPTIMIZE FINAL. sample-storage records selected filesystem disk snapshots. check-external-services probes enabled external service URLs and records availability transitions.

Storage And External Services

Selected storage disks default to local/public and can be changed without touching code:

Local disks expose total_files, file_count_delta, total_bytes, disk_total_bytes, disk_free_bytes, and used_percent. Remote disks are checked for bounded listability without write probes.

External services are registered through the API with name and url; scheduled checks classify 2xx/3xx as up, 4xx as reachable_warning, and 5xx, timeout, DNS, or TLS failures as down. Notifications are emitted only when the latest status changes.

Firebase Browser Push

Firebase Cloud Messaging uses server-only service-account env values and the HTTP v1 API. Do not publish the private key or store it in dashboard-facing settings.

Browser tokens are persisted through POST /notifications/fcm/register and removed through DELETE /notifications/fcm/register. Test notifications use POST /notifications/test.

External Requests And Mail

Outbound HTTP request monitoring captures Laravel Http:: events without storing request headers, request bodies, response bodies, or sensitive query strings. The stored URL is normalized to scheme, host, port, and path. Registered service health checks are tagged as source=external_service_check so the dashboard can separate synthetic checks from application traffic.

Apps that instantiate Guzzle directly can opt in by pushing the package middleware onto their handler stack:

Raw curl_* calls do not emit Laravel or Guzzle events and are outside v1 automatic capture.

Mail monitoring stores metadata only: send status, mailer, transport, duration, message id, recipient count, recipient domains, salted recipient hashes, attachment presence, and error class/message on failures. It does not store body text, subject, attachments, or full recipient addresses.

Log Capture

Add the tap to any logging channel you want monitored:

Only levels configured in cosmos-monitor.logs.levels are written to telemetry. Sensitive keys such as authorization, cookie, password, token, api_key, and secret are redacted.

Heavy Data Controls

The package is designed for production load:

Use cursor pagination for high-volume list screens:

The response includes:

API Catalog

• GET /health
• GET /metrics/summary
• GET /metrics/timeseries
• GET /requests
• GET /queues
• GET /queues/{queue}/jobs
• GET /logs
• GET /exceptions
• PUT /exceptions/{hash}/status
• GET /schedules
• GET /database/latency
• GET /performance
• GET /cache
• GET /storage
• GET /external-requests
• GET /mail
• GET /external-services
• POST /external-services
• PUT /external-services/{id}
• DELETE /external-services/{id}
• POST /external-services/{id}/check
• GET /settings
• PUT /settings
• POST /notifications/test
• POST /diagnostics/logs/test
• POST /diagnostics/exceptions/test
• POST /diagnostics/database/test-query

Diagnostic endpoints are blocked unless:

Dashboard Integration

The companion dashboard can run in mock, hybrid, or live mode:

The dashboard proxy maps package envelopes into the existing dashboard data shape and keeps mock mode available for demos.

ClickHouse Storage Notes

Sizing depends on event rate, payload size, indexed fields, and retention. A practical first pass:

• Keep ClickHouse retention to the operations window you actually inspect, for example 30d.
• Install the schema with php artisan cosmos-monitor:install-clickhouse-schema before live capture.
• Use async_insert=1,wait_for_async_insert=1 for reliable high-concurrency inserts.
• ClickHouse TTL deletion is merge-driven and is not immediate; expired rows are removed during background merges.
• Turn on sampling for very high RPS apps.
• Keep max_payload_bytes low and rely on hashes/traces for drill-down.
• Prefer cursor pagination and indexed filters over deep page numbers.
• Watch /health for clickhouse=ok and telemetry_storage=ok.

CI/CD

GitHub Actions runs Composer validation, PHP linting, and PHPUnit on pushes and pull requests.

Release tags matching v* run the release workflow, create or update a GitHub Release, and can notify Packagist when these repository secrets are configured:

Create releases with semantic version tags:

E2E Test Host

This repository was validated against a separate Laravel 12 app with SQLite app data and local ClickHouse telemetry, and its Composer constraints support Laravel 13 applications:

The E2E app installs this package through a Composer path repository, triggers real HTTP, DB, cache, log, exception, queue, schedule, settings, diagnostics, notification, heavy-data, cursor, and retention scenarios, and includes a command for 100k mixed telemetry events:

Documentation

• Full API guide: docs/api.md
• OpenAPI spec: docs/openapi.yaml