juncture_telemetry/lib.rs
1//! Langfuse-compatible observability engine for Juncture AI agents.
2//!
3//! This crate provides a zero-dependency telemetry system that captures
4//! traces, observations (LLM calls, tool calls, spans), sessions, and
5//! metrics directly within the Juncture process. No external services
6//! (otel-collector, Jaeger, Prometheus) are required.
7//!
8//! # Architecture
9//!
10//! ```text
11//! TelemetryCollector
12//! └── BatchWriter (async, non-blocking)
13//! └── TraceStore (SQLite / PostgreSQL)
14//! └── Web Viewer (Langfuse-compatible API)
15//! ```
16//!
17//! # Quick Start
18//!
19//! ```ignore
20//! use juncture_telemetry::{TelemetryCollector, SqliteStore};
21//! use std::sync::Arc;
22//!
23//! #[tokio::main]
24//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
25//! let store = Arc::new(SqliteStore::new("telemetry.db").await?);
26//! let collector = TelemetryCollector::new(store);
27//!
28//! // ... run your graph with collector ...
29//!
30//! collector.flush().await?;
31//! Ok(())
32//! }
33//! ```
34
35pub mod batch_writer;
36pub mod collector;
37pub mod config;
38pub mod langfuse;
39pub mod models;
40#[cfg(feature = "web")]
41pub mod otlp;
42#[cfg(feature = "sqlite")]
43pub mod sqlite_store;
44pub mod trace_store;
45#[cfg(feature = "web")]
46pub mod web;
47
48// Re-exports for convenience
49pub use batch_writer::{BatchWriter, TelemetryItem};
50pub use collector::TelemetryCollector;
51pub use config::{TelemetryConfig, TelemetryHandle};
52pub use langfuse::{LangfuseConfig, LangfuseExporter};
53
54/// Create a new telemetry configuration builder.
55///
56/// This is the recommended entry point for setting up telemetry.
57/// It follows the same pattern as `juncture_tracing::init()`.
58///
59/// # Examples
60///
61/// ```ignore
62/// use juncture_telemetry::init;
63///
64/// // Minimal -- in-memory store, no export
65/// let telemetry = init().await?;
66///
67/// // Full setup
68/// let telemetry = init()
69/// .with_store("telemetry.db")
70/// .with_langfuse_from_env()
71/// .with_dashboard(8123)
72/// .await?;
73/// ```
74#[must_use]
75pub fn init() -> TelemetryConfig {
76 TelemetryConfig::new()
77}
78pub use models::{
79 CaptureConfig, EnrichedSession, Id, ModelStats, Observation, ObservationLevel, ObservationType,
80 Session, SummaryStats, TokenUsage, Trace,
81};
82#[cfg(feature = "sqlite")]
83pub use sqlite_store::SqliteStore;
84pub use trace_store::{
85 DailyStats, PaginatedResponse, StoreError, TraceQuery, TraceStore, TraceWithObservations,
86};
87
88// Rust guideline compliant 2026-06-01