Watchers System

Purpose and Scope

This document provides a comprehensive overview of Telescope's watcher ecosystem, which monitors different aspects of application execution. It explains the role of watchers, their categories, and how they integrate with the Telescope core system.

For detailed information about specific watcher implementations, see:

• Base watcher pattern and registration: 2.3.1
• Individual watcher deep-dives: 2.3.2 through 2.3.8

For information about how watcher data flows through the recording and storage pipeline, see Architecture and Data Storage.

What Are Watchers?

Watchers are specialized monitoring components that observe specific aspects of application behavior. Each watcher:

1. Listens to framework events or intercepts method calls
2. Extracts relevant data from the monitored operation
3. Filters data based on configuration rules
4. Creates IncomingEntry objects containing the extracted data
5. Records entries by calling Telescope::recordX() methods

Watchers operate transparently—application code requires no modifications to be monitored.

Sources: High-level system diagrams

Watcher Architecture

Integration with Telescope Core

Sources: src/Telescope.php275-319 src/Telescope.php354-493

Recording Method Dispatch

Each watcher type has a dedicated recording method in the Telescope facade that associates the entry with its EntryType:

Recording Method	Entry Type	Line Reference
recordBatch()	EntryType::BATCH	src/Telescope.php354-357
recordCache()	EntryType::CACHE	src/Telescope.php362-365
recordCommand()	EntryType::COMMAND	src/Telescope.php370-373
recordDump()	EntryType::DUMP	src/Telescope.php378-381
recordEvent()	EntryType::EVENT	src/Telescope.php386-389
recordException()	EntryType::EXCEPTION	src/Telescope.php394-397
recordGate()	EntryType::GATE	src/Telescope.php402-405
recordJob()	EntryType::JOB	src/Telescope.php410-413
recordLog()	EntryType::LOG	src/Telescope.php418-421
recordMail()	EntryType::MAIL	src/Telescope.php426-429
recordNotification()	EntryType::NOTIFICATION	src/Telescope.php434-437
recordQuery()	EntryType::QUERY	src/Telescope.php442-445
recordModelEvent()	EntryType::MODEL	src/Telescope.php450-453
recordRedis()	EntryType::REDIS	src/Telescope.php458-461
recordRequest()	EntryType::REQUEST	src/Telescope.php466-469
recordScheduledCommand()	EntryType::SCHEDULED_TASK	src/Telescope.php474-477
recordView()	EntryType::VIEW	src/Telescope.php482-485
recordClientRequest()	EntryType::CLIENT_REQUEST	src/Telescope.php490-493

All methods delegate to the central Telescope::record() method at src/Telescope.php275-319 which handles filtering, tagging, user association, and queueing.

Sources: src/Telescope.php354-493 src/Telescope.php275-319

Watcher Categories

Telescope's 18 specialized watchers are organized into four functional categories:

Infrastructure Watchers

Monitor application execution contexts and lifecycle events.

Watcher Class	Purpose	Config Key
Watchers\RequestWatcher	HTTP request/response data	config/telescope.php212-217
Watchers\CommandWatcher	Console command execution	config/telescope.php157-160
Watchers\JobWatcher	Queue job processing	config/telescope.php187
Watchers\BatchWatcher	Queue job batches	config/telescope.php148
Watchers\ScheduleWatcher	Scheduled task execution	config/telescope.php219

Data Layer Watchers

Track persistence and caching operations.

Watcher Class	Purpose	Config Key
Watchers\QueryWatcher	Database query execution	config/telescope.php203-208
Watchers\ModelWatcher	Eloquent model events	config/telescope.php196-199
Watchers\CacheWatcher	Cache hit/miss/write operations	config/telescope.php150-153
Watchers\RedisWatcher	Redis command execution	config/telescope.php210

Communication Watchers

Observe external interactions and messaging.

Watcher Class	Purpose	Config Key
Watchers\MailWatcher	Email sending	config/telescope.php194
Watchers\NotificationWatcher	Notification dispatch	config/telescope.php201
Watchers\HttpClientWatcher	Outgoing HTTP requests (Guzzle)	config/telescope.php181-185
Watchers\ClientRequestWatcher	HTTP client requests (AOP-based)	config/telescope.php155

Application Watchers

Monitor internal application behavior and debugging.

Watcher Class	Purpose	Config Key
Watchers\EventWatcher	Application event dispatching	config/telescope.php167-170
Watchers\GateWatcher	Authorization gate checks	config/telescope.php174-179
Watchers\ExceptionWatcher	Exception throwing	config/telescope.php172
Watchers\LogWatcher	Log message writing	config/telescope.php189-192
Watchers\ViewWatcher	View rendering	config/telescope.php220
Watchers\DumpWatcher	Debug dump output	config/telescope.php162-165

Sources: config/telescope.php147-221 High-level system diagrams

Interception Mechanisms

Event Listener Pattern

Most watchers use Hyperf's PSR-14 event system for loose coupling:

Examples:

• QueryWatcher listens to QueryExecuted events from the database layer
• RequestWatcher listens to RequestHandled events from the HTTP server
• CacheWatcher listens to CacheHit, CacheMissed, KeyWritten events

AOP Aspect Pattern

HTTP client watchers use Aspect-Oriented Programming for transparent method interception:

Key Differences:

Aspect	Event Listeners	AOP Aspects
Coupling	Requires framework to emit events	Transparent, no framework support needed
Configuration	Enable/disable via event registration	Enable/disable via aspect weaving
Use Case	Standard framework operations	Third-party libraries (Guzzle)
Watchers	17 watchers	1 watcher (ClientRequestWatcher)

Sources: src/Aspects/GuzzleHttpClientAspect.php High-level system diagrams, config/telescope.php155

Configuration Structure

Watcher Enable/Disable

Each watcher can be configured in config/telescope.php using one of two patterns:

Boolean Configuration (simple enable/disable):

Array Configuration (with additional options):

Common Configuration Options

Option	Type	Purpose	Example Watchers
enabled	bool	Enable/disable watcher	All watchers
ignore	array	Commands/events to skip	CommandWatcher, EventWatcher
ignore_paths	array	Request paths to skip	QueryWatcher, GateWatcher
ignore_packages	bool	Skip framework packages	QueryWatcher, GateWatcher
slow	int	Threshold for slow queries (ms)	QueryWatcher
level	string	Minimum log level	LogWatcher
size_limit	int	Max payload size (KB)	RequestWatcher, HttpClientWatcher
request_size_limit	int	Max request body size (KB)	HttpClientWatcher
response_size_limit	int	Max response body size (KB)	HttpClientWatcher
hidden	array	Cache keys to hide	CacheWatcher
hydrations	bool	Record model hydrations	ModelWatcher
always	bool	Always capture (even when not recording)	DumpWatcher
ignore_http_methods	array	HTTP methods to skip	RequestWatcher
ignore_status_codes	array	Status codes to skip	RequestWatcher
ignore_abilities	array	Authorization abilities to skip	GateWatcher

Sources: config/telescope.php147-221

Data Flow Through Watchers

Key Stages

1. Event Detection: Framework fires an event (e.g., QueryExecuted)
2. Recording Check: Watcher calls Telescope::isRecording() to check if monitoring is active src/Telescope.php263-270
3. Data Extraction: Watcher extracts relevant data (SQL, bindings, duration, etc.)
4. Watcher-Level Filtering: Applies watcher-specific filters (ignore patterns, thresholds)
5. Entry Creation: Creates an IncomingEntry object with extracted data
6. Core Recording: Calls appropriate Telescope::recordX() method
7. Core Filtering: Central record() method applies global filters via $filterUsing callbacks src/Telescope.php307-311
8. Enrichment: Adds tags and user information src/Telescope.php295-304
9. Queueing: Appends entry to context-scoped ENTRIES_QUEUE src/Telescope.php308-310

Sources: src/Telescope.php275-319 src/Telescope.php263-270 High-level system diagrams

Watcher Registration

Watchers are registered during application bootstrap by TelescopeServiceProvider. The RegistersWatchers trait (used by the Telescope facade) handles the registration process:

1. Reads watcher configuration from config/telescope.php
2. Instantiates enabled watchers
3. Calls each watcher's register() method to attach event listeners

For details on the registration mechanism, see Service Provider and Bootstrap.

Sources: src/Telescope.php34 src/RegistersWatchers.php

Privacy and Sanitization

Watchers respect Telescope's privacy controls for sensitive data:

• Hidden Request Headers: Configured via Telescope::$hiddenRequestHeaders src/Telescope.php80-83
• Hidden Request Parameters: Configured via Telescope::$hiddenRequestParameters src/Telescope.php88-91
• Hidden Response Parameters: Configured via Telescope::$hiddenResponseParameters src/Telescope.php95-96

Watchers replace hidden values with ******** during data extraction. See individual watcher documentation for specific sanitization behaviors.

Sources: src/Telescope.php80-96 src/Telescope.php672-707

Performance Considerations

Watchers are designed to minimize performance impact:

1. Conditional Recording: All watchers check Telescope::isRecording() before extracting data
2. Re-entrancy Guard: IS_RECORDING flag prevents infinite loops when watchers trigger their own monitored events src/Telescope.php281-283
3. Deferred Storage: Entries are batched in memory and stored at request completion src/Telescope.php286-290
4. Configurable Size Limits: Request/response payloads can be truncated to prevent memory bloat
5. Selective Enabling: Each watcher can be individually disabled to reduce overhead

For details on storage optimization, see Storage Lifecycle Management.

Sources: src/Telescope.php275-319 config/telescope.php80 config/telescope.php147-221