Data Models & Typings
Relevant source files
The following files were used as context for generating this wiki page:
The Data Models and Typings within the flext-observability package serve as the domain foundation for enterprise monitoring, metrics, and distributed tracing. Built upon Clean Architecture and Domain-Driven Design (DDD) principles, these models ensure type safety, strict domain validation, and seamless integration with the broader FLEXT ecosystem. The system utilizes Pydantic patterns for entity definition and leverages railway-oriented programming (via p.Result[T]) for consistent error handling across all observability concerns.
Sources: src/README.md:14-25, src/flext_observability/README.md:14-23, src/flext_observability/models.py:12-23
Domain Entities
The core domain layer resides in models.py and provides entities for tracking the four pillars of observability: metrics, traces, alerts, and logs. These entities inherit from m.Entity (provided by flext-core) and use composition to maintain a zero-domain-specific logic, focusing on pure generic foundations.
Core Observability Models
The following table summarizes the primary domain entities defined within the FlextObservabilityModels namespace:
| Entity | Description | Key Fields |
|---|---|---|
| Metric | Captures numeric measurements over time. | name, value, unit, metric_type, labels |
| Trace | Represents a distributed trace span. | trace_id, name, attributes |
| Alert | Manages system notifications and severity levels. | title, message, severity, source, labels |
| HealthCheck | Tracks the status of system components. | component, status, details |
| LogEntry | Structured JSON logging with correlation IDs. | message, level, component, timestamp, context |
Sources: src/flext_observability/models.py:30-105, src/flext_observability/README.md:27-33
Entity Relationship Diagram
The following diagram illustrates the shared inheritance and structure of the core domain entities:
The _EntityWithId base class provides an auto-generated unique identifier using uuid4 for most domain entities.
Sources: src/flext_observability/models.py:53-105
Specialized Value Objects & Payloads
Beyond core entities, the module defines specialized value objects for context propagation, performance tracking, and error fingerprinting. These are used primarily in the application and infrastructure layers to coordinate complex observability tasks.
Context and Correlation
For distributed tracing and asynchronous operations, the ContextSnapshot and LogContext models capture the state required to correlate telemetry across different services or threads.
- Correlation ID: A unique identifier linking all telemetry for a specific request.
- Baggage: Key-value pairs propagated across service boundaries.
- Fingerprint: SHA256 hashes used for error deduplication.
Sources: src/flext_observability/models.py:127-142, src/flext_observability/models.py:192-215
Performance Metrics Model
The PerformanceMetrics model tracks the internal efficiency of the observability platform itself, capturing duration, memory usage, and CPU consumption of operations.
Type Safety & Validation
The project enforces strict typing using Python 3.13+ features and Pydantic's Annotated types. This ensures that data entering the observability system conforms to required constraints (e.g., NonEmptyStr, PositiveFloat).
Common Type Aliases
The system relies on specialized type aliases (often referenced via the t and c namespaces) to enforce domain constraints:
t.NonEmptyStr: Strings that cannot be empty, used for names and titles.t.PositiveFloat: Numeric values that must be greater than zero.t.Observability.DomainLabels: Immutable mappings (MappingProxyType) for metadata.c.Observability.AlertLevel: Constants defining severity (INFO, WARNING, ERROR, CRITICAL).
Sources: src/flext_observability/models.py:38-110, examples/01_functional.py:79-84
Implementation Patterns
Observability models are designed to be used through factory patterns and simple API facades, hiding the complexity of Pydantic initialization and validation from the end user.
Functional Usage Example
from flext_observability import FlextObservability, c
# Simple API usage for creating a metric
metric_result = FlextObservability.flext_metric(
name="api_requests",
value=150.0,
unit="count"
)
# Creating an alert with severity validation
alert_result = FlextObservability.flext_alert(
source="database",
title="Connection Fail",
message="Unable to reach DB",
severity=c.Observability.AlertLevel.ERROR
)
Sources: examples/01_functional.py:31-43, src/flext_observability/README.md:120-135
Conclusion
The "Data Models & Typings" system provides a robust, type-safe foundation for the flext-observability package. By separating concerns into a distinct domain layer within models.py and utilizing strict Pydantic validation, the system ensures that all collected telemetry—metrics, traces, logs, and health checks—is consistent, reliable, and ready for enterprise-scale processing and export.
Sources: src/flext_observability/README.md:148-160, AGENTS.md:12-25