Struct WorkflowTraceContext

Source

pub struct WorkflowTraceContext { /* private fields */ }

Expand description

W3C Trace Context for distributed tracing across workflow steps.

Each WorkflowTraceContext carries a trace_id (32 lowercase hex chars) and a span_id (16 lowercase hex chars). Use new_root to start a new trace, child to create a child span, and to_traceparent to emit the W3C header.

§Examples

use ironflow_core::trace_context::WorkflowTraceContext;

let ctx = WorkflowTraceContext::new_root();
assert_eq!(ctx.trace_id().len(), 32);
assert_eq!(ctx.span_id().len(), 16);
assert_eq!(ctx.to_traceparent().len(), 55); // 2 + 1 + 32 + 1 + 16 + 1 + 2

Implementations§

Source §

impl WorkflowTraceContext

Source

pub fn new_root() -> Self

Create a new root trace context with a random trace-id and span-id.

The trace-id is derived from the current timestamp, process ID, and an atomic counter to ensure uniqueness without requiring a CSPRNG.

§Examples

use ironflow_core::trace_context::WorkflowTraceContext;

let ctx = WorkflowTraceContext::new_root();
assert_eq!(ctx.trace_id().len(), 32);
assert_eq!(ctx.span_id().len(), 16);

Source

pub fn from_workflow_run_id(run_id: &str) -> Self

Create a trace context derived from a workflow run ID.

The run_id is hashed (SHA-256) to produce a deterministic 32-hex trace-id. This allows correlating all spans of a given workflow run under a single trace. A fresh span-id is generated for this context.

§Examples

use ironflow_core::trace_context::WorkflowTraceContext;

let ctx = WorkflowTraceContext::from_workflow_run_id("run-abc-123");
assert_eq!(ctx.trace_id().len(), 32);

// Same run_id always produces the same trace_id.
let ctx2 = WorkflowTraceContext::from_workflow_run_id("run-abc-123");
assert_eq!(ctx.trace_id(), ctx2.trace_id());

§Panics

Panics if run_id is empty.

Source

pub fn child(&self) -> Self

Create a child context that shares this trace-id but has a new span-id.

Use this when a workflow step fans out to sub-steps: each child gets its own span-id while remaining part of the same trace.

§Examples

use ironflow_core::trace_context::WorkflowTraceContext;

let parent = WorkflowTraceContext::new_root();
let child = parent.child();
assert_eq!(child.trace_id(), parent.trace_id());
assert_ne!(child.span_id(), parent.span_id());

Source

pub fn to_traceparent(&self) -> String

Format as a W3C traceparent header value.

The output follows the format 00-{trace_id}-{span_id}-01, where 01 indicates the trace is sampled.

§Examples

use ironflow_core::trace_context::WorkflowTraceContext;

let ctx = WorkflowTraceContext::from_traceparent(
    "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
).unwrap();
assert_eq!(
    ctx.to_traceparent(),
    "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
);

Source

pub fn from_traceparent(header: &str) -> Result<Self, TraceContextError>

Parse a W3C traceparent header into a WorkflowTraceContext.

Accepts any version field (not just "00"), but always emits version "00" when calling to_traceparent. Extra fields beyond the 4th are silently ignored.

§Errors

Returns TraceContextError if the header is malformed:

Fewer than 4 dash-separated fields
trace-id is not exactly 32 lowercase hex characters
span-id is not exactly 16 lowercase hex characters
trace-id or span-id is all zeros

§Examples

use ironflow_core::trace_context::WorkflowTraceContext;

let ctx = WorkflowTraceContext::from_traceparent(
    "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
).unwrap();
assert_eq!(ctx.trace_id(), "4bf92f3577b34da6a3ce929d0e0e4736");
assert_eq!(ctx.span_id(), "00f067aa0ba902b7");

Source