reference
@kestrel-agents/observability
Kestrel-native tracing and OpenTelemetry export for runs, streams, resumptions, and subscriptions.
SDKintermediate0.7.0 Stable
The package starts with a Kestrel-native trace model and offers OTEL export as a bridge.
Install
Bash
pnpm add @kestrel-agents/observability@0.7.0 @kestrel-agents/sdk@0.7.0
Core 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 |
Wrap an agent
TypeScript
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 |
Use the trace data
Your application continues to work with runs, sessions, and subscriptions while exporters translate trace records for external observability tools.
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 |
Use traces in operation
