Telescope Core System

Purpose and Scope

This document provides a comprehensive technical reference for the Telescope core system, implemented primarily in the Telescope static facade class. It covers the central orchestration mechanisms including recording state management, context-based queuing, entry filtering, tagging, privacy controls, and storage coordination. This is the heart of Telescope's monitoring infrastructure.

For information about how Telescope initializes and bootstraps, see Service Provider and Bootstrap. For details on storage lifecycle management across different execution contexts, see Storage Lifecycle Management. For watcher implementations that feed data into this core system, see Watchers System.

---

Core Architecture

The Telescope class is a static facade that serves as the central orchestration point for all monitoring activities. It does not use traditional dependency injection but instead operates as a static API that coordinates between watchers, storage, and the application.

Class Structure

Sources: src/Telescope.php1-750

---

Context Management System

Telescope uses Hypervel's Context system for coroutine-safe state management. All recording state is stored in context variables rather than static properties, ensuring proper isolation in concurrent environments.

Context Keys

Constant	Value	Purpose
ENTRIES_QUEUE	telescope.entries_queue	Array of IncomingEntry objects awaiting storage
UPDATES_QUEUE	telescope.updates_queue	Array of EntryUpdate objects for existing entries
SHOULD_RECORD	telescope.should_record	Boolean indicating if recording is enabled
IS_RECORDING	telescope.is_recording	Boolean to prevent recursive recording
HAS_STORED	telescope.has_stored	Boolean indicating if storage has been deferred
BATCH_ID	telescope.batch_id	UUID grouping related entries

Context Operations

Key Methods:

• src/Telescope.php324-327 - getEntriesQueue() retrieves queued entries
• src/Telescope.php332-335 - getUpdatesQueue() retrieves queued updates
• src/Telescope.php665-668 - getBatchId() gets or generates batch UUID
• src/Telescope.php308-310 - Context::override() safely appends to queues

Sources: src/Telescope.php36-46 src/Telescope.php218-234 src/Telescope.php324-335 src/Telescope.php665-668

---

Recording State Machine

Telescope implements a multi-level state machine to control when and how entries are recorded.

State Checks

The recording state is evaluated through multiple checks:

1. Started Check - Telescope::$started must be true src/Telescope.php265-267
2. Recording Check - Context::get(SHOULD_RECORD) must be true src/Telescope.php269
3. Not Currently Recording - Context::get(IS_RECORDING) must be false src/Telescope.php281-283
4. Not Paused - Cache key telescope:pause-recording must be false src/Telescope.php225-227

State Transition Methods

Method	Purpose	Context Impact
start()	Initialize system	Sets $started = true, initializes $store
startRecording()	Enable recording	Sets SHOULD_RECORD = true, generates BATCH_ID
stopRecording()	Disable recording	Sets SHOULD_RECORD = false
withoutRecording()	Temporary disable	Saves/restores SHOULD_RECORD state
isRecording()	Check state	Reads $started and SHOULD_RECORD

Sources: src/Telescope.php123-135 src/Telescope.php216-234 src/Telescope.php239-242 src/Telescope.php247-258 src/Telescope.php263-270

---

Entry Recording Pipeline

The core recording mechanism follows a precise flow that ensures data consistency, applies filters, enriches entries, and queues for storage.

Core Recording Method

The record() method at src/Telescope.php275-319 implements the pipeline:

1. Recording Check - Verify isRecording() returns true
2. Recursion Guard - Check IS_RECORDING is not already true
3. Storage Deferral - On first entry, schedule defer(store) and set HAS_STORED
4. Recursion Flag - Set IS_RECORDING = true
5. User Enrichment - Attach authenticated user if available
6. Type and Tags - Set entry type and apply tag callbacks
7. Filtering - Run entry through all $filterUsing callbacks
8. Queuing - If passed filters, append to ENTRIES_QUEUE via Context::override()
9. After Hook - Execute $afterRecordingHook if defined
10. Cleanup - Reset IS_RECORDING = false

Sources: src/Telescope.php275-319

---

Specialized Recording Methods

Telescope provides 18 type-specific recording methods that wrap the core record() method. Each method accepts an IncomingEntry and records it with the appropriate type classification.

Recording Method Table

Method	Entry Type	Constant	Line Reference
recordBatch()	Batch Jobs	EntryType::BATCH	src/Telescope.php354-357
recordCache()	Cache Operations	EntryType::CACHE	src/Telescope.php362-365
recordCommand()	Console Commands	EntryType::COMMAND	src/Telescope.php370-373
recordDump()	Debug Dumps	EntryType::DUMP	src/Telescope.php378-381
recordEvent()	Application Events	EntryType::EVENT	src/Telescope.php386-389
recordException()	Exceptions	EntryType::EXCEPTION	src/Telescope.php394-397
recordGate()	Authorization Gates	EntryType::GATE	src/Telescope.php402-405
recordJob()	Queue Jobs	EntryType::JOB	src/Telescope.php410-413
recordLog()	Log Messages	EntryType::LOG	src/Telescope.php418-421
recordMail()	Sent Emails	EntryType::MAIL	src/Telescope.php426-429
recordNotification()	Notifications	EntryType::NOTIFICATION	src/Telescope.php434-437
recordQuery()	Database Queries	EntryType::QUERY	src/Telescope.php442-445
recordModelEvent()	Model Events	EntryType::MODEL	src/Telescope.php450-453
recordRedis()	Redis Commands	EntryType::REDIS	src/Telescope.php458-461
recordRequest()	HTTP Requests	EntryType::REQUEST	src/Telescope.php466-469
recordScheduledCommand()	Scheduled Tasks	EntryType::SCHEDULED_TASK	src/Telescope.php474-477
recordView()	View Rendering	EntryType::VIEW	src/Telescope.php482-485
recordClientRequest()	Outgoing HTTP	EntryType::CLIENT_REQUEST	src/Telescope.php490-493

Usage Pattern

Sources: src/Telescope.php354-493

---

Filtering System

Telescope implements a two-level filtering system: entry-level filters and batch-level filters.

Entry Filters

Entry filters are callbacks stored in Telescope::$filterUsing that evaluate individual entries before queuing.

Registration:

src/Telescope.php529-534

Evaluation: Entry filters are applied at src/Telescope.php307 within the record() method:

Each callback receives an IncomingEntry and must return true to allow recording. All filters must pass (AND logic).

Batch Filters

Batch filters evaluate entire batches of entries before storage.

Registration:

src/Telescope.php539-544

Evaluation: Batch filters are applied at src/Telescope.php599 within executeStore():

Each callback receives a Collection of entries and must return true to allow storage. If any filter returns false, the entire batch is discarded.

Request Filtering

In addition to programmatic filters, Telescope includes path-based filtering for HTTP requests:

Method	Purpose	Configuration
handlingApprovedRequest()	Check if request should be monitored	Uses telescope.only_paths and telescope.ignore_paths
requestIsToApprovedDomain()	Check domain whitelist	Uses telescope.domain
requestIsToApprovedUri()	Check URI patterns	Merges config with default ignored URIs
getIgnoredUris()	Build ignore list	Includes Telescope/Horizon paths

Sources: src/Telescope.php51-56 src/Telescope.php166-211 src/Telescope.php307-311 src/Telescope.php529-544 src/Telescope.php599-601

---

Tag System

Tags are labels attached to entries for categorization and filtering in the UI. Telescope provides a flexible callback-based tagging system.

Tag Registration

src/Telescope.php569-574

Callbacks are stored in Telescope::$tagUsing and receive an IncomingEntry parameter. They should return an array of tag strings.

Tag Application

Tags are applied during the recording pipeline at src/Telescope.php302-304:

All tag callbacks are invoked, and their results are merged and collapsed into a flat array.

Built-in Tag Extractors

Telescope includes specialized tag extraction:

• Mailable Tags - The ExtractsMailableTags trait (used by Telescope) provides registerMailableTagExtractor() for extracting tags from mail messages
• User Tags - User information is automatically attached at src/Telescope.php295-297

Sources: src/Telescope.php32 src/Telescope.php73-75 src/Telescope.php302-304 src/Telescope.php569-574

---

Privacy Controls

Telescope provides static arrays to hide sensitive data from recorded entries. These are applied by watchers during data extraction.

Hidden Data Configuration

Configuration Methods

Method	Target Array	Purpose	Line Reference
hideRequestHeaders()	$hiddenRequestHeaders	Add headers to hide from requests	src/Telescope.php673-681
hideRequestParameters()	$hiddenRequestParameters	Add parameters to redact from request bodies	src/Telescope.php686-694
hideResponseParameters()	$hiddenResponseParameters	Add parameters to redact from responses	src/Telescope.php699-707

Each method merges the provided array with the existing configuration and returns a new Telescope instance for method chaining.

Default Hidden Values

• Request Headers: authorization, php-auth-pw src/Telescope.php80-83
• Request Parameters: password, password_confirmation src/Telescope.php88-91
• Response Parameters: Empty by default src/Telescope.php96

Sources: src/Telescope.php78-96 src/Telescope.php673-707

---

Storage Coordination

Telescope coordinates storage through a deferred execution model that persists entries at the end of the request/job/command lifecycle.

Storage Flow

Storage Methods

store(EntriesRepository $storage) src/Telescope.php579-591

• Checks if queues are empty
• If telescope.defer is true, defers executeStore() again
• Otherwise executes executeStore() immediately

executeStore(EntriesRepository $storage) src/Telescope.php596-637

• Runs within withoutRecording() to prevent infinite loops
• Applies batch filters at src/Telescope.php599-601
• Collects entries with batch ID via collectEntries() src/Telescope.php606
• Stores entries to repository src/Telescope.php606
• Collects updates with batch ID via collectUpdates() src/Telescope.php608
• Updates existing entries src/Telescope.php608
• Dispatches ProcessPendingUpdates job for async updates src/Telescope.php610-621
• Calls terminate() on repository if TerminableRepository src/Telescope.php623-625
• Executes $afterStoringHooks src/Telescope.php627
• Flushes queues src/Telescope.php635-636

Queue Flushing

Method	Queue	Line Reference
flushEntries()	ENTRIES_QUEUE	src/Telescope.php498-503
flushUpdates()	UPDATES_QUEUE	src/Telescope.php508-513

Both methods clear the context queue and return a new Telescope instance.

Sources: src/Telescope.php285-290 src/Telescope.php498-513 src/Telescope.php579-637 src/Telescope.php642-663

---

Lifecycle Hooks

Telescope provides three hook points for custom logic during the recording and storage lifecycle.

Hook Types

After Recording Hook

Registration:

src/Telescope.php549-554

Execution: Called at src/Telescope.php313-315 within record() method after entry is queued:

Callback Signature: function(Telescope $telescope, IncomingEntry $entry)

Note: Only one after-recording hook can be active at a time (not an array).

After Storing Hooks

Registration:

src/Telescope.php559-564

Execution: Called at src/Telescope.php627 within executeStore() after successful storage:

Callback Signature: function(array $entries, string $batchId)

Note: Multiple after-storing hooks can be registered and all are executed.

Sources: src/Telescope.php61 src/Telescope.php64-68 src/Telescope.php313-315 src/Telescope.php549-564 src/Telescope.php627

---

Utility Methods

Telescope provides several utility methods for exception handling, UI configuration, and feature flags.

Exception Handling

catch(Throwable $e, array $tags = []) src/Telescope.php518-524

Converts an exception into a logged message with Telescope tags:

This is picked up by the LogWatcher which records it as a log entry.

Configuration Methods

Method	Purpose	Line Reference
recordFrameworkEvents()	Enable recording of framework events	src/Telescope.php712-717
night()	Enable dark theme	src/Telescope.php722-727
avatar(Closure)	Register avatar callback	src/Telescope.php732-737
scriptVariables()	Get JS configuration	src/Telescope.php742-749

Script Variables

The scriptVariables() method returns configuration for the frontend:

• path - Telescope UI path from config
• timezone - Application timezone
• recording - Current recording state (inverse of pause cache)

Sources: src/Telescope.php518-524 src/Telescope.php712-749

---

Summary

The Telescope class serves as the central orchestration point for the entire monitoring system. Key responsibilities include:

1. Context Management - Coroutine-safe state via six context keys
2. Recording Control - Multi-level state machine with recursion protection
3. Entry Pipeline - 18 specialized recording methods feeding a core pipeline
4. Filtering - Entry-level and batch-level filter chains
5. Tagging - Flexible callback-based tag system
6. Privacy - Configurable hiding of sensitive headers/parameters
7. Storage - Deferred execution with batch grouping
8. Lifecycle Hooks - Extensibility points for custom logic

All operations are designed for coroutine safety using Hypervel's Context system, making Telescope fully compatible with Hyperf's async architecture.

Sources: src/Telescope.php1-750