The package starts with a Kestrel-native trace model and offers OTEL export as a bridge.
Install
pnpm add @kestrel-agents/observability@0.8.5 @kestrel-agents/sdk@0.8.5Core APIs
| API | Purpose | Common use |
|---|---|---|
createTracer() | construct the tracer | attach processors and exporters |
InMemoryTraceProcessor | keep traces in process | local debugging and tests |
wrapAgent() | instrument one agent | add trace coverage without changing route logic |
toOpenTelemetrySpans() | bridge to OTEL-compatible records | vendor-neutral export |
Trace context and attributes
Trace context connects actor, tenant, request, correlation, session, thread, run, turn, operation, tool/effect, and terminal identities. Resolve trusted actor fields at the application boundary and propagate identifiers unchanged.
Wrap an agent
const tracer = createTracer({
processors: [new InMemoryTraceProcessor()],
});
const tracedAgent = tracer.wrapAgent(agent);What gets instrumented
| Agent call | Trace kind |
|---|---|
run() | run |
stream() | stream |
resume() | resume |
subscribe() | subscription |
Model/tool operations, terminal outcomes, waits, recovery choices, external approvals/effects, and evaluations remain separately identifiable within the trace. Provider reasoning and agent-authored progress keep their declared source and retention boundary.
Propagation and correlation
Generate request/correlation identity once, carry it across application, runner, worker, provider/tool, and result, and verify all records agree before joining them.
Use the trace data
Your application continues to work with runs, sessions, and subscriptions while exporters translate trace records for external observability tools.
Retention and security
Do not export credentials, active leases, approval secrets, provider continuation state, private reasoning, or unrestricted tool payloads. Apply tenant authorization and retention to trace inspection.
Common failure cases
| Failure | Usually means |
|---|---|
| no traces appear | wrapped agent is not the one used by routes |
| traces lack actor or tenant metadata | request context is incomplete |
| export succeeds but related activity is hard to follow | routes, runs, or reports do not share correlation identifiers |