Metrics & Observability
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Metrics & Observability within the flext-grpc platform provides a structured framework for monitoring the health, performance, and operational state of gRPC services. This system is integrated into the core architecture via the flext-observability ecosystem, enabling performance tracking for gRPC operations and distributed tracing for cross-service calls.
The framework utilizes thread-safe collection mechanisms to record operational telemetry such as request latency, error counts, and server lifecycle states. This ensures that enterprise gRPC applications maintain visibility into their internal state while adhering to the Clean Architecture principles established in the project.
Sources: [src/README.md:144-147](https://github.com/flext-sh/flext-grpc/blob/778437972a9c000ae68aa3779be6909d84e03084/src/README.md#L144-L147), [src/flext_grpc/services/metrics.py:11-15](https://github.com/flext-sh/flext-grpc/blob/778437972a9c000ae68aa3779be6909d84e03084/src/flext_grpc/services/metrics.py#L11-L15)
Metrics Architecture
The observability architecture is built upon a mixin pattern that extends the FlextGrpc facade with telemetry capabilities. Central to this is the MetricsCollector, which manages internal state using a thread-safe implementation.
Components & Data Flow
The architecture consists of the following key components:
- FlextGrpcMetrics: A mixin class providing the public interface for recording and retrieving metrics.
- MetricsCollector: An internal class that utilizes a
threading.RLockto ensure thread-safe operations on the metrics payload. - Grpc.Payload: A Pydantic-based data structure used to store and validate metric key-value pairs.
The diagram shows the hierarchical relationship and control flow from the facade down to the thread-safe storage.
Sources: [src/flext_grpc/services/metrics.py:11-30](https://github.com/flext-sh/flext-grpc/blob/778437972a9c000ae68aa3779be6909d84e03084/src/flext_grpc/services/metrics.py#L11-L30), [src/flext_grpc/models.py:539-556](https://github.com/flext-sh/flext-grpc/blob/778437972a9c000ae68aa3779be6909d84e03084/src/flext_grpc/models.py#L539-L556)
Thread Safety and Normalization
Metrics recording involves a normalization process to ensure that all data is JSON-serializable. Values that are not primitives (str, int, float, bool) or None are converted to strings before storage.
def _normalize_value(val: t.JsonValue | None) -> t.JsonValue | None:
if val is None:
return ""
if u.primitive(val):
return val
return str(val)
Sources: [src/flext_grpc/services/metrics.py:64-71](https://github.com/flext-sh/flext-grpc/blob/778437972a9c000ae68aa3779be6909d84e03084/src/flext_grpc/services/metrics.py#L64-L71)
Monitoring Configuration
Observability is controlled through the MonitoringConfig model, which defines how metrics and tracing are handled within the system.
| Field | Type | Default | Description |
|---|---|---|---|
metrics_enabled | bool | True | Enables metrics collection. |
tracing_enabled | bool | False | Enables distributed tracing. |
health_check_enabled | bool | True | Enables gRPC health check services. |
health_check_interval | int | 30 | Interval in seconds between checks. |
log_level | str | "INFO" | Standard logging level. |
Sources: [src/flext_grpc/models.py:277-303](https://github.com/flext-sh/flext-grpc/blob/778437972a9c000ae68aa3779be6909d84e03084/src/flext_grpc/models.py#L277-L303)
Domain Observability Models
The system defines specific models to represent the state and performance of gRPC streams and health checks.
Stream Telemetry
Streaming operations are monitored via the StreamInfo model, which tracks lifecycle and performance data for every gRPC stream.
| Field | Description |
|---|---|
stream_id | Unique identifier for the stream instance. |
total_requests_sent | Counter for all requests transmitted on the stream. |
average_latency_ms | Calculated average response time. |
error_count | Number of failed operations on the stream. |
Sources: [src/flext_grpc/models.py:59-75](https://github.com/flext-sh/flext-grpc/blob/778437972a9c000ae68aa3779be6909d84e03084/src/flext_grpc/models.py#L59-L75)
Health Monitoring
The health check system uses the HealthCheck model to provide snapshots of service status.
The sequence shows how health status transitions from the service to the metrics storage.
Sources: [src/flext_grpc/models.py:77-82](https://github.com/flext-sh/flext-grpc/blob/778437972a9c000ae68aa3779be6909d84e03084/src/flext_grpc/models.py#L77-L82), [src/flext_grpc/services/metrics.py:73-82](https://github.com/flext-sh/flext-grpc/blob/778437972a9c000ae68aa3779be6909d84e03084/src/flext_grpc/services/metrics.py#L73-L82)
Integration with flext-observability
The project integrates with standard industry tools for externalizing observability data:
- Prometheus: Supported via
prometheus-clientfor metric scraping. - Logging: Structured logging with context (e.g., field names, configuration keys) is used throughout error handling pipelines.
- Tracing: Distributed tracing capabilities are planned/implemented for cross-service calls.
Sources: [pyproject.toml:34](https://github.com/flext-sh/flext-grpc/blob/778437972a9c000ae68aa3779be6909d84e03084/pyproject.toml#L34), [src/README.md:144-147](https://github.com/flext-sh/flext-grpc/blob/778437972a9c000ae68aa3779be6909d84e03084/src/README.md#L144-L147), [examples/03_error_handling_patterns.py:202-212](https://github.com/flext-sh/flext-grpc/blob/778437972a9c000ae68aa3779be6909d84e03084/examples/03_error_handling_patterns.py#L202-L212)
Summary
Metrics & Observability in flext-grpc provides a robust, thread-safe foundation for monitoring enterprise gRPC communications. By utilizing the MetricsCollector pattern and standardized domain models like StreamInfo and HealthCheck, the platform ensures that performance bottlenecks and operational failures are visible and actionable. The integration with flext-observability and prometheus-client further enables external monitoring and alerting in production environments.