minitor / agent
Self-hosted local agent that replaces Laravel Nightwatch's closed-source agent.phar and forwards telemetry to a self-hosted MINITOR server.
Maintainers
Requires
- php: ^8.2
- illuminate/console: ^10.0|^11.0|^12.0|^13.0
- illuminate/support: ^10.0|^11.0|^12.0|^13.0
- laravel/nightwatch: ^1.0
- react/event-loop: ^1.5
- react/socket: ^1.15
Requires (Dev)
- phpunit/phpunit: ^10.5|^11.0
README
minitor/agent
Self-hosted replacement for Laravel Nightwatch's closed-source local agent
(agent.phar). Installing this package pulls in the official, unmodified
laravel/nightwatch package as a
dependency - that's the real Laravel-maintained instrumentation (request
timing, query listener, exception handler, queue events, etc.), completely
untouched. This package only replaces the piece Laravel never open-sourced:
the local agent that receives from it. Instead of forwarding to Laravel's
hosted service, it forwards to your own self-hosted
MINITOR server.
laravel/nightwatch already knows how to talk to a local agent on
127.0.0.1:2407 - this package speaks that same protocol, so no changes to
laravel/nightwatch or your application code are needed.
This package is only useful alongside a running MINITOR server. See github.com/enioladev1/minitor to self-host that first - it's where you create a project and get both values this agent needs below. You never invent or generate either one yourself; the dashboard generates both together and shows them as a ready-to-paste snippet in the project's Settings dialog.
Install
On the Laravel app you want to monitor, one command installs both this
agent and laravel/nightwatch itself:
composer require minitor/agent
Paste the snippet from your project's Settings dialog into .env - it
looks like this, with both values already filled in for you:
NIGHTWATCH_TOKEN=<generated by the MINITOR dashboard for this project>
MINITOR_SERVER_URL=https://minitor.example.com
MINITOR_PROJECT_TOKEN=<generated by the MINITOR dashboard for this project>
Nightwatch's own NIGHTWATCH_INGEST_URI (what this agent listens on) and
this agent's MINITOR_AGENT_LISTEN already default to the same
127.0.0.1:2407, so nothing extra is needed there unless you're changing
that port.
NIGHTWATCH_TOKEN never leaves this server - it's only used locally to
verify frames came from this app's own Nightwatch instance. It's named
NIGHTWATCH_TOKEN (not something MINITOR-branded) because that's the
exact environment variable the real, unmodified laravel/nightwatch
package reads for it - we can't rename that without forking Nightwatch.
MINITOR_PROJECT_TOKEN is what authenticates this app's data to your
central MINITOR dashboard. Regenerating the project in the dashboard
rotates both values together - update .env again after doing so.
Run the agent (keep it running with Supervisor, systemd, Forge's daemon manager, etc. - same operational requirement as Nightwatch's own agent):
php artisan minitor:agent
Configuration
Publish the config file to customize buffer thresholds or which record types get forwarded:
php artisan vendor:publish --tag=minitor-config
See config/minitor.php for all options.
How it works
laravel/nightwatch frames every batch of telemetry as
{length}:{version}:{tokenHash}:{payload} and sends it over a local TCP
connection, expecting a 4-byte 2:OK acknowledgement back - this is
exactly what Laravel's real (closed-source) agent does too. This package's
AgentServer implements that same protocol (see
src/Protocol/FrameDecoder.php and
src/Protocol/TokenHasher.php), decodes
each record, buffers them, and forwards batches to your MINITOR server's
POST /api/ingest over HTTPS.
Testing
composer install ./vendor/bin/phpunit
License
MIT