Request Monitoring and Storage

This document describes how Telescope captures and stores HTTP request lifecycle data. It covers the request monitoring system, storage backends (database and Elasticsearch), and the web-based viewing interface.

For general Telescope configuration and the watcher system, see Configuration and Data Collection. For development tools overview, see Development Tools.

Request Lifecycle Tracking

Telescope monitors HTTP requests through a series of event listeners that capture data at different stages of the request lifecycle. The system creates timestamped entries that record request details, response information, and execution metadata.

Monitoring Architecture

Diagram: Request Monitoring Flow

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

Event Listeners

The request monitoring system registers listeners in the ConfigProvider to observe the request lifecycle:

Listener	Purpose	Registration
RequestHandledListener	Captures completed request data including method, path, status code, duration	Registered in ConfigProvider
SetRequestLifecycleListener	Sets request lifecycle metadata and response information	Registered in ConfigProvider
BeforeHandle Event Handler	Sets telescope.recording flag before request processing begins	Fires early in request lifecycle

The telescope.recording context flag is set before request handling to ensure all subsequent operations can check whether recording is active. This prevents unnecessary data collection when Telescope is disabled.

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

Entry Data Structure

Each request creates an entry containing:

• Request Information: HTTP method, URI, headers, body content
• Response Data: Status code, headers, response body (encoded if binary)
• Timing Metrics: Request start time, duration, memory usage
• Context: User information, session data, tags
• Related Entries: Links to database queries, cache operations, HTTP client calls made during the request

Content encoding is optimized to handle binary responses efficiently, using helper functions to determine appropriate encoding strategies.

Sources: CHANGELOG-3.1.md327

Storage Architecture

Telescope provides a flexible storage architecture using the repository pattern. Storage backends can be configured independently, allowing different persistence strategies based on deployment requirements.

Repository Pattern

Diagram: Storage Repository Architecture

The repository manager resolves the configured storage driver and delegates all entry operations to the appropriate implementation. This allows seamless switching between storage backends without changing application code.

Sources: CHANGELOG-3.1.md441-444

Storage Configuration

Storage drivers are configured in telescope.php:

Configuration Key	Type	Description
telescope.storage.driver	string	Storage backend: 'database' or 'elasticsearch'
telescope.storage.connection	string	Database connection name for database driver
telescope.storage.elasticsearch.connection	string	Elasticsearch connection configuration

The storage driver is specified during repository management initialization and affects where entries are persisted.

Sources: CHANGELOG-3.1.md411-414

Database Storage Implementation

The DatabaseEntries class provides the default storage backend using a relational database. It implements efficient querying, filtering, and retrieval of entries.

Database Schema

The database storage uses a telescope_entries table with the following structure:

Column	Type	Purpose
uuid	string	Primary key, unique entry identifier
batch_id	string	Groups related entries from same request
family_hash	string	Groups similar entries for pattern analysis
type	string	Entry type: request, query, cache, etc.
content	text/json	Serialized entry data
created_at	timestamp	Entry creation time

Indexes are created on batch_id, family_hash, type, and created_at for efficient querying.

Repository Methods

The DatabaseEntries class provides methods for entry management:

Method	Parameters	Return	Purpose
store()	EntryInterface	void	Persists entry to database
find()	string $uuid	?Entry	Retrieves single entry by UUID
get()	array $filters	Collection	Queries entries with filters
delete()	string $uuid	void	Removes entry from storage
prune()	int $hours	int	Deletes entries older than specified hours

The store() method was renamed from create() for better semantic clarity, emphasizing the persistence operation.

Sources: CHANGELOG-3.1.md438

Content Encoding Optimization

The DatabaseEntries repository optimizes content encoding using helper functions:

Diagram: Content Encoding Decision Flow

The encoding strategy uses the with() helper function to conditionally apply transformations, reducing code complexity and improving readability.

Sources: CHANGELOG-3.1.md327

Elasticsearch Storage Integration

The telescope-elasticsearch component provides an alternative storage backend using Elasticsearch for high-volume deployments requiring advanced querying and retention management.

Component Architecture

Diagram: Elasticsearch Storage Architecture

Sources: CHANGELOG-3.1.md411-413 CHANGELOG-3.1.md444

Version Compatibility

The telescope-elasticsearch component supports both major versions of the official Elasticsearch PHP client:

Client Version	Elasticsearch Version	Composer Requirement
v7	7.17.0+	^7.17.0
v8	8.8.0+	^8.8.0

Version detection and API compatibility are handled automatically by the ClientFactory, which adapts method calls based on the installed client version.

Sources: CHANGELOG-3.1.md413

Index Management

The Elasticsearch storage implementation creates time-based indices with automatic rotation:

Feature	Implementation	Benefit
Index Template	Defines mapping and settings for all telescope-* indices	Consistent schema across indices
Time-based Sharding	Creates monthly indices: telescope-entries-2024.12	Efficient pruning and querying
Dynamic Mapping	Automatically adapts to new entry types	Flexible schema evolution
ILM Policies	Configurable retention and rollover rules	Automated data lifecycle

Index management is implemented in the IndexManager class, which handles template creation, index rotation, and cleanup operations.

Sources: CHANGELOG-3.1.md411

Configuration Example

Elasticsearch storage is configured in telescope.php:

The configuration specifies the Elasticsearch connection name, index naming pattern, and retention period for automatic pruning.

Sources: CHANGELOG-3.1.md416

Web Interface

Telescope provides a web-based dashboard for viewing and filtering captured entries. The interface is automatically registered and includes authorization middleware for access control.

Route Registration

Diagram: Web Interface Route Architecture

Routes are automatically registered during application bootstrap, eliminating the need for manual route configuration. The path prefix /telescope is used by default.

Sources: CHANGELOG-3.1.md432

Authorization Middleware

Default authorization middleware is provided to control access to the Telescope dashboard:

Configuration	Default	Description
telescope.middleware	['authorize']	Middleware stack for dashboard routes
telescope.authorization	Callback returning true	Authorization logic

The authorization callback can be customized to implement environment-based access control, user role checks, or IP whitelisting.

Sources: CHANGELOG-3.1.md436

Dashboard Features

The web interface provides:

Feature	Implementation	Purpose
Entry List View	React-based table with pagination	Browse all captured entries
Type Filtering	Dropdown selector for entry types	Filter by request, query, cache, etc.
Batch Grouping	Groups entries by batch_id	View all operations from single request
Detail View	Modal with formatted JSON	Inspect full entry data
Search	Query string filtering	Find specific entries by content
Time Range Selection	Date picker for created_at filtering	Narrow results to specific time periods

The interface is built with React and uses the Telescope API endpoints for data retrieval. Assets are served from the package directory and cached for performance.

Sources: CHANGELOG-3.1.md796

UI Customization

Telescope replaces Laravel branding with Hyperf branding in the web interface, adapting the UI to match the Hyperf framework's visual identity. This includes logo updates, color scheme adjustments, and framework-specific terminology.

Sources: CHANGELOG-3.1.md417

Entry Query Optimization

The repository implementations optimize entry querying for common access patterns:

Query Patterns

Pattern	Optimization	Storage Driver
Recent Entries	Index on created_at DESC	Database
Batch Retrieval	Index on batch_id	Database
Type Filtering	Index on type	Database
Time Range	Partitioned indices by month	Elasticsearch
Full-text Search	Inverted index on content fields	Elasticsearch
Family Grouping	Index on family_hash	Database

Performance Considerations

The storage architecture is designed for different deployment scenarios:

Deployment	Recommended Driver	Rationale
Low Traffic (<1000 req/day)	Database	Simple setup, no additional infrastructure
Medium Traffic (1000-10000 req/day)	Database with pruning	Reliable, familiar tooling
High Traffic (>10000 req/day)	Elasticsearch	Horizontal scaling, advanced queries
Multi-region	Elasticsearch	Cluster replication, distributed search

The prune() method should be scheduled regularly (e.g., daily) when using database storage to prevent unbounded growth. Elasticsearch automatically manages retention through ILM policies.

Sources: CHANGELOG-3.1.md432-444