Watcher Configuration

Purpose and Scope

This page documents the watchers array in the Telescope configuration file (config/telescope.php147-221), which controls which watchers are enabled and their specific behaviors. Each watcher can be individually enabled or disabled and configured with watcher-specific options such as ignore lists, size limits, slow query thresholds, and log levels.

For information about core Telescope settings like the master switch and storage configuration, see Core Settings. For path-based and command-based filtering that applies globally across all watchers, see Filtering and Privacy. For detailed information about how watchers work internally, see Watchers System.

Sources: config/telescope.php136-221

---

Configuration Structure

The watchers array maps fully-qualified watcher class names to their configuration. Each watcher accepts one of two configuration formats:

1. Boolean Format: A simple true/false value to enable or disable the watcher
2. Array Format: An associative array with an enabled key plus watcher-specific options

All watcher configurations support environment variable overrides for the enabled state, allowing runtime control without modifying the configuration file.

Sources: config/telescope.php147-221

Configuration Pattern Diagram

Sources: config/telescope.php147-221

---

Watcher Configuration Reference

Infrastructure Watchers

BatchWatcher

Monitors queue job batches. Uses boolean format with environment variable override.

Configuration Options:

Option	Type	Default	Description
(enabled)	bool	true	Enable/disable batch monitoring

Sources: config/telescope.php148

---

CommandWatcher

Monitors console command execution. Uses array format with ignore list.

Configuration Options:

Option	Type	Default	Description
enabled	bool	true	Enable/disable command monitoring
ignore	array	[]	Array of command names to exclude from monitoring

The ignore array should contain command signatures (e.g., 'inspire', 'schedule:run'). Commands in this list will not generate entries even if the watcher is enabled.

Sources: config/telescope.php157-160

---

JobWatcher

Monitors queue job execution. Uses boolean format.

Configuration Options:

Option	Type	Default	Description
(enabled)	bool	true	Enable/disable job monitoring

Sources: config/telescope.php187

---

RequestWatcher

Monitors HTTP requests and responses. Uses array format with size limits and filtering options.

Configuration Options:

Option	Type	Default	Description
enabled	bool	true	Enable/disable request monitoring
size_limit	int	64	Maximum KB for response content capture
ignore_http_methods	array	[]	HTTP methods to exclude (e.g., ['OPTIONS'])
ignore_status_codes	array	[]	Status codes to exclude (e.g., [404, 500])

The size_limit prevents capturing large responses that would bloat storage. Responses exceeding this limit have their content truncated.

Sources: config/telescope.php212-217

---

ScheduleWatcher

Monitors scheduled task execution. Uses boolean format.

Configuration Options:

Option	Type	Default	Description
(enabled)	bool	true	Enable/disable schedule monitoring

Sources: config/telescope.php219

---

Data Layer Watchers

CacheWatcher

Monitors cache operations (hits, misses, writes, forgets). Uses array format with hidden keys option.

Configuration Options:

Option	Type	Default	Description
enabled	bool	true	Enable/disable cache monitoring
hidden	array	[]	Cache keys to exclude from monitoring

The hidden array should contain cache key patterns to exclude. For example, ['user.*', 'session.*'] would prevent monitoring of any cache operations on keys matching these patterns.

Sources: config/telescope.php150-153

---

ModelWatcher

Monitors Eloquent model events (created, updated, deleted, etc.). Uses array format with hydration toggle.

Configuration Options:

Option	Type	Default	Description
enabled	bool	true	Enable/disable model monitoring
hydrations	bool	true	Whether to record model hydration events

Model hydration events occur when Eloquent populates models from database results. Disabling this reduces noise if you only care about mutations.

Sources: config/telescope.php196-199

---

QueryWatcher

Monitors database queries with slow query detection. Uses array format with multiple filtering options.

Configuration Options:

Option	Type	Default	Description
enabled	bool	true	Enable/disable query monitoring
ignore_packages	bool	true	Whether to ignore queries from vendor packages
ignore_paths	array	[]	File paths to exclude from query monitoring
slow	int	100	Slow query threshold in milliseconds

The slow threshold marks queries as slow if their execution time exceeds the specified milliseconds. Slow queries are highlighted in the UI. The ignore_packages option prevents monitoring queries originating from vendor code, reducing noise from framework and package internals.

Sources: config/telescope.php203-208

---

RedisWatcher

Monitors Redis commands. Uses boolean format.

Configuration Options:

Option	Type	Default	Description
(enabled)	bool	true	Enable/disable Redis monitoring

Sources: config/telescope.php210

---

Communication Watchers

ClientRequestWatcher

Monitors outgoing HTTP requests made via Guzzle HTTP client (via AOP aspect). Uses boolean format.

Configuration Options:

Option	Type	Default	Description
(enabled)	bool	true	Enable/disable Guzzle HTTP client aspect

Note the environment variable name differs from the pattern (TELESCOPE_GUZZLE_HTTP_CLIENT_ASPECT instead of TELESCOPE_CLIENT_REQUEST_WATCHER), reflecting that this watcher requires AOP aspect activation.

Sources: config/telescope.php155

---

HttpClientWatcher

Monitors outgoing HTTP requests with size limits for request and response bodies.

Configuration Options:

Option	Type	Default	Description
enabled	bool	true	Enable/disable HTTP client monitoring
request_size_limit	int	64	Maximum KB for request body capture
response_size_limit	int	64	Maximum KB for response body capture

Size limits prevent capturing large payloads that would bloat storage. Content exceeding these limits is truncated.

Sources: config/telescope.php181-185

---

MailWatcher

Monitors sent emails. Uses boolean format.

Configuration Options:

Option	Type	Default	Description
(enabled)	bool	true	Enable/disable mail monitoring

Sources: config/telescope.php194

---

NotificationWatcher

Monitors sent notifications. Uses boolean format.

Configuration Options:

Option	Type	Default	Description
(enabled)	bool	true	Enable/disable notification monitoring

Sources: config/telescope.php201

---

Application Watchers

DumpWatcher

Monitors debug dumps (dump(), dd() calls). Uses array format with "always record" option.

Configuration Options:

Option	Type	Default	Description
enabled	bool	true	Enable/disable dump monitoring
always	bool	false	Whether to record dumps even when Telescope recording is paused

The always option allows dumps to be recorded even when Telescope::stopRecording() has been called, useful for debugging Telescope itself or recording specific diagnostic information.

Sources: config/telescope.php162-165

---

EventWatcher

Monitors application events dispatched via the event system. Uses array format with ignore list.

Configuration Options:

Option	Type	Default	Description
enabled	bool	true	Enable/disable event monitoring
ignore	array	[]	Event class names to exclude from monitoring

The ignore array should contain fully-qualified event class names (e.g., [\App\Events\UserActivity::class]). High-frequency events should be added to reduce monitoring overhead.

Sources: config/telescope.php167-170

---

ExceptionWatcher

Monitors thrown exceptions. Uses boolean format.

Configuration Options:

Option	Type	Default	Description
(enabled)	bool	true	Enable/disable exception monitoring

Sources: config/telescope.php172

---

GateWatcher

Monitors authorization gate checks. Uses array format with multiple filtering options.

Configuration Options:

Option	Type	Default	Description
enabled	bool	true	Enable/disable gate monitoring
ignore_abilities	array	[]	Ability names to exclude
ignore_packages	bool	true	Whether to ignore gate checks from vendor packages
ignore_paths	array	[]	File paths to exclude from gate monitoring

The ignore_abilities array should contain ability names (e.g., ['viewAny', 'view']). The ignore_packages option prevents monitoring authorization checks originating from vendor code.

Sources: config/telescope.php174-179

---

LogWatcher

Monitors log entries with configurable minimum level. Uses array format with level threshold.

Configuration Options:

Option	Type	Default	Description
enabled	bool	true	Enable/disable log monitoring
level	string	'error'	Minimum log level to capture

The level option accepts PSR-3 log levels: 'debug', 'info', 'notice', 'warning', 'error', 'critical', 'alert', 'emergency'. Only logs at or above this level are recorded. Setting this to 'error' prevents recording of informational logs that would clutter storage.

Sources: config/telescope.php189-192

---

ViewWatcher

Monitors view rendering. Uses boolean format.

Configuration Options:

Option	Type	Default	Description
(enabled)	bool	true	Enable/disable view monitoring

Sources: config/telescope.php220

---

Environment Variable Override Pattern

All watchers support environment variable overrides for their enabled state. The naming convention follows the pattern: TELESCOPE_{WATCHER_TYPE}_WATCHER, where {WATCHER_TYPE} is the watcher name in uppercase with underscores.

Environment Variable Mapping

Exception: ClientRequestWatcher uses TELESCOPE_GUZZLE_HTTP_CLIENT_ASPECT instead of following the standard pattern, as it controls AOP aspect registration rather than just watcher enablement.

Additional environment variables control watcher-specific numeric options:

Watcher	Option	Environment Variable	Default
RequestWatcher	size_limit	TELESCOPE_RESPONSE_SIZE_LIMIT	64
HttpClientWatcher	request_size_limit	TELESCOPE_HTTP_CLIENT_REQUEST_SIZE_LIMIT	64
HttpClientWatcher	response_size_limit	TELESCOPE_HTTP_CLIENT_RESPONSE_SIZE_LIMIT	64
DumpWatcher	always	TELESCOPE_DUMP_WATCHER_ALWAYS	false

Sources: config/telescope.php147-221

---

Configuration Loading Flow

The service provider iterates through the watchers array during the register() method. For each watcher:

1. The configuration value is retrieved from the array
2. If boolean true or array with 'enabled' => true, the watcher is bound to the DI container
3. Array configurations pass additional options to the watcher constructor
4. If false or 'enabled' => false, the watcher is skipped entirely
5. Enabled watchers are registered with the Telescope core system

This design allows watchers to be completely removed from memory when disabled, minimizing overhead.

Sources: config/telescope.php147-221

---

Configuration Best Practices

Performance Optimization

1. Disable unused watchers: Set watchers you don't need to false to prevent their instantiation
2. Use ignore lists: For high-frequency operations (events, commands), use ignore lists rather than disabling the entire watcher
3. Set appropriate size limits: Large response bodies can bloat storage; set size_limit values based on your typical payload sizes
4. Configure slow query threshold: Set QueryWatcher::slow based on your performance requirements (default 100ms may be too low for complex queries)
5. Disable model hydrations: If you only need mutation tracking, set ModelWatcher::hydrations => false

Security Considerations

1. Use hidden arrays: Cache keys containing sensitive data should be added to CacheWatcher::hidden
2. Ignore sensitive abilities: Authorization checks for sensitive features should be added to GateWatcher::ignore_abilities
3. Ignore sensitive paths: Files containing sensitive logic should be added to path ignore lists
4. Response size limits: Ensure size limits prevent capturing sensitive large payloads

Development vs Production

Environment variables allow different configurations per environment:

Sources: config/telescope.php147-221