Documentation
¶
Overview ¶
Package observability provides OpenTelemetry metrics and tracing for the SDK.
Index ¶
- Constants
- Variables
- func ClassifyHTTPStatus(status int) agenterrclass.Class
- func CompactTrigger(v string) attribute.KeyValue
- func FinishReasons(reasons ...string) attribute.KeyValue
- func HTTPStatusCode(v int) attribute.KeyValue
- func HookEvent(v string) attribute.KeyValue
- func NewPrometheusMeterProvider(reg prometheus.Registerer) (metric.MeterProvider, error)
- func Outcome(v string) attribute.KeyValue
- func RateLimitStatus(v string) attribute.KeyValue
- func ThinkingTokens(v int64) attribute.KeyValue
- type Config
- type Observer
- func (o *Observer) Classify(err error) agenterrclass.Class
- func (o *Observer) RecordAPIRetry(ctx context.Context, class agenterrclass.Class, httpStatus *int)
- func (o *Observer) RecordCompaction(ctx context.Context, trigger string)
- func (o *Observer) RecordCost(ctx context.Context, costUSD float64, model string)
- func (o *Observer) RecordHookDuration(ctx context.Context, seconds float64, event, outcome string)
- func (o *Observer) RecordOperationDuration(ctx context.Context, seconds float64, ...)
- func (o *Observer) RecordRateLimitEvent(ctx context.Context, status string)
- func (o *Observer) RecordTTFT(ctx context.Context, seconds float64, model string)
- func (o *Observer) RecordTokenUsage(ctx context.Context, tokens int64, tokenType upstreamgenai.TokenTypeAttr, ...)
- func (o *Observer) RecordToolCall(ctx context.Context, toolName, outcome string)
- func (o *Observer) RecordToolCallDuration(ctx context.Context, seconds float64, toolName string)
- func (o *Observer) RecordWebSearchRequests(ctx context.Context, count int64, model string)
- func (o *Observer) RegisterMatcher(matcher agenterrclass.Matcher)
- func (o *Observer) RegisterSentinel(err error, class agenterrclass.Class)
- func (o *Observer) StartHookSpan(ctx context.Context, event string) (context.Context, *agenttracer.Span)
- func (o *Observer) StartQuerySpan(ctx context.Context, operationName upstreamgenai.OperationNameAttr, ...) (context.Context, *agenttracer.Span)
- func (o *Observer) StartSessionSpan(ctx context.Context, model, sessionID string) (context.Context, *agenttracer.Span)
- func (o *Observer) StartToolSpan(ctx context.Context, toolName, callID string) (context.Context, *agenttracer.Span)
Constants ¶
const ( ClassCLINotFound errclass.Class = "cli_not_found" ClassProcessError errclass.Class = "process_error" ClassParseError errclass.Class = "parse_error" ClassOverload errclass.Class = "overload" ClassPromptTooLong errclass.Class = "prompt_too_long" ClassMediaTooLarge errclass.Class = "media_too_large" ClassBilling errclass.Class = "billing" ClassExecution errclass.Class = "execution" )
SDK-local error classes. Define only where distinguishing the class on dashboards is worth the extra cardinality. The upstream classes (errclass.Timeout, errclass.RateLimited, errclass.Auth, errclass.Upstream5xx, errclass.Network, errclass.InvalidRequest, errclass.PermissionDenied, errclass.Canceled, errclass.Unknown) cover the cross-SDK cases.
Variables ¶
var ( OutcomeKey = attribute.Key("outcome") HookEventKey = attribute.Key("hook.event") CompactTriggerKey = attribute.Key("compact.trigger") RateLimitStatusKey = attribute.Key("rate_limit.status") HTTPStatusCodeKey = attribute.Key("http.status_code") ThinkingTokensKey = attribute.Key("thinking.tokens") )
SDK-local attribute keys. Not covered by any OTel spec; Claude-specific operational labels. Value sets must stay bounded (cardinality discipline).
Functions ¶
func ClassifyHTTPStatus ¶
func ClassifyHTTPStatus(status int) agenterrclass.Class
ClassifyHTTPStatus exposes the status-to-class mapping for use by APIRetry observation paths that have a status code but no error value.
func CompactTrigger ¶
func FinishReasons ¶
FinishReasons returns the gen_ai.response.finish_reasons span attribute. Per GenAI semconv this is a string array; Claude has a single stop reason.
func HTTPStatusCode ¶
func NewPrometheusMeterProvider ¶
func NewPrometheusMeterProvider(reg prometheus.Registerer) (metric.MeterProvider, error)
NewPrometheusMeterProvider returns an OTel MeterProvider backed by the given Prometheus registerer, with exponential histograms and trace-based exemplars applied by the shared observability helpers.
func RateLimitStatus ¶
func ThinkingTokens ¶
Types ¶
type Config ¶
type Config struct {
MeterProvider metric.MeterProvider
TracerProvider trace.TracerProvider
Logger *slog.Logger
}
Config holds the providers and logger used when constructing an Observer.
type Observer ¶
type Observer struct {
// contains filtered or unexported fields
}
Observer holds the meter/tracer and pre-constructed instruments.
func New ¶
New returns an Observer. Providers default to noop when nil. The upstream instrument constructors can return errors; New propagates them.
func Noop ¶
func Noop() *Observer
Noop returns an Observer with noop providers. A noop meter cannot produce a real instrument-construction error; a non-nil error here would be a library bug, so we panic rather than force every caller to handle an impossible case.
func (*Observer) Classify ¶
func (o *Observer) Classify(err error) agenterrclass.Class
Classify returns the error.type class for err. Returns "" for nil.
func (*Observer) RecordAPIRetry ¶
RecordAPIRetry increments the API retry counter and emits a span event.
func (*Observer) RecordCompaction ¶
RecordCompaction increments the compaction counter and emits a span event.
func (*Observer) RecordCost ¶
RecordCost accumulates USD cost on the SDK-local counter.
func (*Observer) RecordHookDuration ¶
RecordHookDuration records the hook dispatch duration histogram.
func (*Observer) RecordOperationDuration ¶
func (o *Observer) RecordOperationDuration( ctx context.Context, seconds float64, operationName upstreamgenai.OperationNameAttr, model string, class agenterrclass.Class, )
RecordOperationDuration records the spec gen_ai.client.operation.duration histogram with provider+operation positional attributes and optional request.model / error.type extras.
func (*Observer) RecordRateLimitEvent ¶
RecordRateLimitEvent increments the rate-limit counter and emits a span event. status is the status field from the CLI's rate_limit event (e.g., "allowed_warning", "exceeded").
func (*Observer) RecordTTFT ¶
RecordTTFT records time-to-first-token on the SDK-local histogram.
func (*Observer) RecordTokenUsage ¶
func (o *Observer) RecordTokenUsage( ctx context.Context, tokens int64, tokenType upstreamgenai.TokenTypeAttr, operationName upstreamgenai.OperationNameAttr, model string, )
RecordTokenUsage records the spec gen_ai.client.token.usage histogram. Emits a span event for "thinking" tokens.
func (*Observer) RecordToolCall ¶
RecordToolCall increments the tool-call counter.
func (*Observer) RecordToolCallDuration ¶
RecordToolCallDuration records the tool-call duration histogram.
func (*Observer) RecordWebSearchRequests ¶
RecordWebSearchRequests records web search requests made during a turn.
func (*Observer) RegisterMatcher ¶
func (o *Observer) RegisterMatcher(matcher agenterrclass.Matcher)
RegisterMatcher appends a custom matcher to the registry.
func (*Observer) RegisterSentinel ¶
func (o *Observer) RegisterSentinel(err error, class agenterrclass.Class)
RegisterSentinel wires a sentinel error to a class.
func (*Observer) StartHookSpan ¶
func (o *Observer) StartHookSpan(ctx context.Context, event string) (context.Context, *agenttracer.Span)
StartHookSpan opens a child span for a hook dispatch.
func (*Observer) StartQuerySpan ¶
func (o *Observer) StartQuerySpan( ctx context.Context, operationName upstreamgenai.OperationNameAttr, model string, conversationID string, ) (context.Context, *agenttracer.Span)
StartQuerySpan opens the top-level span for a Query()/Client.Query() call.
func (*Observer) StartSessionSpan ¶
func (o *Observer) StartSessionSpan(ctx context.Context, model, sessionID string) (context.Context, *agenttracer.Span)
StartSessionSpan opens a session-level span with the "chat" operation name. This is a convenience wrapper around StartQuerySpan for persistent client sessions.
func (*Observer) StartToolSpan ¶
func (o *Observer) StartToolSpan(ctx context.Context, toolName, callID string) (context.Context, *agenttracer.Span)
StartToolSpan opens a child span for a tool invocation. Spec-conformant "execute_tool {name}" span name and gen_ai.operation.name=execute_tool attribute per GenAI semantic conventions. callID is optional.
Source Files