telescope:pause and telescope:resume

Purpose

This document explains the telescope:pause and telescope:resume console commands, which provide global control over Telescope's recording behavior. These commands allow administrators to temporarily disable and re-enable all Telescope watchers without modifying configuration files or restarting the application.

For information about other Telescope management commands, see Management Commands Overview. For details on clearing recorded data, see telescope:clear.

Command Overview

Telescope provides two commands for controlling recording state at runtime:

Command	Signature	Description	Effect
Pause	telescope:pause	Pause all Telescope watchers	Sets global pause flag via cache
Resume	telescope:resume	Unpause all Telescope watchers	Removes global pause flag from cache

Both commands operate by manipulating a shared cache key that is checked during the recording process. The pause state persists across application restarts and process boundaries because it is stored in the cache system.

Sources: src/Console/PauseCommand.php1-35 src/Console/ResumeCommand.php1-35

Implementation Architecture

Cache-Based State Management

Both commands use a cache-based mechanism to control recording state globally:

The cache key telescope:pause-recording serves as a global flag. When present and set to true, Telescope recording is disabled across all requests, commands, and background jobs. When absent, recording proceeds normally according to configuration.

Sources: src/Console/PauseCommand.php25-34 src/Console/ResumeCommand.php25-34

PauseCommand Implementation

Command Structure

The PauseCommand class extends the Hypervel Command base class and implements recording suspension:

Property	Value	Purpose
$signature	'telescope:pause'	Console command name
$description	'Pause all Telescope watchers'	Help text

Sources: src/Console/PauseCommand.php10-20

Execution Logic

The handle() method implements the pause logic:

Implementation details:

1. Check Current State src/Console/PauseCommand.php28: The command first checks if the pause key already exists
2. Set Pause Flag src/Console/PauseCommand.php30: If not set, stores true with a 30-day expiration using $cache->put()
3. Idempotent Behavior: Running the command multiple times is safe; it only sets the key if not already present
4. Success Message src/Console/PauseCommand.php33: Outputs confirmation to console

The 30-day TTL ensures the pause state doesn't persist indefinitely if administrators forget to resume recording.

Sources: src/Console/PauseCommand.php25-34

ResumeCommand Implementation

Command Structure

The ResumeCommand class extends the Hypervel Command base class and implements recording resumption:

Property	Value	Purpose
$signature	'telescope:resume'	Console command name
$description	'Unpause all Telescope watchers'	Help text

Sources: src/Console/ResumeCommand.php10-20

Execution Logic

The handle() method implements the resume logic:

Implementation details:

1. Check Current State src/Console/ResumeCommand.php28: The command first checks if the pause key exists
2. Remove Pause Flag src/Console/ResumeCommand.php30: If set, removes the key using $cache->forget()
3. Idempotent Behavior: Running the command multiple times is safe; it only removes the key if present
4. Success Message src/Console/ResumeCommand.php33: Outputs confirmation to console

Sources: src/Console/ResumeCommand.php25-34

Integration with Recording System

Recording Flow with Pause Check

The pause state integrates into Telescope's recording pipeline. While the provided files don't show the exact integration point, the cache key is checked during the recording decision process:

The pause check acts as an early exit in the recording decision flow. When the telescope:pause-recording cache key is present and set to true, all recording is bypassed regardless of other configuration settings.

Sources: src/Console/PauseCommand.php28-30 src/Console/ResumeCommand.php28-30

Technical Specifications

Cache Key Details

Attribute	Value	Notes
Key Name	telescope:pause-recording	Hard-coded in both commands
Value When Paused	true (boolean)	Stored as boolean, not string
Value When Active	Key absent from cache	Not stored as false
TTL When Paused	30 days	Set by now()->addDays(30)
Cache Store	Application default	Uses configured cache driver

Sources: src/Console/PauseCommand.php28-30 src/Console/ResumeCommand.php28-30

Dependency Injection

Both commands receive the CacheFactory instance via constructor injection:

Class	Injected Type	Variable	Usage
PauseCommand	Hypervel\Cache\Contracts\Factory	$cache	Parameter in handle()
ResumeCommand	Hypervel\Cache\Contracts\Factory	$cache	Parameter in handle()

The CacheFactory contract provides a framework-agnostic interface to the cache system, supporting multiple cache drivers (Redis, File, Database, Memcached, etc.) configured in the application.

Sources: src/Console/PauseCommand.php25 src/Console/ResumeCommand.php25

Use Cases

Temporary Maintenance

Pause recording during maintenance windows to prevent irrelevant entries:

Performance Troubleshooting

Disable monitoring when investigating whether Telescope itself is causing performance issues:

Load Testing

Prevent database overload during load testing by disabling entry recording:

Incident Response

Temporarily disable recording during production incidents to reduce database load:

Sources: src/Console/PauseCommand.php20 src/Console/ResumeCommand.php20

Command Execution Examples

Pausing Recording

After execution, the cache contains:

• Key: telescope:pause-recording
• Value: true
• TTL: 30 days from execution time

All Telescope watchers immediately stop recording new entries across all application processes.

Resuming Recording

After execution, the cache key telescope:pause-recording is removed, and recording resumes according to normal configuration settings.

Sources: src/Console/PauseCommand.php33 src/Console/ResumeCommand.php33

Persistence and Scope

Multi-Process Behavior

The cache-based mechanism ensures pause state is shared across:

• Web Workers: All Hyperf HTTP server workers respect the pause state
• Console Commands: Commands check pause state before recording
• Queue Workers: Background jobs respect the global pause flag
• Scheduled Tasks: Cron tasks honor the pause state

This global behavior is possible because all processes share the same cache store (typically Redis in production).

State Persistence

The pause state persists across:

• Application restarts
• Server reboots (if using persistent cache like Redis)
• Process crashes
• Framework reloads

The state does not persist:

• After 30-day TTL expiration (automatic resume)
• If cache is cleared/flushed manually
• If cache driver fails (defaults to recording enabled)

Sources: src/Console/PauseCommand.php30

Differences from Configuration-Based Control

Cache Control vs Configuration

Aspect	Cache Control (pause/resume)	Configuration Control (config/telescope.php)
Persistence	Cache store (volatile)	Configuration file (permanent)
Scope	Runtime-only	Requires code change
Application Restart	Survives restart	Requires restart to apply
Deployment	Not tracked in version control	Tracked in version control
Override Priority	Checked first	Checked after pause state
Use Case	Temporary operational control	Permanent environment configuration

The pause commands provide operational flexibility without requiring configuration file changes or deployments.

Sources: src/Console/PauseCommand.php1-35 src/Console/ResumeCommand.php1-35