Overview

Hypervel Telescope is an application monitoring and debugging package for the Hypervel framework. It provides comprehensive observability by recording HTTP requests, database queries, cache operations, queue jobs, console commands, exceptions, and 12 additional event types during application execution. The recorded data is stored in a database and presented through a Vue.js web interface, enabling developers to debug production issues, identify performance bottlenecks, and understand application behavior.

This document provides a high-level overview of Telescope's architecture, components, and data flow. For detailed information about specific subsystems, see: Architecture for component relationships, Watchers System for data collection mechanisms, Data Storage for persistence layer details, Configuration for setup options, and Web Interface for UI documentation.

Technology Stack and Framework Position

Telescope is implemented as a Hypervel package that integrates deeply with both the Hyperf and Hypervel framework layers. The following diagram illustrates its position in the technology stack:

Technology Stack Dependencies

Layer	Component	Version	Role
Language Runtime	PHP	8.2+	Modern language features (readonly properties, enums)
Async Engine	Swoole	-	Coroutine support and asynchronous I/O
Base Framework	Hyperf	~3.1.0	Dependency injection, routing, database abstraction
Extended Framework	Hypervel	^0.3	Additional framework services and conventions
Monitoring Package	hypervel/telescope	-	Application observability and debugging

The package leverages five core Hyperf components: hyperf/context for request-scoped state management, hyperf/collection for data manipulation, hyperf/support for utility functions, hyperf/stringable for string operations, and hyperf/tappable for chainable method calls.

Sources: composer.json1-53

Package Structure and Integration Points

Telescope uses a dual-provider pattern to integrate with both framework layers:

The ConfigProvider class registers container bindings at the Hyperf level, while TelescopeServiceProvider performs high-level framework bootstrap at the Hypervel level. This dual integration enables Telescope to hook into both low-level infrastructure (dependency resolution) and high-level application services (event listeners, middleware).

Sources: composer.json36-47

Core Architecture

The system consists of six major subsystems organized into distinct architectural layers:

Core Components

Component	Class/File	Purpose
Static Facade	Telescope	Central entry point for recording, filtering, and storage coordination
Service Provider	TelescopeServiceProvider	System initialization, watcher registration, event listener setup
Lifecycle Manager	ListensForStorageOpportunities	Detects request/command start/end, triggers recording and storage
Watcher System	18+ watcher classes	Observes specific application events and creates entry records
Data Models	IncomingEntry, EntryUpdate, EntryResult	Represent entries during creation, update, and retrieval
Storage Contract	EntriesRepository	Abstract interface for entry persistence
Database Storage	DatabaseEntriesRepository	Relational database implementation of storage
Web Interface	Vue.js SPA + controllers	User interface for viewing and filtering entries

Sources: src/Telescope.php1-750 composer.json1-53

Data Flow Pipeline

Telescope processes monitoring data through a three-phase pipeline that minimizes performance impact:

Pipeline Phases

Phase 1: Data Generation

When an application event occurs (HTTP request, database query, cache hit), the corresponding watcher checks if recording is enabled via Telescope::isRecording() src/Telescope.php263-270 This method reads the SHOULD_RECORD context flag src/Telescope.php40 If enabled, the watcher extracts relevant data and creates an IncomingEntry object, then submits it to the appropriate recording method (e.g., Telescope::recordQuery() src/Telescope.php442-445).

Phase 2: Queueing

The Telescope::record() method src/Telescope.php275-319 implements re-entrancy protection using the IS_RECORDING flag src/Telescope.php42 to prevent infinite loops. Entries are enriched with user information and tags src/Telescope.php295-304 then filtered through callbacks src/Telescope.php307-311 Accepted entries are appended to the ENTRIES_QUEUE context variable src/Telescope.php36 Storage is deferred using Hyperf's defer() function src/Telescope.php286-289 scheduled only once per batch via the HAS_STORED flag src/Telescope.php44

Phase 3: Deferred Storage

At request completion, Telescope::executeStore() src/Telescope.php596-637 retrieves queued entries from the context, assigns a BATCH_ID src/Telescope.php604 for grouping, applies batch-level filters src/Telescope.php599-601 and persists to the repository src/Telescope.php606 Updates are processed separately src/Telescope.php608 and may dispatch background jobs for complex operations src/Telescope.php610-621 Finally, queues are flushed src/Telescope.php635-636 and hooks execute src/Telescope.php627

Sources: src/Telescope.php275-319 src/Telescope.php596-637

Context-Based State Management

Telescope leverages Hyperf Context for request-scoped state management, ensuring coroutine safety:

Context Variables

Constant	Value	Type	Purpose
SHOULD_RECORD	telescope.should_record	bool	Controls whether recording is active
IS_RECORDING	telescope.is_recording	bool	Re-entrancy guard to prevent infinite loops
HAS_STORED	telescope.has_stored	bool	Tracks if defer() has been scheduled
BATCH_ID	telescope.batch_id	string	UUID grouping all entries in a request
ENTRIES_QUEUE	telescope.entries_queue	array	Queued IncomingEntry objects
UPDATES_QUEUE	telescope.updates_queue	array	Queued EntryUpdate objects

Each HTTP request or console command execution operates in its own coroutine context, with these variables automatically isolated. The BATCH_ID is generated once per request using Str::orderedUuid() src/Telescope.php665-668 and used to group related entries in the database.

Sources: src/Telescope.php36-46 src/Telescope.php665-668

Storage Schema

Telescope persists data to three database tables with a denormalized schema optimized for fast writes and filtered queries:

Table Purposes

Table	Purpose	Key Columns
telescope_entries	Stores all entry records	uuid (unique identifier), batch_id (groups entries), type (entry type), content (JSON payload)
telescope_entries_tags	Many-to-many tags for filtering	entry_uuid (foreign key), tag (indexed string)
telescope_monitoring	Tracks monitored tags	tag (primary key)

The content column stores a JSON-encoded representation of entry-specific data. The family_hash column groups similar entries (e.g., repeated queries) for aggregation. Indexes on batch_id, type, created_at, and tag optimize common query patterns.

Sources: database/migrations/2025_02_08_000000_create_telescope_entries_table.php1-70

Watcher Ecosystem

Telescope includes 18+ specialized watchers that observe different aspects of application execution:

Each watcher listens for specific framework events (PSR-14) or intercepts method calls (AOP), extracts relevant data, and submits IncomingEntry objects to Telescope. Watchers are configurable via config/telescope.php and can be individually enabled/disabled or customized with ignore lists and size limits. For detailed documentation of each watcher, see Watchers System.

Sources: src/Telescope.php1-750

Web Interface

Telescope provides a Vue.js single-page application for viewing and analyzing recorded entries:

The UI is mounted at the path configured in config('telescope.path') (default: /telescope). Access is controlled by the Authorize middleware, which delegates to application-defined authorization logic. The interface provides filtering by entry type, tag, batch, and time range, with detailed views for each entry type showing request/response data, stack traces, and related entries.

For frontend architecture details, see Web Interface. For authorization configuration, see Configuration.

Sources: src/Telescope.php742-749

Performance Optimization

Telescope employs several strategies to minimize performance impact:

Strategy	Implementation	Benefit
Deferred Storage	defer() function schedules storage at request end src/Telescope.php286-289	Avoids blocking main request processing
Batch Processing	Groups entries by BATCH_ID src/Telescope.php604	Reduces database round-trips
Re-entrancy Guard	IS_RECORDING flag prevents nested recording src/Telescope.php281-283	Avoids infinite loops and overhead
Conditional Recording	isRecording() check src/Telescope.php263-270	Skips monitoring when disabled
Async Updates	Background jobs process complex updates src/Telescope.php612-615	Offloads expensive operations
Configurable Filtering	Ignore paths, commands, and custom callbacks src/Telescope.php184-211	Reduces recorded data volume

Recording can be paused system-wide via console commands see Console Commands, and the entire system can be disabled via configuration see Configuration.

Sources: src/Telescope.php123-135 src/Telescope.php216-234 src/Telescope.php275-319

Key Features Summary

• Comprehensive Monitoring: 18+ watchers cover HTTP requests, database queries, cache operations, queue jobs, console commands, scheduled tasks, exceptions, logs, and more
• Request Grouping: All entries in a single request/command execution are linked via BATCH_ID for correlation
• Tag System: Flexible tagging enables filtering by user, model, job class, or custom dimensions
• Privacy Controls: Hide sensitive headers and parameters src/Telescope.php80-96
• Filtering: Path-based, command-based, and programmatic filtering via closures
• Self-Service Debugging: Vue.js web interface provides immediate access to historical data
• Coroutine Safe: Leverages Hyperf Context for proper state isolation in Swoole environment
• Production Ready: Pause/resume recording, retention policies, and minimal overhead
• Extensible: Custom watchers, filters, tags, and storage drivers

For installation and configuration instructions, see Configuration. For extending Telescope with custom functionality, see Extension and Customization.

Sources: src/Telescope.php1-750 README.md1-4