Why NightGuardian?
Your apps break at 3 AM. You find out at 9 AM — from a customer.
Hosted monitoring tools are great, until you add up per-seat pricing, event quotas, data-residency
questions and a credit card you can never quite cancel. NightGuardian is the other option:
- Self-hosted, free, MIT. Your server, your database, your data. No quotas, no seats.
- API-first. The collector speaks a small, documented HTTP protocol.
Laravel is the first SDK; PHP, Node, Python — even Delphi — can follow.
- Never breaks your app. SDKs send after the response, with short timeouts, a circuit breaker
and an on-disk queue. If the collector is down, your app doesn't notice and nothing is lost.
- Quiet by default. Errors are grouped into issues. You get notified when something is
new, regresses, or spikes — not on every occurrence.
- Friendly to end users. Optional error page with a reference code (
NG-7F3K-92QD) and a
"what were you doing?" box, so support can find the exact error in seconds.
- Built with Laravel + Filament. If you know Laravel, you can contribute today.
What it does (v0.1.1)
| |
|---|
| Capture | Exceptions, error logs, failed jobs, failed scheduled tasks, slow requests, slow queries, deploys, user feedback |
| Triage | Grouping by smart fingerprint, statuses new / regressed / resolved / ignored, merge issues, search by reference code |
| Installations | One app, many copies (a SaaS with one install per customer): share a token and the same bug stays one issue, with the affected hosts listed, a host filter and the host in every alert |
| Alerts | Telegram and e-mail per project, minimum level per channel, "always notify" rules, cooldowns, daily digest |
| Access | Multiple projects, per-project roles (admin / member / viewer), optional 2FA |
| Privacy | Secrets scrubbed in the SDK and again in the collector; IPs and request bodies off by default |
| Retention | Configurable per project (default 30 days); issues and counters are kept |
The panel
| Issue detail | Feedback from users |
|---|
| |
| Tokens (shown once, with the install snippet) | Dark mode |
|---|
| |
- Dashboard: a card per project (open issues, new today, events in 24 h, 7-day chart).
- Triage: filter by project, status, environment, type, level and release; sort by last seen or events; resolve or ignore in bulk.
- Issue detail: latest event with the stack trace (in-app frames highlighted, code context), request, user, tags and context; tabs for events, feedback and activity; actions to resolve, resolve in a release, ignore (1 h / 24 h / forever), reopen and merge.
- Search: the search box finds an event by the reference code a user gives you (
NG-7F3K-92QD, in any case, with or without dashes) and issues by title.
- Tokens: creating a token shows it once, with the two lines to paste in the app's
.env and composer require nightguardian/laravel; only its hash is stored.
- Access: invitation links (signed, 7 days, one use) for projects and for the instance; super admins manage users.
Running the queue and the scheduler
Alerts, digests and retention need a queue worker and the scheduler. In production use a systemd/Supervisor worker and
one cron line (* * * * * php artisan schedule:run). To try it locally, in two consoles:
php artisan queue:work --tries=3
php artisan schedule:work
Telegram bot tokens are entered in the panel (project → Alert channels), stored encrypted, and never written to files.
Quick start
1. Run the collector (PHP 8.3+, MySQL 8 / MariaDB 10.6+):
git clone https://github.com/pablozagni/nightguardian.git
cd nightguardian
composer install
cp .env.example .env # then set DB_DATABASE, DB_USERNAME and DB_PASSWORD
php artisan key:generate
php artisan nightguardian:install
nightguardian:install checks the requirements, creates the tables and your first super admin. Alerts, digests and
retention need a queue worker and the scheduler: the command prints the cron line and a systemd unit, and
docs/deploy.md is a copy-paste guide for Ubuntu 22.04 + Apache + PHP-FPM + MySQL (HTTPS, worker,
cron, updates and backups). To try it first, Docker is two commands away:
docker compose up -d --build
docker compose exec app php artisan nightguardian:install --skip-migrate # then open http://localhost:8080
Locally, without a worker or cron: php artisan queue:work and php artisan schedule:work in two consoles.
2. Create a project and a token in the panel, which shows the lines to paste (once). Then, in your Laravel app (5.8 → 13):
composer require nightguardian/laravel
NIGHTGUARDIAN_URL=https://nightguardian.example.com
NIGHTGUARDIAN_TOKEN= # created in the collector panel
php artisan nightguardian:test
That's it. Break something and watch it arrive.
How it works
Your app ──(SDK)──► spool on disk ──HTTPS, after response──► Collector API ──► MySQL
│
Filament panel ◄──────────────┤
Telegram / e-mail ◄── queue ──┘
Read the full architecture.
SDKs
| Platform | Package | Status |
|---|
| Laravel 9 – 13 | nightguardian/laravel 2.x | ✅ v2.0.0 |
| Laravel 5.8 – 8 | nightguardian/laravel 1.x | ✅ v1.0.0 |
| Plain PHP | nightguardian/php | 🙋 looking for a maintainer |
| Node.js | nightguardian-node | 🙋 looking for a maintainer |
| Python | nightguardian-python | 🙋 looking for a maintainer |
Want to write one? Start with docs/sdk-authors.md. The collector has a
dry-run mode that validates your payloads.
Contributing
NightGuardian is young, which means your PR can shape it. Good places to start:
Read CONTRIBUTING.md. Be kind: Code of Conduct.
Security issues: SECURITY.md.
License
MIT © Pablo Zagni and contributors. Born at z.system, Argentina.
