Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.usenightowl.com/llms.txt

Use this file to discover all available pages before exploring further.

NightOwl is a bring-your-own-database product. Your telemetry — every request, query, exception, job attempt, and log line — lives in a PostgreSQL instance you control. That gives you full ownership of retention, backups, and compliance, and it keeps storage costs decoupled from per-seat dashboard pricing.

​
Storage model

Every connected app points at one PostgreSQL database. The agent writes through SQLite’s WAL buffer into ~20 nightowl_* tables using COPY for high-volume event tables and INSERT … ON CONFLICT for upsert tables (nightowl_exceptions, nightowl_users). Because the data lives in your PostgreSQL, you can:
  • Connect your own BI tools (Metabase, Grafana, Superset) directly to the nightowl schema.
  • Run arbitrary SQL for ad-hoc analysis without hitting an API rate limit.
  • Control exactly where the data is geographically stored, for GDPR or data-residency reasons.
  • Back it up alongside the rest of your database with tools you already trust.

​
Retention

Telemetry is high-volume and low-shelf-life. The agent ships with a single global retention window — 14 days by default — applied uniformly to every event table it prunes. Set it in the customer app’s environment: 
NIGHTOWL_RETENTION_DAYS=14
What the prune command deletes, and what it leaves alone:
TablesBehavior
nightowl_requests, nightowl_queries, nightowl_exceptions, nightowl_commands, nightowl_jobs, nightowl_cache_events, nightowl_mail, nightowl_notifications, nightowl_outgoing_requests, nightowl_scheduled_tasks, nightowl_logs, nightowl_alertsRows older than NIGHTOWL_RETENTION_DAYS are deleted.
nightowl_issues, nightowl_issue_activity, nightowl_issue_commentsNever auto-pruned. Triage state survives occurrence cleanup.
nightowl_settings, nightowl_alert_channels, nightowl_usersConfiguration and user identity — never auto-pruned.
Resolving an issue doesn’t delete its history. Only the raw occurrence rows feeding the fingerprint are subject to retention.

​
Pruning

The nightowl:prune artisan command deletes rows older than NIGHTOWL_RETENTION_DAYS (or --days=N to override for one run). Schedule it alongside your other Laravel scheduled tasks: 
// app/Console/Kernel.php
$schedule->command('nightowl:prune')->hourly();
The command issues one DELETE … WHERE created_at < ? per table. On PostgreSQL, follow up occasionally with VACUUM (ANALYZE) to reclaim disk — the command doesn’t do this automatically because it may compete with production workload.

​
Manual cleanup and resets

​
Selective delete (Data Management)

The Data Management page in the sidebar lets you delete telemetry for a specific date range, narrowed by table and filter. Use it to clear out noise from a staging incident, a runaway log level, or a single bad deploy without waiting for retention to catch up.
  1. Pick a From / To date range. The To date must be at least 30 days in the past — the endpoint rejects anything newer to prevent accidental deletion of live data.
  2. Select which tables to include. By default all 12 event tables are selected (nightowl_requests, nightowl_queries, nightowl_exceptions, nightowl_commands, nightowl_jobs, nightowl_cache_events, nightowl_mail, nightowl_notifications, nightowl_outgoing_requests, nightowl_scheduled_tasks, nightowl_logs, nightowl_alerts).
  3. Optionally narrow by route path, status code, duration, user, job status, log level, exception class, or cache event type. Filters only apply to tables where the column exists.
  4. Preview shows counts per table before you commit. Deletion is then chunked in 10,000-row batches. After the deletion, any nightowl_issues row of type = 'exception' whose fingerprint no longer has a matching row in nightowl_exceptions is cleaned up automatically; performance issues are not touched by this sweep.
Issue triage state, settings, alert channels, and user identity rows are never touched by this flow.

​
Delete app (Danger Zone)

From Settings → Danger Zone, Delete app removes the app from NightOwl along with its agent token and alert routing. Does not drop or truncate your nightowl_* tables — that’s your database, and we won’t touch it. If you want the telemetry gone too, use Data Management for a targeted range or run php artisan nightowl:clear in the customer app for a full truncate.
Data Management deletions are irreversible — there’s no soft-delete. Take a PostgreSQL backup first if the data has any archival value.

​
Backups

NightOwl doesn’t manage backups — that’s your PostgreSQL provider’s job. The nightowl_* tables back up the same way the rest of your database does. If you use pg_dump, include the schema you configured (public by default) and you’ll capture everything. If you use managed snapshots (RDS, Cloud SQL), they already cover it. For point-in-time-restore strategies, treat the nightowl_* tables like any other high-write workload — their WAL volume scales with telemetry throughput, so budget your WAL storage accordingly.

​
Sizing expectations

As a rough baseline for capacity planning:
WorkloadDaily rowsDaily storage (compressed)
Small app (~100 req/s)~8.6M~500 MB
Medium app (~1,000 req/s)~86M~5 GB
Large app (~10,000 req/s)~860M~50 GB
At the default 14-day retention these multiply by 14. See PostgreSQL sizing for disk, memory, and vCPU guidance.

​
Exporting data

For compliance exports, legal holds, or moving to another tool, use direct PostgreSQL access: 
pg_dump -h <host> -U <user> -d <db> \
  --table='nightowl_*' \
  --format=custom \
  -f nightowl-export.dump
There’s no proprietary format — the schema is plain PostgreSQL, and every column is documented in the agent package’s migration files.