What is this?
NightOwl Agent is an MIT-licensed Laravel package that:
- 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.
- 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.
- 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:
composer require nightowl/agent
php artisan nightowl:install # publishes config + runs migrations against your PG
php artisan nightowl:agent # starts the agent: TCP ingest on 2407, health API on 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). 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
composer update nightowl/agent
# then restart the agent however you already restart it
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:
[NightOwl Agent] Update available: a newer nightowl/agent is installed on disk
(v2.0.0#… -> v2.1.0#…) but this process is still running the old one. Restart
the agent to pick it up …
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:
<!-- phpunit.xml -->
<php>
<env name="NIGHTOWL_ENABLED" value="false"/>
</php>
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:
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
These features run in the agent process, against your Postgres.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
