embeddenator_obs/
lib.rs

1//! # embeddenator-obs
2//!
3//! Observability: metrics, logging, tracing, and telemetry for Embeddenator.
4//!
5//! Extracted from embeddenator core as part of Phase 2A component decomposition.
6//!
7//! ## Features
8//!
9//! This crate provides comprehensive observability infrastructure:
10//!
11//! - **Metrics**: Lock-free atomic counters for performance tracking
12//! - **Logging**: Structured logging with environment-based filtering
13//! - **Tracing**: Span instrumentation for distributed tracing
14//! - **Telemetry**: Aggregation and export of observability data
15//! - **Hi-Res Timing**: Picosecond-scale timing for performance analysis
16//! - **Test Metrics**: Comprehensive testing/benchmarking utilities
17//!
18//! ## Feature Flags
19//!
20//! - `metrics` (default): Enable atomic performance counters
21//! - `tracing`: Enable span instrumentation and distributed tracing
22//! - `logging`: Enable structured logging (implies tracing)
23//! - `telemetry`: Enable telemetry aggregation and export
24//! - `prometheus`: Enable Prometheus metrics export format
25//! - `opentelemetry`: Enable OpenTelemetry distributed tracing
26//! - `streaming`: Enable real-time metric streaming with callbacks
27//! - `advanced-stats`: Enable advanced statistical analysis (percentiles, std dev)
28//! - `full`: Enable all features
29//!
30//! ## Quick Start
31//!
32//! ```rust
33//! use embeddenator_obs::{init_tracing, TestMetrics};
34//!
35//! // Initialize at startup
36//! init_tracing();
37//!
38//! // Track performance in tests
39//! let mut metrics = TestMetrics::new("operation");
40//! metrics.start_timing();
41//! // ... perform work ...
42//! metrics.stop_timing();
43//! println!("{}", metrics.summary());
44//! ```
45//!
46//! ## Metrics Usage
47//!
48//! ```rust
49//! use embeddenator_obs::metrics;
50//! use std::time::Duration;
51//!
52//! // Increment counters
53//! metrics().inc_sub_cache_hit();
54//! metrics().inc_sub_cache_miss();
55//!
56//! // Record durations
57//! metrics().record_retrieval_query(Duration::from_micros(1500));
58//!
59//! // Get snapshot
60//! let snapshot = metrics().snapshot();
61//! println!("Cache hits: {}", snapshot.sub_cache_hits);
62//! ```
63//!
64//! ## Tracing Usage
65//!
66//! ```rust,ignore
67//! use embeddenator_obs::create_span;
68//!
69//! let _span = create_span("query_operation", &[("dim", "768")]);
70//! // Work happens here, timing is automatic
71//! ```
72//!
73//! ## Architecture
74//!
75//! See [ADR-016](https://github.com/tzervas/embeddenator/blob/main/docs/adr/ADR-016-component-decomposition.md)
76//! for component decomposition rationale.
77
78pub mod obs;
79pub use obs::*;
80
81// Re-export commonly used types for convenience
82pub use obs::{
83    create_span, init_tracing, metrics, EventLevel, HiResMetrics, HiResTimer, HiResTimestamp,
84    MetricEvent, MetricStream, Metrics, MetricsSnapshot, OperationStats, OtelExporter, OtelSpan,
85    PrometheusExporter, SpanGuard, SpanKind, SpanStatus, Telemetry, TelemetryConfig,
86    TelemetrySnapshot, TestMetrics, ThresholdAlert, TimingStats,
87};
88
89#[cfg(test)]
90mod tests {
91    use super::*;
92
93    #[test]
94    fn component_loads() {
95        assert!(true);
96    }
97
98    #[test]
99    fn test_metrics_accessible() {
100        let snapshot = metrics().snapshot();
101        // Should compile and not panic
102        let _ = snapshot.sub_cache_hits;
103    }
104
105    #[test]
106    fn test_init_tracing_no_panic() {
107        init_tracing();
108    }
109}
embeddenator_obs/lib.rs

embeddenator_obs/
lib.rs
