README

One production-safe dashboard for everything happening in the background of your Laravel app — scheduled tasks, queues & jobs, and errors — that also lets you fix them. Works with any queue driver (database, Redis, SQS) and any database setup — single-database, multi-database, or multi-tenant. No Redis required.

📦 View on Packagist

🤔 Why Watchtower?

Laravel already ships excellent observability tools — so why another one? Because most of them either can't be left on in production, are locked to a single queue driver, or only let you look at problems instead of fixing them. Watchtower is built to live in production permanently, work no matter how your queues are configured, and turn the dashboard into a control panel.

It also adapts to any database layout: keep its tables in your main database (single-database), isolate them on a dedicated connection (multi-database) via WATCHTOWER_DB_CONNECTION, or run it in a multi-tenant app by pointing it at a stable central connection so you get one dashboard across all tenants. See Installation.

Why not Telescope / Horizon / Pulse?

These tools are complementary, not strictly competitors. Horizon is unmatched for deep Redis queue throughput, Telescope is a fantastic local debugger, and Pulse gives you a great application health overview. Watchtower fills the gap in between: a single, always-on, driver-agnostic place to watch crons, queues and errors — and act on them.

✅ Requirements

• PHP 8.2+
• Laravel 11.x or 12.x

📦 Installation in 2 commands

composer require devifyo/watchtower
php artisan watchtower:install

watchtower:install publishes the config file, publishes the dashboard assets, and runs the migrations for you. The compiled dashboard assets ship inside the package (served straight from its dist/ directory), so there is no npm install or build step in your host application.

Zero-config first run: once installed, just visit:

https://your-app.test/watchtower

Out of the box the dashboard is accessible in your local environment with no extra setup. (See Security before exposing it in production.)

First run / multi-tenant apps: if the tables haven't been created on the connection Watchtower is using, the dashboard shows a "Set up database" screen with a one-click button to run its migrations. In a multi-tenant app whose default connection changes per request, point Watchtower at a stable central connection so its data lives in one place:

WATCHTOWER_DB_CONNECTION=mysql   # your central/landlord connection name

then php artisan config:clear and click the setup button (or php artisan migrate).

🚀 Usage

Open /watchtower and you get a single-page dashboard with a summary bar across the top and three tabs:

• 📅 Schedule — every scheduled task, its cron expression (in plain English), last run, duration, status, and whether an expected run was missed. Hit Run now to dispatch any task on demand without waiting for the next tick.
• ⚙️ Queues & Jobs — live queue metrics plus the failed-jobs table. Retry a single failed job, delete it, or bulk-retry — including filtering by exception type or a time window so you can re-run only the jobs from that bad deploy.
• 🐛 Errors — every captured exception, grouped and counted, with the full stack trace and request/job context. Mark an error resolved once you've shipped a fix, or reopen it if it comes back.

The summary bar keeps the headline numbers — recent failures, missed schedules, open errors — in view at all times, and the dashboard polls for fresh data automatically (interval is configurable).

🖼️ Screenshots

Previews below are illustrative; replace with real screenshots of your running dashboard at /watchtower.

📅 Schedule — scheduled tasks with missed-run detection and run-now

⚙️ Queues & Jobs — queue metrics and bulk failed-job retry

🐛 Errors — exception tracker with resolve / reopen

⚙️ Configuration

After installing, the config file lives at config/watchtower.php. Every option is environment-overridable.

🛡️ Production safety

Watchtower is designed to be left on in production. Here's how it stays out of your hot path and keeps your database bounded:

• After-response / deferred writes — with writes.after_response (default true), metrics are written in the framework's terminating() callback, so request and job latency are untouched.

• Sampling — set sampling.rate below 1.0 to store only a fraction of records on high-traffic apps. Failures and schedule runs are always recorded, so you never miss the things that matter.

• Truncation — every stored field is capped via limits.* (trace, payload, output, message) to bound row size.

• Separate connection — point connection at a dedicated database so Watchtower's writes never contend with your application's traffic.

• Bounded retention + pruning — old records are deleted per retention.*. Schedule the prune command to run daily:

  // routes/console.php (Laravel 11/12) or app/Console/Kernel.php
  $schedule->command('watchtower:prune')->daily();

• Global kill switch — set WATCHTOWER_ENABLED=false to stop all recording instantly. The dashboard still renders historical data.

• Ignore lists — silence noisy or expected items with ignore.jobs, ignore.commands, and ignore.exceptions.

• Redact sensitive payloads — set limits.store_payload=false to never persist job payloads at all.

🔒 Security

The dashboard and the JSON API run behind the middleware stack you configure (default ['web']) plus an Authorize middleware that checks a viewWatchtower gate. The gate defaults to allowing only the local environment — the same pattern Horizon and Telescope use — so the dashboard is never accidentally public in production.

To grant access in production, define the gate in a service provider (e.g. app/Providers/AppServiceProvider.php):

use Illuminate\Support\Facades\Gate;

public function boot(): void
{
    Gate::define('viewWatchtower', function ($user) {
        return $user !== null && $user->isAdmin();
    });
}

Or use the fluent Watchtower::auth() callback, which takes precedence over the gate:

use Watchtower\Watchtower;

public function boot(): void
{
    Watchtower::auth(fn ($request) => $request->user()?->isAdmin());
}

Either way, any request that fails authorization gets a 403 — there is no path to the dashboard or API without passing the gate.

🔔 Alerts (optional)

Alerts are off by default. When enabled, Watchtower sends notifications when something needs your attention. They're implemented as standard Laravel notifications, so they slot into your existing setup.

Channels (each independent — configure any combination):

• Slack — incoming-webhook URL via WATCHTOWER_SLACK_WEBHOOK
• Generic webhook — POST alerts anywhere via WATCHTOWER_WEBHOOK_URL
• Mail — comma-separated recipients via WATCHTOWER_ALERT_MAIL

Triggers:

• A scheduled task fails (alerts.on.schedule_failed)
• A scheduled run is missed (alerts.on.schedule_missed)
• Failed jobs cross a threshold (alerts.on.failed_jobs_threshold) — default 25 failures within a 60-minute window, tunable via WATCHTOWER_FAILED_THRESHOLD and WATCHTOWER_FAILED_WINDOW

Enable alerts and run the monitor on a schedule:

WATCHTOWER_ALERTS_ENABLED=true
WATCHTOWER_SLACK_WEBHOOK=https://hooks.slack.com/services/XXX/YYY/ZZZ

$schedule->command('watchtower:monitor')->everyFiveMinutes();

🛠️ Artisan commands

🧪 Testing

composer test

The suite runs on Pest with Orchestra Testbench.

🤝 Contributing

Contributions are welcome! Please open an issue to discuss substantial changes first, then send a PR. See CONTRIBUTING.md for guidelines. Bug reports, docs improvements, and pull requests are all appreciated.

📄 License

Watchtower is open-source software licensed under the MIT license.