Observability

Tracer that exports TraceEvents as OpenTelemetry spans.

Construction options are documented on OTelTracerOptions.

The tracer field is a Tracer reference suitable for passing into runAgent/Maniac.run; the underlying emit() calls are still recorded on the in-memory tracer (so the existing AgentResult.trace/runAgentStream consumers continue to work) and forwarded to OTel as spans for export.

Constructors

Constructor

new OTelTracer(options?): OTelTracer

Defined in: src/observability/otel.ts:145

Parameters

options?

OTelTracerOptions = {}

Returns

OTelTracer

Properties

tracer

readonly tracer: Tracer

Defined in: src/observability/otel.ts:122

The wrapped in-memory tracer.

Accessors

errors

Get Signature

get errors(): readonly Error[]

Defined in: src/observability/otel.ts:223

Errors caught inside the dispatch path (telemetry MUST NOT crash the agent loop). Mostly useful for tests.

Returns

readonly Error[]

Methods

fromOtlp()

static fromOtlp(options?): Promise<OTelTracer>

Defined in: src/observability/otel.ts:179

Build a self-contained tracer that ships OTLP/HTTP spans.

Wires up an OTLP HTTP span exporter + BatchSpanProcessor against a BasicTracerProvider. Requires the optional @opentelemetry/exporter-trace-otlp-http peer dependency to be installed; throws a helpful error otherwise.

For any other backend (Honeycomb, Datadog, Tempo) configure your own TracerProvider once and pass it via the constructor instead.

Parameters

options?

OTelTracerFromOtlpOptions = {}

Returns

Promise<OTelTracer>

shutdown()

shutdown(): Promise<void>

Defined in: src/observability/otel.ts:234

Flush and shut down the OTel pipeline if we own it.

Safe to call multiple times. When tracerProvider was passed in (BYO-provider path), this only closes outstanding spans and is a no-op on the provider — the caller owns the lifecycle.

Returns

Promise<void>

onEvent()

onEvent(event): void

Defined in: src/observability/otel.ts:254

Translate an emitted TraceEvent into an OTel span action.

Parameters

event

{ ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "token"; payload: {[key: string]: unknown; model?: string; scope?: string; iteration?: number; toolset?: string | null; lm_span_id?: string | null; usage_delta?: { prompt: number; completion: number; cost_usd?: number | null; cache_creation_input_tokens?: number | null; cache_read_input_tokens?: number | null; } | null; finish_reason?: string | null; raw_finish_reason?: string | null; }; delta: string; chunk_kind?: "text" | "reasoning" | "json_partial" | "object_partial" | "tool_call_partial" | "control" | null; content_part_kind?: "file" | "text" | "image" | null; partial_object?: JsonDict | null; tool_call_delta?: { index: number; id?: string | null; name?: string | null; arguments_partial: string; } | null; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "lm_call_start"; payload: {[key: string]: unknown; model: string; scope: string; iteration: number; toolset?: string | null; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "lm_call"; payload: {[key: string]: unknown; model: string; scope: string; iteration: number; usage: { prompt: number; completion: number; cost_usd?: number | null; cache_creation_input_tokens?: number | null; cache_read_input_tokens?: number | null; }; finish_reason: string; toolset?: string | null; raw_finish_reason?: string | null; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "tool"; payload: {[key: string]: unknown; tool_call_id: string; tool_name: string; toolset?: string | null; phase: "completed" | "failed" | "cancelled" | "started"; args?: JsonDict; result?: JsonDict | null; result_preview?: {[key: string]: unknown; ok?: boolean; value?: unknown; error?: string | null; metadata?: JsonDict | null; result_truncated?: boolean; value_omitted_reason?: string | null; } | null; ok?: boolean | null; allowed?: boolean | null; error?: string | null; reason?: string | null; started_at?: string | null; finished_at?: string | null; elapsed_ms?: number | null; decision?: {[key: string]: unknown; allowed: boolean; requires_approval: boolean; matched_rule_id?: string | null; reason?: string | null; } | null; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "tool_call_arguments_delta"; payload: {[key: string]: unknown; tool_call_id?: string | null; tool_name?: string | null; index: number; arguments_delta: string; sequence: number; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "cell"; payload: {[key: string]: unknown; cell_id: string; phase: "completed" | "failed" | "cancelled" | "started"; code?: string | null; result?: JsonDict | null; error?: string | null; elapsed_ms?: number | null; stdout_len?: number | null; stderr_len?: number | null; variables?: string[] | null; src?: string | null; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "subagent"; payload: {[key: string]: unknown; phase: "error" | "completed" | "intent" | "start" | "paused" | "errored"; agent_id?: string | null; toolset?: string | null; role?: string | null; prompt_summary?: string | null; prompt?: string | null; parent_span_id?: string | null; background?: boolean | null; iterations?: number | null; reason?: string | null; max_depth?: number | null; repl?: boolean | null; usage?: { prompt: number; completion: number; cost_usd?: number | null; cache_creation_input_tokens?: number | null; cache_read_input_tokens?: number | null; } | null; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "agent"; payload: {[key: string]: unknown; phase: "completed" | "started"; agent_id: string; principal?: string | null; iterations?: number | null; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "approval"; payload: {[key: string]: unknown; phase: "requested" | "approved" | "denied" | "resolved"; id?: string; toolset?: string | null; tool?: string | null; rule_id?: string | null; reason?: string | null; source: "guardrail" | "policy"; decision?: "approve" | "deny" | null; approvals: object[]; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "memory"; payload: {[key: string]: unknown; op: string; phase?: string | null; principal?: string | null; depth?: number | null; summary?: string | null; namespace?: string | null; agent_id?: string | null; thread_id?: string | null; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "guardrail"; payload: {[key: string]: unknown; phase: string; boundary?: string | null; action?: string | null; decision?: string | null; rule_id?: string | null; reason?: string | null; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "background_task"; payload: {[key: string]: unknown; phase: string; task_id: string; status?: string | null; progress?: number | null; output?: JsonDict | null; agent_id?: string | null; sub_agent_id?: string | null; tool?: string | null; attempt?: number | null; error?: string | null; iterations?: number | null; timeout_ms?: number | null; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "step"; payload: {[key: string]: unknown; phase: "before" | "after" | "repair" | "stopped" | "finalize_vetoed"; turn_index: number; iteration?: number | null; source?: string | null; reason?: string | null; elapsed_ms?: number | null; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "retry"; payload: {[key: string]: unknown; attempt: number; reason: string; model?: string | null; max_attempts?: number | null; delay_s?: number | null; fallback?: boolean | null; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "final"; payload: {[key: string]: unknown; source: string; iterations?: number | null; validated?: boolean | null; error?: string | null; pending?: number | null; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "error"; payload: {[key: string]: unknown; message: string; kind_of_error?: string | null; cause?: string | null; retryable?: boolean | null; reason?: string | null; detail?: string | null; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "stream_gap"; payload: {[key: string]: unknown; dropped_count_so_far: number; }; } | { ts: string; depth: number; principal?: string | null; span_id?: string | null; parent_span_id?: string | null; seq: number; event_id: string; run_id: string; turn_id?: string | null; message_id?: string | null; block_id?: string | null; thread_id?: string | null; kind: "plan"; payload: {[key: string]: unknown; entries: object[]; }; }

void

Type Aliases

OTelTracerOptions

OTelTracerOptions = object

Defined in: src/observability/otel.ts:73

Properties

tracerProvider?

optional tracerProvider?: TracerProvider

Defined in: src/observability/otel.ts:81

An existing TracerProvider. If provided, we use it as-is. If not, the constructor uses trace.getTracerProvider() (the global default, which is a no-op provider unless something else has configured it). For an out-of-the-box OTLP setup, prefer the static OTelTracer.fromOtlp(...) factory.