Configuration

All configuration lives in config/nightowl.php after running php artisan nightowl:install. Most values are driven by environment variables — the defaults are tuned for a single-instance deployment doing up to a few thousand requests per second.

Database connection

Variable	Default	Description
`NIGHTOWL_DB_HOST`	`127.0.0.1`	PostgreSQL host
`NIGHTOWL_DB_PORT`	`5432`	PostgreSQL port
`NIGHTOWL_DB_DATABASE`	`nightowl`	PostgreSQL database name
`NIGHTOWL_DB_USERNAME`	`nightowl`	PostgreSQL username
`NIGHTOWL_DB_PASSWORD`	`nightowl`	PostgreSQL password
`NIGHTOWL_DB_SSLMODE`	`prefer`	PostgreSQL SSL mode (`disable`, `allow`, `prefer`, `require`, `verify-ca`, `verify-full`)

Use the same credentials you entered when creating the app in the dashboard — the hosted UI uses them to read the telemetry your agent wrote.

Managed Postgres (Supabase, Neon, RDS): point the agent at the direct or session connection on port 5432, not a transaction-mode pooler (Supabase’s 6543). The agent holds a long-lived drain connection and relies on session-level settings (synchronous_commit) that transaction-mode poolers don’t preserve, so a session-scoped connection is the right fit. Set NIGHTOWL_DB_SSLMODE=require, and use the provider’s existing database (postgres on Supabase, neondb on Neon) — NightOwl creates the tables, not the database.

NightOwl stamps an environment column (your APP_ENV) on every row, so you can point several app environments (local, staging, production) at one NightOwl database and filter them apart in the dashboard. The environments are separated only by that column; the nightowl_* tables themselves are shared. (Unrelated to table partitioning — see Data management for that.) nightowl:install and nightowl:migrate track their migration history inside the NightOwl database, so they’re idempotent across every environment that shares it. Run php artisan nightowl:migrate as part of each deploy:

the first environment to deploy creates the tables;
the rest are no-ops;
when a package upgrade adds a migration, it applies on whichever environment deploys first.

No “owner” environment, no flags. If a database already has the nightowl_* tables but no NightOwl migration history (for example it was created by an older version, or by your app’s php artisan migrate), the command adopts the existing schema as a baseline instead of trying to recreate it — so you never hit relation "nightowl_requests" already exists.

By default NightOwl’s migrations are not bundled into your app’s php artisan migrate. Manage the schema with nightowl:migrate (or nightowl:install). See NIGHTOWL_RUN_MIGRATIONS below if you want the legacy ride-along behavior.

If a package upgrade adds a migration and you forget to run nightowl:migrate, php artisan nightowl:agent warns at startup that the schema is behind (and keeps running) rather than failing silently mid-drain. So wiring nightowl:migrate into your deploy is the way to keep the schema current.

Agent runtime

Variable	Default	Description
`NIGHTOWL_ENABLED`	`true`	Master switch. Set `false` to make the package inert — no telemetry is collected or transmitted, and the migrations are not registered. Most commonly flipped off in the `testing` environment so your test suite doesn’t pay the ingest overhead or require the `nightowl` database. `nightowl:install` still runs its migrations regardless.
`NIGHTOWL_RUN_MIGRATIONS`	`false`	Legacy ride-along. When `true`, NightOwl’s migrations also run as part of your app’s `php artisan migrate` (history tracked in your primary database). Off by default because the schema is managed by `nightowl:migrate` / `nightowl:install`, which track history in the NightOwl database. Don’t combine the two — they record history in different places and would both try to create the tables. Only enable for a single-database setup where you’d rather not run `nightowl:migrate`.
`NIGHTOWL_AGENT_HOST`	`127.0.0.1`	TCP host the agent binds/listens on (use `0.0.0.0` to accept payloads from other hosts). This is the listener address — not where your app transmits.
`NIGHTOWL_AGENT_PORT`	`2407`	TCP port the agent listens on
`NIGHTOWL_INGEST_URI`	`127.0.0.1:2407`	Where your app transmits telemetry — the agent’s `host:port` as seen from your app. Defaults to the loopback listener (co-located agent). Set it to the agent’s private address when the app and agent run on different hosts — a dedicated monitoring server or a serverless host like Laravel Vapor. A bare host with no port falls back to `NIGHTOWL_AGENT_PORT`. Mirrors nightwatch’s `NIGHTWATCH_INGEST_URI`.
`NIGHTOWL_INGEST_TIMEOUT`	`0.5`	Connect + write timeout (seconds) for transmitting to the agent. The default suits a loopback agent; raise it when the agent is a network hop away (`1.0` on a private network, `3` across the public internet) — otherwise transient latency surfaces as intermittent `Connection timed out` exceptions and dropped batches.
`NIGHTOWL_AGENT_DRIVER`	`async`	Server driver (`async` or `sync`). `async` needs `pcntl` + `posix`
`NIGHTOWL_ENVIRONMENT`	`APP_ENV`	Override `APP_ENV` for the `environment` column stamped on every row

The async server enables SO_REUSEPORT automatically on Linux, so multiple agents can bind the same port without extra configuration — see Running multiple instances.

Authentication

Variable	Description
`NIGHTOWL_TOKEN`	Agent token copied from the NightOwl dashboard (Settings → Agent token). The agent verifies inbound payloads against it and uses it as a `Bearer` credential when reporting health to the NightOwl platform. For a standalone install this is the only token you need.
`NIGHTOWL_APP_ID`	Connected-app ID, copied from the NightOwl dashboard (Settings → Agent token, alongside `NIGHTOWL_TOKEN`). Required for alert emails and webhooks to include a direct-link `view_url` pointing at the issue. Without it, links fall back to the generic dashboard root.
`NIGHTWATCH_TOKEN`	Only needed in parallel mode, when NightOwl runs alongside Nightwatch’s hosted agent. This is your real Nightwatch token — the Nightwatch SDK uses it to authenticate against Laravel Cloud’s hosted ingest. Don’t set it for a standard install.

For a standalone install, set NIGHTOWL_TOKEN only. For parallel mode, set both: NIGHTOWL_TOKEN is what the NightOwl agent verifies against, NIGHTWATCH_TOKEN is your Nightwatch token used by the Nightwatch SDK to reach Laravel Cloud’s hosted ingest in parallel.

Drain pipeline

Variable	Default	Description
`NIGHTOWL_DRAIN_WORKERS`	`1`	Parallel drain worker processes (forked, atomic SQLite row claiming)
`NIGHTOWL_DRAIN_BATCH_SIZE`	`5000`	Rows per PostgreSQL `COPY` batch
`NIGHTOWL_DRAIN_INTERVAL_MS`	`100`	Drain loop sleep interval when the buffer is idle
`NIGHTOWL_MAX_PENDING_ROWS`	`100000`	Reject new payloads once the buffer hits this depth
`NIGHTOWL_MAX_BUFFER_MEMORY`	`268435456`	RSS ceiling (bytes) before back-pressure kicks in (default 256 MB)

Issue lifecycle

Variable	Default	Description
`NIGHTOWL_REOPEN_COOLDOWN_HOURS`	`0`	Hours of silence required before a `resolved` issue auto-reopens on recurrence. `0` = always reopen on first new occurrence (Sentry-style behavior). Set higher to suppress flapping issues — e.g. `24` only reopens if the issue has been resolved for at least a day. `ignored` issues are never auto-reopened regardless of this setting.

See throughput tuning for how to size these.

Sampling

Sampling is handled upstream by laravel/nightwatch before the payload reaches the agent. Configure it in your customer app’s .env:

NIGHTWATCH_REQUEST_SAMPLE_RATE=0.1                    # Keep ~10% of HTTP requests (1.0 = keep all)
NIGHTWATCH_COMMAND_SAMPLE_RATE=1.0                    # Keep all artisan commands
NIGHTWATCH_EXCEPTION_SAMPLE_RATE=1.0                  # Keep all exceptions
NIGHTWATCH_SCHEDULED_TASK_SAMPLE_RATE=1.0             # Keep all scheduled tasks

The decision is made before transport, so the agent only sees and stores what Nightwatch decided to ship — no double-sampling. See Filtering and context for the full recipe.

Redaction

PII redaction is handled upstream by laravel/nightwatch before the payload reaches the agent. Configure it in your customer app’s .env:

NIGHTWATCH_REDACT_HEADERS=Authorization,Cookie,Proxy-Authorization,X-XSRF-TOKEN
NIGHTWATCH_REDACT_PAYLOAD_FIELDS=_token,password,password_confirmation

Both lists are applied inside the customer’s PHP process before the record leaves the host, so the agent’s TCP buffer and PostgreSQL drain never see the un-redacted values.

Retention and caching

Variable	Default	Description
`NIGHTOWL_RETENTION_DAYS`	`14`	Default for `nightowl:prune --days=?` — nothing is deleted until the command is run
`NIGHTOWL_ROLLUP_RETENTION_DAYS`	`90`	Retention for the minute-granular rollup tables (pruned by `nightowl:prune`)
`NIGHTOWL_HOURLY_ROLLUP_RETENTION_DAYS`	`366`	Retention for the hourly rollup tier (60× sparser than minute)
`NIGHTOWL_DAILY_ROLLUP_RETENTION_DAYS`	`1100`	Retention for the daily rollup tier (1440× sparser than minute)
`NIGHTOWL_THRESHOLD_CACHE_TTL`	`86400`	Seconds to cache performance thresholds (restart to pick up changes immediately)

Full retention and pruning strategy lives in Data management.

Searchable log context

By default a log’s context is stored compressed. PostgreSQL cannot decompress it while running a query, so the dashboard’s log search matches the message only and shows a “Narrowed search” note saying so.

Variable	Default	Description
`NIGHTOWL_LOG_CONTEXT_SEARCHABLE`	`false`	Store log context uncompressed so log search can match inside it

NIGHTOWL_LOG_CONTEXT_SEARCHABLE=true

With this on, searching your logs for 8412 finds the line written by Log::error('Payment failed', ['order_id' => 8412]), not just lines with 8412 in the message. Restart the agent after changing it. The agent only stores context uncompressed once its schema has the column for it (added by php artisan nightowl:migrate, which the agent normally runs itself on boot). If the setting is on but the column is missing, the agent keeps storing compressed context, logs a warning saying so, and the dashboard keeps showing the “Narrowed search” note — nothing breaks, it just is not searchable yet. Run the migration and restart.

This trades storage for searchability, and how much depends entirely on what your app logs — small contexts barely compress at all (under about 256 bytes, compression can make them larger), while large ones compress well. Measure yours before deciding:

php artisan nightowl:backfill-log-context --dry-run

That reports what your context currently occupies and what it would occupy uncompressed, and changes nothing.

Making existing logs searchable

Turning the flag on is forward-only — it changes what the agent stores from that moment. Logs already on disk stay compressed and stay unsearchable, and because NightOwl retention is typically long, waiting for them to age out is not a real answer. Convert them:

php artisan nightowl:backfill-log-context

It works newest-first, so the logs you are most likely to search become searchable first, and you can stop it at any time and re-run later to continue — an interrupted run leaves a smaller searchable range, never a wrong one. The dashboard keeps showing the “Narrowed search” note for ranges it has not reached yet. Useful options:

Option	Description
`--dry-run`	Measure against your own rows and change nothing
`--since=`	Only convert this far back (e.g. `--since='2026-06-01'`) to cap the cost
`--vacuum`	Reclaim the rewritten rows immediately instead of leaving it to autovacuum

A full conversion rewrites every log row in range, which leaves dead rows behind until autovacuum (or --vacuum) reclaims them, so the table temporarily needs more disk than the figures above. On a large history, run it deliberately rather than during a deploy. --since is usually the better trade: most people search recent logs.

If the setting is turned off again

Removing NIGHTOWL_LOG_CONTEXT_SEARCHABLE (a deploy that drops the variable, for instance) makes the agent store compressed context again, and log search goes back to matching the message only — including over the history you converted. That data is not lost or changed; the search simply cannot cover a range that has compressed logs in it. To get it back, set the variable again, restart the agent, and re-run:

php artisan nightowl:backfill-log-context

This second run is quick — your already-converted logs need no conversion, so it only re-establishes the searchable range over them.

Parallel mode

Variable	Default	Description
`NIGHTOWL_PARALLEL_WITH_NIGHTWATCH`	`false`	Fan telemetry out to both Nightwatch and NightOwl simultaneously

See Running alongside Nightwatch.

Artisan commands

Command	Description
`nightowl:agent`	Start the monitoring agent
`nightowl:install`	Publish config, create/update the schema, verify fork safety
`nightowl:migrate`	Create/update the NightOwl schema (idempotent — run on each deploy)
`nightowl:prune`	Delete monitoring data older than retention period (drops whole expired day-partitions instantly on partitioned tables)
`nightowl:partition`	Convert existing raw telemetry tables to native daily partitioning — no data copying (except `nightowl_logs`, whose legacy text date column is rewritten); new installs are partitioned automatically
`nightowl:drop-v1-histograms`	Post-transition cleanup: drop the legacy histogram columns once every rollup row carries a DDSketch — refuses to run before that, requires an agent restart after
`nightowl:backfill-log-context`	Convert already-stored log context to the searchable uncompressed form (`--dry-run` to measure first)
`nightowl:clear`	Truncate all monitoring tables
`nightowl:check-thresholds`	Poll and dispatch threshold-breach notifications

The agent command accepts --driver=async|sync. async is the default and required for multi-worker drain; sync is a single-process fallback for hosts without pcntl/posix.

Getting Started

Agent

NightOwl Features

Performance

Database connection

Agent runtime

Authentication

Drain pipeline

Issue lifecycle

Sampling

Redaction

Retention and caching

Searchable log context

Making existing logs searchable

If the setting is turned off again

Parallel mode

Artisan commands

​Database connection

​Sharing one database across environments

​Agent runtime

​Authentication

​Drain pipeline

​Issue lifecycle

​Sampling

​Redaction

​Retention and caching

​Searchable log context

​Making existing logs searchable

​If the setting is turned off again

​Parallel mode

​Artisan commands

Database connection

Sharing one database across environments

Agent runtime

Authentication

Drain pipeline

Issue lifecycle

Sampling

Redaction

Retention and caching

Searchable log context

Making existing logs searchable

If the setting is turned off again

Parallel mode

Artisan commands