Telescope Monitoring System

Purpose and Scope

The Telescope Monitoring System provides observability and debugging capabilities for Hypervel applications through a comprehensive set of watchers that monitor various aspects of application execution. This document covers the Telescope architecture, watcher configuration, AOP-based interception, and entry recording system.

For enhanced debugging output and dumper functionality, see Enhanced VarDumper. For AOP framework details, see Aspect-Oriented Programming.

---

Architecture Overview

Telescope operates as a monitoring layer that transparently observes application events through two primary mechanisms:

1. Watcher-based monitoring: Event-driven watchers that subscribe to framework events
2. AOP-based interception: Aspect-oriented programming to intercept method calls transparently

Sources: src/telescope/config/telescope.php1-222 src/telescope/src/ConfigProvider.php1-19

---

Configuration System

Master Configuration File

Telescope is configured through config/telescope.php, which defines global settings and individual watcher configurations.

Configuration Key	Default	Purpose
enabled	env('TELESCOPE_ENABLED', true)	Master switch for all monitoring
path	env('TELESCOPE_PATH', 'telescope')	URI path for dashboard
driver	env('TELESCOPE_DRIVER', 'database')	Storage backend
defer	env('TELESCOPE_STORE_DEFER', true)	Queue storage operations
middleware	['web', Authorize::class]	Route middleware stack
watchers	Array of watcher classes	Individual watcher configuration

Sources: src/telescope/config/telescope.php10-113

Storage Configuration

The chunk parameter controls batch size for bulk inserts when storing entries.

Sources: src/telescope/config/telescope.php63-68

Queue Configuration

When defer is enabled, Telescope uses the queue system to avoid blocking request processing:

The delay parameter (in seconds) batches entries before processing to improve efficiency.

Sources: src/telescope/config/telescope.php93-97

---

Watcher Architecture

Watcher Configuration Format

Watchers can be configured in two formats:

Boolean format (simple enable/disable):

Array format (with options):

Sources: src/telescope/config/telescope.php147-221

Available Watchers

Sources: src/telescope/config/telescope.php147-221

Watcher Base Class Pattern

All watchers extend a base Watcher class and implement a register() method:

The register() method subscribes to framework events or sets up monitoring hooks.

Sources: src/telescope/src/Watchers/HttpClientWatcher.php19-30

---

HTTP Client Monitoring via AOP

Aspect Registration

The GuzzleHttpClientAspect is registered through the ConfigProvider:

Sources: src/telescope/src/ConfigProvider.php9-18

GuzzleHttpClientAspect Implementation

The aspect intercepts GuzzleHttp\Client::transfer() method calls:

Key characteristics:

• Intercepts all Guzzle HTTP client transfers
• Delegates recording logic to HttpClientWatcher
• Transparent to application code

Sources: src/telescope/src/Aspects/GuzzleHttpClientAspect.php1-28

HttpClientWatcher Request Recording

Sources: src/telescope/src/Watchers/HttpClientWatcher.php35-83

Request Data Extraction

The watcher extracts comprehensive request information:

Request data (src/telescope/src/Watchers/HttpClientWatcher.php85-94):

• method: HTTP method (GET, POST, etc.)
• uri: Full request URI
• headers: Sanitized headers (hides sensitive values)
• payload: Request body (with size limits)
• duration: Request duration in milliseconds

Response data (src/telescope/src/Watchers/HttpClientWatcher.php130-137):

• response_status: HTTP status code
• response_headers: Response headers
• response: Response body (with size limits)

Size Limiting and Truncation

Both request and response payloads are subject to configurable size limits:

The default limit is 64 KB for both requests and responses.

Sources: src/telescope/src/Watchers/HttpClientWatcher.php107-110 src/telescope/src/Watchers/HttpClientWatcher.php149-152

Parameter Hiding

Sensitive data is masked using Telescope's hidden parameter lists:

This applies to:

• Request headers: Telescope::$hiddenRequestHeaders
• Response data: Telescope::$hiddenResponseParameters

Sources: src/telescope/src/Watchers/HttpClientWatcher.php207-216

---

IncomingEntry Recording System

Entry Creation Pattern

Telescope uses IncomingEntry objects to represent monitoring data:

IncomingEntry structure:

• Contains event data as array
• Supports tagging for filtering
• Includes metadata (timestamp, type, etc.)

Sources: src/telescope/src/Watchers/HttpClientWatcher.php69-72

Recording Methods

The Telescope class provides static methods for recording different entry types:

Each method:

1. Checks Telescope::$started flag
2. Checks Telescope::isRecording() state
3. Creates IncomingEntry with appropriate type
4. Stores entry via storage driver

Sources: src/telescope/src/Watchers/HttpClientWatcher.php38-40

Filtering and Control Flow

Sources: src/telescope/src/Watchers/HttpClientWatcher.php37-51

Per-Request Opt-Out

Applications can disable Telescope for specific HTTP requests using the telescope_enabled option:

Via request options:

Via Guzzle client config:

Sources: src/telescope/src/Watchers/HttpClientWatcher.php47-51

---

Watcher-Specific Configuration

QueryWatcher Configuration

The slow threshold highlights queries exceeding the specified duration.

Sources: src/telescope/config/telescope.php203-208

RequestWatcher Configuration

Allows filtering by HTTP method and status code.

Sources: src/telescope/config/telescope.php212-217

CacheWatcher Configuration

The hidden array prevents sensitive cache keys from being recorded.

Sources: src/telescope/config/telescope.php150-153

DumpWatcher Configuration

When always is true, dumps are recorded even outside HTTP requests (e.g., in console commands).

Sources: src/telescope/config/telescope.php162-165

---

Path and Command Filtering

Path-Based Filtering

Behavior:

• If only_paths is specified, only matching paths are monitored
• ignore_paths excludes specific paths from monitoring
• Supports wildcard patterns

Sources: src/telescope/config/telescope.php126-131

Command Filtering

Console commands in this array will not be monitored by CommandWatcher. Note that some commands (migrations, queue workers) are always ignored by default.

Sources: src/telescope/config/telescope.php133-134

---

Storage and Persistence

Storage Driver Selection

The storage driver is configured via the driver key:

Available drivers:

• database: Stores entries in relational database
• null: Discards entries (useful for disabling storage in specific environments)

Sources: src/telescope/config/telescope.php61

Database Storage Schema

Database storage requires migrations that create tables for storing entries:

• telescope_entries: Main entry storage
• telescope_entries_tags: Entry tagging for filtering
• telescope_monitoring: Aggregated metrics

The chunk parameter controls bulk insert batch size for improved performance.

Sources: src/telescope/config/telescope.php64-67

Deferred Storage via Queue

When defer is enabled, entries are queued for asynchronous storage:

This prevents monitoring from blocking application execution during high-traffic periods.

Sources: src/telescope/config/telescope.php80 src/telescope/config/telescope.php96

---

Authorization and Access Control

Middleware Configuration

Telescope routes are protected by middleware:

The Authorize middleware should be customized to implement application-specific access control logic (e.g., checking user roles, IP whitelist).

Sources: src/telescope/config/telescope.php110-113

Domain and Path Configuration

The Telescope dashboard can be isolated to a subdomain or mounted at a custom path for security purposes.

Sources: src/telescope/config/telescope.php35 src/telescope/config/telescope.php48

---

Integration with DataObject Pattern

While not directly related to Telescope's core functionality, the codebase includes support for monitoring DataObject instances through the model watcher system. When Eloquent models use AsDataObject casts, Telescope can record model events including DataObject property changes.

The AsDataObject cast enables automatic serialization of DataObject instances for storage in entry payloads.

Sources: src/core/src/Database/Eloquent/Casts/AsDataObject.php1-69 src/support/src/DataObject.php574-577

---

Summary

The Telescope Monitoring System provides comprehensive observability through:

1. Flexible Configuration: Master switch, per-watcher settings, and filtering options
2. Dual Monitoring Approach: AOP interception for transparent monitoring and event-driven watchers
3. Intelligent Recording: Size limits, parameter hiding, and opt-out mechanisms
4. Efficient Storage: Deferred queue-based storage with bulk inserts
5. 20+ Watchers: Coverage for HTTP, database, cache, jobs, events, and more

The system is designed for production use with minimal performance impact through deferred storage and configurable monitoring granularity.