PHPackages aksoom-hussain/kaveh - 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. aksoom-hussain/kaveh ActiveLibrary[Logging & Monitoring](/categories/logging) aksoom-hussain/kaveh ==================== Kaveh — Telescope/Pulse-inspired Laravel monitoring (client + self-hosted server in one package) v0.1.4(today)014↑2685.7%MITPHPPHP ^8.2CI passing Since Aug 8Pushed todayCompare [ Source](https://github.com/Aksoom-Hussain/kaveh)[ Packagist](https://packagist.org/packages/aksoom-hussain/kaveh)[ RSS](/packages/aksoom-hussain-kaveh/feed)WikiDiscussions main Synced today READMEChangelog (1)Dependencies (11)Versions (6)Used By (0) Kaveh ===== [](#kaveh) **Self-hosted Laravel monitoring** — one Composer package that can run as a **client**, a **server**, or **both**. Inspired by [Laravel Telescope](https://github.com/laravel/telescope) and [Laravel Pulse](https://github.com/laravel/pulse), with a key difference: production apps can **ship telemetry off the app disk** to a separate Kaveh host instead of storing everything locally. PackagistSourceLicenseMIT``` composer require aksoom-hussain/kaveh php artisan kaveh:install ``` --- Why Kaveh? ---------- [](#why-kaveh) ProblemWhat Kaveh doesTelescope fills production disksRemote mode batches events to a central serverYou need request / exception / job visibilityBuilt-in watchers (Telescope-style)You want Pulse-like graphsDashboard charts + optional `laravel/pulse` metrics APIMultiple apps, one ops dashboardProjects + API keys (multi-tenant ingest)“What failed for checkout today?”Custom `Kaveh::track()` events + optional event RAG--- Use cases (pick one) -------------------- [](#use-cases-pick-one) ### 1) Production app → central Kaveh server *(recommended)* [](#1-production-app--central-kaveh-server-recommended) **Who:** teams with one or more Laravel apps who want a shared monitoring host. ``` ┌─────────────────────┐ HTTPS batch ┌──────────────────────┐ │ Your Laravel app │ ─────────────────────────► │ Kaveh server │ │ role=client │ POST /api/v1/ingest │ role=server │ │ mode=remote │ Authorization: Bearer kv_ │ /kaveh dashboard │ └─────────────────────┘ └──────────────────────┘ ``` **Server (once):** ``` composer require aksoom-hussain/kaveh php artisan kaveh:install --role=server --non-interactive php artisan migrate # Open /kaveh → register → Projects → Issue API key ``` **Client (each app):** ``` composer require aksoom-hussain/kaveh php artisan kaveh:install --role=client --mode=remote \ --server-url=https://kaveh.yourcompany.com \ --api-key=kv_xxxxxxxx \ --non-interactive # Keep a worker running so batches flush off-request php artisan queue:work ``` ``` KAVEH_ENABLED=true KAVEH_ROLE=client KAVEH_MODE=remote KAVEH_SERVER_URL=https://kaveh.yourcompany.com KAVEH_API_KEY=kv_xxxxxxxx KAVEH_USE_QUEUE=true ``` Then open the server dashboard → select the **project** → time range `1h / 6h / 24h / 7d` → browse requests, exceptions, jobs, slow queries. --- ### 2) Local / staging only (Telescope replacement on one box) [](#2-local--staging-only-telescope-replacement-on-one-box) **Who:** developers who want Telescope-like insight without a second host. ``` php artisan kaveh:install --role=both --mode=local --non-interactive php artisan migrate php artisan serve # Visit /kaveh/login ``` Events stay in the same app database. Good for staging; for production prefer **use case 1**. --- ### 3) Same app as client + server [](#3-same-app-as-client--server) **Who:** small installs that want watchers and dashboard on one Laravel app. ``` php artisan kaveh:install --role=both --mode=both \ --server-url="${APP_URL}" --non-interactive ``` ``` KAVEH_ROLE=both KAVEH_MODE=both KAVEH_SERVER_ENABLED=true KAVEH_SERVER_URL="${APP_URL}" KAVEH_API_KEY=kv_xxxxxxxx # from Projects after first login KAVEH_USE_QUEUE=true # important — avoids request/ingest deadlock ``` Always run `php artisan queue:work`. Prefer `role=server` on the monitor host and `role=client` on production apps if traffic is high (avoids the monitor watching itself). --- ### 4) Custom business events (beyond HTTP / jobs) [](#4-custom-business-events-beyond-http--jobs) Track domain failures that watchers will not see automatically: ``` use Kaveh\Kaveh; public function checkout(Order $order): void { try { $this->payment->charge($order); } catch (\Throwable $e) { Kaveh::track('checkout.failed', [ 'order_id' => $order->id, 'customer_id' => $order->customer_id, 'gateway' => $order->payment_gateway, 'reason' => $e->getMessage(), ], tags: ['billing', 'checkout'], level: 'error'); throw $e; } Kaveh::track('checkout.completed', [ 'order_id' => $order->id, 'total' => $order->total, ], tags: ['billing', 'checkout']); } ``` These show up in **Events** like Telescope entries, with type `custom`, searchable name/tags, and full JSON context on the detail page. --- Quick start ----------- [](#quick-start) ### Requirements [](#requirements) - PHP **8.2+** - Laravel **11 / 12 / 13** - A queue worker when `KAVEH_USE_QUEUE=true` (recommended) ### Install [](#install) ``` composer require aksoom-hussain/kaveh php artisan kaveh:install ``` RoleYou get`client`Watchers + `Kaveh::track()` + local/remote ship`server`Ingest API + dashboard + alerts + metrics API`both`Everything on one appPublishes: - `config/kaveh.php` - `App\Providers\KavehServiceProvider` (gate `viewKaveh`, same idea as Telescope/Pulse) - `.env` keys (`KAVEH_*`) --- What gets collected automatically? ---------------------------------- [](#what-gets-collected-automatically) WatcherCapturesToggleExceptionsError/critical exceptions + stack`KAVEH_WATCH_EXCEPTIONS`RequestsMethod, URI, status, duration, IP`KAVEH_WATCH_REQUESTS`QueriesSlow SQL over threshold`KAVEH_WATCH_QUERIES` + `KAVEH_SLOW_QUERY_MS`JobsProcessed / failed queue jobs`KAVEH_WATCH_JOBS`LogsError logs (noisy; off by default)`KAVEH_WATCH_LOGS`Request watcher ignores `/kaveh/*`, `/pulse/*`, `/telescope/*`, `/api/v1/ingest`, Livewire, etc. Add more with `KAVEH_IGNORE_PATHS`. Kaveh’s own jobs (`FlushEventsJob`, `EmbedEventJob`, …) are ignored so the monitor does not flood itself. --- Server dashboard ---------------- [](#server-dashboard) After server install: SurfaceURLLogin`/kaveh/login`OverviewGraphs + recent events (project + `1h/6h/24h/7d`)EventsTelescope-style list (verb, path, status, duration)AlertsThreshold rules → webhook / emailProjectsMulti-tenant projects + API keys**Authorization** — edit the published provider: ``` // app/Providers/KavehServiceProvider.php Gate::define('viewKaveh', function ($user) { return in_array($user->email, [ 'ops@yourcompany.com', ], true); }); ``` Default: open in `local`, denied elsewhere until you customize the gate. ### Optional Pulse graphs [](#optional-pulse-graphs) If [`laravel/pulse`](https://github.com/laravel/pulse) is installed on the **server** host, Overview charts read `pulse_aggregates` (CPU, memory, traffic, queue, cache): ``` GET /kaveh/api/metrics/pulse?period=60&range=3600 # session auth GET /kaveh/api/metrics/events?hours=24&project_id=1 ``` --- Ingest API (for custom shippers / debugging) -------------------------------------------- [](#ingest-api-for-custom-shippers--debugging) ``` POST /api/v1/ingest Authorization: Bearer kv_xxxxxxxx Content-Type: application/json ``` ``` { "events": [ { "type": "custom", "name": "deploy.finished", "timestamp": "2026-08-08T12:00:00Z", "environment": "production", "hostname": "web-1", "level": "info", "tags": ["deploy"], "context": { "version": "1.4.2" } } ] } ``` - `202` accepted · `401` bad key · `422` invalid · `429` rate limited - Duplicate event ids per project are ignored (idempotent) cURL check: ``` curl -X POST "https://kaveh.yourcompany.com/api/v1/ingest" \ -H "Authorization: Bearer kv_xxxxxxxx" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{"events":[{"type":"custom","name":"healthcheck","timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","environment":"production","hostname":"ci","level":"info","context":{"ok":true},"tags":["health"]}]}' ``` --- Configuration cheatsheet ------------------------ [](#configuration-cheatsheet) ``` KAVEH_ENABLED=true KAVEH_ROLE=client|server|both KAVEH_MODE=local|remote|both KAVEH_SERVER_URL=https://kaveh.yourcompany.com KAVEH_API_KEY=kv_xxxxxxxx KAVEH_PATH=kaveh KAVEH_USE_QUEUE=true KAVEH_FAIL_SILENTLY=true # never break the host app KAVEH_WATCH_EXCEPTIONS=true KAVEH_WATCH_REQUESTS=true KAVEH_WATCH_QUERIES=true KAVEH_SLOW_QUERY_MS=100 KAVEH_WATCH_JOBS=true KAVEH_WATCH_LOGS=false ``` Schedule on the server: ``` // routes/console.php or Kernel Schedule::command('kaveh:prune-events')->daily(); Schedule::command('kaveh:evaluate-alerts')->everyMinute(); ``` --- Example: wire a production app in 5 minutes ------------------------------------------- [](#example-wire-a-production-app-in-5-minutes) 1. On **Kaveh server**: Projects → create a project (e.g. **Shop**) → Issue API key → copy `kv_…` 2. On the **application** you want to monitor: ``` composer require aksoom-hussain/kaveh php artisan kaveh:install --role=client --mode=remote \ --server-url=https://kaveh.yourcompany.com \ --api-key=kv_xxxxxxxx \ --non-interactive php artisan queue:work # supervisord / Horizon in production ``` 3. Hit any HTTP route or fail a job → refresh Kaveh **Events** (select that project). 4. Optionally track checkout / webhook failures with `Kaveh::track()` (see use case 4). --- Security notes -------------- [](#security-notes) - Treat API keys like passwords; rotate from **Projects**. - Context is redacted (passwords, tokens, auth headers) before ship. - Lock down `viewKaveh` before exposing `/kaveh` on the public internet. - Prefer HTTPS for `KAVEH_SERVER_URL`. More: [docs/security.md](docs/security.md) --- Documentation ------------- [](#documentation) DocDescription[docs/use-cases.md](docs/use-cases.md)Deeper scenarios & architecture diagrams[docs/client.md](docs/client.md)Client install, watchers, queue, track()[docs/server.md](docs/server.md)Server install, dashboard, alerts, keys[docs/ingest-api.md](docs/ingest-api.md)Ingest payload reference[docs/custom-events.md](docs/custom-events.md)Snippets for billing, queues, webhooks--- Development ----------- [](#development) ``` composer test ``` Package layout: `src/`, `config/`, `routes/`, `resources/views/`, `database/migrations/`, `stubs/`, `docs/`. --- License ------- [](#license) [MIT](LICENSE.md) ### Health Score 40 — FairBetter than 86% of packages Maintenance100 Actively maintained with recent releases Popularity8 Limited adoption so far Community6 Small or concentrated contributor base Maturity39 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 Every ~0 days Total 5 Last Release 0d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/8469844?v=4)[Axum](/maintainers/Aksoom-Hussain)[@Aksoom-Hussain](https://github.com/Aksoom-Hussain) --- Top Contributors [![Aksoom-Hussain](https://avatars.githubusercontent.com/u/8469844?v=4)](https://github.com/Aksoom-Hussain "Aksoom-Hussain (8 commits)") --- Tags laravelloggingmonitoringobservabilitytelescopepulserag ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/aksoom-hussain-kaveh/health.svg) ``` [![Health](https://phpackages.com/badges/aksoom-hussain-kaveh/health.svg)](https://phpackages.com/packages/aksoom-hussain-kaveh) ``` ### Alternatives [psalm/plugin-laravel Psalm plugin for Laravel 3345.4M354](/packages/psalm-plugin-laravel)[roots/acorn Framework for Roots WordPress projects built with Laravel components. 9922.4M142](/packages/roots-acorn)[laravel/pulse Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application. 1.7k16.3M146](/packages/laravel-pulse)[laravel/cashier Laravel Cashier provides an expressive, fluent interface to Stripe's subscription billing services. 2.6k31.8M156](/packages/laravel-cashier)[api-platform/laravel API Platform support for Laravel 58190.1k19](/packages/api-platform-laravel)[fleetbase/core-api Core Framework and Resources for Fleetbase API 1239.7k25](/packages/fleetbase-core-api) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)