NightOwl Agent

Open-source Laravel monitoring agent. Captures telemetry from laravel/nightwatch and drains it into a PostgreSQL database you control.

What is this?

NightOwl Agent is an MIT-licensed Laravel package that:

1. Sits in front of 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 with non-blocking ReactPHP ingest. An ingest-only benchmark accepted 13,400 payloads/s on a single instance; see the throughput guide for drain numbers.
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

This package is fully usable on its own. Point it at a PostgreSQL database you control and you have a self-hosted Laravel APM:

Minimal .env (PostgreSQL credentials — that's it):

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). Without a token the agent also sends nothing to NightOwl's platform (see Data ownership & privacy).

UDP ingest on port 2408 is off unless you set NIGHTOWL_ENABLE_UDP=true.

Tables fill up. Run any SQL you want against them.

Updating

The migrate step happens on boot: when the agent starts and its schema is behind, it applies the pending migrations itself before it accepts traffic, so schema changes arrive with the code that needs them. That schema run is bounded by NIGHTOWL_AUTO_MIGRATE_TIMEOUT (300s) and executes in a child process the agent kills at the deadline — a lock on your database can never leave the ingest port unbound. If it doesn't finish, the agent starts anyway on the old schema and retries next boot. Long rollup backfills continue in a detached background process (log: storage/logs/nightowl-boot-migrate.log) and are retried on a later boot if one dies partway.

The agent does not restart itself. A running process keeps the code it booted with, so until you restart it the update isn't live. To make that visible rather than silent, the daemon checks vendor/composer/installed.php every few minutes and logs a warning once it sees a newer version on disk than the one it's running:

Restarting is deliberately left to you: whether a supervisor would bring the agent back after a self-initiated exit depends on configuration the agent can't verify, and being wrong about that leaves you with no agent at all rather than a slightly stale one.

Running nightowl:migrate in your deploy pipeline is still worthwhile — the boot-time run is the safety net, and a pipeline run does the rollup backfill where its latency is visible.

Opt out with NIGHTOWL_AUTO_MIGRATE=false (e.g. a DB role without DDL rights) or NIGHTOWL_UPDATE_CHECK=false.

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

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:

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

These features run in the agent process, against your Postgres.

• 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.

  Verify that path with:

  This matters more than it sounds. New-issue and reopened-issue alerts, and agent health alerts, are sent by the agent, from your server, over its own SMTP and HTTP. If you use the hosted dashboard, its "Send test" button and its status-change alerts are sent by NightOwl's API from NightOwl's infrastructure. Two different senders reading the same channel row — so a green test in the dashboard does not prove your server can reach your SMTP relay. nightowl:test-alert is the one that does, and it prints the actual failure per channel rather than leaving it in the log.

  It ignores each channel's event filter on purpose, so a transport problem can't hide behind one, and tells you afterwards if a channel that passed has new-issue alerts switched off.

  SMTP settings, if your relay is fussy or far away. The credentials themselves stay in the dashboard:

• 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

ReactPHP non-blocking TCP ingest, SQLite WAL buffering, PostgreSQL COPY drain with synchronous_commit = off. An ingest-only benchmark accepted 13,400 payloads/s on a single instance. In a July 2026 load test, one drain worker wrote about 2,500 payloads/s to PostgreSQL. Details in the throughput guide.

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

• 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

The agent writes telemetry directly to your PostgreSQL database. Request, query, exception and log data is never sent to NightOwl.

When the agent has a token (NIGHTOWL_TOKEN, or NIGHTWATCH_TOKEN as a fallback), it also sends two things to the NightOwl platform at NIGHTOWL_API_URL (default https://api.usenightowl.com):

• A health report every 30 seconds by default: the agent's host name, process id, version and uptime, the name of its PostgreSQL database, ingest and drain rates, buffer depth, PostgreSQL latency, CPU and memory, the active diagnoses, and counts of requests, 5xx responses, exceptions and open issues. This is what the dashboard's Agent Health page shows. NIGHTOWL_HEALTH_REPORT_ENABLED=false turns it off.
• An hourly sample of table statistics about the nightowl_* tables (row counts, sizes, scan and vacuum counters, server settings), read from PostgreSQL's catalog views. NIGHTOWL_TABLE_STATS=false turns it off.

Without a token, neither is sent. The alerts the agent sends go straight to the channels you configure (your SMTP server, Slack, Discord, your webhooks).

The schema is documented and stable, so your data stays usable even if you stop running the agent.

Optional: the hosted dashboard

If you'd rather not build and maintain a UI, 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

Contributing

Contributions are welcome. See GitHub Issues.

License

MIT.

Related

• Docs — docs.usenightowl.com