tael_server/storage/
mod.rs

1mod backend;
2mod blobs;
3mod duckdb_store;
4mod fanout;
5pub mod models;
6mod remote;
7mod search;
8
9pub use backend::{TaelBackend, WalSink};
10pub use blobs::BlobStore;
11pub use duckdb_store::DuckDbStore;
12pub use fanout::FanoutStore;
13pub use remote::{RemoteStore, RemoteWalSink, WAL_EPOCH_HEADER};
14pub use search::SearchIndex;
15
16use anyhow::Result;
17
18use models::{
19    AnomalyReport, CorrelateReport, LogQuery, LogRecord, MetricPoint, MetricQuery, ServiceInfo,
20    Span, SummaryReport, TraceComment, TraceQuery,
21};
22
23/// Storage backend for all telemetry signals. The server depends on
24/// `Arc<dyn Store>`, so backends (DuckDB today, `TaelBackend` next) are
25/// swappable without touching the API, ingest, or query layers.
26///
27/// Synchronous by design — see `docs/tael-backend-impl-plan.md`, Phase 0.
28/// `Send + Sync` so it can be shared as `Arc<dyn Store>` across tokio tasks and
29/// held in axum state.
30pub trait Store: Send + Sync {
31    // ── Spans / traces ──────────────────────────────────────────────
32    fn insert_spans(&self, spans: &[Span]) -> Result<()>;
33    fn query_traces(&self, query: &TraceQuery) -> Result<Vec<Span>>;
34    fn get_trace(&self, trace_id: &str) -> Result<Vec<Span>>;
35    fn list_services(&self) -> Result<Vec<ServiceInfo>>;
36
37    // ── Comments ────────────────────────────────────────────────────
38    fn add_comment(
39        &self,
40        trace_id: &str,
41        span_id: Option<&str>,
42        author: &str,
43        body: &str,
44    ) -> Result<TraceComment>;
45    fn get_comments(&self, trace_id: &str) -> Result<Vec<TraceComment>>;
46
47    // ── Logs ────────────────────────────────────────────────────────
48    fn insert_logs(&self, logs: &[LogRecord]) -> Result<()>;
49    fn query_logs(&self, query: &LogQuery) -> Result<Vec<LogRecord>>;
50
51    // ── Metrics ─────────────────────────────────────────────────────
52    fn insert_metrics(&self, metrics: &[MetricPoint]) -> Result<()>;
53    fn query_metrics(&self, query: &MetricQuery) -> Result<Vec<MetricPoint>>;
54
55    // ── Cross-signal analytics ──────────────────────────────────────
56    fn query_summary(&self, last_seconds: i64, service: Option<&str>) -> Result<SummaryReport>;
57    fn query_anomalies(
58        &self,
59        current_seconds: i64,
60        baseline_seconds: i64,
61        service: Option<&str>,
62    ) -> Result<AnomalyReport>;
63    fn query_correlate(&self, trace_id: &str) -> Result<Option<CorrelateReport>>;
64
65    /// Read-only SQL query surface (`SELECT`/`WITH`) over the telemetry tables,
66    /// returning rows as JSON objects.
67    fn query_sql(&self, sql: &str) -> Result<Vec<serde_json::Value>>;
68
69    // ── Lifecycle / operability (default no-ops) ────────────────────
70    /// Readiness probe — `Ok(())` when this store can serve requests. Backs the
71    /// REST `/readyz` endpoint (`docs/tael-server-scaling-ha.md` §5.4). The
72    /// default is `Ok(())`: an embedded backend that constructed successfully
73    /// and holds its file locks is, by definition, ready. Backends that depend
74    /// on the network (e.g. [`RemoteStore`], [`FanoutStore`](crate::storage))
75    /// override this to probe their dependencies.
76    fn health(&self) -> Result<()> {
77        Ok(())
78    }
79
80    /// Flush durable buffered state ahead of a graceful shutdown. The WAL fsync
81    /// on the write path is the real durability boundary, so this is
82    /// best-effort: it tightens the hot tier's on-disk state so a restart or
83    /// standby replays less WAL (§5.4 "flush the hot tier"). Default is a no-op.
84    fn flush(&self) -> Result<()> {
85        Ok(())
86    }
87
88    /// Standby entrypoint for WAL replication: durably accept a framed WAL
89    /// record shipped from a leader and bring local state up to it
90    /// (`docs/tael-server-scaling-ha.md` §5.1). Backs the
91    /// `POST /internal/wal/records` endpoint. Default: rejected — only the
92    /// tael-backend engine, which owns a WAL, can act as a standby.
93    fn apply_framed_wal(&self, _framed: &[u8]) -> Result<()> {
94        anyhow::bail!("this store does not accept WAL replication")
95    }
96}
tael_server/storage/mod.rs

tael_server/storage/
mod.rs
