HTTP Client Watchers

Purpose and Scope

HTTP Client Watchers monitor outgoing HTTP requests made by the application to external services. Telescope provides two watcher classes for this purpose: HttpClientWatcher and ClientRequestWatcher, which work together to capture comprehensive data about HTTP client operations including request details, response data, timing information, and error states. These watchers use Aspect-Oriented Programming (AOP) for transparent method interception of Guzzle HTTP client operations.

For monitoring incoming HTTP requests to your application, see Request Watcher. For scheduled task monitoring, see Schedule Watcher.

Sources: src/Watchers/HttpClientWatcher.php1-217 src/Watchers/ClientRequestWatcher.php1-19

Architecture Overview

The HTTP client monitoring system consists of two components that work in tandem:

Diagram: HTTP Client Watcher Architecture

The ClientRequestWatcher class serves as a configuration container and registry entry, while the actual monitoring logic resides in HttpClientWatcher. The GuzzleHttpClientAspect (documented in Guzzle HTTP Client Aspect) performs the method interception and delegates to HttpClientWatcher::recordRequest().

Sources: src/Watchers/HttpClientWatcher.php19-30 src/Watchers/ClientRequestWatcher.php9-18

Component Responsibilities

HttpClientWatcher

The HttpClientWatcher class implements the core monitoring logic for outgoing HTTP requests. It extends the base Watcher class and uses the FormatsClosure trait for handling closure formatting.

Component	Responsibility
register()	No-op method since registration happens via AOP aspect
recordRequest()	Main entry point called by AOP aspect; wraps request execution with monitoring
getRequest()	Extracts request data (method, URI, headers, payload, duration)
getResponse()	Extracts response data (status, headers, body)
getRequestPayload()	Reads and formats request body with size limiting
getResponsePayload()	Reads and formats response body with size limiting
headers()	Formats and sanitizes header arrays
hideParameters()	Applies privacy controls to hide sensitive data

Sources: src/Watchers/HttpClientWatcher.php19-217

ClientRequestWatcher

The ClientRequestWatcher class is a minimal watcher that serves as a configuration container. Its register() method contains only a comment explaining that the actual implementation is in GuzzleHttpClientAspect.

Diagram: ClientRequestWatcher Configuration Role

Sources: src/Watchers/ClientRequestWatcher.php9-18

Data Capture Process

The HTTP client monitoring flow involves intercepting Guzzle requests through AOP and extracting data from the request/response lifecycle:

Diagram: HTTP Client Request Recording Sequence

The key mechanism is the injection of a custom on_stats callback in src/Watchers/HttpClientWatcher.php54-80 This callback is invoked by Guzzle after the request completes, providing access to TransferStats which contains timing information and references to the request and response objects.

Sources: src/Watchers/HttpClientWatcher.php35-83

Request Data Extraction

The getRequest() method extracts comprehensive request information from the RequestInterface and TransferStats objects:

Diagram: Request Data Extraction Flow

Request Payload Processing

The request payload extraction in src/Watchers/HttpClientWatcher.php99-128 implements several important features:

Feature	Implementation	Line Reference
Size Limiting	Configurable via request_size_limit option (default 64KB)	107-109
Truncation	Appends " (truncated...)" when size limit exceeded	109
Stream Safety	Rewinds seekable streams before and after reading	103-106, 124-126
JSON Detection	Attempts JSON decode and applies parameter hiding to structured data	113-118
Error Handling	Returns "Purged By Telescope: {error}" on exception	121-123

Sources: src/Watchers/HttpClientWatcher.php85-128

Response Data Extraction

The getResponse() method extracts response data including status code, headers, and body:

Diagram: Response Payload Processing Logic

Response Payload Special Cases

The response payload extraction in src/Watchers/HttpClientWatcher.php139-181 handles multiple special cases:

Case	Detection	Return Value
Streamed Response	!stream->isSeekable()	"Streamed Response"
Size Limited	size >= response_size_limit	Truncated content + " (truncated...)"
JSON Response	Valid JSON decode	Decoded array with hidden parameters
Text Response	Content-Type: text/plain	Raw content string
Redirect	Status 300-399	"Redirected to {Location header}"
Empty Response	Empty body content	"Empty Response"
HTML Response	Non-matching cases	"HTML Response"
Error During Read	Exception thrown	"Purged By Telescope: {error}"

Sources: src/Watchers/HttpClientWatcher.php130-181

Privacy and Security Controls

The HTTP client watchers implement comprehensive privacy controls to prevent sensitive data from being logged:

Diagram: Privacy Control Flow

Parameter Hiding Implementation

The hideParameters() method in src/Watchers/HttpClientWatcher.php207-216 uses Arr::get() and Arr::set() to support dot-notation paths for nested parameter hiding:

// Example hidden parameters:
// ['password', 'api_key', 'headers.authorization', 'data.secret_token']

// Results in masking:
{
 "password": "********",
 "api_key": "********",
 "headers": {
 "authorization": "********"
 },
 "data": {
 "secret_token": "********"
 }
}

Sources: src/Watchers/HttpClientWatcher.php186-216

Configuration Options

HTTP client watchers support the following configuration options in config/telescope.php:

Option	Type	Default	Description
enabled	bool	true	Master toggle for HTTP client monitoring
request_size_limit	int	64	Maximum request payload size in KB before truncation
response_size_limit	int	64	Maximum response payload size in KB before truncation

Per-Request Disabling

Individual requests can disable Telescope monitoring by setting the telescope_enabled option to false:

This is checked in src/Watchers/HttpClientWatcher.php47-51 where the watcher examines both the per-request options['telescope_enabled'] and the Guzzle client's configuration config['telescope_enabled'].

Sources: src/Watchers/HttpClientWatcher.php37-51 src/Watchers/HttpClientWatcher.php107-109 src/Watchers/HttpClientWatcher.php149-151

Entry Recording

HTTP client entries are recorded with the entry type "client-request" through the Telescope::recordClientRequest() method. The entry includes:

Diagram: HTTP Client Entry Structure

The hostname from the request URI is automatically added as a tag in src/Watchers/HttpClientWatcher.php71 allowing entries to be filtered by destination host in the Telescope UI.

Sources: src/Watchers/HttpClientWatcher.php69-72

Integration with Guzzle TransferStats

The watcher leverages Guzzle's TransferStats object, which provides detailed information about the HTTP transfer:

TransferStats Method	Usage in Watcher
getRequest()	Returns RequestInterface for extracting request data
getResponse()	Returns ResponseInterface or null if request failed
getTransferTime()	Returns transfer duration in seconds, converted to milliseconds

The watcher's on_stats callback is injected into the Guzzle options in src/Watchers/HttpClientWatcher.php55-80 ensuring it receives the TransferStats object after each request completes. The callback carefully preserves any pre-existing on_stats handler by calling it after Telescope's recording logic.

Sources: src/Watchers/HttpClientWatcher.php54-80 src/Watchers/HttpClientWatcher.php85-94

Error Handling

The HTTP client watchers implement defensive error handling to prevent monitoring from disrupting application functionality:

1. Top-level try-catch: The entire recording logic in the on_stats callback is wrapped in a try-catch that silently suppresses exceptions src/Watchers/HttpClientWatcher.php73
2. Stream read errors: Payload extraction catches exceptions and returns descriptive error messages src/Watchers/HttpClientWatcher.php121-173
3. Stream rewinding: Stream rewind operations are performed in finally blocks to ensure cleanup src/Watchers/HttpClientWatcher.php124-177

This ensures that even if Telescope encounters errors during data extraction, the original HTTP request continues normally and the application remains unaffected.

Sources: src/Watchers/HttpClientWatcher.php56-80 src/Watchers/HttpClientWatcher.php99-128 src/Watchers/HttpClientWatcher.php139-181