API Surface & Facades
Relevant source files
The following files were used as context for generating this wiki page:
The FLEXT Observability API surface provides a multi-layered interface for monitoring, metrics collection, distributed tracing, and health checks. It is designed around Clean Architecture and Domain-Driven Design (DDD) principles, offering various entry points ranging from high-level "simple" functional APIs to advanced factory patterns and service orchestration layers. The primary goal is to provide a consistent observability interface across the entire FLEXT ecosystem while maintaining strict type safety and railway-oriented programming (ROP) patterns.
The API surface is organized into four distinct layers: the Simple Interface (Functional API), the Factory Layer (Master Factory), the Application Layer (Services), and the Infrastructure Layer (Platform Orchestration). Each layer serves a specific level of complexity, allowing developers to choose between ease of use and granular control.
Sources: src/README.md:15-20, src/flext_observability/README.md:13-18
Simple API Interface
The Simple API provides a high-level, functional gateway to the observability system. It consists of standalone functions designed for rapid integration and common monitoring tasks without requiring manual dependency injection or service management.
Functional Entry Points
The following functions form the primary public surface for basic observability operations:
| Function | Purpose | Key Parameters |
|---|---|---|
flext_metric | Records numerical measurements. | name, value, unit |
flext_trace | Initiates distributed tracing spans. | operation_name, service_name |
flext_alert | Generates system notifications. | source, title, severity |
flext_health_check | Reports component status. | component, status |
flext_log_entry | Emits structured log data. | message, severity |
Sources: examples/01_functional.py:23-35, src/flext_observability/README.md:53-57
Implementation Logic
These functional helpers typically wrap the FlextObservabilityMasterFactory or FlextObservabilityPlatformV2. They utilize the r[T] result pattern from flext-core to return success or failure states, ensuring errors are handled via Railway-Oriented Programming.
The flow above illustrates how a simple API call traverses the architecture layers to produce a validated observability entity.
Sources: src/flext_observability/README.md:104-108, tests/unit/test_init.py:64-70
Master Factory Pattern
The FlextObservabilityMasterFactory serves as the central orchestration point for entity creation. It implements the Factory pattern to decouple entity instantiation and validation from business logic.
Capabilities
- Validation-Driven Creation: Every entity (Metric, Trace, etc.) created through the factory undergoes domain validation before being returned.
- Dependency Injection Integration: The factory accepts a
FlextContainerto resolve necessary infrastructure components. - Global Instance: A
global_factoryis provided for scenarios where manual lifecycle management is not required.
Sources: src/flext_observability/README.md:46-48, examples/02_solid_observability_demo.py:108-114
Factory Sequence
The following sequence diagram shows the interaction between the factory and the underlying domain entities.
Monitoring Decorators
The API surface includes automatic instrumentation via decorators, primarily flext_monitor_function. This allows for non-intrusive monitoring of business logic.
Features
- Automatic Execution Tracking: Measures function latency.
- Success/Failure Counting: Automatically records outcomes based on return values or exceptions.
- Context Propagation: Maintains correlation IDs and trace context across decorated function calls.
@flext_monitor_function("order_processing")
def process_order(order_data: dict) -> dict:
# Automatically records metrics, traces, and logs
return {"status": "processed"}
Sources: src/flext_observability/README.md:111-118, examples/01_functional.py:53-58
Context & Sampling API
For advanced scenarios, the API exposes interfaces for managing observability context and data sampling rates, typically used in production environments to control telemetry volume.
Key Components
- FlextObservabilityContext: Static interface for updating
correlation_idandtrace_id. - FlextObservabilitySampling: Service for defining operation-specific or environment-specific sampling rates (e.g., "production" vs "staging").
- FlextObservabilityAdvancedContext: Provides "snapshot" and "restore" capabilities for metadata and baggage, supporting asynchronous or distributed workflows.
Sources: tests/integration/test_phase_11_integration.py:27-41, tests/integration/test_phase_11_integration.py:104-123
Application Services Facade
Beneath the factories and simple APIs lie the specialized services that handle specific domain concerns. These are typically accessed via the FlextObservabilityPlatformV2.
| Service | Responsibility |
|---|---|
FlextMetricsService | Aggregation, validation, and export of metrics. |
FlextTracingService | Coordination of distributed spans and context propagation. |
FlextHealthService | Aggregating health statuses and dependency reporting. |
FlextLoggingService | Managing JSON-structured logging and correlation. |
Sources: src/flext_observability/README.md:31-41, src/README.md:31-36
Summary
The FLEXT Observability API surface is designed for scalability and developer ergonomics. By providing the Simple API for rapid development, the Master Factory for structured entity creation, and Monitoring Decorators for automated instrumentation, the system ensures that enterprise-grade observability can be integrated with minimal friction while strictly adhering to domain-driven design standards.
Sources: src/flext_observability/README.md:120-134, src/README.md:40-45