Laravel

Raccoon speaks the same protocol as Laravel Nightwatch. Your app keeps the official laravel/nightwatch package, which records requests, jobs, commands, scheduled tasks, queries, cache, mail, notifications, outgoing requests, logs and exceptions. Its agent sends them to Raccoon instead of the hosted Nightwatch service.

Install#

1. Install the package if it isn't there yet:

   composer require laravel/nightwatch
   

2. Set the environment's token and Raccoon's URL. Copy the token from Settings → Environments. The variable names belong to the Nightwatch package.

   NIGHTWATCH_TOKEN=<environment token>
   NIGHTWATCH_BASE_URL=https://raccoon.watch
   

3. Run the agent next to the app and keep it running:

   php artisan nightwatch:agent
   

   The app hands events to the agent on 127.0.0.1:2407. The agent sends them to Raccoon about every 10 seconds.

The agent logs each step: Nightwatch agent initiated, then Authentication successful, then Ingest successful for each batch. A batch that fails is logged and dropped, not retried.

Where to run the agent#

Run one agent on every server or container that runs the app, including servers that only run queue workers or the scheduler. Use your process manager: Supervisor, systemd, a Forge daemon or a sidecar container.

Where you can't run an agent, as on Laravel Cloud's managed queue or on Vapor, install raccoonwatch/laravel. Those processes then send their events over HTTPS themselves.

Laravel Cloud#

1. Don't use Cloud's Connect Nightwatch action. It connects the environment to the hosted Nightwatch service, and Cloud's managed agent ignores NIGHTWATCH_BASE_URL. If an environment is already connected, disconnect it.
2. Add NIGHTWATCH_TOKEN and NIGHTWATCH_BASE_URL to the environment's custom environment variables.
3. On the App cluster, add a background process: Custom worker, command php artisan nightwatch:agent, 1 process. Run exactly one per instance, because a second agent can't bind the same port.
4. If you use Cloud's managed queue, also install raccoonwatch/laravel. Managed-queue workers run outside the App cluster, where no agent is listening.
5. Deploy.

Deployments#

Record each deploy so the dashboard's charts show a marker where it happened. Run this from your deploy script:

php artisan nightwatch:deploy

It uses NIGHTWATCH_DEPLOY as the deploy's name, or the argument you pass it, such as a commit hash.

Troubleshooting#

• Nothing arrives and the agent logs nothing. The agent isn't running where the app runs, so events sent to 127.0.0.1:2407 are dropped.
• Authentication failed ... 401. The token doesn't match an environment. Copy it again from Settings → Environments.
• Incoming token hash mismatch. The app and the agent see different NIGHTWATCH_TOKEN values. Set it once for both, then restart both.
• Requests arrive but jobs don't. The queue workers run without an agent. Run one next to them, or install raccoonwatch/laravel. The Jobs page shows a warning when it sees queued jobs with no attempts.
• An environment stops sending. Turn on silence alerts to get an email when no events arrive for a while.