Watchdog: Usage and Commands
Dashboard, status display, Run now, history with filters and the make and console commands for operating and maintaining Watchdog.
Watchdog: Usage and Commands
Dashboard
The dashboard shows one card per client. The card badge shows the worst status among the client's active checks that already have a result. Inactive checks do not count. If no active check has a result yet, the badge reads PENDING.
| Status | Meaning |
|---|---|
OK |
The check passed |
WARN |
A warning threshold has been crossed |
FAIL |
The check failed |
UNKNOWN |
The check could not produce a result, for example because of missing configuration or a missing Docker socket |
PENDING |
No result exists yet |
Severity order is FAIL before WARN before UNKNOWN before OK. At the top there is a search box for client names and a filter by status. Clicking the check count on a card expands the individual checks with status, time and response time.
Client page
A client's page lists URLs, alert contacts and all checks with last status, message, time and response time. Filters by status and check type plus a search help when there are many checks. Each check offers:
| Action | Effect |
|---|---|
| Run now | Runs the check immediately. Dashboard checks go into the queue and the result appears after a few seconds. For agent checks Watchdog sets a flag that the agent picks up on its next poll, which takes up to about 30 seconds |
| History | Result history |
| Edit | Edit the check |
Run now works for inactive clients as well. A manual run can trigger the same notifications as a scheduled one.
History
A check's history shows time, status, HTTP code, response time and message. Filters:
| Filter | Effect |
|---|---|
| Status | Only OK, WARN, FAIL or UNKNOWN |
| HTTP Code | Only results with this status code (100 to 599) |
| From / To | Date range, the To day is included |
| Entries | 10, 25, 50 or 100 per page, default 50 |
Agents
Under Agents you see each agent's status Online (reported within the last 10 minutes), Offline or Never seen, its assigned checks and the last contact. Here you register agents, rename them, regenerate tokens or delete them. Details are on Agents.
An agent that goes offline triggers no notification. Its checks then deliver no new results, and the last reported status stays on the dashboard.
make commands
All targets run in the repository directory. make help lists them in full.
| Command | Effect |
|---|---|
make local-build / local-up / local-down / local-logs / local-shell |
Local development stack |
make stage-build |
Rebuild the stage image without cache |
make stage-up / stage-down / stage-restart |
Start stage (with migrations), stop, restart |
make stage-update |
Rebuild the image, restart containers, clear the cache, run migrations |
make stage-logs / stage-app-logs / stage-shell |
Logs of all containers, logs of the app, shell in the app |
make stage-checks-off / stage-checks-on |
Pause or resume all checks |
make stage-clients-off / stage-clients-on |
Deactivate or activate all clients |
make live-up / live-down / live-restart |
Start live (with migrations), stop, restart |
make live-build |
Rebuild the live image without cache |
make live-update |
Rebuild and roll out with minimal interruption, then migrate |
make live-logs / live-shell |
Logs, shell in the app |
make live-checks-off / live-checks-on / live-clients-off / live-clients-on |
Same as for stage, for live |
make migrate, make cc |
Run migrations or clear the cache (stage) |
make setup |
Create missing legal-text and override files from the templates |
make test, make stan, make cs, make fix, make lint, make smoke |
Quality tooling (PHPUnit, PHPStan level 9, code style, lint) |
The *-checks-off targets set is_active = 0 via SQL for all checks and *-checks-on sets all of them to active. That also overrides checks you had deliberately disabled before.
Agent console command
Watchdog ships one console command of its own:
php bin/console watchdog:agent:run
| Option | Default | Meaning |
|---|---|---|
--dashboard-url |
env WATCHDOG_DASHBOARD_URL |
Dashboard base URL |
--token |
env WATCHDOG_AGENT_TOKEN |
Agent token |
--tick |
30 |
Seconds between two passes (minimum 1) |
--config-refresh |
300 |
Seconds between two fetches of the check list (minimum 60) |
--run-once |
off | Fetch the check list, run all checks once, push the results and exit |
Without a dashboard URL or token the command exits with code 1. With --run-once the exit code is 0 on success and 1 if fetching or pushing fails.
Other commands come from the framework, for example php bin/console doctrine:migrations:migrate, security:hash-password and messenger:failed:show. Run them in the container like this:
docker compose -f compose.live.yml exec --user www-data app php bin/console messenger:failed:show