Documentation
¶
Overview ¶
Package observability provides OpenTelemetry metrics and tracing for the SDK.
Index ¶
- Constants
- Variables
- func CheckpointOp(v string) attribute.KeyValue
- 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 Retry(v bool) attribute.KeyValue
- func RetryAttempt(v int) attribute.KeyValue
- func RetryDelay(v time.Duration) attribute.KeyValue
- func StatusClass(v string) attribute.KeyValue
- func StatusClassOf(code int) string
- func ThinkingTokens(v int64) attribute.KeyValue
- type Config
- type HTTPStatusError
- type Observer
- func (o *Observer) Classify(err error) agenterrclass.Class
- func (o *Observer) RecordCheckpointOp(ctx context.Context, op, outcome string)
- func (o *Observer) RecordHTTPRequest(ctx context.Context, statusClass string, isRetry bool)
- func (o *Observer) RecordHTTPRequestDuration(ctx context.Context, seconds float64, statusClass string, isRetry bool)
- 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)
- 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) StartHTTPSpan(ctx context.Context, endpoint string) (context.Context, *agenttracer.Span)
- 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) StartToolSpan(ctx context.Context, toolName, callID string) (context.Context, *agenttracer.Span)
Constants ¶
const ( ClassUnsupportedHookEvent errclass.Class = "unsupported_hook_event" ClassUnsupportedHookOutput errclass.Class = "unsupported_hook_output" ClassExecution errclass.Class = "execution" )
SDK-local error classes. Define only where distinguishing the class on dashboards is worth the extra cardinality.
Variables ¶
var ( StatusClassKey = attribute.Key("status_class") RetryKey = attribute.Key("retry") RetryAttemptKey = attribute.Key("retry.attempt") RetryDelayKey = attribute.Key("retry.delay") OutcomeKey = attribute.Key("outcome") CheckpointOpKey = attribute.Key("checkpoint.op") HookEventKey = attribute.Key("hook.event") ThinkingTokensKey = attribute.Key("thinking.tokens") )
SDK-local attribute keys. Not covered by any OTel spec; OpenRouter-specific operational labels. Value sets must stay bounded (cardinality discipline).
Functions ¶
func CheckpointOp ¶
func FinishReasons ¶
FinishReasons returns the gen_ai.response.finish_reasons span attribute. Per GenAI semconv this is a string array; OpenRouter has a single stop reason.
func NewPrometheusMeterProvider ¶
func NewPrometheusMeterProvider(reg prometheus.Registerer) (metric.MeterProvider, error)
func RetryAttempt ¶
func StatusClass ¶
func StatusClassOf ¶
StatusClassOf returns "2xx"/"3xx"/"4xx"/"5xx"/"other" for an HTTP status code.
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 HTTPStatusError ¶
HTTPStatusError is returned by the transport for non-2xx HTTP responses.
func (*HTTPStatusError) Error ¶
func (e *HTTPStatusError) Error() string
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) RecordCheckpointOp ¶
RecordCheckpointOp increments the checkpoint-ops counter and emits a span event.
func (*Observer) RecordHTTPRequest ¶
RecordHTTPRequest increments the HTTP request counter.
func (*Observer) RecordHTTPRequestDuration ¶
func (o *Observer) RecordHTTPRequestDuration(ctx context.Context, seconds float64, statusClass string, isRetry bool)
RecordHTTPRequestDuration records the HTTP request duration histogram.
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.
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) StartHTTPSpan ¶
func (o *Observer) StartHTTPSpan( ctx context.Context, endpoint string, ) (context.Context, *agenttracer.Span)
StartHTTPSpan opens a child span for a vLLM HTTP request. The transport only issues POSTs, so method is hardcoded.
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) 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. provider.name is set so tool spans carry the same filterable labels as query spans. callID is optional; pass "" if the tool call has no upstream identifier.
Source Files