Monitoring and Debugging

This document covers the monitoring, debugging, and observability tools built into the Hypervel framework. The system provides enhanced debugging capabilities through an improved VarDumper implementation with source resolution and editor integration, as well as comprehensive application monitoring via the Telescope system with AOP-based interception. For general exception handling, see Exception Handling and Debugging. For testing utilities, see Testing Infrastructure.

Enhanced VarDumper System

Hypervel extends Symfony's VarDumper component with source resolution capabilities that trace dump() calls to their original file locations, including support for compiled view files. The system provides both CLI and HTML dumpers with customizable editor integration.

VarDumper Registration and Configuration

The FoundationServiceProvider registers the enhanced dumpers during application bootstrap based on the VAR_DUMPER_FORMAT environment variable or SAPI detection:

src/foundation/src/Providers/FoundationServiceProvider.php181-201

Sources: src/foundation/src/Providers/FoundationServiceProvider.php181-201 src/foundation/src/Console/CliDumper.php46-53 src/foundation/src/Http/HtmlDumper.php53-60

Source Resolution and Backtrace Analysis

The ResolvesDumpSource trait provides the core logic for tracing dump() calls to their original source files:

Component	Purpose	Key Method
ResolvesDumpSource	Backtrace analysis and source resolution	resolveDumpSource()
$adjustableTraces	Maps special files to backtrace offsets	Static array property
$dumpSourceResolver	Custom resolver callback	Static property
isCompiledViewFile()	Detects compiled view files	Protected method
getOriginalFileForCompiledView()	Extracts original view path from compiled file	Protected method

The resolution algorithm:

1. Backtrace Analysis: Captures debug backtrace and searches for dump function entry point src/foundation/src/Concerns/ResolvesDumpSource.php66-88
2. Offset Adjustment: Applies special offset for known files like symfony/var-dumper/Resources/functions/dump.php src/foundation/src/Concerns/ResolvesDumpSource.php40-42
3. Compiled View Detection: Checks if file is in compiled view path src/foundation/src/Concerns/ResolvesDumpSource.php118-125
4. Original File Extraction: Parses /**PATH ... ENDPATH*/ comment from compiled views src/foundation/src/Concerns/ResolvesDumpSource.php130-139
5. Path Normalization: Converts absolute paths to relative paths for display src/foundation/src/Concerns/ResolvesDumpSource.php108-110

Sources: src/foundation/src/Concerns/ResolvesDumpSource.php56-113 src/foundation/src/Concerns/ResolvesDumpSource.php118-139

CliDumper Implementation

The CliDumper extends Symfony's CLI dumper with source annotations for console output:

src/foundation/src/Console/CliDumper.php58-76

The dumper appends source information to the last line of output before the final newline, formatted with color codes for terminal display src/foundation/src/Console/CliDumper.php81-97 The output format is: <fg=gray>// <fg=gray%s>%s%s</> where the href parameter enables clickable links in compatible terminals.

Sources: src/foundation/src/Console/CliDumper.php16-103 tests/Foundation/Console/CliDumperTest.php220-229

HtmlDumper Implementation

The HtmlDumper extends Symfony's HTML dumper with inline source annotations for browser display:

src/foundation/src/Http/HtmlDumper.php65-94

The dumper injects source HTML at two possible locations based on dump structure:

• Expanded dumps: After class=sf-dump-expanded> src/foundation/src/Http/HtmlDumper.php23
• Non-expanded dumps: Before \n</pre><script> src/foundation/src/Http/HtmlDumper.php30

The source content includes clickable links when editor configuration is available src/foundation/src/Http/HtmlDumper.php99-114

Sources: src/foundation/src/Http/HtmlDumper.php14-115 tests/Foundation/Http/HtmlDumperTest.php198-213

Editor Integration

The dumpers support deep linking to source files in various editors through the app.editor configuration:

Built-in editor protocols src/foundation/src/Concerns/ResolvesDumpSource.php16-33:

Editor	Protocol Template
phpstorm	phpstorm://open?file={file}&line={line}
vscode	vscode://file/{file}:{line}
sublime	subl://open?url=file://{file}&line={line}
cursor	cursor://file/{file}:{line}
atom	atom://core/open/file?filename={file}&line={line}

The base_path option enables path translation for Docker/remote environments src/foundation/src/Concerns/ResolvesDumpSource.php162-164

Sources: src/foundation/src/Concerns/ResolvesDumpSource.php146-171 tests/Foundation/Http/HtmlDumperTest.php215-288

Custom Casters for Framework Objects

The dumper system registers custom casters to simplify output for framework objects src/foundation/src/Providers/FoundationServiceProvider.php183-186:

This prevents verbose output of internal properties when dumping database connections, the container, event dispatcher, or query grammar objects.

Sources: src/foundation/src/Providers/FoundationServiceProvider.php181-201

Telescope Monitoring System

Telescope provides comprehensive application monitoring through a watcher architecture that records HTTP requests, database queries, cache operations, and other application events. The system uses AOP (Aspect-Oriented Programming) for transparent interception and supports deferred storage to minimize performance impact.

Telescope Configuration and Architecture

Configuration structure src/telescope/config/telescope.php1-222:

Key	Purpose	Default
enabled	Master switch for all watchers	TELESCOPE_ENABLED (true)
path	URI path for Telescope dashboard	TELESCOPE_PATH ('telescope')
driver	Storage driver for entries	TELESCOPE_DRIVER ('database')
defer	Defer storage to avoid blocking	TELESCOPE_STORE_DEFER (true)
queue.connection	Queue connection for deferred storage	TELESCOPE_QUEUE_CONNECTION
queue.delay	Delay before processing entries	TELESCOPE_QUEUE_DELAY (10)
watchers	Array of watcher classes and configs	See watcher configs

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

Watcher Configuration

Each watcher can be enabled/disabled individually and configured with specific options:

Example watcher configurations src/telescope/config/telescope.php147-221:

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

IncomingEntry Data Structure

The IncomingEntry class represents a recorded event with metadata, payload, and tagging capabilities. All watchers create IncomingEntry instances that are then processed and stored.

Key properties and methods:

• make(array $content): Factory method to create entry
• tags(array $tags): Associate tags for filtering
• Entry contains: type, content, timestamp, batch ID
• Supports parameter hiding for sensitive data

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

AOP-Based HTTP Client Monitoring

Hypervel uses Hyperf's Aspect-Oriented Programming (AOP) system to transparently intercept HTTP client requests for monitoring without modifying application code.

GuzzleHttpClientAspect Architecture

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

Join Point Interception Process

The GuzzleHttpClientAspect intercepts the Client::transfer method and delegates to HttpClientWatcher::recordRequest() src/telescope/src/Aspects/GuzzleHttpClientAspect.php23-27:

The watcher implementation:

1. Configuration Check: Verifies watcher is enabled and Telescope is recording src/telescope/src/Watchers/HttpClientWatcher.php37-41
2. Option Extraction: Retrieves request options and Guzzle client config src/telescope/src/Watchers/HttpClientWatcher.php43-44
3. Per-Request Control: Respects telescope_enabled option for opt-out src/telescope/src/Watchers/HttpClientWatcher.php47-51
4. Stats Callback Override: Replaces or wraps existing on_stats callback src/telescope/src/Watchers/HttpClientWatcher.php54-80
5. Request Continuation: Calls $proceedingJoinPoint->process() to execute original method src/telescope/src/Watchers/HttpClientWatcher.php82

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

HTTP Request/Response Recording

The on_stats callback captures comprehensive request and response data:

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

• HTTP method
• Full URI
• Request headers (with sensitive header hiding)
• Request payload (JSON decoded if possible, size-limited)
• Transfer duration in milliseconds

Response data captured src/telescope/src/Watchers/HttpClientWatcher.php130-181:

• Response status code
• Response headers
• Response body (size-limited, JSON decoded if possible)
• Special handling for redirects, empty responses, HTML responses

Sources: src/telescope/src/Watchers/HttpClientWatcher.php85-181

Sensitive Data Protection

The watcher system includes mechanisms to hide sensitive information:

Protection Method	Purpose	Implementation
hideParameters()	Mask sensitive request/response data	src/telescope/src/Watchers/HttpClientWatcher.php207-216
Telescope::$hiddenRequestHeaders	Header blacklist	Referenced in hideParameters
Telescope::$hiddenResponseParameters	Response field blacklist	Referenced in hideParameters
Size limits	Prevent huge payloads	request_size_limit, response_size_limit
telescope_enabled = false	Opt-out specific requests	Per-request option

The hideParameters() method replaces matched parameters with '********' src/telescope/src/Watchers/HttpClientWatcher.php207-216

Sources: src/telescope/src/Watchers/HttpClientWatcher.php99-128 src/telescope/src/Watchers/HttpClientWatcher.php186-216

Opting Out of Monitoring

Applications can disable monitoring for specific HTTP requests by setting the telescope_enabled option:

This is useful for high-frequency internal health checks or requests to monitoring services themselves to avoid recursion src/telescope/src/Watchers/HttpClientWatcher.php47-51

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

Stream Handling and Error Recovery

The watcher includes robust error handling for stream operations:

1. Seekable Stream Rewind: Attempts to rewind request/response streams before and after reading src/telescope/src/Watchers/HttpClientWatcher.php103-105 src/telescope/src/Watchers/HttpClientWatcher.php124-126
2. Non-Seekable Streams: Returns 'Streamed Response' for non-rewindable response bodies src/telescope/src/Watchers/HttpClientWatcher.php142-146
3. Exception Handling: Wraps all stream operations in try-catch with descriptive error messages src/telescope/src/Watchers/HttpClientWatcher.php121-123
4. Size Limit Enforcement: Reads only up to configured size limit with truncation indicator src/telescope/src/Watchers/HttpClientWatcher.php107-110

Sources: src/telescope/src/Watchers/HttpClientWatcher.php99-181