Introduction & Purpose
Relevant source files
The following files were used as context for generating this wiki page:
flext-observability is an enterprise-grade foundation library designed to implement comprehensive monitoring, metrics, and telemetry patterns within the FLEXT ecosystem. The project serves as a centralized observability component for all FLEXT projects, ensuring consistent monitoring solutions across 33 different ecosystem projects. It is built using Clean Architecture and Domain-Driven Design (DDD) principles to provide type-safe, validated, and high-performance observability features.
The module provides a unified interface for metrics collection, distributed tracing, health checks, and structured logging. By utilizing Railway-Oriented Programming (ROP) with p.Result[T] patterns, the library ensures robust error handling and domain validation for all observability entities. It is designed to integrate with industry standards such as OpenTelemetry and Prometheus while maintaining deep integration with core FLEXT dependencies like flext-core.
Sources: README.md:9-11, src/README.md:12-16, src/flext_observability/README.md:16-18, pyproject.toml:28-35
Core Objectives and Architecture
The primary purpose of flext-observability is to provide a standardized, typed, and enterprise-ready observability stack. The architecture is strictly layered to separate domain logic from infrastructure concerns.
Layered Architecture Overview
The package is organized into four distinct layers following Clean Architecture:
- Domain Layer: Contains core entities like
FlextMetricandFlextTracewith encapsulated business rules. - Application Layer: Manages service coordination and business operations (e.g.,
FlextMetricsService). - Interface Layer: Provides external APIs, factory patterns, and monitoring decorators.
- Infrastructure Layer: Handles data access patterns, utilities, and external adapters for logging and metrics.
Sources: src/README.md:20-25, src/flext_observability/README.md:22-68
System Component Flow
The following diagram illustrates how observability data flows from the application interface through the domain and services.
The diagram shows the transition from the high-level API to validated domain entities and eventually to service-level processing and external export.
Sources: src/flext_observability/README.md:22-68, src/README.md:37-42
Key Features and Components
flext-observability provides several sub-modules tailored to specific observability needs:
| Component | Description | Key Classes/Functions |
|---|---|---|
| Metrics | Collection of performance and business counters/gauges. | FlextMetric, FlextMetricsService |
| Tracing | Distributed tracing with span context propagation. | FlextTrace, FlextTracingService |
| Alerting | Management of system alerts with varying severity. | FlextAlert, FlextAlertService |
| Health | Component-level status monitoring and dependency checks. | FlextHealthCheck, FlextHealthService |
| Logging | JSON structured logging with correlation ID support. | FlextLogEntry, FlextStructuredLogger |
Sources: src/flext_observability/README.md:28-48, src/README.md:28-42
Design Principles and Development Standards
The project adheres to rigorous engineering standards to ensure reliability in production environments.
Technical Design Patterns
- Railway-Oriented Programming: Every operation returns a
Resulttype (typically denoted asr[T]), forcing explicit handling of success and failure paths. - Type Safety: The project targets 100% type coverage for public APIs using MyPy strict mode.
- Ecosystem Integration: The library depends on
flext-corefor base patterns likeFlextModels.Entity,r,p, andFlextContainerfor dependency injection.
Sources: src/README.md:46-52, src/flext_observability/README.md:124-129, AGENTS.md:32-37
Quality Gates
The library enforces a "Zero Tolerance Quality" policy:
- 100% Type Coverage for public APIs.
- 95% Minimum Test Coverage across all modules.
- Ruff linting with all rules enabled.
- Bandit security scanning.
Sources: src/README.md:54-58, tests/README.md:166-170
Integration with FLEXT Ecosystem
flext-observability acts as a foundation layer that other FLEXT projects (like flext-cli or flext-core) leverage for their internal monitoring.
Dependency Interaction
The following sequence diagram shows how a service typically interacts with the observability stack during a business operation.
This sequence demonstrates the decoupling of entity creation (Factory) from execution (Service) via a unified API.
Sources: examples/README.md:58-95, src/flext_observability/README.md:79-106
Summary
The flext-observability library is the authoritative source for monitoring patterns within the FLEXT ecosystem. By enforcing clean architectural boundaries and strict domain validation, it provides a robust infrastructure for metrics, tracing, and logging that is both type-safe and performant. Its primary purpose is to abstract the complexities of enterprise telemetry (like OpenTelemetry and Prometheus integration) into a simple, reliable API for all FLEXT contributors.
Sources: README.md:1-20, src/README.md:1-18, src/flext_observability/README.md:16-20