HTTP Client Instrumentation

Relevant source files

The following files were used as context for generating this wiki page:

• src/flext_observability/services/http_client_instrumentation.py
• src/README.md
• src/flext_observability/README.md
• tests/integration/test_phase_11_integration.py
• examples/02_solid_observability_demo.py

Introduction

HTTP Client Instrumentation provides automatic request tracing and metrics collection for service-to-service communication within the FLEXT ecosystem. It is designed to allow developers to instrument standard Python HTTP clients, specifically httpx and aiohttp, without requiring manual changes to existing application logic. This feature ensures that every outbound request is automatically enriched with observability data, such as correlation IDs and timing metrics.

The primary purpose of this instrumentation is to facilitate distributed tracing and service-to-service correlation. By injecting standardized headers into outbound requests, the system maintains a continuous trace across microservice boundaries, which is essential for debugging and performance monitoring in complex distributed architectures.

Sources: src/flext_observability/services/http_client_instrumentation.py:1-20, src/flext_observability/README.md:55-60

Architecture and Components

The instrumentation is centered around the FlextObservabilityHTTPClient class, which serves as a container for specialized instrumentation logic for different HTTP libraries. It follows the project's Clean Architecture principles by acting as an interface adapter between the application's HTTP clients and the underlying observability services.

Core Components

Component	Description
FlextObservabilityHTTPClient	The main entry point and facade for HTTP instrumentation.
HTTPX Implementation	Nested class providing sync and async instrumentation for the httpx library.
AIOHTTP Implementation	Nested class providing async instrumentation for aiohttp client sessions.
FlextObservabilityContext	Used to retrieve current correlation, trace, and span IDs for propagation.
FlextObservabilityLogging	Handles structured logging of request/response metadata.

Sources: src/flext_observability/services/http_client_instrumentation.py:46-60, src/flext_observability/README.md:35-45

Data Flow Diagram

The following diagram illustrates how the instrumentation intercepts a standard HTTP request to inject context and record telemetry.

The diagram shows the lifecycle of an instrumented request, from context fetching to post-request telemetry logging.
Sources: src/flext_observability/services/http_client_instrumentation.py:126-175, src/flext_observability/services/http_client_instrumentation.py:284-338

Implementation Details

Context Propagation

The instrumentation ensures that three critical identifiers are propagated to downstream services via HTTP headers:

• X-Correlation-ID: Tracks a single logical transaction across multiple services.
• X-Trace-ID: Identifies the entire distributed trace.
• X-Span-ID: Identifies the specific operation within the trace.

Sources: src/flext_observability/services/http_client_instrumentation.py:133-145, src/flext_observability/services/http_client_instrumentation.py:291-303

instrumentation Logic (httpx)

For httpx, the instrumentation supports both httpx.Client (synchronous) and httpx.AsyncClient (asynchronous). The setup_instrumentation method performs monkey-patching on the client's request method to inject the traced_request wrapper.

# From src/flext_observability/services/http_client_instrumentation.py
def traced_request(
    method: str,
    url: str,
    *args: t.Scalar,
    **kwargs: t.Scalar,
) -> p.Observability.HttpClient.HTTPXResponse:
    start_time = time.time()
    correlation_id = FlextObservabilityContext.correlation_id()
    # ... header injection ...
    try:
        response = original_sync_request(method, url, *args, headers=headers, **call_kwargs)
        duration_ms = (time.time() - start_time) * 1000
        # ... logging ...
        return response
    except Exception as e:
        # ... error logging ...
        raise

Sources: src/flext_observability/services/http_client_instrumentation.py:186-248

instrumentation Logic (aiohttp)

The aiohttp implementation focuses on ClientSession objects. Similar to httpx, it wraps the session's request method and uses async/await to ensure non-blocking telemetry recording.

The sequence diagram demonstrates the asynchronous flow of header injection and response tracking.
Sources: src/flext_observability/services/http_client_instrumentation.py:307-338

Integration and Usage

Setup Patterns

Instrumentation is designed to be "zero-config" after the initial setup call. Integration typically occurs at the infrastructure layer where HTTP clients are initialized.

import httpx
from flext_observability import FlextObservabilityHTTPClient

client = httpx.Client()
FlextObservabilityHTTPClient.HTTPX.setup_instrumentation(client)
# Outbound requests now carry correlation IDs automatically

Sources: src/flext_observability/services/http_client_instrumentation.py:65-80

Integration with Phase 11 Scenarios

In advanced integration scenarios (Phase 11), HTTP instrumentation is combined with environment-aware sampling and custom metrics to provide a holistic view of system health. This includes tracking request success rates and histogram data for latency across different components like APIs and databases.

Sources: tests/integration/test_phase_11_integration.py:35-65, examples/02_solid_observability_demo.py:40-50

Conclusion

HTTP Client Instrumentation is a foundational component of the FLEXT observability stack, enabling seamless distributed tracing across httpx and aiohttp clients. By automating header propagation and duration tracking, it reduces the boilerplate required for enterprise-grade monitoring and ensures high visibility into service-to-service interactions without altering business logic.

Sources: src/README.md:15-25, src/flext_observability/README.md:150-160