///|
priv struct TraceShared {
dispatch : Dispatch
trace_ids : TraceIdAllocator
root_parent : SpanContext?
trace_flags : TraceFlags
trace_state : TraceState
trace_id : Ref[TraceId?]
next_span_id : Ref[Int64]
}
///|
/// Handle that owns the lifecycle of a started span.
///
/// A disabled handle represents a span callsite that was filtered out. Disabled
/// handles never emit records and all lifecycle methods report `false`.
pub struct SpanHandle {
priv span : SpanContext?
priv lanes : Array[Lane]
priv closed : Ref[Bool]
}
///|
/// Snapshot of tracing state that callers pass explicitly across async
/// boundaries.
pub struct TraceContext {
priv shared : TraceShared
priv current_span : SpanContext?
priv baggage : Baggage
}
///|
fn new_trace_shared(
dispatch : Dispatch,
trace_ids : TraceIdAllocator,
root_parent : SpanContext?,
) -> TraceShared {
let trace_id = match root_parent {
Some(parent) if parent.is_valid() => Some(parent.trace_id)
_ => None
}
let trace_flags = match root_parent {
Some(parent) if parent.is_valid() => parent.trace_flags
_ => TraceFlags::sampled()
}
let trace_state = match root_parent {
Some(parent) if parent.is_valid() => parent.trace_state
_ => TraceState::empty()
}
{
dispatch,
trace_ids,
root_parent,
trace_flags,
trace_state,
trace_id: Ref(trace_id),
next_span_id: Ref(0L),
}
}
///|
fn TraceShared::allocate_span_id(self : TraceShared) -> SpanId {
self.trace_ids.allocate_span_id(self.next_span_id)
}
///|
fn TraceContext::ensure_trace_id(self : TraceContext) -> TraceId {
match self.shared.trace_id.val {
Some(trace_id) => trace_id
None => {
let trace_id = self.shared.trace_ids.allocate()
self.shared.trace_id.val = Some(trace_id)
trace_id
}
}
}
///|
fn SpanHandle::disabled() -> SpanHandle {
{ span: None, lanes: [], closed: Ref(true), }
}
///|
fn SpanHandle::enabled(span : SpanContext, lanes : Array[Lane]) -> SpanHandle {
{ span: Some(span), lanes, closed: Ref(false), }
}
///|
/// Return the span identity owned by this handle.
///
/// Disabled handles return `None`.
pub fn SpanHandle::span_context(self : SpanHandle) -> SpanContext? {
self.span
}
///|
pub fn SpanHandle::span_ref(self : SpanHandle) -> SpanContext? {
self.span_context()
}
///|
/// Record additional fields on an active span.
///
/// The function returns `false` when the handle is disabled or the span was
/// already closed.
pub fn SpanHandle::record(self : SpanHandle, fields : ArrayView[Field]) -> Bool {
guard self.span is Some(span) else { return false }
guard !self.closed.val else { return false }
validate_fields(fields)
let record = { span, fields: fields.to_owned(), }
for lane in self.lanes {
lane.subscriber.on_span_record(record)
}
true
}
///|
/// Emit a follows-from link from this span to `cause`.
///
/// The function returns `false` when the handle is disabled or the span was
/// already closed.
pub fn SpanHandle::follows_from(self : SpanHandle, cause : SpanContext) -> Bool {
guard self.span is Some(span) else { return false }
guard !self.closed.val else { return false }
let link = { span, follows_from: cause, }
for lane in self.lanes {
lane.subscriber.on_span_link(link)
}
true
}
///|
/// Close a span handle exactly once.
///
/// `status` defaults to `Ok`. When `error` is provided it is carried in the
/// emitted `SpanEnd` record.
///
/// The function returns `true` only for the first successful close.
pub fn SpanHandle::close(
self : SpanHandle,
status~ : SpanStatus = Ok,
error? : String,
) -> Bool {
guard self.span is Some(span) else { return false }
guard !self.closed.val else { return false }
self.closed.val = true
let record = { span, status, error, }
for lane in self.lanes {
lane.subscriber.on_span_end(record)
}
true
}
///|
fn TraceContext::start_span(
self : TraceContext,
level : Level,
name : String,
target : String?,
fields : ArrayView[Field],
follows_from : ArrayView[SpanContext],
parent : SpanContext?,
filtered_ctx : TraceContext,
loc : SourceLoc,
) -> (SpanHandle, TraceContext) {
validate_fields(fields)
let metadata = {
kind: Span,
level,
name,
target: normalize_target(target, loc),
loc,
}
let lanes = self.dispatch().select_lanes(metadata)
if lanes.is_empty() {
(SpanHandle::disabled(), filtered_ctx)
} else {
let trace_id = self.ensure_trace_id()
let span = SpanContext::new(
trace_id,
self.shared.allocate_span_id(),
trace_flags=self.shared.trace_flags,
trace_state=self.shared.trace_state,
)
let start = { metadata, span, parent, fields: fields.to_owned(), }
for lane in lanes {
lane.subscriber.on_span_start(start)
}
let handle = SpanHandle::enabled(span, lanes)
for link in follows_from {
ignore(handle.follows_from(link))
}
(
handle,
{ shared: self.shared, current_span: Some(span), baggage: self.baggage, },
)
}
}
///|
async fn[X] run_started_span(
handle : SpanHandle,
child_ctx : TraceContext,
filtered_ctx : TraceContext,
f : async (TraceContext) -> X,
) -> X {
guard handle.span_context() is Some(_) else { return f(filtered_ctx) }
defer (if @async.is_being_cancelled() {
ignore(handle.close(status=Cancelled))
})
let result : Result[X, Error] = Ok(f(child_ctx)) catch { err => Err(err) }
match result {
Err(err) => {
ignore(handle.close(status=Error, error=err.to_string()))
raise err
}
Ok(value) => {
ignore(handle.close())
value
}
}
}
///|
/// Create a root tracing context backed by `dispatch`.
///
/// The trace identifier is allocated lazily when the context first emits an
/// enabled record.
pub fn TraceContext::root(
dispatch : Dispatch,
trace_ids : TraceIdAllocator,
) -> TraceContext {
{
shared: new_trace_shared(dispatch, trace_ids, None),
current_span: None,
baggage: Baggage::empty(),
}
}
///|
/// Create a root tracing context that inherits a propagated remote parent.
pub fn TraceContext::root_with_parent(
dispatch : Dispatch,
trace_ids : TraceIdAllocator,
parent : SpanContext,
baggage~ : Baggage = Baggage::empty(),
) -> TraceContext {
let root_parent = if parent.is_valid() { Some(parent) } else { None }
{
shared: new_trace_shared(dispatch, trace_ids, root_parent),
current_span: None,
baggage,
}
}
///|
/// Return the current span, if any.
pub fn TraceContext::current_span(self : TraceContext) -> SpanContext? {
self.current_span
}
///|
/// Return the span that should be propagated to downstream work.
///
/// This is the current local span when one exists, otherwise the propagated
/// remote parent captured by `root_with_parent`.
pub fn TraceContext::propagated_span(self : TraceContext) -> SpanContext? {
match self.current_span {
Some(span) => Some(span)
None => self.shared.root_parent
}
}
///|
fn TraceContext::dispatch(self : TraceContext) -> Dispatch {
self.shared.dispatch
}
///|
pub fn TraceContext::baggage(self : TraceContext) -> Baggage {
self.baggage
}
///|
pub fn TraceContext::with_baggage(
self : TraceContext,
baggage : Baggage,
) -> TraceContext {
{ ..self, baggage, }
}
///|
/// Emit an event from the current trace context.
///
/// If no dispatch lane enables the callsite metadata, the event is ignored.
#callsite(autofill(loc))
pub fn TraceContext::event(
self : TraceContext,
level : Level,
name : String,
message? : String,
target? : String,
fields~ : ArrayView[Field] = [],
loc~ : SourceLoc,
) -> Unit {
validate_fields(fields)
let metadata = {
kind: Event,
level,
name,
target: normalize_target(target, loc),
loc,
}
let lanes = self.dispatch().select_lanes(metadata)
if lanes.is_empty() {
return
}
let record = {
metadata,
trace_id: self.ensure_trace_id(),
span: self.current_span,
message,
fields: fields.to_owned(),
}
for lane in lanes {
lane.subscriber.on_event(record)
}
}
///|
/// Emit a `Trace` level event from the current trace context.
#callsite(autofill(loc))
pub fn TraceContext::trace(
self : TraceContext,
name : String,
message? : String,
target? : String,
fields~ : ArrayView[Field] = [],
loc~ : SourceLoc,
) -> Unit {
self.event(Trace, name, message?, target?, fields~, loc~)
}
///|
/// Emit a `Debug` level event from the current trace context.
#callsite(autofill(loc))
pub fn TraceContext::debug(
self : TraceContext,
name : String,
message? : String,
target? : String,
fields~ : ArrayView[Field] = [],
loc~ : SourceLoc,
) -> Unit {
self.event(Debug, name, message?, target?, fields~, loc~)
}
///|
/// Emit an `Info` level event from the current trace context.
#callsite(autofill(loc))
pub fn TraceContext::info(
self : TraceContext,
name : String,
message? : String,
target? : String,
fields~ : ArrayView[Field] = [],
loc~ : SourceLoc,
) -> Unit {
self.event(Info, name, message?, target?, fields~, loc~)
}
///|
/// Emit a `Warn` level event from the current trace context.
#callsite(autofill(loc))
pub fn TraceContext::warn(
self : TraceContext,
name : String,
message? : String,
target? : String,
fields~ : ArrayView[Field] = [],
loc~ : SourceLoc,
) -> Unit {
self.event(Warn, name, message?, target?, fields~, loc~)
}
///|
/// Emit an `Error` level event from the current trace context.
#callsite(autofill(loc))
pub fn TraceContext::error(
self : TraceContext,
name : String,
message? : String,
target? : String,
fields~ : ArrayView[Field] = [],
loc~ : SourceLoc,
) -> Unit {
self.event(Error, name, message?, target?, fields~, loc~)
}
///|
/// Start a child span below the current span, if the callsite is enabled.
///
/// If the span is filtered out, the returned child context is exactly `self`
/// and the handle is disabled.
#callsite(autofill(loc))
pub fn TraceContext::span(
self : TraceContext,
level : Level,
name : String,
target? : String,
fields~ : ArrayView[Field] = [],
follows_from~ : ArrayView[SpanContext] = [],
loc~ : SourceLoc,
) -> (SpanHandle, TraceContext) {
let parent = match self.current_span {
Some(span) => Some(span)
None => self.shared.root_parent
}
self.start_span(level, name, target, fields, follows_from, parent, self, loc)
}
///|
/// Run `f` inside a child span when the callsite is enabled.
///
/// On normal return an enabled span ends with `SpanStatus::Ok`.
/// When `f` is cancelled, an enabled span ends with
/// `SpanStatus::Cancelled`.
/// Any other error ends an enabled span with `SpanStatus::Error`, records
/// `err.to_string()` as the end error text, and then re-raises the original
/// error.
///
/// If the callsite is filtered out, `f` runs with the original context and no
/// span records are emitted.
#callsite(autofill(loc))
pub async fn[X] TraceContext::with_span(
self : TraceContext,
level : Level,
name : String,
target? : String,
fields~ : ArrayView[Field] = [],
follows_from~ : ArrayView[SpanContext] = [],
loc~ : SourceLoc,
f : async (TraceContext) -> X,
) -> X {
let parent = match self.current_span {
Some(span) => Some(span)
None => self.shared.root_parent
}
let (handle, child_ctx) = self.start_span(
level, name, target, fields, follows_from, parent, self, loc,
)
run_started_span(handle, child_ctx, self, f)
}
///|
/// Spawn a task that inherits the exact tracing context `ctx`.
pub fn[G, X] spawn_inherit(
group : @async.TaskGroup[G],
ctx : TraceContext,
f : async (TraceContext) -> X,
no_wait~ : Bool = false,
allow_failure~ : Bool = false,
) -> @async.Task[X] {
group.spawn(no_wait~, allow_failure~, () => f(ctx))
}
///|
/// Spawn a task inside a new child span in `ctx`'s trace.
///
/// The new span is a child of `ctx.current_span()` when one exists. Otherwise
/// it falls back to the propagated root parent, if any.
#callsite(autofill(loc))
pub fn[G, X] spawn_child_span(
group : @async.TaskGroup[G],
ctx : TraceContext,
level : Level,
name : String,
target? : String,
fields~ : ArrayView[Field] = [],
loc~ : SourceLoc,
f : async (TraceContext) -> X,
no_wait~ : Bool = false,
allow_failure~ : Bool = false,
) -> @async.Task[X] {
let (handle, child_ctx) = ctx.start_span(
level,
name,
target,
fields,
[],
match ctx.current_span() {
Some(span) => Some(span)
None => ctx.shared.root_parent
},
ctx,
loc,
)
group.spawn(no_wait~, allow_failure~, () => {
run_started_span(handle, child_ctx, ctx, f)
})
}
///|
/// Spawn a task in a new span that stays in the same trace but is not a tree
/// child of the current span.
///
/// When `ctx.current_span()` exists, the new span emits a single follows-from
/// link to it. When there is no current span, the spawned task still stays in
/// the same trace and no link is emitted.
#callsite(autofill(loc))
pub fn[G, X] spawn_follower_span(
group : @async.TaskGroup[G],
ctx : TraceContext,
level : Level,
name : String,
target? : String,
fields~ : ArrayView[Field] = [],
loc~ : SourceLoc,
f : async (TraceContext) -> X,
no_wait~ : Bool = false,
allow_failure~ : Bool = false,
) -> @async.Task[X] {
let follows_from : Array[SpanContext] = []
if ctx.current_span() is Some(current_span) {
follows_from.push(current_span)
}
let (handle, child_ctx) = ctx.start_span(
level,
name,
target,
fields,
follows_from[:],
None,
ctx,
loc,
)
group.spawn(no_wait~, allow_failure~, () => {
run_started_span(handle, child_ctx, ctx, f)
})
}