PHPackages nightowl/agent - 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. nightowl/agent ActiveLibrary[Logging & Monitoring](/categories/logging) nightowl/agent ============== NightOwl monitoring agent — collects telemetry from laravel/nightwatch and writes to PostgreSQL v1.0.4(3w ago)732285MITPHPPHP ^8.2CI passing Since Mar 30Pushed 2w ago3 watchersCompare [ Source](https://github.com/lemed99/nightowl-agent)[ Packagist](https://packagist.org/packages/nightowl/agent)[ Fund](https://buy.polar.sh/polar_cl_K2ykmjbHPVEaOBpuU4FtomEg5yGMBp4W2Tcxf0ob7Cm)[ RSS](/packages/nightowl-agent/feed)WikiDiscussions main Synced 3w ago READMEChangelogDependencies (33)Versions (34)Used By (0) [![NightOwl](.github/assets/logo.svg)](.github/assets/logo.svg) NightOwl Agent ============== [](#nightowl-agent) **Open-source Laravel monitoring agent. Captures telemetry from [`laravel/nightwatch`](https://github.com/laravel/nightwatch) and drains it into a PostgreSQL database you control.** [![Packagist Version](https://camo.githubusercontent.com/473e7fa6579e2336f6a975915ee4be8360a55c3cd04b19f866018eaa519a59db/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6e696768746f776c2f6167656e742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/nightowl/agent) [![PHP 8.2+](https://camo.githubusercontent.com/36f43f80df056872e314cbb084b77cf0d8d6625e842c12b25db6a56bb90c8b96/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6e696768746f776c2f6167656e742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/nightowl/agent) [![MIT License](https://camo.githubusercontent.com/5f49060d51dd5b2e81c0b338bb22877a3b0728a91333fe4afec08ffbea71f64a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6c656d656439392f6e696768746f776c2d6167656e742e7376673f7374796c653d666c61742d737175617265)](LICENSE) [![Tests](https://camo.githubusercontent.com/8cbbfde7646cf09b1e198770cb7758e6e96faf1cd361f2931b44a98c744a1a9b/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6c656d656439392f6e696768746f776c2d6167656e742f74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/lemed99/nightowl-agent/actions/workflows/tests.yml) --- What is this? ------------- [](#what-is-this) NightOwl Agent is an MIT-licensed Laravel package that: 1. **Sits in front of [`laravel/nightwatch`](https://github.com/laravel/nightwatch)** — Laravel's official observability SDK. Nightwatch already does the hard part: instrumenting all 12 record types — requests, queries, jobs, exceptions, commands, cache events, mail, notifications, outgoing HTTP, scheduled tasks, logs, users. The agent receives those payloads over a local TCP socket. 2. **Buffers them in a local SQLite WAL** — non-blocking ReactPHP ingest, ~13,400 payloads/s on a single instance. 3. **Drains them into a PostgreSQL database you provision** via the COPY protocol. Telemetry never leaves your network. All tables are prefixed `nightowl_` and the schema is documented. You're free to query the data with `psql`, point Metabase at it, or build your own UI on top — Livewire, Next.js, whatever. Run it standalone ----------------- [](#run-it-standalone) This package is fully usable on its own. Point it at a PostgreSQL database you control and you have a self-hosted Laravel APM: ``` composer require nightowl/agent php artisan nightowl:install # publishes config + runs migrations against your PG php artisan nightowl:agent # starts the TCP/UDP/health daemon (ports 2407/2408/2409) ``` Minimal `.env` (PostgreSQL credentials — that's it): ``` NIGHTOWL_DB_HOST=127.0.0.1 NIGHTOWL_DB_PORT=5432 NIGHTOWL_DB_DATABASE=nightowl NIGHTOWL_DB_USERNAME=nightowl NIGHTOWL_DB_PASSWORD=nightowl NIGHTOWL_DB_SSLMODE=prefer ``` You don't need to wire up Nightwatch's transport — the service provider automatically redirects its ingest to the local agent on `127.0.0.1:2407`. For a local-only setup you also don't need any token; the agent only enforces one if you set `NIGHTOWL_TOKEN` (useful when the agent listens on something other than loopback). Tables fill up. Run any SQL you want against them. Disabling NightOwl ------------------ [](#disabling-nightowl) Set `NIGHTOWL_ENABLED=false` to make the package fully inert — the Nightwatch ingest hook is not wired (no telemetry is collected or transmitted) and the migrations are not registered. The most common use is turning it off in your test suite so tests don't pay the ingest overhead or require the `nightowl` database to exist: ``` ``` `nightowl:install` runs its migrations regardless of this flag (it's an explicit opt-in), so you can still install while the switch is off. Sharing one database across environments ---------------------------------------- [](#sharing-one-database-across-environments) NightOwl stamps an `environment` column (your `APP_ENV`) on every row, so several app environments (local, staging, production) can point at one NightOwl database and be filtered apart in the dashboard. The data is partitioned by environment; the `nightowl_*` tables are shared. `nightowl:install` and `nightowl:migrate` track their migration history **inside the NightOwl database**, so they're idempotent across environments. Run the schema sync as part of each deploy: ``` php artisan nightowl:migrate ``` The first environment to deploy creates the tables, the rest are no-ops, and upgrades' new migrations apply on whichever environment deploys first. No "owner" environment and no flags. A database that already has the tables but no NightOwl migration history (e.g. created by an older version or by your app's `php artisan migrate`) is adopted as a baseline, so you never hit `relation "nightowl_requests" already exists`. By default these migrations are **not** bundled into your app's `php artisan migrate`. If you'd rather run them that way (single-database setups only — it tracks history in your primary database and must not be combined with `nightowl:install`), set `NIGHTOWL_RUN_MIGRATIONS=true`. What you get out of the box --------------------------- [](#what-you-get-out-of-the-box) These features run in the agent process. Postgres is the only thing it talks to. - **Exception fingerprinting** — `nightowl_exceptions` upserts into `nightowl_issues` keyed on `(group_hash, type, environment)`, so repeats roll up into one grouped issue. - **New-issue alerts** — when an issue is seen for the first time the drain worker fans it out to whatever you've configured in `nightowl_alert_channels`: Email (BYO SMTP), Webhook (HMAC-signed), Slack, Discord. - **Threshold-based performance issues** — set a threshold per record type (slow request, slow query, slow job, and so on), and durations above it get turned into issues. - **Agent + host health diagnosis** — ring buffers and EWMA feed a rule engine that produces a health score and surfaces stalls (drain lag, buffer depth, CPU, memory, load average). - **Raw rows for every Nightwatch record type** — all 12 sit in your Postgres. `psql`, Metabase, or your own UI on top. Architecture ------------ [](#architecture) ``` Your Laravel app Your infrastructure ┌──────────────────┐ TCP ┌──────────────────────────────┐ │ laravel/ │──2407────▶│ NightOwl Agent (ReactPHP) │ │ nightwatch │ │ ├─ SQLite WAL buffer │ └──────────────────┘ │ └─ pcntl drain workers │ │ │ │ │ │ COPY protocol │ │ ▼ │ │ PostgreSQL (yours) │ └────────────┬─────────────────┘ │ ▼ ┌─────────────────────────┐ │ Your own UI / scripts │ │ (psql, Metabase, vibe- │ │ coded Next.js, etc.) │ └─────────────────────────┘ ``` > **13,400 payloads/s** on a single instance — ReactPHP non-blocking TCP ingest, SQLite WAL buffering, PostgreSQL `COPY` drain with `synchronous_commit = off`. What the agent collects ----------------------- [](#what-the-agent-collects) Whatever Nightwatch emits, the agent persists. Each row carries duration (microseconds), `environment`, `deploy`, and the request/job correlation IDs Nightwatch attaches. - **Requests** — method, route, path, status, duration, memory, user ID - **Jobs** — queue, attempts, status (queued/processed/released/failed), exception link - **Queries** — SQL, bindings, connection, duration, request correlation - **Exceptions** — class, message, stack trace, fingerprint hash (upserted into `nightowl_issues`) - **Logs** — level, message, context, request correlation - **Users** — `users_count` upsert (request + exception counters per authenticated user) - **Cache events, mail, notifications, outgoing HTTP, scheduled tasks, commands** — same shape as Nightwatch - **Host metrics** — CPU, memory, load average (Linux `/proc`) - **Agent self-health** — ingest/drain rates, buffer depth, back-pressure, diagnosis rules P95s, N+1 detection, slow-query rankings, request timelines, etc. are queries you write against these tables. Requirements ------------ [](#requirements) - PHP **8.2+** with extensions: `pdo_pgsql`, `pdo_sqlite` (always), `pcntl` + `posix` (for the async driver), `zlib` (for gzipped payloads) - PostgreSQL **14+** (16 or 17 recommended) - Laravel **11, 12, 13** Data ownership & privacy ---------------------------- [](#data-ownership--privacy) The agent writes telemetry **directly to your PostgreSQL database**. Zero request, query, or exception data leaves your infrastructure. The only thing the agent *can* send outbound, and only if you opt in to remote health reporting, is **agent/host health metadata** (ingest rates, buffer depth, drain lag, CPU/memory), so a remote backend can warn you when the agent is unhealthy. The schema is documented and stable, so your data stays usable even if you stop running the agent. Optional: the hosted dashboard ------------------------------ [](#optional-the-hosted-dashboard) If you'd rather not build and maintain a UI, [usenightowl.com](https://usenightowl.com) is a managed service that connects to your Postgres with credentials you supply (and can rotate or revoke at any time). It adds an issue lifecycle UI (resolve / ignore / reopen, assignees, comments, activity timeline), alerts for those state transitions, teams, and an MCP server for AI tools. The agent itself stays MIT and works the same with or without it. Full guide: [docs.usenightowl.com](https://docs.usenightowl.com) Contributing ------------ [](#contributing) Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, test suite structure, and conventions. Bug reports and feature requests go through [GitHub Issues](https://github.com/lemed99/nightowl-agent/issues). License ------- [](#license) [MIT](LICENSE). Related ------- [](#related) - **Docs** — [docs.usenightowl.com](https://docs.usenightowl.com) ### Health Score 52 — FairBetter than 96% of packages Maintenance96 Actively maintained with recent releases Popularity30 Limited adoption so far Community11 Small or concentrated contributor base Maturity58 Maturing project, gaining track record 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 ~2 days Total 33 Last Release 22d ago Major Versions v0.2.5 → v1.0.02026-05-08 ### Community Maintainers ![](https://www.gravatar.com/avatar/102576929b3053fff0a8910dc1e4aedb9ac23bf8780899c12c2488ee56f02b39?d=identicon)[Lemed99](/maintainers/Lemed99) --- Top Contributors [![lemed99](https://avatars.githubusercontent.com/u/45576683?v=4)](https://github.com/lemed99 "lemed99 (54 commits)") --- Tags apmlaravelmonitoringnightwatchobservabilityphppostgresqlreactphpself-hostedlaravelmonitoringAgenttelemetrynightwatch ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/nightowl-agent/health.svg) ``` [![Health](https://phpackages.com/badges/nightowl-agent/health.svg)](https://phpackages.com/packages/nightowl-agent) ``` ### Alternatives [leventcz/laravel-top Real-time monitoring straight from the command line for Laravel applications. 583112.2k1](/packages/leventcz-laravel-top)[lucianotonet/laravel-telescope-mcp MCP Server extension for Laravel Telescope 2019.6k](/packages/lucianotonet-laravel-telescope-mcp) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)