Watcher Overview and Base Pattern

Purpose and Scope

This document explains the watcher pattern used throughout Telescope's data collection system. Watchers are specialized observers that monitor specific aspects of application execution—such as HTTP requests, database queries, or cache operations—and record relevant data for later analysis. This page covers the base watcher architecture, registration mechanisms, and integration patterns. For details on specific watcher implementations, see sections 2.3.2 through 2.3.8. For information on how watchers submit data to the storage layer, see 2.1.1.

Watcher Architecture

Watchers form the data collection layer of Telescope, acting as specialized observers that monitor different execution contexts within the application. Each watcher focuses on a specific domain (HTTP requests, database queries, cache operations, etc.) and extracts relevant diagnostic information.

Watcher Registry

Telescope includes 18+ specialized watchers organized into four functional categories:

Category	Watchers	Purpose
Infrastructure	RequestWatcher, CommandWatcher, JobWatcher, ScheduleWatcher, BatchWatcher	Monitor application execution contexts
Data Layer	QueryWatcher, ModelWatcher, CacheWatcher, RedisWatcher	Track persistence and caching operations
Communication	MailWatcher, NotificationWatcher, ClientRequestWatcher, HttpClientWatcher	Observe external interactions
Application	EventWatcher, GateWatcher, ExceptionWatcher, LogWatcher, ViewWatcher, DumpWatcher	Monitor internal application behavior

All watchers are configured in the watchers array within config/telescope.php147-221

Sources: config/telescope.php147-221

Watcher Integration Diagram

Sources: src/Watchers/RequestWatcher.php26-60 src/Watchers/CacheWatcher.php18-40

Base Watcher Pattern

All watchers follow a consistent pattern by extending a base Watcher class. While the base class file is not directly visible in the provided code, its contract is evident from concrete implementations.

Core Responsibilities

Each watcher implementation provides:

1. Event Registration: Subscribe to relevant framework events or system hooks
2. Recording Guard: Check if recording is currently enabled before processing
3. Data Extraction: Transform raw event data into structured entry content
4. Entry Creation: Build IncomingEntry objects with type-specific data
5. Entry Submission: Submit entries to the Telescope core for storage

Watcher Class Structure

Sources: src/Watchers/RequestWatcher.php26-118 src/Watchers/CacheWatcher.php18-117

Registration System

Watchers are registered during application bootstrap through the TelescopeServiceProvider. Each watcher's register() method is invoked with the DI container, allowing it to resolve dependencies and subscribe to events.

Registration Flow

Sources: src/Watchers/RequestWatcher.php51-60

Configuration Integration

Watcher configuration from config/telescope.php is passed to each watcher as an options array. Configuration can be:

1. Boolean: Simple enable/disable toggle
2. Array: Detailed configuration with enabled key and additional options

Example configuration patterns:

The options array is accessible to watcher implementations via the $this->options property.

Sources: config/telescope.php147-221 src/Watchers/RequestWatcher.php125-145

Event Integration

Watchers integrate with the framework through PSR-14 event dispatching, providing loose coupling between application code and monitoring logic.

Event Listener Pattern

The standard pattern for event-based watchers:

1. Obtain Event Dispatcher: Resolve EventDispatcherInterface from the container
2. Register Listeners: Call listen() with event class and callback
3. Handle Events: Implement callback methods that receive event objects

Example from RequestWatcher:

src/Watchers/RequestWatcher.php58-60

Recording Guard Pattern

Every event handler implements a recording guard to prevent data collection when disabled:

src/Watchers/RequestWatcher.php88-93

The guard checks:

• Telescope::isRecording(): Global recording state from context
• Watcher-specific filters: HTTP methods, status codes, paths, etc.

Sources: src/Watchers/RequestWatcher.php86-93 src/Watchers/CacheWatcher.php59-63

Watcher Lifecycle

Complete Recording Flow

Sources: src/Watchers/RequestWatcher.php86-118 src/Watchers/CacheWatcher.php59-70

Data Extraction Patterns

Watchers extract event-specific data and transform it into a normalized format suitable for storage:

Request Data Extraction src/Watchers/RequestWatcher.php99-114:

• IP address, URI, HTTP method
• Controller action and middleware stack
• Request headers and payload
• Response headers, status, and body
• Execution duration and memory usage
• Request context from Hyperf Context

Cache Data Extraction src/Watchers/CacheWatcher.php65-69:

• Operation type (hit, missed, set, forget)
• Cache key
• Value (with optional hiding)
• Expiration time (for writes)

Privacy Controls: Watchers apply privacy filters to hide sensitive data using the hideParameters() pattern src/Watchers/RequestWatcher.php177-186:

This pattern masks values for configured parameter names (passwords, tokens, etc.) before storage.

Sources: src/Watchers/RequestWatcher.php99-186 src/Watchers/CacheWatcher.php122-138

Configuration Options

Watcher-Specific Options

Each watcher class has access to its configuration via $this->options. Common option patterns:

Option Type	Purpose	Example Watchers
ignore_*	Filter out specific items	ignore_http_methods, ignore_status_codes, ignore_commands
size_limit	Limit data capture size	size_limit (RequestWatcher), request_size_limit (HttpClientWatcher)
hidden	Hide sensitive data	hidden (CacheWatcher)
slow	Performance thresholds	slow (QueryWatcher)
level	Severity filtering	level (LogWatcher)

Special Configuration Requirements

Some watchers require additional configuration setup:

CacheWatcher src/Watchers/CacheWatcher.php46-54: Requires cache events to be enabled before cache system initialization:

This static method must be called during service provider boot before cache drivers are instantiated.

RequestWatcher src/Watchers/RequestWatcher.php62-81: Enables request lifecycle events in Hyperf HTTP server:

This ensures RequestReceived and RequestHandled events are dispatched.

Sources: src/Watchers/CacheWatcher.php46-54 src/Watchers/RequestWatcher.php62-81 config/telescope.php147-221

Entry Submission Methods

Watchers submit entries through type-specific recording methods on the Telescope facade:

Method	Entry Type	Example Watcher
recordRequest()	request	RequestWatcher
recordCache()	cache	CacheWatcher
recordQuery()	query	QueryWatcher
recordCommand()	command	CommandWatcher
recordJob()	job	JobWatcher
recordException()	exception	ExceptionWatcher
recordEvent()	event	EventWatcher
recordLog()	log	LogWatcher
recordMail()	mail	MailWatcher
recordNotification()	notification	NotificationWatcher
recordScheduledCommand()	scheduled_task	ScheduleWatcher
recordClientRequest()	client_request	HttpClientWatcher
recordGate()	gate	GateWatcher
recordModelEvent()	model	ModelWatcher
recordRedis()	redis	RedisWatcher
recordView()	view	ViewWatcher

Each method automatically sets the appropriate entry type and forwards the entry to the internal queueing system for batch processing.

Sources: src/Watchers/RequestWatcher.php99 src/Watchers/CacheWatcher.php65

Specialized Entry Types

Some watchers create specialized entry subclasses for domain-specific behavior:

IncomingExceptionEntry src/IncomingExceptionEntry.php10-47: Extends IncomingEntry to carry the actual exception instance and provide exception-specific methods:

• isReportableException(): Checks if exception should be reported via exception handler
• isException(): Type identification override
• familyHash(): Groups related exceptions by file and line number

This demonstrates how watchers can create custom entry types when the base IncomingEntry class needs additional behavior or properties.

Sources: src/IncomingExceptionEntry.php10-47