Getting Started

Relevant source files

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

• examples/basic-usage.md
• examples/README.md
• src/README.md
• src/flext_observability/README.md
• README.md
• examples/01_functional.py
• pyproject.toml

FLEXT Observability is an enterprise-grade monitoring, metrics, and telemetry library designed for the FLEXT ecosystem. It implements Clean Architecture and Domain-Driven Design (DDD) principles to provide type-safe observability patterns, including metrics collection, distributed tracing, health checks, and structured logging. The system utilizes Railway-Oriented Programming (ROP) via p.Result[T] patterns to ensure robust error handling across all operations.

Sources: src/README.md:12-16, README.md:7-9, src/flext_observability/README.md:31-33

Installation and Environment

FLEXT Observability requires Python 3.13 or higher. The project is managed with standard enterprise quality gates and requires several core dependencies from the FLEXT ecosystem.

Sources: pyproject.toml:34, README.md:5

Core Dependencies

Dependency	Purpose
flext-core	Foundation patterns (Result, Container, Entities)
flext-cli	CLI support and utility facades
opentelemetry-sdk	Industry-standard telemetry implementation
structlog	Structured JSON logging
pydantic	Data validation and settings management

Sources: pyproject.toml:21-33, src/README.md:46-49

Core Architecture

The library is organized into four distinct layers following Clean Architecture principles:

1. Domain Layer: Contains core entities like FlextMetric and FlextTrace with business rule validation.
2. Application Layer: Implements services such as FlextMetricsService and FlextTracingService for business logic coordination.
3. Interface Layer: Provides the FlextObservabilityMasterFactory and "Simple APIs" for easy integration.
4. Infrastructure Layer: Handles utilities, repository patterns, and cross-cutting concerns.

Sources: src/README.md:21-26, src/flext_observability/README.md:35-86

Data Flow Architecture

The following diagram illustrates the flow from a functional call through the validation layer to the application services.

A conceptual flow showing how telemetry data is initiated, validated by domain rules, and processed by services.
Sources: src/flext_observability/README.md:35-86, src/README.md:29-44

Basic Usage Patterns

Simple API

The Simple API provides high-level functions for immediate observability without manual factory orchestration.

from flext_observability import (
    flext_create_metric,
    flext_create_trace,
    flext_create_alert
)

# Create a metric
metric_result = flext_create_metric("api_requests", 1, "count")

# Create a trace span
trace_result = flext_create_trace("user_login", "auth-service")

Sources: src/flext_observability/README.md:65-72, examples/01_functional.py:34-47

Function Monitoring

The @flext_monitor_function decorator provides automatic instrumentation for execution time, success/failure tracking, and trace span creation.

from flext_observability import flext_monitor_function

@flext_monitor_function("business_operation")
def process_order(order_data: dict):
    # This function is automatically monitored
    return {"status": "processed"}

Sources: src/README.md:73-77, examples/README.md:95-108

Component Overview

Key Classes and Services

Component	Layer	Description
FlextObservabilityPlatformV2	Application	Central orchestrator coordinating all observability services.
FlextObservabilityMasterFactory	Interface	Central factory for validated entity creation.
FlextMetricsService	Application	Manages metrics collection, validation, and export.
FlextHealthService	Application	Coordinates health checks and dependency reporting.
FlextStructuredLogger	Infrastructure	Handles JSON structured logging with correlation IDs.

Sources: src/flext_observability/README.md:52-82

Service Interaction Sequence

The sequence below demonstrates how a service uses the factory and metrics service within a dependency injection container.

Shows the interaction between application logic and observability services using Result types.
Sources: examples/README.md:73-93, src/flext_observability/README.md:104-124

Quality and Development Standards

All contributions to the project must adhere to strict quality gates:

• Railway-Oriented Programming: All operations must return a p.Result[T] (aliased as r).
• Type Safety: 100% type coverage is required for public APIs.
• Validation: Entities must implement validate_business_rules().
• Testing: A minimum of 95% test coverage must be maintained.

Sources: src/README.md:81-88, src/flext_observability/README.md:144-156

Conclusion

Getting started with FLEXT Observability involves selecting the appropriate level of integration: using the Simple API for quick instrumentation, decorators for automatic function monitoring, or the full Service Layer for complex enterprise patterns. Regardless of the entry point, the system ensures architectural consistency through centralized validation and standardized Result-based error handling.

Sources: src/flext_observability/README.md:31-33, examples/README.md:162-173