Weave Code
Monitor Laravel Package
kirschbaum-development/monitor
Monitor is a Laravel package from Kirschbaum Development that helps you keep tabs on your application's health and performance. It offers a lightweight, configurable way to add monitoring and catch issues before they affect your users or services. Designed for simple setup and integration into exist...
Control points for Laravel: declare what a critical operation tolerates, bound it, record every outcome, and verify it in CI.
Frequently asked questions about Monitor
- What is kirschbaum-development/monitor and what problem does it solve in Laravel?
- Monitor is a control-flow and policy layer for Laravel critical operations. You declare what an operation tolerates with recover, what it guarantees with ensure, how long it may take with within, how often it may retry, and who gets paged with escalate. It records every outcome and verifies control points in CI. It is not an observability backend; it complements existing APM and tracing tools.
- Does Monitor replace Sentry, Datadog, or OpenTelemetry?
- No. Monitor sits between domain code and side effects and focuses on declaration plus verification of critical operations. StartTrace reads and writes W3C traceparent, Http::traced() propagates it outbound, and trace state lives in Laravel Context so Monitor records land inside the trace you already have. If you run Sentry, Datadog, or OTel, the value is the policy and verification layer, not the transport.
- What PHP and Laravel versions does Monitor support?
- Monitor requires PHP 8.3 through 8.5 and Laravel 12 or 13. Laravel 11 is dropped, so the version window is narrow and coupled to the newest framework. It also has a hard dependency on kirschbaum-development/redactor 1.x. Check that every service you plan to instrument matches these constraints before adopting.
- How do I install Monitor without changing my application's behavior?
- Install it with Composer and publish what you need; the service provider is deliberately inert at boot. Commands and publishing are behind runningInConsole(), the migration is published but never auto-loaded, middleware aliases resolve lazily, and the store and MCP server are off by default. Store flushes hook into kernels, per-job, Queue::looping, and Octane-safe paths. Nothing changes in behavior until someone declares a control point.
- How do I declare a control point in my code?
- You can start inline with Monitor::control('payment.charge', $this) inside an existing method to prove the pattern. When the contract earns its own file, promote it to a #[Point]-annotated ControlPoint class. The make:control-point command generates the class plus a test that already uses Monitor::fake(), so the first commit is correct by construction. Adoption can be incremental per operation.
- What do recover, ensure, within, attempts, once, and escalate mean?
- These are the declared tolerances and guarantees for a critical operation. Recover defines what the operation tolerates, ensure defines what it guarantees, within bounds how long it may take, and attempts or once controls retry behavior. Escalate defines who is paged when the policy is violated. Together they let you bound an operation, record every outcome, and verify the declaration in CI.
- Where is circuit breaker state stored, and do I need Redis?
- Breaker state is backed by a cache store, so you need a shared store such as Redis for any multi-process deployment. Without shared cache, breaker state is per-process and the guarantee is effectively illusory. If a breaker opens and refuses work such as payment runs, BreakerOpened alerting should be mandatory rather than optional. Confirm your cache topology before relying on breaker behavior in production.
- How do I test control points and enforce them in CI?
- Use Monitor::fake() in tests and the Pest expectations such as toBeControlled() and toHaveCompleteControlPoints(). The package also provides a PHPStan rule, monitor.uncontrolled, so static analysis can flag uncontrolled operations. The monitor:points command emits SARIF that plugs into GitHub code scanning, so findings land where security and quality already report. MonitorFake implements Laravel's Fake contract for familiar test workflows.
- Is Monitor production-ready at v1.0.0?
- Treat v1.0.0 as early-adopter territory. It has very little production mileage, few stars, and zero dependents, and it shipped as a full rewrite with no compatibility layer from 0.1. Support concentrates on a single vendor agency that is credible in the Laravel ecosystem but is not a funded platform. The engineering risk is low and installation is reversible, but adoption and community bug-report risk are the real concerns.
- Can I reorder the breaker, retry, and transaction pipeline or add custom policies?
- The pipeline order is fixed as breaker, then retry, then transaction. Custom policies can implement the provided interface, but they cannot be reordered within that pipeline. Plan your control points around that fixed sequence. The concept surface is also large for a team to absorb, so start with one operation and expand deliberately.
Weaver
How can I help you explore Laravel packages today?