Protocols & Interfaces

Relevant source files

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

• src/flext_observability/protocols.py
• src/flext_observability/README.md
• src/README.md
• examples/README.md
• AGENTS.md
• tests/integration/test_phase_11_integration.py

Protocols and interfaces in the flext-observability package define the contract for monitoring, metrics, tracing, and health check capabilities across the FLEXT ecosystem. These definitions ensure that all 33 FLEXT projects adhere to a consistent observability standard, utilizing Clean Architecture and Domain-Driven Design (DDD) principles to separate domain logic from infrastructure implementations.

The architecture relies heavily on Python's typing.Protocol to define runtime-checkable interfaces. This approach facilitates Dependency Inversion (DIP), allowing the system to depend on abstractions rather than concrete implementations. Every protocol is integrated into the unified p namespace, inheriting foundation patterns like p.Result[T] for railway-oriented programming.

Sources: src/flext_observability/README.md:1-12, src/flext_observability/protocols.py:20-40

Core Observability Protocols

The system defines specialized protocols for distinct observability domains, including metrics, tracing, alerting, and health monitoring. These protocols are housed within the FlextObservabilityProtocols.Observability namespace.

Metrics Protocol

The Metrics protocol defines the standard interface for recording and managing telemetry data. It supports various metric types such as counters, gauges, and histograms.

Method	Description	Key Parameters
create_counter	Initializes a cumulative metric that only increases.	name, description, unit
create_gauge	Initializes a metric representing a single numerical value that can go up and down.	name, description, unit
record_metric	Records a specific data point for a metric.	name, value, tags

Sources: src/flext_observability/protocols.py:59-106

Tracing and Span Protocols

Tracing protocols facilitate distributed tracing by defining how spans are created, updated, and searched.

• Span Protocol: An interface for individual OpenTelemetry-compatible spans, allowing updates to attributes and status.
• Tracing Protocol: Manages the lifecycle of spans, including starting, finishing, and searching for traces across services.

Instrumentation Interfaces

The package provides specific interfaces for instrumenting different types of workloads, ranging from HTTP servers to asynchronous clients.

HTTP Instrumentation

Specialized protocols are defined for both Flask and FastAPI frameworks to enable consistent request/response monitoring.

• Flask Protocols: Defines FlaskHook, FlaskErrorHandler, and FlaskApp to intercept before_request and after_request events.
• FastAPI Protocol: Defines a simple add_middleware interface for ASGI-based instrumentation.

Sources: src/flext_observability/protocols.py:270-316

HTTP Client Protocols

To support cross-service observability, the system defines protocols for popular HTTP clients like httpx and aiohttp.

Protocol	Target	Key Methods/Properties
HTTPXRequest	Sync/Async HTTPX	headers, method, url
HTTPXResponse	Sync/Async HTTPX	status_code
AIOHTTPSession	AIOHTTP Client	request (Awaitable)

Sources: src/flext_observability/protocols.py:344-410

Infrastructure & Utility Interfaces

Beyond telemetry collection, the protocols cover operational concerns like health checks and logging.

Health and Alerting

The HealthCheck protocol allows services to register check functions and report status (Healthy, Degraded, Unhealthy). The Alerting protocol manages the lifecycle of alerts and notification rules.

Structured Logging

The Logging protocol enforces JSON-structured logging with support for correlation IDs. This ensures that logs are machine-readable and traceable across service boundaries.

# Usage pattern for Logging Protocol
def setup_logging(logger_service: p.Observability.Logging):
    result = logger_service.configure_logging({"format": "json"})
    if result.success:
        logger = logger_service.create_logger("app-service").data
        logger_service.log_message("Service started", "info")

Sources: src/flext_observability/protocols.py:195-228, src/flext_observability/README.md:120-135

Architectural Integration

The observability protocols are integrated into the FLEXT p namespace (Protocols). This allows developers to access observability-specific interfaces alongside core foundation protocols.

• Inheritance: FlextObservabilityProtocols extends the base p class, inheriting Result, Service, and Container patterns.
• DI Pattern: Implementation details are hidden; services are injected via FlextContainer and accessed through their protocol definitions.

Sources: src/flext_observability/protocols.py:20-40, AGENTS.md:§9

Conclusion

Protocols and interfaces in flext-observability provide the essential contracts required for enterprise-grade monitoring. By defining clear boundaries for metrics, tracing, health, and logging through Python protocols, the system enables highly decoupled and testable observability implementations that remain consistent across the entire FLEXT platform.