Module tracer 

Tracer capability trait for distributed-tracing exporters.

A Tracer plugin turns span events produced by the bext runtime (and other plugins) into whatever wire format its backend expects — OTLP, Datadog, Honeycomb, line-oriented stdout for development, and so on. See plan/ecosystem/02-capabilities.md for the design rationale and the list of reference implementations landing in E1.

Design rules

• No opentelemetry crate types in the trait. Trace IDs, span IDs, attribute values, kinds, and status codes are all plain data. A non-otel implementation (like @bext/tracer-stdout) must be able to satisfy the trait without pulling in opentelemetry as a transitive dep. An OTLP-based implementation maps these types 1:1 into the otel SDK.
• Aligned with OpenTelemetry semantic conventions. IDs are the same widths as the OTel wire format (16 bytes trace id, 8 bytes span id), status codes match OTel’s Unset/Ok/Error, span kinds match OTel’s Internal/Server/Client/Producer/Consumer, and attribute value types cover the OTel semantic-convention allowed set (string / bool / int / float / arrays). Plugin authors are expected to use the OTel semconv attribute keys (e.g. http.request.method, http.response.status_code); the trait does not enforce this.
• Explicit parent context, not thread-local. A span is started with an explicit Option<SpanHandle> parent, so callers control propagation and the trait stays async-runtime-agnostic. Thread-local propagation, if wanted, is a concern for a helper layer above this trait, not the trait itself.
• Infallible recording, fallible flush. start_span / set_attribute / set_status / add_event / end_span never return errors — a tracing failure must never break the caller. Only flush (which does real I/O) returns Result. Implementations that hit transient errors record them internally and surface them at flush time or via their own metrics.
• Sync and object-safe. Matches the rest of the plugin API: all methods are synchronous, there are no generic parameters on trait methods, and SpanHandle is a plain Copy value — so dyn Tracer works across the WASM ABI and the in-process host-function table alike.

Structs

SpanEvent

A point-in-time event recorded inside a span. Events do not have durations; they are the OTel equivalent of a structured log line scoped to a span.

SpanHandle

An opaque handle returned by TracerPlugin::start_span. Passing a SpanHandle back to the same tracer is how the runtime attaches attributes, events, and status to an active span. Handles are cheap Copy values — they are just the id pair the tracer already emits on the wire.

SpanStart

Arguments for TracerPlugin::start_span. A struct rather than a long positional parameter list so the trait stays forward-compatible: new optional fields can be added without breaking existing implementations that use ..Default::default().

Enums

AttrValue

Attribute value for spans and events. Matches the value types allowed by the OpenTelemetry semantic-convention specification: string, bool, signed 64-bit int, 64-bit float, and homogeneous arrays of each.

SpanKind

OpenTelemetry-aligned span kind. Mirrors opentelemetry::trace::SpanKind without depending on it. Used by backends to colour spans in the UI and to apply kind-specific semantic conventions.

SpanStatus

OpenTelemetry-aligned span status. Mirrors opentelemetry::trace::Status without depending on it.

Traits

TracerPlugin

A distributed-tracing exporter plugin.