Monitor Documentation
Monitor gives a Laravel application control points: the operations where a failure matters, declared in code as a contract. A control point says what it is called, which domain it belongs to, which failures it expects and what to return instead, which policies bound it (retry, transaction, circuit breaker), which limits it should stay within, and who is told when something it did not expect gets out. Every run ends in exactly one outcome, succeeded, recovered, escalated or refused, and every transition is written as a record with the same fields.
Because the declaration is data, the rest of the package can read it: monitor:points lists every control point in the application and checks the declarations in CI, Monitor::fake() asserts on outcomes in tests, an optional store keeps outcomes queryable without a log backend, and an MCP server lets an agent ask the application what its control points are and what happened at them.
Start Here
If you are new to the package, read the pages in this order:
- Getting Started installs the package, declares a first control point and shows what it writes to the log.
- Control Points covers the inline and class forms, naming, domains and nesting.
- Risks and Corrections and Policies and Limits are the two halves of a point's contract.
- Inventory and Testing are how the contract is verified.
Everything else can be read as you need it.
Pages
| Page | What it covers |
|---|---|
| Getting Started | Installation, the inline form, run() and attempt(), the Outcome, a first class-form point, the trace middleware, and where the records go. |
| Control Points | Names, origin and domain, the full inline builder, the class form, the constraint on control(), nesting, and what lands in Laravel's Context. |
| Risks and Corrections | recover() semantics, the catch-all, escalate() with a closure or a class, EscalationFailed, and the risks Monitor raises itself. |
| Policies and Limits | Retry, Transaction, Breaker, pipeline order, custom policies, the three limits, and the shipped profiles. |
| Records | The record every transition writes, its fields and levels, the JSON schema, the NDJSON tap, redaction, and the events behind it. |
| Tracing | The trace ID, traceparent and the legacy header, the middleware, outgoing propagation with Http::traced(), queued jobs and console. |
| Jobs | What a job inherits, ChargeCard::dispatch() and RunControlPoint, Horizon tags, the WaitForBreaker job middleware, and why the queue keeps its retries. |
| Breakers | The circuit state machine, the standalone Monitor::breaker() API, and the CheckBreakers route middleware. |
| Store | The optional outcomes table, when it is written, monitor:outcomes, monitor:prune, and retention. |
| Inventory | monitor:points, the rules --check enforces, table, JSON and SARIF output, monitor:explain, and make:control-point. |
| Testing | Monitor::fake() and its assertions, the Pest expectations, the PHPStan rule, and the package's own tests. |
| Agents | The guideline and skill shipped for Laravel Boost, and the MCP server's tools, resources and prompt. |
| Configuration | Every key in config/monitor.php with its type, default and environment variable. |
| Extending | Writing a policy, an escalation, an inventory rule, and listening to the events. |
| Upgrading | Every 0.1 surface and its 1.0 replacement. |
Conventions
Code samples assume the facade is imported:
use Kirschbaum\Monitor\Facades\Monitor;
Configuration paths are written relative to the file, so records.store.enabled means config('monitor.records.store.enabled').