Documentation
¶
Overview ¶
Package observability provides OpenTelemetry metrics and tracing for the SDK.
Index ¶
- Constants
- Variables
- func ClassifyHTTPStatus(status int) agenterrclass.Class
- func FinishReasons(reasons ...string) attribute.KeyValue
- func HookEvent(v string) attribute.KeyValue
- func NewPrometheusMeterProvider(reg prometheus.Registerer) (metric.MeterProvider, error)
- func Outcome(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) 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) 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) 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" 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") ThinkingTokensKey = attribute.Key("thinking.tokens") )
SDK-local attribute keys. Not covered by any OTel spec; Codex-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 observation paths that have a status code but no error value.
func FinishReasons ¶
FinishReasons returns the gen_ai.response.finish_reasons span attribute. Per GenAI semconv this is a string array; Codex has a single stop reason.
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 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) 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) 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) 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