Laravel Nightwatch

Laravel Nightwatch is the official instrumentation package that connects a Laravel application to Nightwatch, a hosted application-performance-monitoring platform built specifically for the Laravel ecosystem. Rather than bolting on a generic APM agent, this package hooks directly into framework-native events — HTTP requests, queries, queued jobs, cache hits/misses, outgoing HTTP calls, mail, notifications, exceptions, and scheduled tasks — and streams structured records to a lightweight local agent process that batches and forwards them to the Nightwatch service.

Because the package is written by the Laravel core team and ships as MIT-licensed source, teams can read exactly what data leaves their servers and how it’s captured, even though the dashboard and long-term storage backend is a paid, hosted product.

What You Get

• Automatic instrumentation of HTTP requests, DB queries, queued jobs, scheduled tasks, cache operations, outgoing HTTP requests, mail, notifications, and unhandled exceptions with zero manual instrumentation calls
• A local nightwatch:agent Artisan command that runs a lightweight background process to batch and forward telemetry, keeping request-path overhead minimal
• Deep framework integration via dedicated Sensor classes for each event type, plus Octane and Livewire-aware hooks
• A Nightwatch facade and context helpers for attaching custom metadata (user identity, request execution stage) to captured records
• Deploy and status Artisan commands (nightwatch:deploy, nightwatch:status) for operating the agent in production

Common Use Cases

• Diagnosing slow endpoints and N+1 query patterns in a production Laravel application without adding manual timing code
• Getting queue-job-level visibility (attempts, duration, failures) across Horizon-managed workers
• Centralizing exception and error visibility across a fleet of Laravel apps in one Laravel-native dashboard
• Tracking outgoing HTTP call latency to third-party APIs from within a Laravel app

Under The Hood

Architecture - The package centers on NightwatchServiceProvider, which during boot registers dozens of Laravel event listeners (in src/Hooks/) for framework events like RequestHandled, QueryExecuted, JobQueued, CacheHit/CacheMissed, MessageSending, and Terminating. Each listener converts the event into a typed record (in src/Records/) produced by a corresponding class under src/Sensors/ (e.g. QuerySensor, RequestSensor, ExceptionSensor, JobAttemptSensor). Records accumulate in RecordsBuffer and are periodically flushed by Ingest/Core through a SocketStreamFactory to a locally running agent process (a separate compiled binary under agent/, built via agent/build.sh and shipped as a PHAR/binary), which handles batching, compression, and authenticated delivery to the hosted Nightwatch service. Console commands (AgentCommand, DeployCommand, Console/StatusCommand) manage running and deploying that local agent.

Tech Stack - PHP 8.2+, targeting Laravel 10 through 13. Depends on guzzlehttp/promises, monolog/monolog, nesbot/carbon, ramsey/uuid, and Symfony console/http-foundation components. Dev tooling includes PHPStan for static analysis, Pint for formatting, PHPUnit + Orchestra Testbench for testing against multiple Laravel versions, and a composer-dependency-analyser check. The bundled agent (under agent/) has its own Node-based build pipeline (watch.js, package.json) alongside a PHP/Docker build for the compiled agent binary.

Code Quality - The repository has a substantial tests/Feature and tests/Unit suite plus tests/fixtures, backed by fake implementations (FakeIngest, FakeJob, FakeRecord, FakeTcpStream) that let sensors and hooks be tested without a live agent connection. Code is organized into clear single-responsibility directories (Hooks, Sensors, Records, Console, Contracts, Types, State), and PHPStan plus Pint enforce static typing and style consistently across 738+ commits from 13 contributors, with releases shipped multiple times a week.

API Design - Integration is zero-config for the common path: installing the package and adding credentials is enough to get full framework instrumentation, since all hooks attach automatically via the service provider. Advanced usage (custom context, manual sampling via Console/Sample.php) is exposed through a small Nightwatch facade rather than a sprawling public API, keeping the day-to-day developer surface minimal even though the internal hook/sensor system is extensive.