Configuration and Data Collection

This document covers the Telescope configuration system, storage driver options, watcher architecture, and the entry creation pipeline. Telescope is a real-time debugging and monitoring dashboard that passively observes application activity through a watcher-based system. For information about the web interface and querying stored entries, see Request Monitoring and Storage.

Configuration Overview

Telescope configuration is managed through the config/autoload/telescope.php file, which controls recording behavior, storage backends, and watcher registration. The component was refactored in v3.1.49 to use an enum-based record_mode system for improved type safety.

Core Configuration Structure

The configuration file defines several key settings:

Configuration Key	Type	Purpose
enabled	boolean	Master toggle for Telescope functionality (default: true)
record_mode	RecordMode enum	Controls when entries are recorded
storage.driver	string	Storage backend selection (database or elasticsearch)
storage.connection	string	Database connection name for database driver
path	string	Web UI route path (default: telescope)
middleware	array	Middleware stack for web routes

The record_mode replaced the deprecated save_mode configuration and uses a dedicated enum class for type-safe recording control.

Sources: CHANGELOG-3.1.md435 High-Level Diagram 2

RecordMode Enum System

The RecordMode enum provides three recording strategies:

The FetchRecordingOnBootListener evaluates the record_mode at boot time and stores the recording state in Hyperf's coroutine context as telescope.recording. The SetRequestLifecycleListener ensures this state is properly initialized before request handling begins.

Sources: CHANGELOG-3.1.md435 CHANGELOG-3.1.md15 CHANGELOG-3.1.md295-296

Storage Driver Configuration

Telescope supports two storage backends with distinct performance and scalability characteristics.

Database Storage Driver

The database driver stores entries in a relational database using Hyperf's database component. This is the default option suitable for most applications.

The DatabaseEntries repository implements entry storage, retrieval, and querying operations. Content encoding optimizations were added in v3.1.56 to handle large entry payloads efficiently.

Configuration keys:

• storage.driver: Set to 'database'
• storage.connection: Database connection name (defaults to default connection)
• storage.database.chunk: Batch size for bulk operations

Sources: CHANGELOG-3.1.md327 CHANGELOG-3.1.md441 CHANGELOG-3.1.md783

Elasticsearch Storage Driver

The telescope-elasticsearch component (added in v3.1.49) provides Elasticsearch-based storage for high-volume scenarios. It supports both Elasticsearch v7 and v8.

The Elasticsearch driver creates separate indices for each entry type and implements automatic index management including lifecycle policies and mappings.

Configuration keys:

• storage.driver: Set to 'elasticsearch'
• storage.elasticsearch.client: Elasticsearch client configuration
• storage.elasticsearch.index_prefix: Index name prefix (default: telescope_)

Sources: CHANGELOG-3.1.md444 CHANGELOG-3.1.md785 CHANGELOG-3.1.md791 CHANGELOG-3.1.md793

Watcher System Architecture

Watchers are observer classes that passively monitor specific aspects of application behavior and create entries when relevant events occur. The watcher system follows an event-driven architecture where watchers register as listeners for Hyperf framework events.

Watcher Registration and Activation

Each watcher class:

1. Registers as a listener for specific framework events
2. Checks Context::get('telescope.recording') before creating entries
3. Extracts relevant data from the event payload
4. Creates appropriately typed entries via Telescope::recordXxx() methods

Sources: CHANGELOG-3.1.md393 CHANGELOG-3.1.md15 High-Level Diagram 3

Watcher Categories

Watcher Type	Observes	Event Triggers
RequestWatcher	HTTP requests	RequestHandled, RequestTerminated
CommandWatcher	Console commands	BeforeCommand, AfterCommand
QueryWatcher	Database queries	QueryExecuted
RedisWatcher	Redis operations	RedisCommandExecuted
ExceptionWatcher	Exceptions	ExceptionHandled
ScheduleWatcher	Cron jobs	ScheduleRun, ScheduleFinished
ClientWatcher	Outgoing HTTP	Guzzle middleware integration

The RedisCommandExecutedListener was enhanced in v3.1.56 to provide comprehensive Redis command tracking across all connection types.

Sources: CHANGELOG-3.1.md329 CHANGELOG-3.1.md393

Entry Creation Pipeline

Entries flow through a multi-stage pipeline from observation to persistent storage. The pipeline ensures entries are properly formatted, tagged, and batched for efficiency.

Entry Lifecycle

Entry Structure

Each entry is represented as an IncomingEntry object with standardized fields:

Field	Description
uuid	Unique identifier for the entry
type	Entry type (request, command, query, etc.)
batch_id	UUID linking related entries
content	JSON-encoded entry-specific data
tags	Array of searchable tags
created_at	Timestamp of creation

The content field structure varies by entry type. For example, query entries include SQL, bindings, and execution time, while request entries contain URL, method, status, and controller information.

Sources: CHANGELOG-3.1.md327 CHANGELOG-3.1.md441

Batch Processing and Storage

Entries are buffered during request/command execution and flushed in batches at termination. The DatabaseEntries repository uses chunked inserts for efficiency, while the Elasticsearch driver leverages the bulk API for index operations.

The entry storage was refactored in v3.1.49 to improve the repository management architecture and enhance querying capabilities.

Sources: CHANGELOG-3.1.md780 CHANGELOG-3.1.md783-784 CHANGELOG-3.1.md441

Integration with Elasticsearch

The Elasticsearch integration provides advanced features for high-volume deployments.

Index Management

The telescope:install command initializes Elasticsearch indices with proper mappings and index lifecycle management (ILM) policies. Each entry type gets a dedicated index for optimal query performance.

Index names follow the pattern: {prefix}_{type}_{date} where:

• prefix: Configurable prefix (default: telescope)
• type: Entry type (requests, queries, etc.)
• date: Optional date suffix for time-based partitioning

Sources: CHANGELOG-3.1.md791 CHANGELOG-3.1.md793 CHANGELOG-3.1.md797

Version Compatibility

The Elasticsearch driver supports both major versions through a compatibility layer:

Elasticsearch Version	Client Package	Features
v7.17+	elasticsearch/elasticsearch:^7.17.0	Standard APIs, ILM
v8.8+	elasticsearch/elasticsearch:^8.8.0	New APIs, enhanced ILM

The repository automatically adapts to the installed client version, ensuring seamless operation across different Elasticsearch deployments.

Sources: CHANGELOG-3.1.md793 CHANGELOG-3.1.md413

Authorization and Security

Telescope includes authorization middleware to restrict access to the web interface. The default authorization is configured to allow all access in local environments and deny all in production.

Users should implement custom authorization logic in the telescope.php configuration file to secure production deployments:

The authorization system was added as a default feature in v3.1.49 to prevent accidental exposure of debugging data.

Sources: CHANGELOG-3.1.md776 CHANGELOG-3.1.md433