Trait TracerPlugin 

pub trait TracerPlugin: Send + Sync {
    // Required methods
    fn name(&self) -> &str;
    fn start_span(&self, span: SpanStart<'_>) -> SpanHandle;
    fn set_attribute(&self, span: SpanHandle, key: &str, value: AttrValue);
    fn set_status(&self, span: SpanHandle, status: SpanStatus);
    fn add_event(&self, span: SpanHandle, event: SpanEvent<'_>);
    fn end_span(&self, span: SpanHandle, end_time_unix_nanos: Option<u64>);
    fn flush(&self) -> Result<(), String>;
}

A distributed-tracing exporter plugin.

Bext’s observability hooks (and any plugin that wants to emit custom spans) call into the active TracerPlugin through host functions. There is at most one active TracerPlugin per site; multiple backends are achieved by chaining (a fan-out tracer that forwards to several children) rather than by running several implementations side-by-side.

Implementations must be cheap on the hot path. start_span, set_attribute, set_status, add_event, and end_span run inline with the operation they describe; they should buffer rather than perform network I/O. Actual export happens during TracerPlugin::flush, which the runtime calls on an interval and at shutdown.

Required Methods

fn name(&self) -> &str

Unique plugin identifier (e.g. "tracer-otlp", "tracer-stdout").

fn start_span(&self, span: SpanStart<'_>) -> SpanHandle

Begin a new span and return a handle the caller can use to record further state on it. A handle equal to SpanHandle::INVALID means the span was not sampled; the caller should still thread it through as the parent of any children so that sampled/non-sampled codepaths stay structurally identical.

fn set_attribute(&self, span: SpanHandle, key: &str, value: AttrValue)

Attach or overwrite a single attribute on a live span. Keys should follow the OTel semantic conventions (e.g. "http.request.method", "db.system"). Calls against an unknown or invalid handle are a no-op.

fn set_status(&self, span: SpanHandle, status: SpanStatus)

Set the span’s final status. Most backends treat the last call before TracerPlugin::end_span as authoritative. Calls against an unknown or invalid handle are a no-op.

fn add_event(&self, span: SpanHandle, event: SpanEvent<'_>)

Record a point-in-time event on a live span. Calls against an unknown or invalid handle are a no-op.

fn end_span(&self, span: SpanHandle, end_time_unix_nanos: Option<u64>)

End a live span. end_time_unix_nanos is an optional override — pass None to use the tracer’s current clock. After this call the handle must not be used again; implementations are free to recycle its id space.

fn flush(&self) -> Result<(), String>

Flush any buffered spans to the backend. The runtime calls this on a periodic timer and once during graceful shutdown. A flush that cannot reach its backend should return an error string so the host can surface it through the observability layer; buffered spans remain the plugin’s responsibility (drop, retry, or spill to disk, at the plugin’s discretion).

Implementors