#OpenTelemetry Trace API

#Main Types

• TracerProvider: entry point that creates tracers
• Tracer: creates spans for one instrumentation scope
• Span: mutable handle for one in-flight operation
• SpanBuilder: immutable descriptor for creating a span with kind, start time, attributes, events, and links
• Event: named timestamped occurrence during a span
• Link: relationship to another span context, often from queues or fan-in workflows
• SpanKind, Status, StatusCode: API trace metadata

#Getting A Tracer

///|
fn _trace_readme_get_tracer() -> Tracer {
  TracerProvider::noop().tracer("moonbit-community/example-library")
}

#Creating Spans

///|
async fn _trace_readme_span_lifecycle() -> Unit {
  let tracer = TracerProvider::noop().tracer("example")
  let builder = tracer
    .span_builder("http.request")
    .with_kind(Server)
    .with_attributes([
      @common.KeyValue::new("http.request.method", String("GET")),
    ])
  let span = tracer.build(builder)

  span.add_event("handler.start")
  span.set_status(Status::ok())
  span.end()
}

#Parent Context And Propagation

#Events, Attributes, Links, And Status

• Attributes describe span dimensions such as route, peer, queue, or database system. Prefer low-cardinality values.
• Events describe point-in-time facts inside a span, such as retries or exceptions.
• Links connect a span to another span context without making it the parent. They are useful for batch processing, queues, or fan-in/fan-out workflows.
• Status communicates final outcome. record_error(message) adds an exception event but intentionally does not set error status for you.

#Builder Reference

• Event::new(name, timestamp?, attributes?, dropped_attributes_count?) creates one event. The timestamp defaults to current Unix time in nanoseconds.
• Link::new(span_context, attributes?, dropped_attributes_count?) creates one link. Invalid linked span contexts are ignored when a span is built.
• SpanBuilder::from_name(name) starts a builder.
• with_kind(kind) sets client/server/producer/consumer/internal kind.
• with_start_time(ts) sets an explicit start timestamp.
• with_attributes(attributes) replaces initial attributes.
• with_events(events) replaces initial events.
• with_links(links) replaces initial links.

#Provider Reference

• TracerProvider::noop() creates non-recording spans.
• tracer(name) creates a tracer for one instrumentation name.
• tracer_with_scope(scope) creates a tracer from a full instrumentation scope.

#Span Reference

• span_context() returns the context that should be propagated downstream.
• context() returns a Context carrying this span context.
• is_recording() reports whether mutations are being recorded.
• has_ended() reports whether the span has ended.
• add_event(name, attributes?) and add_event_with_timestamp(name, ts,attributes?) add events.
• set_attribute(attribute) and set_attributes(attributes) update attributes.
• set_status(status), update_name(new_name), and add_link(span_context,attributes?) mutate span metadata.
• end() and end_with_timestamp(ts) finish the span.

#No-Op Behavior

• is_recording() is false
• mutating methods do not export or store telemetry
• a valid incoming parent span context is still propagated
• ending the span only marks the local no-op handle as ended