Introduction
All of the package's configuration lives in config/monitor.php. Publish it with php artisan vendor:publish --tag=monitor-config. Every key has a default, so the package runs unpublished.
domains
How a class name becomes the domain field on every record.
| Key | Type | Default | Meaning |
|---|
map | array<string, string|null> | App\ControlPoints\, App\Services\, App\ all null | Namespace prefix to domain. null takes the namespace segment right after the prefix; a string is used as-is. Tried in order, first match wins. |
fallback | string | 'App' | The domain for a class matching no prefix, or sitting directly under one. |
critical_namespaces
| Type | Default |
|---|
string[] | ['App\ControlPoints'] |
Namespaces whose classes are expected to be control points. The inventory's critical_namespace_uncontrolled rule, the toBeControlled() Pest expectation and the PHPStan rule read this list: a class here that neither extends ControlPoint nor calls Monitor::control() is reported. Interfaces, traits, enums, abstract classes, escalations and policies are exempt.
point_name_pattern
| Type | Default |
|---|
string (regex) | '/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/' |
Every point name is validated against this at declaration time and by the inventory's name_pattern rule. The default is dotted lowercase with at least one dot.
discovery
| Key | Type | Default | Meaning |
|---|
paths | string[] | ['app'] | Directories the inventory scans for control point classes and inline Monitor::control() calls. Absolute, or relative to base_path(). |
inventory
| Key | Type | Default | Meaning |
|---|
rules | array<string, bool> | [] | Rules to switch off by setting them to false. Every rule is on unless listed. |
The rules are duplicate_names, name_pattern, missing_escalation, critical_namespace_uncontrolled, unreadable_control (errors) and catch_all_without_escalation, dynamic_name (warnings). See Inventory.
profiles
| Type | Default |
|---|
array<string, array> | external, database, messaging, internal |
Named bundles applied with ->profile() or the attribute's profile: argument. Each profile is an array with any of these keys:
| Key | Shape |
|---|
retry | ['times' => int, 'backoff_ms' => int, 'multiplier' => float, 'jitter' => bool, 'on' => class[], 'except' => class[]] |
transaction | ['retries' => int, 'on' => class[], 'except' => class[], 'connection' => string|null, 'backoff_ms' => int] |
breaker | ['name' => string, 'after' => int, 'within' => int, 'for' => int, 'on' => class[], 'except' => class[]]; name defaults to the point's name |
within | seconds, int|float |
attempts | int |
The shipped values are listed in Policies and Limits. Class names in on and except that are not Throwable are ignored.
trace
| Key | Type | Default | Env | Meaning |
|---|
header | string | 'traceparent' | | The W3C header the middleware reads first and writes back. |
legacy_header | string | 'X-Trace-Id' | MONITOR_TRACE_HEADER | A plain trace-ID header read second and written back, for clients that do not speak traceparent. |
console | bool | true | MONITOR_TRACE_CONSOLE | Start a trace when an artisan command starts (on CommandStarting), so commands and workers have one. |
breakers
Defaults for circuits used without explicit numbers, including the standalone Monitor::breaker() API, the route middleware and profiles that omit a value.
| Key | Type | Default | Env | Meaning |
|---|
store | string|null | null | MONITOR_BREAKER_STORE | The cache store holding circuit state; null is the default store. |
prefix | string | 'monitor:breaker:' | | Cache key prefix. |
after | int | 5 | | Failures that open a circuit. |
within | int | 60 | | Seconds a failure stays counted. |
for | int | 120 | | Seconds a circuit stays open before a probe is allowed. |
once
Where the once() policy keeps its idempotency keys.
| Key | Type | Default | Env | Meaning |
|---|
store | string|null | null | MONITOR_ONCE_STORE | The cache store holding the keys; null is the default store. Keys are shared exactly as far as the store is. |
prefix | string | 'monitor:once:' | | Cache key prefix, followed by the point name, a colon and the key. |
records
| Key | Type | Default | Env | Meaning |
|---|
channel | string|null | null | MONITOR_LOG_CHANNEL | The log channel records are written to; null is the default channel. |
redaction | string|null | 'observability' | MONITOR_REDACTION_PROFILE | The Redactor profile applied to record context and exception messages, to stored outcomes, and to MCP responses. Empty or null disables redaction. |
exception_trace | 'never'|'debug'|'always' | 'never' | MONITOR_EXCEPTION_TRACE | Whether exception summaries include a stack trace: never, only when app.debug is on, or always. |
exception_trace_lines | int | 15 | | Trace lines kept when a trace is included; the rest is counted in trace_truncated. |
records.levels
| Type | Default |
|---|
array<string, string> | see below |
The PSR-3 level for each record event. Events not listed are written at info.
| Event | Default |
|---|
point.started | debug |
point.retried | notice |
point.limit | warning |
point.recovered | warning |
point.refused | warning |
point.escalated | error |
point.ended | info |
escalation.failed | critical |
breaker.opened | error |
breaker.half_open | notice |
breaker.closed | info |
Event names contain dots, so set the whole array rather than one nested key.
records.store
| Key | Type | Default | Env | Meaning |
|---|
enabled | bool | false | MONITOR_STORE_ENABLED | Keep outcomes in a table. Publish and run the migration first; see Store. |
connection | string|null | null | MONITOR_STORE_CONNECTION | The database connection for the table; null is the default. |
table | string | 'monitor_outcomes' | | The table name. |
retention_days | int | 30 | | What monitor:prune deletes past. |
mcp
| Key | Type | Default | Env | Meaning |
|---|
enabled | bool | false | MONITOR_MCP_ENABLED | Register the read-only MCP server. Requires laravel/mcp. |
handle | string | 'monitor' | | The handle for php artisan mcp:start monitor. |
Environment Variables
| Variable | Key |
|---|
MONITOR_TRACE_HEADER | trace.legacy_header |
MONITOR_TRACE_CONSOLE | trace.console |
MONITOR_BREAKER_STORE | breakers.store |
MONITOR_ONCE_STORE | once.store |
MONITOR_LOG_CHANNEL | records.channel |
MONITOR_REDACTION_PROFILE | records.redaction |
MONITOR_EXCEPTION_TRACE | records.exception_trace |
MONITOR_STORE_ENABLED | records.store.enabled |
MONITOR_STORE_CONNECTION | records.store.connection |
MONITOR_MCP_ENABLED | mcp.enabled |
Only values that change between environments have a variable; the rest are code-level defaults edited in the published file. php artisan about shows the store, MCP and profile settings in effect.