 |
VOOZH | about |
|
VOOZH | about |
Telescope is a real-time debugging and monitoring dashboard for Hyperf applications. It provides visibility into HTTP requests, database queries, scheduled tasks, and other application events through a web-based interface with multiple storage backend options.
This document covers the core Telescope component. For information about the Elasticsearch storage driver, see Telescope Elasticsearch Driver.
Telescope operates as a passive observation layer that captures application events through a watcher system, stores entries in a configurable backend, and provides a web interface for browsing collected data.
System Architecture: Telescope Data Collection and Storage Pipeline
Sources: CHANGELOG-3.1.md15-16 CHANGELOG-3.1.md329 CHANGELOG-3.1.md393 CHANGELOG-3.1.md432-444
Telescope configuration is managed through a telescope.php configuration file with several key settings that control data collection behavior, storage backend selection, and access control.
The record_mode configuration option controls when entries are captured. It uses an enum-based system with the following values:
| Record Mode | Description |
|---|---|
all | Captures all application events regardless of status |
only_errors | Captures only requests and events that result in errors |
selective | Captures based on custom criteria defined by watchers |
The record mode defaults to all but can be configured per environment. The recording state is managed through context storage and can be dynamically toggled.
Sources: CHANGELOG-3.1.md435 CHANGELOG-3.1.md295-296
Storage Driver Selection Flow
The storage driver is configured in the storage section of the configuration file. The EntriesRepositoryManager class resolves the appropriate repository implementation based on this configuration.
Sources: CHANGELOG-3.1.md412 CHANGELOG-3.1.md441 CHANGELOG-3.1.md413
Watchers are individual components that observe specific types of application events. Each watcher can be enabled or disabled independently through configuration:
| Watcher Type | Observes |
|---|---|
RequestWatcher | HTTP request/response lifecycle |
QueryWatcher | Database query execution |
RedisWatcher | Redis command execution |
ScheduleWatcher | Scheduled task execution |
ExceptionWatcher | Application exceptions |
ClientRequestWatcher | Outgoing HTTP client requests |
Sources: CHANGELOG-3.1.md329 CHANGELOG-3.1.md393
Telescope integrates deeply with the Hyperf request lifecycle to capture comprehensive information about each HTTP request.
Request Lifecycle Event Flow
The SetRequestLifecycleListener listens to the BeforeHandle event to establish the recording context early in the request lifecycle. The RequestHandledListener then captures the completed request/response data when the RequestHandled event fires.
Sources: CHANGELOG-3.1.md15 CHANGELOG-3.1.md295-296
The GuzzleHttpClientAspect aspect intercepts outgoing HTTP client requests made through Guzzle to record them in Telescope. Recent optimizations improve how client request recording handles binary responses and large payloads.
Guzzle HTTP Client Request Recording
Sources: CHANGELOG-3.1.md16 CHANGELOG-3.1.md37 CHANGELOG-3.1.md328
The storage layer abstracts entry persistence through a repository pattern, allowing different backend implementations while maintaining a consistent interface.
Repository Management and Storage Backends
The EntriesRepositoryManager centralizes repository instantiation and management. It supports dependency injection of different repository implementations based on configuration.
Sources: CHANGELOG-3.1.md443 CHANGELOG-3.1.md327 CHANGELOG-3.1.md440
The DatabaseEntriesRepository uses Hyperf's database models to persist entries. It implements methods for:
store(IncomingEntry $entry) - Persists a new entryfind($id) - Retrieves an entry by UUIDget($type, $options) - Queries entries with filteringdelete($id) - Removes an entryEntry content is stored with optimized encoding to handle various data types including binary responses:
Entry Content Encoding Pipeline
Sources: CHANGELOG-3.1.md327 CHANGELOG-3.1.md437-438
The repository layer supports sophisticated querying capabilities:
| Query Parameter | Purpose |
|---|---|
type | Filter by entry type (request, query, redis, etc.) |
family_hash | Group related entries |
tag | Filter by tag values |
before_sequence | Pagination cursor |
limit | Result set size |
Sources: CHANGELOG-3.1.md440
Telescope automatically registers HTTP routes for the web interface during bootstrap, providing a dashboard for browsing collected entries.
Route Registration and Middleware Pipeline
Routes are automatically registered through the component's ConfigProvider and protected by the AuthorizationMiddleware.
Sources: CHANGELOG-3.1.md432 CHANGELOG-3.1.md436
The AuthorizationMiddleware provides access control for the Telescope interface. By default, it implements a simple authorization check that can be customized:
Authorization Flow
The middleware can be configured to check user permissions, IP allowlists, or environment-based access rules.
Sources: CHANGELOG-3.1.md436
The Telescope UI is served through dedicated controllers that query the repository layer and render views. The interface has been updated to replace Laravel branding with Hyperf-specific branding.
Sources: CHANGELOG-3.1.md417
Telescope can monitor scheduled tasks (cron jobs) through a dedicated listener and watcher.
Scheduled Task Recording Flow
The ScheduleListener observes cron task execution events and coordinates with the ScheduleWatcher to create schedule entries containing task metadata, execution duration, and output.
Sources: CHANGELOG-3.1.md393
Telescope captures exceptions through the ExceptionWatcher, creating entries that include stack traces, context data, and related request information.
| Field | Description |
|---|---|
class | Exception class name |
message | Exception message |
file | File where exception occurred |
line | Line number |
trace | Stack trace array |
context | Request/context data |
Exception entries are automatically linked to their parent request entry through the family_hash field, allowing correlation of exceptions with the requests that triggered them.
Sources: CHANGELOG-3.1.md442
Telescope uses Hyperf's context system to manage recording state across coroutines. The recording flag is stored in context and checked by watchers before creating entries.
Recording State Context Management
The FetchRecordingOnBootListener initializes the recording state at application boot, while SetRequestLifecycleListener sets request-specific recording context.
Sources: CHANGELOG-3.1.md295-296 CHANGELOG-3.1.md15
The database storage backend relies on proper indexing for efficient queries. The schema includes indexes on:
type column for filtering by entry typefamily_hash for grouping related entriescreated_at for time-based queriesUnique constraints are applied to prevent duplicate entries while handling high-throughput scenarios.
Sources: CHANGELOG-3.1.md409
To prevent unbounded growth, Telescope entries should be periodically pruned. The repository provides methods for deleting entries older than a specified threshold. This can be automated through a scheduled task.
Recent improvements handle binary response content more efficiently by detecting binary data and applying appropriate encoding before storage, preventing memory issues with large payloads.
Sources: CHANGELOG-3.1.md37 CHANGELOG-3.1.md328
Sources: CHANGELOG-3.1.md435 CHANGELOG-3.1.md412 CHANGELOG-3.1.md436
Telescope entries can be inspected during testing to verify application behavior. The test suite includes helpers for:
Tests are organized under the telescope group in the Pest configuration.
Sources: tests/Pest.php35
Refresh this wiki