use std::sync::Once;
use opentelemetry::trace::{SpanContext, SpanId, TraceContextExt, TraceFlags, TraceId, TraceState};
use serde_json::{Map, Value};
use tracing::Span;
use tracing_opentelemetry::{OpenTelemetrySpanExt, SetParentError};
const KEY: &str = "traceparent";
fn format(context: &SpanContext) -> Option<String> {
context.is_valid().then(|| {
format!(
"00-{}-{}-{:02x}",
context.trace_id(),
context.span_id(),
context.trace_flags().to_u8()
)
})
}
pub(crate) fn inject(span: &Span, metadata: &mut Option<String>) {
let context = span.context();
let Some(value) = format(context.span().span_context()) else {
return;
};
let mut object = match metadata.as_deref() {
None => Map::new(),
Some(raw) => match serde_json::from_str::<Map<String, Value>>(raw) {
Ok(object) => object,
Err(_) => return,
},
};
if let Some(previous) = object.get(KEY).and_then(Value::as_str)
&& previous != value
{
tracing::debug!(
previous,
"replacing a run's `traceparent` with this trigger's own, as the official SDKs do"
);
}
object.insert(KEY.to_string(), Value::String(value));
if let Ok(raw) = serde_json::to_string(&object) {
*metadata = Some(raw);
}
}
pub(crate) fn extract(metadata: Option<&str>) -> Option<opentelemetry::Context> {
let parent = from_metadata(metadata?)?;
Some(opentelemetry::Context::new().with_remote_span_context(parent))
}
pub(crate) fn continue_from(span: &Span, metadata: Option<&str>) {
let Some(parent) = extract(metadata) else {
return;
};
if let Err(SetParentError::LayerNotFound) = span.set_parent(parent) {
warn_once_without_a_layer();
}
}
fn from_metadata(raw: &str) -> Option<SpanContext> {
let object: Map<String, Value> = serde_json::from_str(raw).ok()?;
parse(object.get(KEY)?.as_str()?)
}
fn parse(value: &str) -> Option<SpanContext> {
let mut fields = value.split('-');
let version = fields.next()?;
let trace_id = fields.next()?;
let span_id = fields.next()?;
let flags = fields.next()?;
if !is_lower_hex(version, 2) || version == "ff" {
return None;
}
if version == "00" && fields.next().is_some() {
return None;
}
if !is_lower_hex(trace_id, 32) || !is_lower_hex(span_id, 16) || !is_lower_hex(flags, 2) {
return None;
}
let flags = u8::from_str_radix(flags, 16).ok()?;
let context = SpanContext::new(
TraceId::from_hex(trace_id).ok()?,
SpanId::from_hex(span_id).ok()?,
TraceFlags::new(flags) & TraceFlags::SAMPLED,
true,
TraceState::NONE,
);
context.is_valid().then_some(context)
}
fn is_lower_hex(field: &str, len: usize) -> bool {
field.len() == len
&& field
.bytes()
.all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))
}
fn warn_once_without_a_layer() {
static WARNED: Once = Once::new();
WARNED.call_once(|| {
tracing::warn!(
"a run arrived with a `traceparent`, but the subscriber has no \
tracing-opentelemetry 0.33 layer this SDK can reach, so the trace does not \
continue here; see the `otel` feature in hatchet-client's README"
);
});
}
#[cfg(test)]
mod tests {
use opentelemetry::trace::TracerProvider as _;
use opentelemetry_sdk::trace::SdkTracerProvider;
use serde_json::json;
use tracing_subscriber::layer::SubscriberExt;
use super::*;
fn context(trace: &str, span: &str, flags: TraceFlags) -> SpanContext {
SpanContext::new(
TraceId::from_hex(trace).unwrap(),
SpanId::from_hex(span).unwrap(),
flags,
false,
TraceState::NONE,
)
}
fn traced<R>(f: impl FnOnce() -> R) -> R {
let provider = SdkTracerProvider::builder().build();
let subscriber = tracing_subscriber::registry()
.with(tracing_opentelemetry::layer().with_tracer(provider.tracer("unit")));
tracing::subscriber::with_default(subscriber, f)
}
fn object(raw: Option<&str>) -> Value {
serde_json::from_str(raw.expect("metadata was written")).expect("metadata is JSON")
}
#[test]
fn a_sampled_context_is_a_version_00_traceparent() {
let sampled = context(
"4bf92f3577b34da6a3ce929d0e0e4736",
"00f067aa0ba902b7",
TraceFlags::SAMPLED,
);
assert_eq!(
format(&sampled).as_deref(),
Some("00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01")
);
}
#[test]
fn an_unsampled_context_keeps_its_flags_and_leading_zeros() {
let unsampled = context(
"000000000000000000000000000000ab",
"00000000000000cd",
TraceFlags::NOT_SAMPLED,
);
assert_eq!(
format(&unsampled).as_deref(),
Some("00-000000000000000000000000000000ab-00000000000000cd-00")
);
}
#[test]
fn upper_case_hex_comes_out_lower_case() {
let upper = context(
"4BF92F3577B34DA6A3CE929D0E0E4736",
"00F067AA0BA902B7",
TraceFlags::SAMPLED,
);
assert_eq!(
format(&upper).as_deref(),
Some("00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01")
);
}
#[test]
fn an_invalid_context_is_no_traceparent() {
assert_eq!(format(&SpanContext::NONE), None);
let zero_trace = context(
"00000000000000000000000000000000",
"00f067aa0ba902b7",
TraceFlags::SAMPLED,
);
assert_eq!(format(&zero_trace), None);
let zero_span = context(
"4bf92f3577b34da6a3ce929d0e0e4736",
"0000000000000000",
TraceFlags::SAMPLED,
);
assert_eq!(format(&zero_span), None);
}
#[test]
fn inject_writes_the_spans_traceparent_beside_every_other_key() {
traced(|| {
let span = tracing::info_span!("trigger");
let mut metadata = Some(r#"{"customer":"acme","n":1}"#.to_string());
inject(&span, &mut metadata);
let expected = format(span.context().span().span_context())
.expect("the layer gave the span a valid context");
assert_eq!(
object(metadata.as_deref()),
json!({"customer": "acme", "n": 1, "traceparent": expected})
);
});
}
#[test]
fn inject_makes_an_object_when_there_was_no_metadata() {
traced(|| {
let span = tracing::info_span!("trigger");
let mut metadata = None;
inject(&span, &mut metadata);
let expected = format(span.context().span().span_context()).unwrap();
assert_eq!(
object(metadata.as_deref()),
json!({"traceparent": expected})
);
});
}
#[test]
fn inject_replaces_a_traceparent_already_there() {
traced(|| {
let span = tracing::info_span!("trigger");
let mut metadata = Some(
r#"{"traceparent":"00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"}"#
.to_string(),
);
inject(&span, &mut metadata);
let expected = format(span.context().span().span_context()).unwrap();
assert_eq!(
object(metadata.as_deref()),
json!({"traceparent": expected})
);
});
}
#[test]
fn inject_leaves_metadata_alone_without_a_layer() {
let span = tracing::info_span!("no layer here");
let original =
r#"{"traceparent":"00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"}"#;
let mut metadata = Some(original.to_string());
inject(&span, &mut metadata);
assert_eq!(metadata.as_deref(), Some(original));
let mut none = None;
inject(&span, &mut none);
assert_eq!(none, None);
}
#[test]
fn inject_leaves_metadata_that_is_not_an_object_alone() {
traced(|| {
let span = tracing::info_span!("trigger");
let mut metadata = Some("[1,2]".to_string());
inject(&span, &mut metadata);
assert_eq!(metadata.as_deref(), Some("[1,2]"));
});
}
const TRACE: &str = "4bf92f3577b34da6a3ce929d0e0e4736";
const SPAN: &str = "00f067aa0ba902b7";
const VALID: &str = "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01";
#[test]
fn a_version_00_traceparent_is_a_remote_sampled_context() {
let parsed = parse(VALID).expect("a valid traceparent");
assert_eq!(parsed.trace_id(), TraceId::from_hex(TRACE).unwrap());
assert_eq!(parsed.span_id(), SpanId::from_hex(SPAN).unwrap());
assert!(parsed.is_sampled());
assert!(parsed.is_remote(), "it came from another process");
}
#[test]
fn parse_and_format_round_trip() {
for value in [
VALID,
"00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00",
] {
assert_eq!(format(&parse(value).unwrap()).as_deref(), Some(value));
}
}
#[test]
fn a_later_version_may_carry_more_fields() {
let later = "cc-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01-what-comes-next";
assert!(parse(later).is_some());
}
#[test]
fn only_the_sampled_flag_is_kept() {
let parsed = parse("00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-ff").unwrap();
assert_eq!(parsed.trace_flags(), TraceFlags::SAMPLED);
}
#[test]
fn malformed_traceparents_are_ignored() {
for value in [
"",
"not-a-traceparent",
"00-4BF92F3577B34DA6A3CE929D0E0E4736-00F067AA0BA902B7-01",
"ff-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
"00-00000000000000000000000000000000-00f067aa0ba902b7-01",
"00-4bf92f3577b34da6a3ce929d0e0e4736-0000000000000000-01",
"00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01-extra",
"00-4bf92f3577b34da6a3ce929d0e0e473-00f067aa0ba902b7-01",
"00-+bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
"00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-1",
"0-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
] {
assert!(parse(value).is_none(), "{value:?} must not parse");
}
}
#[test]
fn from_metadata_reads_that_one_key() {
assert!(from_metadata(&format!(r#"{{"traceparent":"{VALID}","other":1}}"#)).is_some());
assert!(from_metadata(&format!(r#"{{"Traceparent":"{VALID}"}}"#)).is_none());
assert!(from_metadata(r#"{"traceparent":7}"#).is_none());
assert!(from_metadata(r#"{"traceparent":""}"#).is_none());
assert!(from_metadata(r#"{"traceparent":null}"#).is_none());
assert!(from_metadata("not json").is_none());
assert!(from_metadata("[]").is_none());
}
#[test]
fn extract_names_the_remote_parent_or_nothing() {
let tracestate = format!(r#"{{"traceparent":"{VALID}","tracestate":"vendor=1"}}"#);
let context = extract(Some(&tracestate)).expect("a parent");
let parent = context.span().span_context().clone();
assert_eq!(parent.trace_id(), TraceId::from_hex(TRACE).unwrap());
assert!(parent.is_remote());
assert!(extract(None).is_none());
assert!(extract(Some(r#"{"customer":"acme"}"#)).is_none());
}
#[test]
fn continue_from_puts_the_span_under_the_remote_parent() {
traced(|| {
let span = tracing::info_span!("run");
continue_from(&span, Some(&format!(r#"{{"traceparent":"{VALID}"}}"#)));
let context = span.context();
let own = context.span().span_context().clone();
assert_eq!(own.trace_id(), TraceId::from_hex(TRACE).unwrap());
assert_ne!(
own.span_id(),
SpanId::from_hex(SPAN).unwrap(),
"a span of its own"
);
});
}
#[test]
fn continue_from_without_a_traceparent_leaves_a_root() {
traced(|| {
let span = tracing::info_span!("run");
continue_from(&span, Some(r#"{"customer":"acme"}"#));
continue_from(&span, None);
let context = span.context();
assert_ne!(
context.span().span_context().trace_id(),
TraceId::from_hex(TRACE).unwrap()
);
});
}
}