Download the PHP package kirschbaum-development/monitor without Composer

Laravel Monitor

Laravel Monitor is an observability helper / toolkit for Laravel applications.

This package is active development and its API can change abruptly without any notice. Please reach out if you plan to use it in a production environment.

Table of Contents

• Installation
• Components
  • Structured Logging
  • Controlled Execution Blocks
  • Distributed Tracing
  • HTTP Middleware
  • Performance Timing
  • Circuit Breaker Direct Access
  • Log Redactor Direct Access
  • Log Redaction
• Complete API Reference
• Configuration
• Output Examples
• Testing
• License

Installation

Install via Composer:

Publish configuration files:

Components

Structured Logging

What it does: Enhances Laravel's logging with automatic enrichment (trace IDs, timing, memory usage, structured context) and smart origin resolution from class namespaces.

Note: While you can override with Monitor::log('CustomName'), using log($this) is preferred as it automatically provides meaningful, consistent origin tracking from your actual class structure.

What it logs:

Note: The event field uses the raw origin name (after path replacers but before wrapper), while the message field uses the wrapped origin name for readability.

Configuration: Origin path replacers, separators, and wrappers control how class names appear in logs:

Controlled Execution Blocks

What it does: Monitors critical operations with automatic start/end logging, exception-specific handling, DB transactions, circuit breakers, and true escalation for uncaught exceptions.

Note: The second parameter $origin (usually $this) is optional and automatically provides origin context to the structured logger used by the controlled block, eliminating the need for a separate ->log() call.

Factory & Execution

Context Management

Exception Handling

Exception-Specific Handlers (catching):

Uncaught Exception Handling (onUncaughtException):

Key Behavior:

• Only specified exception types in catching() are handled
• Handlers can return recovery values to prevent re-throwing
• onUncaughtException() only fires for exceptions not caught by catching() handlers
• True separation between expected (caught) and unexpected (uncaught) failures

Circuit Breaker & Database Protection

What are Circuit Breakers? Circuit breakers prevent cascading failures by temporarily stopping requests to a failing service, allowing it time to recover. They automatically "open" after a threshold of failures and "close" once the service is healthy again, protecting your application from wasting resources on operations likely to fail.

Circuit Breaker HTTP Middleware

You can also protect entire routes or route groups using the CheckCircuitBreakers middleware:

Circuit Breaker Middleware Features:

• Multiple Breakers: Check multiple circuit breakers with circuit:breaker1,breaker2,breaker3
• Graceful Degradation: Returns HTTP 503 (Service Unavailable) when circuit is open
• Standard Headers: Includes Retry-After, X-Circuit-Breaker, and X-Circuit-Breaker-Status headers
• Jitter Protection: Built-in randomized retry delays prevent thundering herd effects
• Auto-Recovery: Circuits automatically close when services recover

Response Headers When Circuit is Open:

The Retry-After header includes intelligent jitter - instead of all clients retrying at the exact same time, it provides a random delay between 0 and the remaining decay time, preventing overwhelming the recovering service.

Tracing & Logging

Complete Example

What it logs:

Success:

Caught Exception (Recovery):

Uncaught Exception (Escalation):

API Reference

Distributed Tracing

What it does: Provides correlation IDs that follow requests across services, jobs, and operations.

Trace Management:

Key Differences:

• start() - Throws exception if trace already exists
• override() - Always sets trace ID, replacing any existing one
• pickup() - Safe method that starts only if not already started

HTTP Middleware

What it does: Automatically manages trace IDs for HTTP requests, enabling seamless distributed tracing across services.

Registration:

Behavior:

• Incoming: Picks up X-Trace-Id header or generates new UUID
• Outgoing: Sets X-Trace-Id header in response
• Preserves: Existing traces when already started

Cross-service usage:

Configuration: Custom header name via trace_header config or MONITOR_TRACE_HEADER env var.

Performance Timing

What it does: Provides millisecond-precision timing for operations.

Note: All Monitor logging automatically includes duration_ms from service start.

Circuit Breaker Direct Access

What it does: Provides direct access to circuit breaker state management for advanced use cases.

Usage in Custom Logic:

Log Redactor Direct Access

What it does: Provides direct access to the redactor for custom redaction needs.

Log Redaction

What it does: Automatically scrubs sensitive data from log context using Kirschbaum Redactor to ensure compliance and security while preserving important data.

Configuration: Simple redaction configuration in config/monitor.php:

Usage: Redaction is automatically applied to all Monitor log context:

For detailed redaction configuration, rules, patterns, and profiles, see the Kirschbaum Redactor documentation.

Complete API Reference

The Monitor facade provides access to all monitoring components:

All components integrate seamlessly and share trace context automatically when used together.

Configuration

Environment Variables:

Logging Channel: Configure a dedicated Monitor logging channel:

Output Examples

Structured Log Entry:

Controlled Block Execution:

Failure with Exception:

Testing

Run the test suite:

License

The MIT License (MIT). Please see License File for more information.