Agent Trace

Distributed tracing through every agent boundary. Composes the existing b.tracing (W3C trace context) so operators get a full request waterfall across the agent stack without wiring spans per-handler.

The substrate at v0.9.29 ships the integration surface:

- startSpan(name, opts) — wrap an agent method call in a span - injectIntoEnvelope(envelope) — inject the currently-active span's W3C traceparent + tracestate into queue / event-bus / sub-agent envelopes so the consumer can continue the trace (call inside the startSpan callback so the right span is live) - extractFromEnvelope(envelope) — parse the envelope's trace context (refused via b.guardTraceContext if malformed) - recordResult(span, result, error?) — close span with success / error status - shouldSample(method) — sampling decision (global + per-method override)

Span shape (per method call):

name: "." // e.g. "mail.agent.search" attributes: agent.method: method name agent.dispatch_mode: "local" | "queue" | "auto" agent.tenant_id: from v0.9.26 tenant scope (if present) agent.posture: JSON-array of v0.9.28 posture set agent.shard: from v0.9.21 shard routing agent.result_status: "success" | "error" | "not_implemented" agent.elapsed_ms: integer

var trace = b.agent.trace.create({
  tracing:    b.tracing.create({ instrumentationName: "mail-agent" }),
  sampleRate: 1.0,
  perMethod:  { fetch: 0.1, search: 0.5, send: 1.0 },
});

var span = trace.startSpan("mail.agent.fetch", { actor, method: "fetch" });
try {
  var result = await agent.fetch(args);
  trace.recordResult(span, result);
} catch (e) {
  trace.recordResult(span, null, e);
  throw e;
}

b.agent.trace.create(opts) #

{
  tracing:    b.tracing instance,       // required for live spans
  audit:      b.audit namespace,         // optional
  sampleRate: number in [0..1],          // default 1.0
  perMethod:  { : number },      // override per-method
}

Create the trace facade. Composes operator-supplied b.tracing instance (or stub if absent — spans become no-ops).

var trace = b.agent.trace.create({ tracing: myTracing, sampleRate: 0.5 });
var span = trace.startSpan("mail.agent.fetch", { actor });

Last updated 2026-08-08T16:39:49.652Z by seeder.