nightowl/agent

NightOwl monitoring agent — collects telemetry from laravel/nightwatch and writes to PostgreSQL

v0.1.1 2026-03-20 12:54 UTC

Requires

• php: ^8.2
• ext-pdo_pgsql: *
• ext-pdo_sqlite: *
• laravel/framework: ^11.0|^12.0
• react/datagram: ^1.10
• react/event-loop: ^1.5
• react/http: ^1.9
• react/socket: ^1.15

Requires (Dev)

• laravel/boost: ^2.3
• mockery/mockery: ^1.6
• phpunit/phpunit: ^11.5

Suggests

• ext-zlib: Required for gzip decompression of compressed payloads
• laravel/nightwatch: Required to collect telemetry from your Laravel app

MIT

• monitoring
• laravel
• Agent
• telemetry
• nightwatch

README

Self-hosted Laravel application monitoring. Collects telemetry from laravel/nightwatch and writes it to your PostgreSQL database.

Requirements

• PHP 8.2+
• Laravel 11 or 12
• PostgreSQL 15+
• PHP extensions: pdo_pgsql, pdo_sqlite
• Recommended: pcntl, posix (for the async driver)

Installation

1. Create an account

Sign up at your NightOwl dashboard, create a new app, and provide your PostgreSQL database credentials. You'll receive an agent token — copy it, you'll only see it once.

2. Install the package

composer require nightowl/agent

3. Configure environment

Add these to your .env:

NIGHTWATCH_TOKEN=your-token-from-the-dashboard
NIGHTOWL_DASHBOARD_URL=https://your-nightowl-dashboard.com

NIGHTOWL_DB_HOST=127.0.0.1
NIGHTOWL_DB_PORT=5432
NIGHTOWL_DB_DATABASE=nightowl
NIGHTOWL_DB_USERNAME=nightowl
NIGHTOWL_DB_PASSWORD=your-db-password

The NIGHTWATCH_TOKEN is used by both Nightwatch (to send telemetry) and the NightOwl agent (to validate it). Use the same database credentials you entered when creating the app in the dashboard.

4. Run the installer

php artisan nightowl:install

This publishes the config file and runs migrations to create the monitoring tables in your database.

5. Install Nightwatch

NightOwl receives telemetry from Laravel's Nightwatch package:

composer require laravel/nightwatch

6. Ensure the buffer directory exists

The agent uses a local SQLite file to buffer data before draining to PostgreSQL. Make sure the storage directory exists and is writable:

mkdir -p storage/nightowl && chmod 775 storage/nightowl

Docker users: This step is required inside your container before starting the agent.

7. Start the agent

php artisan nightowl:agent

The agent listens on port 2407 by default. Nightwatch sends telemetry to the agent, which buffers it locally and drains to your PostgreSQL database.

Open your NightOwl dashboard to see monitoring data.

Running in Production

Use a process manager to keep the agent running:

Supervisor (recommended):

[program:nightowl-agent]
command=php /path/to/your/app/artisan nightowl:agent
autostart=true
autorestart=true
user=www-data
redirect_stderr=true
stdout_logfile=/var/log/nightowl-agent.log

systemd:

[Unit]
Description=NightOwl Agent
After=network.target postgresql.service

[Service]
User=www-data
WorkingDirectory=/path/to/your/app
ExecStart=/usr/bin/php artisan nightowl:agent
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Configuration

All configuration is in config/nightowl.php after running the installer. Key environment variables:

Variable	Default	Description
NIGHTWATCH_TOKEN	—	Token from the dashboard (used by both Nightwatch and the agent)
NIGHTOWL_DASHBOARD_URL	https://app.nightowl.dev	Your NightOwl dashboard URL
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_AGENT_PORT	2407	TCP port the agent listens on
NIGHTOWL_AGENT_DRIVER	async	Server driver (async or sync)
NIGHTOWL_DRAIN_WORKERS	1	Number of parallel drain workers
NIGHTOWL_SAMPLE_RATE	1.0	Sampling rate (1.0 = keep all, exceptions always kept)
NIGHTOWL_RETENTION_DAYS	14	Days to keep monitoring data

Commands

Command	Description
nightowl:agent	Start the monitoring agent
nightowl:install	Publish config and run migrations
nightowl:prune	Delete monitoring data older than retention period
nightowl:clear	Truncate all monitoring tables

How It Works

Your Laravel App
  └─ laravel/nightwatch (collects telemetry)
       └─ TCP → NightOwl Agent (port 2407)
            └─ SQLite buffer (local, crash-safe)
                 └─ PostgreSQL (your database)

NightOwl Dashboard (hosted)
  └─ Reads from your PostgreSQL database
  └─ Receives health reports from the agent

The agent never sends your application data to the dashboard. It writes directly to your database. The dashboard connects to your database (using the credentials you provided) to display monitoring data. The only thing sent to the dashboard is agent health status.

License

MIT