Core Components

Purpose and Scope

This document provides an overview of Telescope's core components that form the foundation of the monitoring system. These components include the main Telescope static facade, the TelescopeServiceProvider for system initialization, and the context management infrastructure that enables request-scoped state tracking in Hyperf's coroutine environment.

For detailed information about specific aspects:

• The internal workings of the Telescope class are covered in Telescope Core System
• Service provider initialization logic is detailed in Service Provider and Bootstrap
• Storage lifecycle hooks and recording triggers are explained in Storage Lifecycle Management
• Context propagation and batch ID management are covered in Context and Batch Management

Sources: src/Telescope.php1-750 src/TelescopeServiceProvider.php1-180

---

Component Overview

Telescope's core system consists of four primary components that work together to provide comprehensive application monitoring:

Component	File	Primary Responsibility
Telescope Facade	src/Telescope.php	Static entry point for recording, filtering, and storage coordination
Service Provider	src/TelescopeServiceProvider.php	System initialization, watcher registration, and framework integration
Context Manager	Hyperf Context + Coroutine	Request-scoped state management and coroutine-safe data storage
Lifecycle Traits	ListensForStorageOpportunities, etc.	Hooks for detecting recording opportunities and triggering storage

These components implement a clear separation of concerns:

• The Telescope facade provides the public API and coordinates entry recording
• The service provider handles bootstrap and dependency injection
• The context system ensures coroutine-safe state management
• The lifecycle traits integrate with framework events to trigger recording

Sources: src/Telescope.php29-750 src/TelescopeServiceProvider.php18-180

---

Core Architecture

Diagram: Core Component Structure and Relationships

This diagram illustrates the architecture of Telescope's core components. The TelescopeServiceProvider initializes the system by calling Telescope::start() and binding the storage repository. The Telescope class composes four traits that provide distinct functionality. Six context keys maintain request-scoped state in Hyperf's coroutine environment. The filtering system uses static properties holding closures that process entries at different stages of the pipeline.

Sources: src/Telescope.php29-119 src/TelescopeServiceProvider.php18-48 src/Telescope.php36-46

---

Telescope Class Structure

The Telescope class serves as the static facade and central coordination point for all monitoring operations. It is implemented as a class with static methods and properties rather than a traditional facade pattern.

Class Composition

The Telescope class src/Telescope.php29-34 composes four traits:

Each trait encapsulates a distinct concern, following the single responsibility principle.

Context Constants

Six constants src/Telescope.php36-46 define the keys used to store state in Hyperf's Context system:

Constant	Type	Purpose
ENTRIES_QUEUE	array	Accumulates IncomingEntry objects during request
UPDATES_QUEUE	array	Accumulates EntryUpdate objects for existing entries
SHOULD_RECORD	bool	Master flag indicating whether recording is enabled
IS_RECORDING	bool	Re-entrancy guard preventing infinite recording loops
HAS_STORED	bool	Flag indicating whether deferred storage has been scheduled
BATCH_ID	string	UUID grouping all entries from a single request

These constants provide compile-time guarantees that context keys are consistent throughout the codebase.

Static Properties

The class maintains several static properties for configuration and hooks src/Telescope.php48-111:

Property	Type	Purpose
$filterUsing	Closure[]	Filters individual entries before queueing
$filterBatchUsing	Closure[]	Filters entire batches before storage
$afterRecordingHook	Closure	Executes after each entry is queued
$afterStoringHooks	Closure[]	Executes after batch storage completes
$tagUsing	Closure[]	Adds tags to entries during recording
$hiddenRequestHeaders	string[]	Headers to redact from request entries
$hiddenRequestParameters	string[]	Parameters to redact from request payloads
$hiddenResponseParameters	string[]	Parameters to redact from response payloads
$ignoreFrameworkEvents	bool	Whether to ignore Hypervel framework events
$useDarkTheme	bool	UI theme preference
$started	bool	Whether start() has been called
$ignoredUris	string[]	Cached list of URI patterns to ignore
$store	EntriesRepository	Storage repository instance

These properties enable runtime customization of Telescope's behavior without modifying configuration files.

Sources: src/Telescope.php29-119

---

Service Provider Structure

The TelescopeServiceProvider class src/TelescopeServiceProvider.php18-180 extends Hypervel\Support\ServiceProvider and implements the standard two-phase initialization pattern used by the Hypervel framework.

Registration Phase (register)

The register() method src/TelescopeServiceProvider.php112-122 executes during container binding and performs:

1. Configuration Merging: Merges package config with application config src/TelescopeServiceProvider.php114-117
2. Storage Driver Binding: Binds repository contracts to implementations src/TelescopeServiceProvider.php119
3. Conditional Event Enablement: Registers Redis/Cache events if watchers are enabled src/TelescopeServiceProvider.php120-121

Diagram: Service Provider Registration Phase

Sources: src/TelescopeServiceProvider.php112-179

Bootstrap Phase (boot)

The boot() method src/TelescopeServiceProvider.php23-48 executes after all service providers have registered and performs:

1. Command Registration: Makes console commands available src/TelescopeServiceProvider.php25
2. Asset Publishing Configuration: Defines publishable resources src/TelescopeServiceProvider.php26
3. Conditional Activation: Checks telescope.enabled config src/TelescopeServiceProvider.php28-30
4. Route Registration: Registers web UI routes src/TelescopeServiceProvider.php32
5. View Registration: Registers view directory src/TelescopeServiceProvider.php33
6. System Initialization: Calls Telescope::start() src/TelescopeServiceProvider.php35
7. Lifecycle Hooks: Calls Telescope::listenForStorageOpportunities() src/TelescopeServiceProvider.php36
8. Context Propagation: Configures coroutine context inheritance src/TelescopeServiceProvider.php38-47

The coroutine context propagation is critical for Hyperf's async environment:

This ensures child coroutines inherit recording state from their parent, preventing lost entries in async operations.

Sources: src/TelescopeServiceProvider.php23-48

---

Context State Flow

The following diagram shows how context state flows through the recording lifecycle:

Diagram: Context State Transitions During Recording Lifecycle

This state diagram shows the complete lifecycle of context state management. The system starts idle, transitions to recording when startRecording() is called (checking for pause status), accumulates entries in context-scoped queues while applying re-entrancy guards, schedules deferred storage on the first entry, and finally executes batch storage when the request completes.

Sources: src/Telescope.php216-243 src/Telescope.php275-319 src/Telescope.php579-637

---

Initialization Sequence

Diagram: System Initialization Sequence

This sequence diagram traces the complete initialization flow from application startup through Telescope activation. The process occurs in two phases: registration (container binding) and bootstrap (runtime initialization). The key steps are storage driver binding, watcher registration, lifecycle hook setup, and coroutine context propagation configuration.

Sources: src/TelescopeServiceProvider.php23-48 src/TelescopeServiceProvider.php112-179 src/Telescope.php123-135

---

Key Responsibilities Summary

Telescope Class

The Telescope class src/Telescope.php29-750 provides:

• Entry Recording API: 18 specialized recordX() methods for different entry types src/Telescope.php354-493
• Recording Control: startRecording(), stopRecording(), isRecording(), withoutRecording() src/Telescope.php216-270
• Filtering Configuration: filter(), filterBatch(), tag() methods src/Telescope.php529-574
• Privacy Controls: hideRequestHeaders(), hideRequestParameters(), hideResponseParameters() src/Telescope.php673-707
• Lifecycle Hooks: afterRecording(), afterStoring() src/Telescope.php549-564
• Storage Coordination: store(), executeStore() src/Telescope.php579-637
• Queue Management: getEntriesQueue(), getUpdatesQueue(), flushEntries(), flushUpdates() src/Telescope.php324-513
• Batch Management: getBatchId() src/Telescope.php665-668

TelescopeServiceProvider Class

The TelescopeServiceProvider class src/TelescopeServiceProvider.php18-180 provides:

• Dependency Injection: Binds repository contracts to implementations src/TelescopeServiceProvider.php151-179
• Configuration Management: Merges package configuration src/TelescopeServiceProvider.php114-117
• Route Registration: Registers web UI routes with middleware src/TelescopeServiceProvider.php53-63
• Asset Publishing: Defines publishable migrations, assets, config src/TelescopeServiceProvider.php76-93
• Command Registration: Makes console commands available src/TelescopeServiceProvider.php98-107
• Conditional Feature Enablement: Activates Redis/Cache events based on watcher config src/TelescopeServiceProvider.php127-146
• Coroutine Context Propagation: Ensures child coroutines inherit recording state src/TelescopeServiceProvider.php38-47

Sources: src/Telescope.php123-750 src/TelescopeServiceProvider.php18-180

---

Context Key Usage Patterns

The six context keys follow specific usage patterns throughout the codebase:

SHOULD_RECORD

Controls whether recording is active. Set by startRecording() src/Telescope.php216-234 after checking cache for pause status. Checked by isRecording() src/Telescope.php263-270 before any recording operation. Cleared by stopRecording() src/Telescope.php239-242

IS_RECORDING

Re-entrancy guard preventing infinite loops when Telescope operations trigger events that would be recorded. Set to true at the start of record() src/Telescope.php292 and cleared at the end src/Telescope.php318 Prevents nested recording when events occur during entry processing.

HAS_STORED

Optimization flag ensuring deferred storage is scheduled only once per request. Set to true when defer() is called src/Telescope.php289 Prevents redundant storage scheduling when multiple entries are recorded.

ENTRIES_QUEUE

Accumulator for IncomingEntry objects. Appended to via Context::override() src/Telescope.php308-310 Retrieved by getEntriesQueue() src/Telescope.php324-327 Flushed by flushEntries() src/Telescope.php498-503

UPDATES_QUEUE

Accumulator for EntryUpdate objects. Appended to via Context::override() src/Telescope.php346-348 Retrieved by getUpdatesQueue() src/Telescope.php332-335 Flushed by flushUpdates() src/Telescope.php508-513

BATCH_ID

UUID grouping all entries from a single request or job. Set once per request via Context::getOrSet() src/Telescope.php665-668 Used to group related entries in storage src/Telescope.php645-651

Sources: src/Telescope.php36-46 src/Telescope.php216-319 src/Telescope.php324-349