Skip to main content

kaniop_operator/
telemetry.rs

1use std::time::Duration;
2
3use opentelemetry::KeyValue;
4use opentelemetry::trace::{TraceId, TracerProvider as _};
5use opentelemetry_otlp::{ExporterBuildError, WithExportConfig};
6use opentelemetry_sdk::Resource;
7use opentelemetry_sdk::trace::{RandomIdGenerator, Sampler, SdkTracerProvider};
8use serde::Serialize;
9use thiserror::Error;
10use tracing::dispatcher::SetGlobalDefaultError;
11use tracing_opentelemetry::OpenTelemetryLayer;
12use tracing_subscriber::fmt::MakeWriter;
13use tracing_subscriber::prelude::*;
14use tracing_subscriber::{EnvFilter, Registry};
15
16/// An error type representing various issues that can occur during tracing initialization.
17#[derive(Error, Debug)]
18pub enum Error {
19    /// Error encountered when setting up OpenTelemetry tracing.
20    #[error("ExporterBuildError: {0}")]
21    ExporterBuildError(#[source] ExporterBuildError),
22
23    /// Error encountered when setting the global tracing subscriber.
24    #[error("SetGlobalDefaultError: {0}")]
25    SetGlobalDefaultError(#[source] SetGlobalDefaultError),
26}
27
28/// Fetches the current `opentelemetry::trace::TraceId` as a hexadecimal string.
29///
30/// This function retrieves the `TraceId` by traversing the full tracing stack, from
31/// the current [`tracing::Span`] to its corresponding [`opentelemetry::Context`].
32/// It returns the trace ID associated with the current span.
33///
34/// # Example
35///
36/// ```rust
37/// # use kaniop_operator::telemetry::get_trace_id;
38/// let trace_id = get_trace_id();
39/// println!("Current trace ID: {:?}", trace_id);
40/// ```
41pub fn get_trace_id() -> TraceId {
42    use opentelemetry::trace::TraceContextExt as _; // opentelemetry::Context -> opentelemetry::trace::Span
43    use tracing_opentelemetry::OpenTelemetrySpanExt as _; // tracing::Span to opentelemetry::Context
44
45    tracing::Span::current()
46        .context()
47        .span()
48        .span_context()
49        .trace_id()
50}
51
52/// Specifies the format of log output, either JSON or plain-text.
53///
54/// This enum derives `clap::ValueEnum` for use in command-line argument parsing,
55/// and is serialized in lowercase when used with `serde`.
56#[derive(clap::ValueEnum, Clone, Copy, Debug, Eq, PartialEq, Serialize)]
57#[serde(rename_all = "lowercase")]
58pub enum LogFormat {
59    /// Newline-delimited JSON (NDJSON), with exactly one JSON object per event line.
60    Json,
61
62    /// Compact, human-readable plain-text log output.
63    Text,
64}
65
66fn logger_layer<W>(
67    log_format: LogFormat,
68    writer: W,
69) -> Box<dyn tracing_subscriber::Layer<Registry> + Send + Sync>
70where
71    W: for<'writer> MakeWriter<'writer> + Send + Sync + 'static,
72{
73    match log_format {
74        // `json()` already emits compact NDJSON. Calling `compact()` after `json()` would switch
75        // the event formatter back to compact text while retaining JSON field formatting.
76        LogFormat::Json => tracing_subscriber::fmt::layer()
77            .with_writer(writer)
78            .json()
79            .boxed(),
80        LogFormat::Text => tracing_subscriber::fmt::layer()
81            .with_writer(writer)
82            .compact()
83            .boxed(),
84    }
85}
86
87/// Initializes logging and tracing subsystems.
88///
89/// This asynchronous function configures and initializes logging and tracing
90/// according to the provided format and filtering parameters. JSON output uses
91/// newline-delimited JSON (NDJSON): every tracing event is one complete JSON object
92/// on one physical output line. It also supports OpenTelemetry tracing when a tracing
93/// URL is specified. If OpenTelemetry is enabled, traces are sent to the given URL
94/// using OTLP over HTTP.
95///
96/// # Example
97///
98/// ```rust
99/// # use kaniop_operator::telemetry::{init, LogFormat};
100///
101/// #[tokio::main]
102/// async fn main() -> Result<(), Box<dyn std::error::Error>> {
103///     let opentelemetry_endpoint_url = std::env::var("OPENTELEMETRY_ENDPOINT_URL").ok();
104///     init("info", LogFormat::Text, opentelemetry_endpoint_url.as_deref(), 0.1)
105///         .await?;
106///
107///     Ok(())
108/// }
109/// ```
110///
111/// # OpenTelemetry Integration
112///
113/// When a tracing URL is provided, OpenTelemetry tracing is configured using OTLP.
114/// The function creates a tracing pipeline with a ratio-based trace sampler and a
115/// default random trace ID generator. Traces will be sampled based on the
116/// `trace_ratio` provided.
117pub async fn init(
118    log_filter: &str,
119    log_format: LogFormat,
120    tracing_url: Option<&str>,
121    trace_ratio: f64,
122) -> Result<(), Error> {
123    let logger = logger_layer(log_format, std::io::stdout);
124
125    // Safe unwrap: the static directive is valid.
126    let filter = EnvFilter::new(log_filter).add_directive("kanidm_client=error".parse().unwrap());
127
128    let collector = Registry::default().with(logger).with(filter);
129
130    if let Some(url) = tracing_url {
131        let exporter = opentelemetry_otlp::SpanExporter::builder()
132            .with_http()
133            .with_endpoint(url)
134            .with_timeout(Duration::from_secs(3))
135            .build()
136            .map_err(Error::ExporterBuildError)?;
137
138        let provider = SdkTracerProvider::builder()
139            .with_sampler(Sampler::TraceIdRatioBased(trace_ratio))
140            .with_id_generator(RandomIdGenerator::default())
141            .with_max_events_per_span(64)
142            .with_max_attributes_per_span(16)
143            .with_max_events_per_span(16)
144            .with_resource(
145                Resource::builder()
146                    .with_service_name("kaniop")
147                    .with_attribute(KeyValue::new("key", "value"))
148                    .build(),
149            )
150            .with_batch_exporter(exporter)
151            .build();
152        let tracer = provider.tracer("opentelemetry-otlp");
153
154        let telemetry = OpenTelemetryLayer::new(tracer);
155        tracing::subscriber::set_global_default(collector.with(telemetry))
156            .map_err(Error::SetGlobalDefaultError)
157    } else {
158        tracing::subscriber::set_global_default(collector).map_err(Error::SetGlobalDefaultError)
159    }
160}
161
162#[cfg(test)]
163mod format_tests {
164    use super::*;
165
166    use std::io::{self, Write};
167    use std::sync::{Arc, Mutex};
168
169    use serde_json::Value;
170
171    #[derive(Clone, Default)]
172    struct TestWriter(Arc<Mutex<Vec<u8>>>);
173
174    struct TestWriterGuard(Arc<Mutex<Vec<u8>>>);
175
176    impl TestWriter {
177        fn contents(&self) -> String {
178            String::from_utf8(self.0.lock().unwrap().clone()).unwrap()
179        }
180    }
181
182    impl<'writer> MakeWriter<'writer> for TestWriter {
183        type Writer = TestWriterGuard;
184
185        fn make_writer(&'writer self) -> Self::Writer {
186            TestWriterGuard(self.0.clone())
187        }
188    }
189
190    impl Write for TestWriterGuard {
191        fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
192            self.0.lock().unwrap().extend_from_slice(buf);
193            Ok(buf.len())
194        }
195
196        fn flush(&mut self) -> io::Result<()> {
197            Ok(())
198        }
199    }
200
201    #[test]
202    fn json_format_is_one_object_per_line_with_canonical_message() {
203        let writer = TestWriter::default();
204        let subscriber = Registry::default().with(logger_layer(LogFormat::Json, writer.clone()));
205
206        tracing::subscriber::with_default(subscriber, || {
207            tracing::info!(controller = "test", attempts = 3_u64, "starting controller");
208            tracing::warn!(error = "retryable", "controller retry scheduled");
209        });
210
211        let output = writer.contents();
212        let lines = output
213            .lines()
214            .filter(|line| !line.is_empty())
215            .collect::<Vec<_>>();
216
217        assert_eq!(lines.len(), 2, "each event must occupy exactly one line");
218
219        let events = lines
220            .iter()
221            .map(|line| serde_json::from_str::<Value>(line).expect("log line must be valid JSON"))
222            .collect::<Vec<_>>();
223
224        for event in &events {
225            assert!(event.is_object());
226            assert!(event.get("timestamp").is_some());
227            assert!(event.get("level").is_some());
228            assert!(event.get("target").is_some());
229            assert!(event.get("fields").is_some_and(Value::is_object));
230            assert!(event["fields"].get("msg").is_none());
231        }
232
233        assert_eq!(events[0]["level"], "INFO");
234        assert_eq!(events[0]["fields"]["message"], "starting controller");
235        assert_eq!(events[0]["fields"]["controller"], "test");
236        assert_eq!(events[0]["fields"]["attempts"], 3);
237    }
238
239    #[test]
240    fn text_format_remains_human_readable() {
241        let writer = TestWriter::default();
242        let subscriber = Registry::default().with(logger_layer(LogFormat::Text, writer.clone()));
243
244        tracing::subscriber::with_default(subscriber, || {
245            tracing::info!(controller = "test", "starting controller");
246        });
247
248        let output = writer.contents();
249        assert!(output.contains("starting controller"));
250        assert!(serde_json::from_str::<Value>(output.trim()).is_err());
251    }
252}
253
254#[cfg(all(test, feature = "integration-test"))]
255mod test {
256    // This test only works when telemetry is initialized fully
257    // and requires OPENTELEMETRY_ENDPOINT_URL pointing to a valid server
258    #[tokio::test]
259    async fn integration_get_trace_id_returns_valid_traces() {
260        use super::*;
261        let opentelemetry_endpoint_url = std::env::var("OPENTELEMETRY_ENDPOINT_URL").ok();
262        super::init(
263            "info",
264            LogFormat::Text,
265            opentelemetry_endpoint_url.as_deref(),
266            0.1,
267        )
268        .await
269        .unwrap();
270        #[tracing::instrument(name = "test_span")] // need to be in an instrumented fn
271        fn test_trace_id() -> TraceId {
272            get_trace_id()
273        }
274        assert_ne!(test_trace_id(), TraceId::INVALID, "valid trace");
275    }
276}