telescope:clear

Purpose and Scope

This document details the telescope:clear console command, which provides a simple mechanism for removing all Telescope entries from storage. This is a destructive management operation used when you need to completely wipe the monitoring database—typically during development, after performance testing, or when resetting a development environment.

For information about removing only old entries based on retention policies, see telescope:prune. For an overview of all management commands, see Management Commands Overview.

Sources: src/Console/ClearCommand.php1-31

---

Command Overview

The telescope:clear command is a zero-argument console command that deletes all Telescope data from the configured storage backend.

Property	Value
Signature	telescope:clear
Description	Delete all Telescope data from storage
Arguments	None
Options	None
Base Class	Hypervel\Console\Command

The command is registered during the Telescope service provider bootstrap and is available immediately after installation.

Sources: src/Console/ClearCommand.php10-20

---

Command Execution Flow

The following diagram illustrates the execution path when telescope:clear is invoked:

Sources: src/Console/ClearCommand.php25-30

---

Implementation Details

Command Handler

The handle() method is the entry point for command execution. It receives a ClearableRepository instance via dependency injection and delegates the clearing operation to it:

The method signature demonstrates Hyperf's dependency injection in action—the container automatically resolves and injects the configured repository implementation.

Sources: src/Console/ClearCommand.php25-30

Dependency Resolution

The following diagram shows how the DI container resolves the ClearableRepository dependency:

The TelescopeServiceProvider binds EntriesRepository to DatabaseEntriesRepository during bootstrap, and since DatabaseEntriesRepository implements ClearableRepository, the container can inject it wherever ClearableRepository is type-hinted.

Sources: src/Console/ClearCommand.php25

---

Repository Contract

ClearableRepository Interface

The command depends on the ClearableRepository contract, which extends EntriesRepository and adds a single method:

This contract ensures that any storage backend implementing it provides a mechanism to completely remove all stored data.

Sources: src/Console/ClearCommand.php8

DatabaseEntriesRepository Implementation

The DatabaseEntriesRepository class implements clear() by truncating all three Telescope database tables:

Table	Purpose	Records Deleted
telescope_entries	Main entry storage	All entries across all types
telescope_entries_tags	Tag associations	All tag relationships
telescope_monitoring	Monitoring metadata	All monitoring records

The truncate operation is atomic and more efficient than DELETE FROM for large datasets, as it:

• Resets auto-increment counters
• Bypasses individual row deletion triggers
• Reclaims disk space immediately (in most database engines)

For detailed schema information, see Database Schema. For repository pattern documentation, see Repository Pattern.

Sources: src/Console/ClearCommand.php25-30

---

Usage Examples

Basic Usage

Clear all Telescope entries from storage:

Output:

Telescope entries cleared!

Common Use Cases

Scenario	Command	Rationale
Development reset	telescope:clear	Clear test data before starting new feature
Post-load testing	telescope:clear	Remove performance test entries
Storage troubleshooting	telescope:clear	Start fresh when debugging storage issues
Pre-deployment cleanup	telescope:clear	Clear dev data before production migration

Automation Example

Include in development setup scripts:

Sources: src/Console/ClearCommand.php15-20

---

Comparison with Related Commands

The following table contrasts telescope:clear with other Telescope management commands:

Command	Operation	Selectivity	Destructiveness	Use Case
telescope:clear	Removes all entries	None—deletes everything	Complete	Full database reset
telescope:prune	Removes old entries	Time-based retention	Partial	Routine maintenance
telescope:pause	Stops recording	N/A—no deletion	None	Temporary disable
telescope:resume	Starts recording	N/A—no deletion	None	Re-enable after pause

Key Differences:

• telescope:clear vs telescope:prune: Clear is an all-or-nothing operation, while prune respects retention policies and only removes entries older than a specified threshold. Use clear for complete resets, prune for scheduled maintenance.

• telescope:clear vs telescope:pause: Clear removes existing data but does not affect recording status. Pause stops new entries from being recorded but preserves existing data. They serve complementary purposes—pause controls input, clear removes output.

For detailed documentation on these commands, see:

• telescope:prune
• telescope:pause and telescope:resume

Sources: src/Console/ClearCommand.php20

---

Important Considerations

Destructive Nature

Warning: The telescope:clear command is irreversible. All monitoring data is permanently deleted with no confirmation prompt. Consider:

• Backup before clearing: If historical data has forensic value, export or backup entries before running the command
• Environment awareness: Verify you're targeting the correct environment (development vs. staging vs. production)
• Team coordination: Communicate with team members before clearing shared development databases

Performance Impact

While the truncate operation is generally fast, consider:

• Table locks: Some database engines lock tables during truncation
• Foreign key constraints: The three tables are truncated sequentially; ensure proper constraint configuration
• Storage reclamation: Disk space recovery timing varies by database engine

Production Environments

Best Practice: Avoid using telescope:clear in production environments. Instead:

1. Use telescope:prune with appropriate retention policies for routine maintenance
2. Configure automated pruning via scheduled tasks (see telescope:prune)
3. If complete clearing is required, coordinate downtime and verify backup procedures

Alternative Approaches

For selective data removal without using telescope:clear:

Approach	Command/Method	Selectivity	Retention
Time-based pruning	telescope:prune --hours=24	Removes entries older than threshold	Keeps recent data
Manual database deletion	SQL DELETE WHERE type = 'request'	Type-specific deletion	Granular control
Configuration filtering	Adjust watcher configuration	Prevents future recording	No data removal

Sources: src/Console/ClearCommand.php1-31

---

Architecture Context

The following diagram shows how ClearCommand fits into the broader Telescope architecture:

This architecture demonstrates:

• Contract segregation: ClearableRepository and PrunableRepository are separate contracts, allowing implementations to choose which operations to support
• Single implementation: DatabaseEntriesRepository implements all contracts, providing a unified storage backend
• Command independence: Each console command depends only on the specific contract it needs, promoting loose coupling

Sources: src/Console/ClearCommand.php1-31