Agent Laravel Package

Getting Started

• Confirm prerequisites before anything else: PHP 8.1+, Laravel 10/11, and a reachable PostgreSQL 13+ instance. This package is Postgres-only by design — do not try to point it at MySQL or SQLite.
• Install with composer require nightowl/agent. Because the package has ~0 dependents and a single maintainer, pin the version ("nightowl/agent": "0.x.*") rather than floating *.
• Publish and read the config first: php artisan vendor:publish --provider="NightOwl\\Agent\\AgentServiceProvider" (verify the exact provider/tag with php artisan vendor:publish interactively — the tag name is the fastest way to discover what's publishable). Open config/nightowl.php before writing any code; connection, batch size, and retention settings almost always live there.
• Set the connection via env (NIGHTOWL_DB_* or a dedicated pgsql connection in config/database.php) and run php artisan migrate. Migrations create the telemetry tables the dashboard reads from.
• Discover the entry point with php artisan list | grep -i nightowl. You are looking for a long-running ingest/worker command — that command, not a middleware or facade, is the actual product.
• First use case: get one request's telemetry into Postgres end-to-end. Enable laravel/nightwatch locally, run the ingest command in the foreground with -vvv, hit a route, then SELECT * FROM <telemetry table> ORDER BY created_at DESC LIMIT 5;. If rows appear, the hard part is done; everything after that is operations.

Implementation Patterns

• Supervisor/systemd, not artisan serve. The agent is a daemon. Run it under Supervisor (numprocs=1, autorestart=true, stopwaitsecs generous enough to flush a batch) or a systemd unit. Never run it from a web request or a scheduled job that might overlap.
• Decouple ingest from write. If the package exposes queue-based buffering, use it: Nightwatch emits, the agent batches, the writer flushes. This keeps request latency independent of Postgres health and gives you a retry surface when the DB blips.
• Tag every row with the app. In a multi-app estate, add an app/environment discriminator (usually a config value injected at insert) so one Postgres cluster can serve staging and production dashboards without cross-contamination. Prefer separate schemas over separate databases — cheaper to operate, same isolation for dashboards.
• Separate the writer role from the reader role. Give the agent an INSERT-only Postgres role and the dashboard a SELECT-only role. This makes it obvious in pg_stat_activity which process is doing what and limits blast radius.
• Retention as a first-class job. Schedule a nightly prune (->where('created_at', '<', now()->subDays(14))->delete() in chunks, or the package's prune command if one exists). Telemetry tables grow monotonically; without this you will hit disk pressure within weeks on a busy app.
• Disable in tests and CI. Add an env guard (NIGHTOWL_ENABLED=false) and assert it in phpunit.xml. Tests should never attempt a Postgres connection through the agent — that turns a fast suite into a flaky one.
• Heartbeat pattern. Have a small scheduled job write a known marker row, and alert if the newest marker is older than N minutes. Monitoring the monitor is not optional when the failure mode is silence.

Gotchas and Tips

• Silent failure is the default failure mode. A dead agent looks exactly like an idle app. Log ingest errors to stderr and a local file, and alert on the heartbeat above. In the first week, tail the Supervisor log after every deploy.
• Restart on deploy. Long-running PHP processes hold old code in memory. Add php artisan nightowl:restart (or supervisorctl restart nightowl:*) to your deploy script, and remember that opcache/config caches are read at boot, not per-message.
• Version-skew between agent and dashboard is the sharpest edge. The agent writes to a schema the dashboard reads. Pin both to compatible versions and upgrade them together; a mid-flight composer update on one side is a common source of empty dashboards.
• Indexes are your job. The migrations ship the minimum. Expect to add composite indexes on (app, created_at) and whatever the dashboard filters on. Check with EXPLAIN ANALYZE when the dashboard gets sluggish — the agent's inserts are cheap, the dashboard's scans are not.
• Store timestamps in UTC. Set timezone => 'UTC' on the connection config. Mixing now() in app timezone with Postgres timestamptz produces dashboards that look correct for you and wrong for everyone else.
• JSON payloads bloat fast. If raw event payloads are stored as jsonb, prune or downsample them before they dominate table size. pg_total_relation_size() on the telemetry table is the metric to watch.
• Connection strings are the usual culprit. sslmode=require for managed Postgres (RDS/Neon/Supabase), and make sure the agent host has egress — the agent runs on the app server, not next to the DB, so it inherits every firewall rule in between.
• Extension points to reach for: config callbacks for filtering which events are captured, custom normalizers if you need to reshape payloads before insert, and Event::listen hooks if the package dispatches pre/post-write events. Filtering at the source is far cheaper than filtering at write or query time.
• Maturity caveat. With 122 stars and no dependents, treat this as a young package: vendor the migrations, keep your own fork discipline for the schema, and read the changelog before every bump. Budget for the possibility that you maintain it yourself.