Documentation
¶
Overview ¶
Package observability defines the OTel metric and span instruments the SDK records. Instruments are created lazily from the supplied MeterProvider / TracerProvider; when those are nil the instruments resolve to noops via the otel API defaults, so instrumentation is always zero-cost when unused.
Index ¶
- Constants
- func NewPrometheusMeterProvider(reg prometheus.Registerer) (metric.MeterProvider, error)
- type Observer
- func (o *Observer) RecordCLISpawn(ctx context.Context, outcome string)
- func (o *Observer) RecordCost(ctx context.Context, amount float64, currency, model string)
- func (o *Observer) RecordElicitationRequest(ctx context.Context, mode, outcome string)
- func (o *Observer) RecordFsDelegation(ctx context.Context, op, outcome string)
- func (o *Observer) RecordInitializeDuration(ctx context.Context, d time.Duration, success bool)
- func (o *Observer) RecordMCPBridge(ctx context.Context, tool, status string)
- func (o *Observer) RecordMCPCapabilityReject(ctx context.Context, transport string)
- func (o *Observer) RecordPermission(ctx context.Context, outcome string)
- func (o *Observer) RecordPrompt(ctx context.Context, duration time.Duration, stopReason string, ...)
- func (o *Observer) RecordRetryAttempt(ctx context.Context, class, outcome string)
- func (o *Observer) RecordSessionUpdate(ctx context.Context, variant string)
- func (o *Observer) RecordStructuredDecode(ctx context.Context, source, outcome string)
- func (o *Observer) RecordToolCall(ctx context.Context, name, kind, status string, duration time.Duration)
- func (o *Observer) RecordTransportFailure(ctx context.Context, kind string)
- func (o *Observer) RecordUpdateDropped(ctx context.Context, sessionID string)
- func (o *Observer) StartInitializeSpan(ctx context.Context) (context.Context, trace.Span)
- func (o *Observer) StartPromptSpan(ctx context.Context, sessionID string, labels PromptLabels) (context.Context, trace.Span)
- func (o *Observer) StartSubprocessSpan(ctx context.Context, path string) (context.Context, trace.Span)
- func (o *Observer) Tracer() trace.Tracer
- type PromptLabels
- type TokenCounts
Constants ¶
const Namespace = "opencodesdk"
Namespace is the prefix for all SDK-emitted metric and span names.
Variables ¶
This section is empty.
Functions ¶
func NewPrometheusMeterProvider ¶
func NewPrometheusMeterProvider(reg prometheus.Registerer) (metric.MeterProvider, error)
NewPrometheusMeterProvider wires an OTel MeterProvider to the supplied Prometheus registerer via the official go.opentelemetry.io/otel/exporters/prometheus bridge. Callers scrape the registerer from their HTTP handler as usual.
Types ¶
type Observer ¶
type Observer struct {
// contains filtered or unexported fields
}
Observer bundles the SDK's OTel instruments. A nil Observer is not valid — always construct through NewObserver.
func NewObserver ¶
func NewObserver(mp metric.MeterProvider, tp trace.TracerProvider) *Observer
NewObserver constructs an Observer. Either provider may be nil; in that case otel's global providers are used (which default to noops).
func (*Observer) RecordCLISpawn ¶
RecordCLISpawn increments the CLI spawn counter with an outcome label ("started" on successful launch, "error" otherwise).
func (*Observer) RecordCost ¶
RecordCost adds a USD-denominated cost delta to the cumulative cost counter. Non-USD currencies are ignored with no metric emission.
func (*Observer) RecordElicitationRequest ¶
RecordElicitationRequest records one agent-initiated elicitation/create request. mode is "form" or "url" (or "unknown" when the discriminator is absent). outcome is "accept", "decline", "cancel", "error", or "no_callback" when no user callback was configured.
func (*Observer) RecordFsDelegation ¶
RecordFsDelegation records an fs/read|write delegation.
func (*Observer) RecordInitializeDuration ¶
RecordInitializeDuration records the initialize handshake duration.
func (*Observer) RecordMCPBridge ¶
RecordMCPBridge increments the bridge counter for one inbound tool invocation routed through the loopback HTTP MCP bridge.
func (*Observer) RecordMCPCapabilityReject ¶
RecordMCPCapabilityReject records one session-lifecycle call rejected locally because an McpServer entry used a transport the agent did not advertise. transport is "http", "sse", or "unknown".
func (*Observer) RecordPermission ¶
RecordPermission records a permission callback outcome.
func (*Observer) RecordPrompt ¶
func (o *Observer) RecordPrompt(ctx context.Context, duration time.Duration, stopReason string, tokens TokenCounts, labels PromptLabels)
RecordPrompt records duration + token usage for a completed prompt.
func (*Observer) RecordRetryAttempt ¶
RecordRetryAttempt records one ResilientQuery retry decision. outcome is "retry" when the loop is about to sleep, "exhausted" when MaxRetries is reached, or "fatal" when the error is not retryable.
func (*Observer) RecordSessionUpdate ¶
RecordSessionUpdate increments the session/update counter for a given variant (e.g. "agent_message_chunk", "tool_call", "usage_update").
func (*Observer) RecordStructuredDecode ¶
RecordStructuredDecode records one DecodeStructuredOutput call. source is "notifications" when the payload came from session-update meta, "text" when parsed from the assistant text, or "prompt_meta" when read from PromptResult.Meta. outcome is "ok" or "missing".
func (*Observer) RecordToolCall ¶
func (o *Observer) RecordToolCall(ctx context.Context, name, kind, status string, duration time.Duration)
RecordToolCall records one tool-call terminal event (a ToolCallUpdate carrying a terminal status, or a ToolCall arriving already in a terminal state). duration may be zero if the SDK never observed the start edge.
func (*Observer) RecordTransportFailure ¶
RecordTransportFailure records one transport-layer failure observation. kind is "send", "read", or "subprocess".
func (*Observer) RecordUpdateDropped ¶
RecordUpdateDropped increments the counter for a session/update notification that was discarded because the per-session updates buffer was full.
func (*Observer) StartInitializeSpan ¶
StartInitializeSpan opens a span covering the ACP initialize handshake.
func (*Observer) StartPromptSpan ¶
func (o *Observer) StartPromptSpan(ctx context.Context, sessionID string, labels PromptLabels) (context.Context, trace.Span)
StartPromptSpan opens a span covering one session/prompt turn.
func (*Observer) StartSubprocessSpan ¶
func (o *Observer) StartSubprocessSpan(ctx context.Context, path string) (context.Context, trace.Span)
StartSubprocessSpan opens a span covering the opencode subprocess's lifetime. The caller is expected to keep the span open until the subprocess exits; End the span at shutdown.
type PromptLabels ¶
PromptLabels describes the optional per-session attributes attached to prompt-scoped metrics. Empty strings are dropped so sessions without a configured model/mode/user don't emit empty labels.
Source Files