Rootcause opentelemetry proposal

Cargo.toml

@@ -11,7 +11,7 @@ documentation = "https://docs.rs/rootcause"
 rust-version = "1.89"
 
 [workspace]
-members = ["rootcause-internals", "rootcause-backtrace", "rootcause-tracing"]
+members = ["rootcause-internals", "rootcause-backtrace", "rootcause-tracing", "rootcause-opentelemetry"]
 
 [features]
 default = []

rootcause-opentelemetry/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "rootcause-opentelemetry"
+version = "0.1.0"
+edition = "2024"
+license = "MIT/Apache-2.0"
+categories = ["rust-patterns", "development-tools::debugging"]
+keywords = ["error", "error-handling", "observability", "opentelemetry", "web-standards"]
+description = "Open Telemetry tracing context support for the rootcause error reporting library"
+repository = "https://github.com/rootcause-rs/rootcause"
+documentation = "https://docs.rs/rootcause-opentelemetry"
+rust-version = "1.89"
+
+[dependencies]
+opentelemetry = "0.31"
+
+# Internal
+rootcause = { path = "../", version = "=0.12.1" }

rootcause-opentelemetry/src/lib.rs

@@ -0,0 +1,23 @@
+//! # Open telemetry tracing contexts for Rootcause reports.
+//!
+//! This crate provides report creation hooks for adding the
+//! [Tracing Context][Tracing Context] provided by Open Telemetry to
+//! reports.
+//!
+//! Two collectors are provided, one which collects the whole
+//! [`SpanContext`][SpanContext] as a single attachment, and
+//! one which splits it up into three separate attachments,
+//! for the purpose of providing a slightly prettier formatting.
+//!
+//! [Tracing Context]: https://www.w3.org/TR/trace-context/
+//! [SpanContext]: opentelemetry::trace::SpanContext
+
+mod separate;
+mod single;
+mod types;
+pub use opentelemetry::trace::TraceState;
+pub use separate::TraceContextCollector;
+pub use single::SpanContextCollector;
+pub use types::TraceContextAttachment;
+pub use types::TraceParent;
+pub use types::TraceSettings;

rootcause-opentelemetry/src/separate.rs

@@ -0,0 +1,135 @@
+use std::fmt;
+
+use opentelemetry::{
+    Context,
+    trace::{TraceContextExt, TraceState},
+};
+use rootcause::{
+    ReportMut,
+    handlers::{
+        AttachmentFormattingPlacement, AttachmentFormattingStyle, AttachmentHandler,
+        FormattingFunction,
+    },
+    hooks::report_creation::ReportCreationHook,
+    markers::{Dynamic, Local, ObjectMarkerFor, SendSync},
+};
+
+use crate::types::{TraceContextAttachment, TraceParent, TraceSettings};
+
+impl AttachmentHandler<TraceParent> for TraceContextAttachment {
+    fn display(value: &TraceParent, formatter: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        fmt::Display::fmt(value, formatter)
+    }
+
+    fn debug(value: &TraceParent, formatter: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        fmt::Debug::fmt(value, formatter)
+    }
+
+    fn preferred_formatting_style(
+        value: &TraceParent,
+        function: FormattingFunction,
+    ) -> AttachmentFormattingStyle {
+        AttachmentFormattingStyle {
+            function,
+            placement: if value.is_valid() {
+                AttachmentFormattingPlacement::InlineWithHeader {
+                    header: "Traceparent:",
+                }
+            } else {
+                AttachmentFormattingPlacement::Hidden
+            },
+            priority: -5,
+        }
+    }
+}
+
+impl AttachmentHandler<TraceState> for TraceContextAttachment {
+    fn display(value: &TraceState, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str(&value.header())
+    }
+
+    fn debug(value: &TraceState, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        fmt::Debug::fmt(value, formatter)
+    }
+
+    fn preferred_formatting_style(
+        value: &TraceState,
+        function: FormattingFunction,
+    ) -> AttachmentFormattingStyle {
+        let _ = value;
+        AttachmentFormattingStyle {
+            function,
+            placement: if value == &TraceState::NONE {
+                AttachmentFormattingPlacement::Hidden
+            } else {
+                AttachmentFormattingPlacement::InlineWithHeader {
+                    header: "Tracestate:",
+                }
+            },
+            priority: -5,
+        }
+    }
+}
+
+impl AttachmentHandler<TraceSettings> for TraceContextAttachment {
+    fn display(value: &TraceSettings, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        fmt::Display::fmt(value, formatter)
+    }
+
+    fn debug(value: &TraceSettings, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        fmt::Debug::fmt(value, formatter)
+    }
+
+    fn preferred_formatting_style(
+        value: &TraceSettings,
+        function: FormattingFunction,
+    ) -> AttachmentFormattingStyle {
+        let _ = value;
+        AttachmentFormattingStyle {
+            function,
+            placement: AttachmentFormattingPlacement::Inline,
+            priority: -5,
+        }
+    }
+}
+
+/// Collector for the [`TraceParent`], [`TraceState`], and [`TraceSettings`]
+/// objects available at time of report creation, if any.
+///
+/// This collector creates three separate attachments.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct TraceContextCollector;
+
+impl ReportCreationHook for TraceContextCollector {
+    fn on_local_creation(&self, report: ReportMut<'_, Dynamic, Local>) {
+        on_creation(report);
+    }
+
+    fn on_sendsync_creation(&self, report: ReportMut<'_, Dynamic, SendSync>) {
+        on_creation(report);
+    }
+}
+
+fn on_creation<T>(report: ReportMut<'_, Dynamic, T>)
+where
+    TraceSettings: ObjectMarkerFor<T>,
+    TraceState: ObjectMarkerFor<T>,
+    TraceParent: ObjectMarkerFor<T>,
+{
+    if Context::current().has_active_span() {
+        let context = Context::current();
+        let span_ref = context.span();
+        let span_context_ref = span_ref.span_context();
+        if span_context_ref.is_valid() {
+            let tracestate = span_context_ref.trace_state().clone();
+
+            let traceparent = TraceParent::from(span_context_ref);
+            let trace_settings = TraceSettings::from(span_context_ref);
+
+            let _ = report
+                .attach_custom::<TraceContextAttachment, _>(traceparent)
+                .attach_custom::<TraceContextAttachment, _>(tracestate)
+                .attach_custom::<TraceContextAttachment, _>(trace_settings);
+        }
+    }
+}

rootcause-opentelemetry/src/single.rs

@@ -0,0 +1,97 @@
+use std::fmt;
+
+use opentelemetry::{
+    Context,
+    trace::{SpanContext, TraceContextExt, TraceState},
+};
+use rootcause::{
+    ReportMut,
+    handlers::{
+        AttachmentFormattingPlacement, AttachmentFormattingStyle, AttachmentHandler,
+        FormattingFunction,
+    },
+    hooks::report_creation::ReportCreationHook,
+    markers::{Dynamic, ObjectMarkerFor},
+};
+
+use crate::types::TraceContextAttachment;
+
+impl AttachmentHandler<SpanContext> for TraceContextAttachment {
+    fn display(value: &SpanContext, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(
+            formatter,
+            "Traceparent: 00-{:x}-{:x}-{:02x}",
+            value.trace_id(),
+            value.span_id(),
+            value.trace_flags(),
+        )?;
+
+        if value.trace_state() != &TraceState::NONE {
+            write!(formatter, "\nTracestate: {}", value.trace_state().header())?;
+        }
+
+        match (value.is_remote(), value.is_sampled()) {
+            (true, true) => write!(formatter, "\n(remote & sampled)"),
+            (true, false) => write!(formatter, "\n(remote)"),
+            (false, true) => write!(formatter, "\n(sampled)"),
+            (false, false) => Ok(()),
+        }
+    }
+
+    fn debug(value: &SpanContext, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        fmt::Debug::fmt(value, formatter)
+    }
+
+    fn preferred_formatting_style(
+        value: &SpanContext,
+        function: FormattingFunction,
+    ) -> AttachmentFormattingStyle {
+        AttachmentFormattingStyle {
+            function,
+            placement: if value.is_valid() {
+                AttachmentFormattingPlacement::InlineWithHeader {
+                    header: "Trace context:",
+                }
+            } else {
+                AttachmentFormattingPlacement::Hidden
+            },
+            priority: -5,
+        }
+    }
+}
+
+/// Collector for the [`SpanContext`] object available at time
+/// of report creation, if any.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct SpanContextCollector;
+
+impl ReportCreationHook for SpanContextCollector {
+    fn on_local_creation(
+        &self,
+        report: rootcause::ReportMut<'_, rootcause::markers::Dynamic, rootcause::markers::Local>,
+    ) {
+        on_creation(report);
+    }
+
+    fn on_sendsync_creation(
+        &self,
+        report: rootcause::ReportMut<'_, rootcause::markers::Dynamic, rootcause::markers::SendSync>,
+    ) {
+        on_creation(report);
+    }
+}
+
+fn on_creation<T>(report: ReportMut<'_, Dynamic, T>)
+where
+    SpanContext: ObjectMarkerFor<T>,
+{
+    if Context::current().has_active_span() {
+        let context = Context::current();
+        let span_ref = context.span();
+        let span_context_ref = span_ref.span_context();
+        if span_context_ref.is_valid() {
+            let span_context = span_context_ref.clone();
+            let _ = report.attach_custom::<TraceContextAttachment, _>(span_context);
+        }
+    }
+}