Configuration

All configuration lives in config/nightowl.php after running php artisan nightowl:install. Most values come from environment variables, and the defaults suit a single agent running on the same host as your app.

When changes take effect. Settings the agent reads (database, drain, health, alerts, retention, ignored routes, searchable log context) apply when you restart nightowl:agent. Settings your app reads (NIGHTOWL_ENABLED, NIGHTOWL_INGEST_URI, NIGHTOWL_INGEST_TIMEOUT, NIGHTOWL_PARALLEL_WITH_NIGHTWATCH and the capture settings) apply when your app’s processes reload their config: reload PHP-FPM or Octane and restart queue workers. NIGHTOWL_TOKEN is read by both.If you run php artisan config:cache, Laravel stops reading .env and the environment at runtime. Re-run it after every change. Variables set inline on a command line or in a systemd Environment= line are ignored under a cached config; the agent’s --host, --port and --sqlite-path options still apply.NightOwl attaches to Nightwatch when your app starts booting, and checks its settings again once every service provider has booted, so a value set in a provider’s boot() still applies. Setting nightowl.enabled there turns NightOwl on or off for that process. Turned off, the process runs as if NightOwl had never attached. A change to nightowl.agent.port, nightowl.agent.token, nightowl.agent.ingest_uri, nightowl.agent.ingest_timeout, nightowl.parallel_with_nightwatch, nightowl.capture, nightwatch.token or nightwatch.redact_payload_fields is applied with the new value.

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 for every agent connection to this database (`disable`, `allow`, `prefer`, `require`, `verify-ca`, `verify-full`). See below

NIGHTOWL_DB_SSLMODE applies to every connection the agent makes to this database: the drain, health alerts, and the artisan commands (nightowl:install, nightowl:migrate, the migration the agent runs at startup, and the other nightowl:* commands), which connect through Laravel’s nightowl connection. The default, prefer, uses TLS when the server offers it, without checking the certificate. When NIGHTOWL_DB_SSLMODE isn’t set, the drain uses prefer. Health alerts and the artisan commands then leave the mode to libpq, which applies a PGSSLMODE environment variable if there is one. Set NIGHTOWL_DB_SSLMODE to give every connection the same mode. 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 one long-lived connection per drain worker, so it needs few connections, and php artisan nightowl:partition needs a direct session: behind a transaction-mode pooler it stops with an error. 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, such as a dedicated monitoring server or a serverless host like Laravel Vapor. A bare host with no port falls back to `NIGHTOWL_AGENT_PORT`. NightOwl never reads Nightwatch’s `NIGHTWATCH_INGEST_URI`: if you moved Nightwatch’s agent off the app host with it, set this one too.
`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
`NIGHTOWL_AGENT_SQLITE_PATH`	`storage/nightowl/agent-buffer.sqlite`	The agent’s SQLite buffer. One agent per buffer: a second agent pointed at the same file waits for the first to exit, and refuses to start if it doesn’t. The `--sqlite-path` option overrides it, even under a cached config
`NIGHTOWL_BUFFER_LOCK_WAIT`	`30`	Seconds a starting agent waits for another agent to release its buffer before it refuses to start. Covers restarts and rolling deploys where the old agent is still stopping. `0` refuses at once
`NIGHTOWL_ENABLE_UDP`	`false`	Also accept payloads over UDP, which has no acknowledgement
`NIGHTOWL_UDP_PORT`	`2408`	UDP port, used only when `NIGHTOWL_ENABLE_UDP=true`

The ingest socket always sets SO_REUSEPORT, so several agents on one host can share a port. Each one still needs its own buffer and its own health port. See Multiple instances.

Health API and reporting

Variable	Default	Description
`NIGHTOWL_HEALTH_ENABLED`	`true`	Serve `GET /status` on the health port. It listens on the same address as the ingest port (`NIGHTOWL_AGENT_HOST`) and has no authentication
`NIGHTOWL_HEALTH_PORT`	`2409`	Health API port. Give each agent on a host its own
`NIGHTOWL_HEALTH_REPORT_ENABLED`	`true`	Send health reports to NightOwl for the Agent Health page. Needs `NIGHTOWL_TOKEN`
`NIGHTOWL_HEALTH_REPORT_INTERVAL`	`30`	Seconds between health reports
`NIGHTOWL_DASHBOARD_URL`	`https://usenightowl.com`	Base of the links in alert emails and messages
`NIGHTOWL_CPU_HIGH_PCT`	`70`	Host CPU percentage, averaged over `NIGHTOWL_CPU_SUSTAIN_SECONDS`, above which `CPU_HIGH` (warning) fires
`NIGHTOWL_CPU_CRITICAL_PCT`	`90`	Same, for `CPU_SATURATION` (critical). A value below `NIGHTOWL_CPU_HIGH_PCT` is raised to it
`NIGHTOWL_CPU_SUSTAIN_SECONDS`	`60`	Seconds the CPU average is taken over, so a short burst such as the scheduler at the top of the hour doesn’t alert. Rounded up to 10-second steps, at most `600`. `0` judges each 10-second sample on its own, and the message then gives that one value

See Health monitoring for what the reports and /status contain.

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`	Drain worker processes, 1 to 16. A higher value is lowered to 16 with a log line; `0` or a non-number means 1. Each worker holds its own PostgreSQL connection. See Multiple instances
`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 more rows than this are waiting, counting rows a drain worker has claimed but not yet written
`NIGHTOWL_MAX_BUFFER_MEMORY`	`268435456`	RSS ceiling (bytes) before back-pressure kicks in (default 256 MB)
`NIGHTOWL_DRAIN_WEDGE_WARN_SECONDS`	`180`	Seconds a drain worker can sit in one database call before the `DRAIN_WEDGED` diagnosis fires. `0` turns it off

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.

Ignored routes

Variable	Default	Description
`NIGHTOWL_IGNORE_ROUTES`	empty	Comma-separated route patterns, matched on the route’s path, name or action. Matching requests and the records they made are never stored; their exceptions and dispatched jobs are kept. Read by the agent, so restart it after a change

See Ignoring routes for the pattern rules and what ignoring does to your error rate.

Sampling

Sampling is a Nightwatch setting, applied in your app before anything reaches the agent. Every rate defaults to 1.0, which keeps everything:

NIGHTWATCH_REQUEST_SAMPLE_RATE=1.0
NIGHTWATCH_COMMAND_SAMPLE_RATE=1.0
NIGHTWATCH_EXCEPTION_SAMPLE_RATE=1.0
NIGHTWATCH_SCHEDULED_TASK_SAMPLE_RATE=1.0

If your app already sets these for Nightwatch, they keep working. The agent stores what Nightwatch ships and never samples a second time. 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.

Request payloads and response bodies

On its own, Nightwatch records a request’s payload only when NIGHTWATCH_CAPTURE_REQUEST_PAYLOAD=true (it’s off by default), and then only for 500 responses. It never records response bodies. The NightOwl settings below replace that. Set them in your application’s .env:

Variable	Default	Description
`NIGHTOWL_CAPTURE_REQUEST_PAYLOAD`	unset	`true` records the payload of every request. `false` records none. Unset leaves it to Nightwatch: nothing, unless `NIGHTWATCH_CAPTURE_REQUEST_PAYLOAD=true`, which records 500s only
`NIGHTOWL_CAPTURE_RESPONSE_BODY`	`false`	`true` records response bodies
`NIGHTOWL_CAPTURE_STATUS_CODE`	empty	Only capture for these statuses, e.g. `422,5xx`. Exact codes and classes (`4xx`) both work. Empty means every status
`NIGHTOWL_CAPTURE_ROUTES`	empty	Only capture for these routes, e.g. `api/,webhooks.`. Matches the route path, name or action. Empty means every route
`NIGHTOWL_CAPTURE_MAX_BYTES`	`0`	Cut each payload and body to this many bytes. `0` means no limit
`NIGHTOWL_REDACT_RESPONSE_FIELDS`	see below	Keys to redact in JSON response bodies

The status and route filters apply to both payloads and response bodies. Route patterns use the same syntax as NIGHTOWL_IGNORE_ROUTES: * is the only wildcard, and a leading slash is optional. If a filter is set but none of its entries is valid (a typo such as errors), nothing is captured and a warning starting [NightOwl Agent] says why. Your app reads these settings, so your app writes that warning, to PHP’s error log (for web requests, the web server or PHP-FPM error log), not to the agent’s output. A mistake in a filter will never widen capture to every request.

# Capture payloads and responses for failing API calls only
NIGHTOWL_CAPTURE_REQUEST_PAYLOAD=true
NIGHTOWL_CAPTURE_RESPONSE_BODY=true
NIGHTOWL_CAPTURE_STATUS_CODE=4xx,5xx
NIGHTOWL_CAPTURE_ROUTES=api/*

Redaction. Payloads are redacted with NIGHTWATCH_REDACT_PAYLOAD_FIELDS, plus any Nightwatch::redactRequests() callback you registered. JSON response bodies are redacted with NIGHTOWL_REDACT_RESPONSE_FIELDS, which matches key names at any depth and ignores case. When unset, it redacts password, password_confirmation, token, access_token, refresh_token, api_key, secret and client_secret. Setting it replaces that list rather than adding to it, and setting it to an empty value turns response redaction off. HTML, XML and plain-text responses have no fields to redact, so they are stored exactly as sent. Keep that in mind before enabling capture on routes that render personal data. What is not stored. File downloads, streamed responses and binary content types (images, PDFs) are recorded as a short marker instead of their bytes. If a request’s payload and response together exceed about 4 MB, the response (and if needed the payload) is replaced by a TOO_LARGE marker whatever NIGHTOWL_CAPTURE_MAX_BYTES says. The agent refuses a single transmission over 10 MB, and that would lose the request’s queries, logs and exceptions along with the body. Storage. Captured bodies are compressed like the rest of your request data. Capturing every response on a busy app adds real storage to your database, so the status and route filters are the main way to keep it small. Response bodies need a new database column, added by a migration in the same agent release. The agent runs pending migrations when it starts; if you set NIGHTOWL_AUTO_MIGRATE=false, run php artisan nightowl:migrate yourself. Until the migration has run, requests are still recorded and only their response bodies are dropped. In parallel mode, Nightwatch’s own copy of each request is not affected by any of these settings.

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 search covers context only for a time range that starts at least 24 hours after the point where uncompressed context begins, which allows for clock differences between machines and drain delays. So context search starts working about a day after you turn the setting on. Converting existing logs (below) moves that point back. 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

In parallel mode NightOwl’s copy goes to NIGHTOWL_INGEST_URI and Nightwatch’s to NIGHTWATCH_INGEST_URI; each side reads only its own. 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:backfill-rollups`	Rebuild the summary (rollup) tables from raw telemetry (`--since`, `--until`, `--type` to narrow it)
`nightowl:test-alert`	Send a test alert through the agent’s own senders to every enabled channel (`--channel=` for one)
`nightowl:clear`	Truncate all monitoring tables

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, and it sends no health reports. It also accepts --host, --port and --sqlite-path, which override the matching settings and still apply under a cached config.

Getting Started

Agent

NightOwl Features

Performance

Database connection

Agent runtime

Health API and reporting

Authentication

Drain pipeline

Issue lifecycle

Ignored routes

Sampling

Redaction

Request payloads and response bodies

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

Health API and reporting

Authentication

Drain pipeline

Issue lifecycle

Ignored routes

Sampling

Redaction

Request payloads and response bodies

Retention and caching

Searchable log context

Making existing logs searchable

If the setting is turned off again

Parallel mode

Artisan commands