Additional Watchers

This document provides an overview of the 12 watchers not covered in dedicated pages: BatchWatcher, DumpWatcher, EventWatcher, ExceptionWatcher, GateWatcher, JobWatcher, LogWatcher, MailWatcher, ModelWatcher, NotificationWatcher, RedisWatcher, and ViewWatcher. Each watcher monitors a specific aspect of application execution and records relevant data through the Telescope system.

For detailed information about other watchers, see Request Watcher, Query Watcher, Cache Watcher, Schedule Watcher, HTTP Client Watchers, and Command Watcher. For the base watcher pattern and registration mechanisms, see Watcher Overview and Base Pattern.

Additional Watchers Overview

The following table summarizes the 12 additional watchers, their primary functions, and configuration locations:

Watcher Class	Category	Purpose	Entry Type	Config Key
BatchWatcher	Infrastructure	Monitor queue job batches	batch	watchers.BatchWatcher
JobWatcher	Infrastructure	Monitor queue job execution	job	watchers.JobWatcher
ModelWatcher	Data Layer	Track Eloquent model events	model	watchers.ModelWatcher
RedisWatcher	Data Layer	Monitor Redis commands	redis	watchers.RedisWatcher
MailWatcher	Communication	Track sent emails	mail	watchers.MailWatcher
NotificationWatcher	Communication	Monitor notifications	notification	watchers.NotificationWatcher
EventWatcher	Application	Record application events	event	watchers.EventWatcher
GateWatcher	Application	Track authorization checks	gate	watchers.GateWatcher
ExceptionWatcher	Application	Capture exceptions	exception	watchers.ExceptionWatcher
LogWatcher	Application	Record log entries	log	watchers.LogWatcher
ViewWatcher	Application	Monitor view rendering	view	watchers.ViewWatcher
DumpWatcher	Application	Capture debug dumps	dump	watchers.DumpWatcher

Sources: config/telescope.php147-221

Watcher Categories and Integration

Sources: config/telescope.php147-221

Infrastructure Watchers

Infrastructure watchers monitor the execution lifecycle of background jobs and batch operations in the queue system.

BatchWatcher

The BatchWatcher monitors queue job batches, recording when batches are created, progress updates, and completion status.

Configuration:

watchers.BatchWatcher => true (boolean)

The watcher can be enabled or disabled using the TELESCOPE_BATCH_WATCHER environment variable. When enabled, it records batch metadata including batch ID, name, total jobs, pending jobs, failed jobs, and processed jobs.

Entry Type: batch

Recorded Data:

• Batch UUID
• Batch name
• Total jobs count
• Pending jobs count
• Failed jobs count
• Processed jobs count
• Progress percentage
• Finished timestamp
• Cancelled timestamp

Sources: config/telescope.php148

JobWatcher

The JobWatcher monitors the execution of individual queue jobs, capturing job class, queue name, connection, payload, and execution results.

Configuration:

watchers.JobWatcher => true (boolean)

The watcher can be enabled or disabled using the TELESCOPE_JOB_WATCHER environment variable. It records job execution start, success, and failure events.

Entry Type: job

Recorded Data:

• Job class name
• Queue connection
• Queue name
• Job payload
• Status (pending, processed, failed)
• Exception details (if failed)
• Duration

Sources: config/telescope.php187

Data Layer Watchers

Data layer watchers observe interactions with persistence mechanisms beyond the primary database, specifically Eloquent ORM events and Redis operations.

ModelWatcher

The ModelWatcher tracks Eloquent model lifecycle events including creation, updates, deletions, and model hydrations.

Configuration:

• enabled: Master enable/disable switch (env: TELESCOPE_MODEL_WATCHER)
• hydrations: Whether to record model hydration events (when models are populated from database results)

Entry Type: model

Recorded Data:

• Model class name
• Event type (created, updated, deleted, restored, retrieved, etc.)
• Model attributes
• Changed attributes (for updates)
• Database connection

Sources: config/telescope.php196-199

RedisWatcher

The RedisWatcher monitors Redis commands executed by the application, useful for debugging cache operations and session management.

Configuration:

watchers.RedisWatcher => true (boolean)

The watcher can be enabled or disabled using the TELESCOPE_REDIS_WATCHER environment variable.

Entry Type: redis

Recorded Data:

• Redis connection name
• Command name
• Command parameters
• Execution time

Sources: config/telescope.php210

Communication Watchers

Communication watchers track outbound notifications and messages sent by the application.

MailWatcher

The MailWatcher records emails sent through the mail system, capturing recipient information, subject lines, and mail content.

Configuration:

watchers.MailWatcher => true (boolean)

The watcher can be enabled or disabled using the TELESCOPE_MAIL_WATCHER environment variable.

Entry Type: mail

Recorded Data:

• Mailable class name
• Recipients (to, cc, bcc)
• Subject line
• HTML body
• Plain text body
• Attachments

Sources: config/telescope.php194

NotificationWatcher

The NotificationWatcher monitors notifications sent through notification channels (mail, database, SMS, etc.).

Configuration:

watchers.NotificationWatcher => true (boolean)

The watcher can be enabled or disabled using the TELESCOPE_NOTIFICATION_WATCHER environment variable.

Entry Type: notification

Recorded Data:

• Notification class name
• Notifiable type and ID
• Notification channels
• Notification data/payload

Sources: config/telescope.php201

Application Watchers

Application watchers provide deep insights into internal application behavior including events, authorization, errors, logging, rendering, and debugging.

EventWatcher

The EventWatcher records application events dispatched through the PSR-14 event system, providing visibility into event-driven application logic.

Configuration:

• enabled: Master enable/disable switch (env: TELESCOPE_EVENT_WATCHER)
• ignore: Array of event class names to exclude from recording

Entry Type: event

Recorded Data:

• Event class name
• Event payload/properties
• Listeners that handled the event
• Broadcasting information (if event is broadcast)

Sources: config/telescope.php167-170

GateWatcher

The GateWatcher monitors authorization checks performed through gates and policies, useful for debugging permission issues.

Configuration:

• enabled: Master enable/disable switch (env: TELESCOPE_GATE_WATCHER)
• ignore_abilities: Array of ability names to exclude
• ignore_packages: Whether to ignore checks from vendor packages
• ignore_paths: Array of file path patterns to ignore

Entry Type: gate

Recorded Data:

• Ability/permission name
• Result (allowed/denied)
• User performing the check
• Arguments passed to the gate
• File and line where check occurred

Sources: config/telescope.php174-179

ExceptionWatcher

The ExceptionWatcher captures exceptions thrown during application execution, providing stack traces and context information for debugging.

Configuration:

watchers.ExceptionWatcher => true (boolean)

The watcher can be enabled or disabled using the TELESCOPE_EXCEPTION_WATCHER environment variable. It uses the specialized IncomingExceptionEntry class for enhanced exception handling.

Entry Type: exception

Entry Class: IncomingExceptionEntry src/IncomingExceptionEntry.php10-47

Recorded Data:

• Exception class name
• Exception message
• File path and line number
• Stack trace
• Exception code
• Previous exceptions (nested)

The IncomingExceptionEntry class extends IncomingEntry with exception-specific methods:

• isReportableException(): Checks if the exception should be reported based on exception handler configuration src/IncomingExceptionEntry.php27-30
• familyHash(): Generates a hash based on file and line number to group similar exceptions src/IncomingExceptionEntry.php43-46

Sources: config/telescope.php172 src/IncomingExceptionEntry.php1-47

LogWatcher

The LogWatcher records log messages written through the logging system, filtered by minimum log level.

Configuration:

• enabled: Master enable/disable switch (env: TELESCOPE_LOG_WATCHER)
• level: Minimum log level to record (debug, info, notice, warning, error, critical, alert, emergency)

Entry Type: log

Recorded Data:

• Log level
• Log message
• Log context (additional data)
• File and line where log was written

Sources: config/telescope.php189-192

ViewWatcher

The ViewWatcher monitors view rendering operations, recording which templates are used and the data passed to them.

Configuration:

watchers.ViewWatcher => true (boolean)

The watcher can be enabled or disabled using the TELESCOPE_VIEW_WATCHER environment variable.

Entry Type: view

Recorded Data:

• View name/path
• View data (variables passed to the template)
• Composers and creators executed
• Render duration

Sources: config/telescope.php220

DumpWatcher

The DumpWatcher captures debug dump operations (e.g., dump(), dd() calls), preserving debugging output for later inspection.

Configuration:

• enabled: Master enable/disable switch (env: TELESCOPE_DUMP_WATCHER)
• always: Whether to record dumps even when Telescope recording is disabled (env: TELESCOPE_DUMP_WATCHER_ALWAYS)

Entry Type: dump

Recorded Data:

• Dumped variable(s)
• Variable type and value
• File and line where dump occurred

The always option allows dumps to be recorded even during local development when Telescope is otherwise disabled, making it useful for capturing intermittent debugging output.

Sources: config/telescope.php162-165

Event-to-Watcher Integration Flow

Sources: src/IncomingExceptionEntry.php1-47 src/Watchers/CacheWatcher.php28-40

Common Configuration Patterns

All watchers follow consistent configuration patterns in config/telescope.php147-221:

Boolean Configuration

Simplest watchers use a boolean value directly:

This can be controlled via environment variables: TELESCOPE_BATCH_WATCHER, TELESCOPE_JOB_WATCHER, TELESCOPE_EXCEPTION_WATCHER.

Array Configuration with Enabled Flag

More complex watchers use an array with an enabled key:

Configuration Options by Type

Ignore Lists: Filter out specific events or abilities

Level Thresholds: Minimum severity to record

Feature Toggles: Enable/disable specific sub-features

Sources: config/telescope.php147-221

Watcher Registration and Lifecycle

All additional watchers extend the base Watcher class and implement the register() method to attach event listeners:

Sources: src/Watchers/CacheWatcher.php28-40