HTTP Server Instrumentation

Relevant source files

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

• src/flext_observability/services/http_instrumentation.py
• src/flext_observability/README.md
• examples/README.md
• src/README.md
• tests/integration/test_phase_11_integration.py

HTTP Server Instrumentation provides automatic telemetry collection for web applications within the FLEXT ecosystem. It is designed as "zero-code-change" middleware that integrates with popular Python frameworks like Flask and FastAPI to capture request/response cycles, latency metrics, and distributed tracing context.

This module acts as an interface adapter within the Package Architecture, bridging the gap between external HTTP requests and the internal observability services such as metrics collection and structured logging. By automatically extracting correlation IDs and creating spans, it ensures consistent visibility across the service mesh.
Sources: src/flext_observability/services/http_instrumentation.py:1-25, src/flext_observability/README.md:39-65

Architecture and Components

The instrumentation logic is encapsulated in the FlextObservabilityHTTP class, which contains specialized nested classes for different web server standards (WSGI for Flask and ASGI for FastAPI).

Framework Support

The system identifies and instruments applications using type guards and specific setup methods for each framework:

Component	Target Framework	Standard	Implementation Strategy
FlextObservabilityHTTP.Flask	Flask	WSGI	Request hooks (before_request, after_request)
FlextObservabilityHTTP.FastAPI	FastAPI / Starlette	ASGI	Middleware dispatch logic

Sources: src/flext_observability/services/http_instrumentation.py:53-62, src/flext_observability/services/http_instrumentation.py:73-75

Core Instrumentation Logic

The following diagram illustrates the lifecycle of a request through the instrumentation middleware:

The instrumentation captures metadata such as HTTP method, path, client IP, and User-Agent. It also calculates http_duration_ms by comparing the start time (stored in the request context) with the completion time.
Sources: src/flext_observability/services/http_instrumentation.py:84-110, src/flext_observability/services/http_instrumentation.py:228-255

Framework Specific Implementations

Flask Instrumentation

Flask instrumentation utilizes the framework's native hook system. It leverages flask.g to store the request start time and correlation ID for the duration of the thread-local context.

• Before Request: Invokes FlextObservabilityContext.from_headers() to propagate tracing information and logs the start of the operation at DEBUG severity.
• After Request: Calculates processing time and logs the result. If the status code is $\ge 400$, the log severity is escalated to WARNING.
• Error Handling: A dedicated _error_handler captures unhandled exceptions, logs them with ERROR severity, and returns a standardized JSON error response with a 500 status code.

Sources: src/flext_observability/services/http_instrumentation.py:81-163, src/flext_observability/services/http_instrumentation.py:65-68

FastAPI and ASGI Instrumentation

The FastAPI implementation uses an async-safe middleware approach compatible with Starlette. It supports async/await patterns to ensure non-blocking telemetry collection.

Unlike the Flask implementation, the FastAPI middleware explicitly injects the X-Correlation-ID into the outgoing response headers, ensuring callers can track requests across service boundaries.
Sources: src/flext_observability/services/http_instrumentation.py:209-289, tests/integration/test_phase_11_integration.py:11-20

Telemetry and Context Propagation

The instrumentation relies on several core observability entities to process the captured data:

• Correlation ID: Extracted from incoming headers (typically X-Correlation-ID) to link logs and traces across the FLEXT ecosystem.
• Metrics: Capture http_duration_ms and status-specific counters (e.g., http.requests.total, http.request.duration_ms).
• Structured Logging: Utilizes FlextObservabilityLogging.log_with_context to ensure HTTP metadata is consistently attached to every log entry generated during the request.

Captured Metadata

Field	Source	Description
http_method	request.method	GET, POST, etc.
http_path	request.path	The requested URL path
http_client_ip	remote_addr	The IP of the requesting client
http_status	response.status_code	Numeric HTTP status (e.g., 200, 404)
http_duration_ms	Internal Timer	Total processing time in milliseconds

Sources: src/flext_observability/services/http_instrumentation.py:102-107, src/flext_observability/services/http_instrumentation.py:136-141, tests/integration/test_phase_11_integration.py:24-42

Usage Example

Developers can instrument their applications by calling the framework-specific setup_instrumentation method.

from fastapi import FastAPI
from flext_observability import FlextObservabilityHTTP

app = FastAPI()

# Zero-code-change setup
FlextObservabilityHTTP.FastAPI.setup_instrumentation(app)

@app.get("/health")
async def health_check():
    return {"status": "ok"}

Sources: src/flext_observability/services/http_instrumentation.py:214-222, examples/README.md:204-220

Conclusion

HTTP Server Instrumentation is a critical component of the FLEXT Observability platform, providing standardized monitoring for both synchronous (Flask) and asynchronous (FastAPI) web services. By automating context propagation and metric collection at the middleware layer, it enables comprehensive distributed tracing and performance analysis without requiring manual instrumentation of individual route handlers.
Sources: src/flext_observability/services/http_instrumentation.py:1-25, src/flext_observability/README.md:1-15