genai

package
v1.86.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 23, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Overview

Package genai provides OpenTelemetry instrumentation helpers that follow the GenAI semantic conventions (https://opentelemetry.io/docs/specs/semconv/gen-ai/).

The package is structured so that callers — provider clients, the agent runtime, MCP clients — describe what they are doing in domain terms and the helpers produce the spec-conformant spans, metrics, and log records. Centralising the OTel surface here lets us upgrade the semantic conventions in one place and keeps the call sites compact.

All gen_ai.* attributes are Development stability per the spec. Attribute keys are declared as constants in this package rather than imported from go.opentelemetry.io/otel/semconv to insulate callers from the upstream reorganisations the GenAI conventions are still going through.

Index

Constants

View Source 
const (
	AttrOperationName  = "gen_ai.operation.name"
	AttrProviderName   = "gen_ai.provider.name"
	AttrConversationID = "gen_ai.conversation.id"
	AttrOutputType     = "gen_ai.output.type"

	AttrAgentName        = "gen_ai.agent.name"
	AttrAgentID          = "gen_ai.agent.id"
	AttrAgentDescription = "gen_ai.agent.description"
	AttrAgentVersion     = "gen_ai.agent.version"

	AttrWorkflowName = "gen_ai.workflow.name"

	AttrRequestModel            = "gen_ai.request.model"
	AttrRequestStream           = "gen_ai.request.stream"
	AttrRequestMaxTokens        = "gen_ai.request.max_tokens"
	AttrRequestTemperature      = "gen_ai.request.temperature"
	AttrRequestTopP             = "gen_ai.request.top_p"
	AttrRequestTopK             = "gen_ai.request.top_k"
	AttrRequestFrequencyPenalty = "gen_ai.request.frequency_penalty"
	AttrRequestPresencePenalty  = "gen_ai.request.presence_penalty"
	AttrRequestStopSequences    = "gen_ai.request.stop_sequences"
	AttrRequestChoiceCount      = "gen_ai.request.choice.count"
	AttrRequestSeed             = "gen_ai.request.seed"
	AttrRequestEncodingFormats  = "gen_ai.request.encoding_formats"

	AttrResponseModel            = "gen_ai.response.model"
	AttrResponseID               = "gen_ai.response.id"
	AttrResponseFinishReasons    = "gen_ai.response.finish_reasons"
	AttrResponseTimeToFirstChunk = "gen_ai.response.time_to_first_chunk"

	AttrUsageInputTokens              = "gen_ai.usage.input_tokens"
	AttrUsageOutputTokens             = "gen_ai.usage.output_tokens"
	AttrUsageCacheReadInputTokens     = "gen_ai.usage.cache_read.input_tokens"
	AttrUsageCacheCreationInputTokens = "gen_ai.usage.cache_creation.input_tokens"
	AttrUsageReasoningOutputTokens    = "gen_ai.usage.reasoning.output_tokens"

	AttrTokenType = "gen_ai.token.type"

	AttrToolName          = "gen_ai.tool.name"
	AttrToolCallID        = "gen_ai.tool.call.id"
	AttrToolType          = "gen_ai.tool.type"
	AttrToolDescription   = "gen_ai.tool.description"
	AttrToolDefinitions   = "gen_ai.tool.definitions"
	AttrToolCallArguments = "gen_ai.tool.call.arguments"
	AttrToolCallResult    = "gen_ai.tool.call.result"

	AttrInputMessages      = "gen_ai.input.messages"
	AttrOutputMessages     = "gen_ai.output.messages"
	AttrSystemInstructions = "gen_ai.system_instructions"

	AttrPromptName = "gen_ai.prompt.name"

	AttrDataSourceID             = "gen_ai.data_source.id"
	AttrEmbeddingsDimensionCount = "gen_ai.embeddings.dimension.count"
	AttrRetrievalDocuments       = "gen_ai.retrieval.documents"
	AttrRetrievalQueryText       = "gen_ai.retrieval.query.text"

	AttrEvaluationName        = "gen_ai.evaluation.name"
	AttrEvaluationScoreLabel  = "gen_ai.evaluation.score.label"
	AttrEvaluationScoreValue  = "gen_ai.evaluation.score.value"
	AttrEvaluationExplanation = "gen_ai.evaluation.explanation"
)

Attribute keys defined by the OTel GenAI semantic conventions. All are Development stability — declared as constants here so call sites depend on a stable local symbol rather than a moving upstream import path.

View Source 
const (
	OperationChat            = "chat"
	OperationTextCompletion  = "text_completion"
	OperationGenerateContent = "generate_content"
	OperationEmbeddings      = "embeddings"
	OperationCreateAgent     = "create_agent"
	OperationInvokeAgent     = "invoke_agent"
	OperationInvokeWorkflow  = "invoke_workflow"
	OperationExecuteTool     = "execute_tool"
	OperationRetrieval       = "retrieval"
)

Operation names — values for AttrOperationName.

View Source 
const (
	TokenTypeInput         = "input"
	TokenTypeOutput        = "output"
	TokenTypeCacheRead     = "cache_read.input"
	TokenTypeCacheCreation = "cache_creation.input"
	TokenTypeReasoning     = "reasoning.output"
)

Token types — values for AttrTokenType when recording the token usage histogram. Spec defines `input` and `output`; we use the cache_read / cache_creation / reasoning variants to mirror the per-token-type usage attributes for richer breakdowns.

View Source 
const (
	ProviderAnthropic   = "anthropic"
	ProviderOpenAI      = "openai"
	ProviderAWSBedrock  = "aws.bedrock"
	ProviderGCPVertexAI = "gcp.vertex_ai"
	ProviderGCPGenAI    = "gcp.gen_ai"
	ProviderAzureAI     = "azure.ai.inference"
	ProviderDMR         = "docker.dmr"
)

Provider names — values for AttrProviderName. Names follow the values defined in the provider-specific GenAI semconv pages.

View Source 
const (
	AttrFallbackPrimaryModel = "cagent.fallback.primary_model"
	AttrFallbackFinalModel   = "cagent.fallback.final_model"
	AttrFallbackAttempts     = "cagent.fallback.attempts"
	AttrFallbackOutcome      = "cagent.fallback.outcome"
	AttrFallbackInCooldown   = "cagent.fallback.in_cooldown"

	AttrCacheHit     = "cagent.cache.hit"
	AttrCacheBacking = "cagent.cache.backing"

	AttrAgentNameRuntime = "cagent.agent.name"

	AttrRetrievalResultCount = "cagent.retrieval.result_count"

	AttrSandboxRuntime   = "cagent.sandbox.runtime"
	AttrSandboxImage     = "cagent.sandbox.image"
	AttrSandboxContainer = "cagent.sandbox.container"
	AttrSandboxExitCode  = "cagent.sandbox.exit_code"
)

Custom (non-spec) attribute keys for runtime-side observability that has no GenAI semconv equivalent yet (fallback chain, response cache, approval pipeline). Kept under the `cagent.` namespace so they are clearly distinguishable from the spec-defined `gen_ai.*` and `mcp.*` attributes when scrolling through a span.

View Source 
const (
	FallbackOutcomeSuccess         = "success"
	FallbackOutcomeFailed          = "failed"
	FallbackOutcomeContextCanceled = "context_canceled"
)

FallbackOutcome values for AttrFallbackOutcome.

View Source 
const EnvCaptureMessageContent = "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"

EnvCaptureMessageContent is the OTel-recommended environment variable that toggles capture of GenAI request/response content as span attributes. Default is off because chat history routinely contains PII, secrets, internal documents, and other content that should not be exported by default.

Recognised truthy values: "true", "1", "yes", "on" (case-insensitive).

View Source 
const EnvSemconvStability = "OTEL_SEMCONV_STABILITY_OPT_IN"

EnvSemconvStability is the OTel-defined environment variable that lets callers opt into experimental versions of the GenAI semantic conventions (https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/README.md).

It is a comma-separated list of opt-in tokens. The only token defined for GenAI today is `gen_ai_latest_experimental` — when present, the instrumentation emits only the spec-defined `gen_ai.*` attributes and drops the legacy attribute names (e.g. `tool.name`, `agent`, `session.id`).

Default behaviour (env var unset) is dual-emit: spans carry both the legacy keys and the `gen_ai.*` keys so existing dashboards keep working alongside spec-aware tooling. This matches the spec's recommendation that instrumentations not change the version of conventions they emit by default and instead require the opt-in for the new version.

View Source 
const ErrorTypeOther = "_OTHER"

ErrorTypeOther is the OTel-mandated fallback for `error.type` when no classifier matches. The spec requires `_OTHER` rather than a Go type name so backends can rely on a bounded cardinality.

Variables

This section is empty.

Functions

func ClassifyError 

func ClassifyError(err error) string

ClassifyError maps a provider error to a low-cardinality `error.type` value suitable for span and metric attributes. Falls back to `_OTHER` (the spec-defined sentinel) when the error does not match any known pattern.

Spec leaves the value space open for callers — these strings are picked for cross-provider comparability on dashboards.

func ConversationIDFromContext 

func ConversationIDFromContext(ctx context.Context) string

ConversationIDFromContext returns the conversation id stored in the context's baggage, or "" when none has been seeded.

func EmitEvaluationResult 

func EmitEvaluationResult(ctx context.Context, result EvaluationResult)

EmitEvaluationResult emits a `gen_ai.evaluation.result` log record. The record links to the active span via the supplied context so dashboards can join evaluation outcomes back onto the operation that produced them. No-op when no logger provider is configured.

func EmitLegacyAttributes 

func EmitLegacyAttributes() bool

EmitLegacyAttributes reports whether legacy (pre-semconv) attribute keys should be emitted. True when stability is StabilityDualEmit; false when the user has opted into `gen_ai_latest_experimental`.

func InjectSandboxEnv 

func InjectSandboxEnv(ctx context.Context) []string

InjectSandboxEnv returns docker-style `-e KEY=VALUE` flags carrying the W3C trace context for the current span so the agent process spawned inside a sandbox container inherits the parent trace. Anything OTel- aware running in the container — another agent, an HTTP client with otelhttp transport, otel-cli — auto-parents its spans onto the active CLIENT span on the host side.

Returns nil when no propagator is configured or when the active context has no span context to inject.

func InjectTraceContextEnv 

func InjectTraceContextEnv(ctx context.Context) []string

InjectTraceContextEnv returns `KEY=VALUE` env-var strings carrying the W3C trace context for the current span. Use to extend `exec.Cmd.Env` for direct subprocess spawns (hook scripts, LSP servers) so OTel-aware children chain onto the active span. Companion to `InjectSandboxEnv`, which formats for `docker -e`.

Returns nil when no propagator is configured or when the active context has no span context to inject.

func IsContentCaptureEnabled 

func IsContentCaptureEnabled() bool

IsContentCaptureEnabled reports whether the OTel content-capture opt-in is set. Read on every call so tests and feature flags can flip the value at runtime.

func LegacyToolAttributes 

func LegacyToolAttributes(toolName, toolType, agentName, sessionID, callID string) []attribute.KeyValue

LegacyToolAttributes returns the historic tool dispatcher attribute set (`tool.name`, `agent`, `session.id`, `tool.call_id`, `tool.type`) — but only when legacy emission is enabled. Returns nil otherwise so call sites can append unconditionally.

func ProviderNameForConfig 

func ProviderNameForConfig(internalName string) string

ProviderNameForConfig maps the project's internal provider type strings (the values used in agent YAML and resolved by pkg/model/provider.resolveProviderType) to the GenAI semconv provider names defined in the per-provider semantic conventions. Unknown providers fall through unchanged so dashboards still receive a value rather than empty string.

func ResetStabilityForTest 

func ResetStabilityForTest()

ResetStabilityForTest clears the cached stability value so a subsequent CurrentStability call re-reads the env var. Test-only — callers must ensure no other goroutine is in CurrentStability when this runs. The mutex protects the sync.Once and cache fields against other Reset calls and against the lock-protected segments of CurrentStability, but CurrentStability releases the mutex before invoking once.Do, so a concurrent reset there races on the sync.Once memory itself (flagged under -race). All in-tree usage is sequential (t.Setenv + t.Cleanup, no t.Parallel), so this is safe in practice; do not introduce parallel callers.

func ServerAddressFromURL 

func ServerAddressFromURL(raw string) (string, int)

ServerAddressFromURL extracts host and port for the ServerAddress / ServerPort fields when callers have a full URL handy.

func SetInputMessages 

func SetInputMessages(span *ChatSpan, messages []chat.Message)

SetInputMessages serialises chat history into `gen_ai.input.messages` per the OTel GenAI examples schema (role + parts) and attaches it to the span. System messages are removed from the array and emitted separately as `gen_ai.system_instructions` per the spec.

No-op when content capture is disabled or the span is nil.

func SetOutputMessages 

func SetOutputMessages(span *ChatSpan, content, reasoning string, toolCalls []tools.ToolCall)

SetOutputMessages serialises the assembled response into `gen_ai.output.messages`. Use after streaming has completed and the final assistant message is known.

func SetToolDefinitions 

func SetToolDefinitions(span *ChatSpan, toolDefs []tools.Tool)

SetToolDefinitions serialises the tool definitions presented to the model into `gen_ai.tool.definitions`.

func WithConversationID 

func WithConversationID(ctx context.Context, id string) context.Context

WithConversationID returns a context that carries the conversation id in OTel baggage. Spans created later in the chain — including ones in helper packages that have no direct access to the session — read it via ConversationIDFromContext and attach `gen_ai.conversation.id` automatically. Empty id is a no-op.

func WrapStream 

func WrapStream(span *ChatSpan, stream chat.MessageStream) chat.MessageStream

WrapStream wraps a chat.MessageStream so that consuming the stream drives the lifecycle of a ChatSpan: per-chunk timing, response-level attributes (id / response.model / finish reasons), usage capture, and final span End on stream close or terminal error.

The returned stream forwards all Recv/Close calls to the underlying stream verbatim and adds no other behaviour, so swapping it in is invisible to callers.

Types

type CacheSpan 

type CacheSpan struct {
	// contains filtered or unexported fields
}

CacheSpan handles cache-operation span lifecycle.

func RecordCacheLookup 

func RecordCacheLookup(ctx context.Context, backing string) (context.Context, *CacheSpan)

RecordCacheLookup increments the cache counter and returns a small span describing the lookup. Callers `defer span.End()` and the helper sets `cagent.cache.hit` from the value returned by SetHit.

func RecordCacheStore 

func RecordCacheStore(ctx context.Context, backing string) (context.Context, *CacheSpan)

RecordCacheStore is the Store-side counterpart of RecordCacheLookup.

func (*CacheSpan) End 

func (s *CacheSpan) End()

End closes the cache span.

func (*CacheSpan) SetHit 

func (s *CacheSpan) SetHit(hit bool)

SetHit records whether the lookup found an entry. Increments the cache counter immediately so the metric reflects the result even if End is called late.

type ChatRequest 

type ChatRequest struct {
	// Provider is the GenAI provider name. Use one of the Provider*
	// constants. Set on the span at creation time per the per-provider
	// semconv MUST clauses.
	Provider string

	// Model is the requested model identifier. Empty model is allowed
	// (some routers do not commit until inside the call) but produces a
	// span name of just "chat".
	Model string

	// Stream is true if the request is streaming. Recorded as
	// gen_ai.request.stream.
	Stream bool

	// ServerAddress / ServerPort identify the GenAI endpoint when known
	// (helpful for routing-aware dashboards). Optional.
	ServerAddress string
	ServerPort    int

	// Sampling parameters. Zero values are treated as unset and not
	// recorded on the span.
	MaxTokens        int
	Temperature      float64
	TopP             float64
	TopK             float64
	FrequencyPenalty float64
	PresencePenalty  float64
	Seed             int
	StopSequences    []string
	ChoiceCount      int

	// HasTemperature / HasTopP / HasTopK / HasFreqPenalty / HasPresPenalty
	// disambiguate "explicitly zero" from "unset" for the float params.
	// Callers that use the zero value as meaningful must set these.
	HasTemperature bool
	HasTopP        bool
	HasTopK        bool
	HasFreqPenalty bool
	HasPresPenalty bool
}

ChatRequest carries the inputs needed to start a `chat {model}` span and to record the matching client metrics. Provider-specific extensions (openai service tier, aws.bedrock guardrail, etc.) attach via ChatSpan.SetAttributes after the span has started.

type ChatSpan 

type ChatSpan struct {
	// contains filtered or unexported fields
}

ChatSpan is the handle returned by StartChat. It wraps an OTel span and captures enough state to emit per-operation metrics on End.

func StartChat 

func StartChat(ctx context.Context, req ChatRequest) (context.Context, *ChatSpan)

StartChat begins a CLIENT-kind `chat {model}` span and records the required gen_ai.* request attributes. The returned context carries the new span; callers MUST call ChatSpan.End to flush the span and metrics.

func (*ChatSpan) AddFinishReason 

func (s *ChatSpan) AddFinishReason(reason string)

AddFinishReason accumulates a finish reason. The spec defines the attribute as a string array — multiple values are recorded once on End.

func (*ChatSpan) End 

func (s *ChatSpan) End()

End closes the span, flushes accumulated finish reasons / usage / timing to the span, and records the duration and token-usage histograms. Safe to call multiple times; subsequent calls are no-ops.

func (*ChatSpan) MarkChunk 

func (s *ChatSpan) MarkChunk()

MarkChunk records the timing of a streamed output chunk. The first call drives gen_ai.response.time_to_first_chunk (and the corresponding metric); subsequent calls accumulate per-chunk durations.

func (*ChatSpan) RecordError 

func (s *ChatSpan) RecordError(err error, errType string)

RecordError marks the span as failed and stores error.type for the duration metric. errType should be a short, low-cardinality string — "rate_limit", "context_length_exceeded", "auth", "network", "context_canceled", or "_OTHER" as the spec-defined fallback. When errType is empty, ClassifyError(err) is called to derive a value, so callers that don't already have a classification can pass "" without losing it to the "_OTHER" bucket.

func (*ChatSpan) RecordUsage 

func (s *ChatSpan) RecordUsage(inputTokens, outputTokens, cacheReadInput, cacheCreationInput, reasoningOutput int64)

RecordUsage stores the token usage for emission as both span attributes and the gen_ai.client.token.usage histogram. Callers pass raw provider values; this package applies the spec-mandated Anthropic input-token sum (`input_tokens` reported by Anthropic excludes cached tokens, so the spec requires summing input + cache_read + cache_creation).

func (*ChatSpan) SetAttributes 

func (s *ChatSpan) SetAttributes(attrs ...attribute.KeyValue)

SetAttributes adds extra attributes to the span. Use for provider-specific fields (openai.*, aws.bedrock.*) and for response-side attributes the caller learns later.

func (*ChatSpan) SetResponseID 

func (s *ChatSpan) SetResponseID(id string)

SetResponseID records gen_ai.response.id.

func (*ChatSpan) SetResponseModel 

func (s *ChatSpan) SetResponseModel(model string)

SetResponseModel records gen_ai.response.model. Some providers return a resolved model name that differs from the requested one (alias expansion, version pinning); both values are useful.

func (*ChatSpan) Span 

func (s *ChatSpan) Span() trace.Span

Span returns the underlying OTel span so callers can attach span events or links when they need finer control than the helpers expose. Returns a real no-op span (not a struct embedding a nil trace.Span) when the receiver is nil so callers don't have to nil-check before invoking Span methods like AddEvent / SetAttributes.

type EmbeddingRequest 

type EmbeddingRequest struct {
	Provider string
	Model    string
	// BatchSize is the number of input texts in the embedding call,
	// recorded as `cagent.embeddings.batch_size`. Zero means
	// single-input.
	BatchSize int
	// EncodingFormats is the optional list of requested output
	// encodings (e.g. "float", "base64") per the GenAI semconv.
	// Recorded as `gen_ai.request.encoding_formats` when non-empty.
	EncodingFormats []string
}

EmbeddingRequest carries the inputs needed to start an `embeddings {model}` span per the OTel GenAI semantic conventions.

type EmbeddingSpan 

type EmbeddingSpan struct {
	// contains filtered or unexported fields
}

EmbeddingSpan handles the lifecycle of an embedding span and the matching `gen_ai.client.operation.duration` / `gen_ai.client.token.usage` metric records.

func StartEmbedding 

func StartEmbedding(ctx context.Context, req EmbeddingRequest) (context.Context, *EmbeddingSpan)

StartEmbedding begins a CLIENT-kind `embeddings {model}` span and records the spec-required `gen_ai.operation.name=embeddings`, `gen_ai.provider.name`, and `gen_ai.request.model` attributes.

func (*EmbeddingSpan) End 

func (s *EmbeddingSpan) End()

End closes the span and records the duration + token-usage metrics.

func (*EmbeddingSpan) RecordError 

func (s *EmbeddingSpan) RecordError(err error, errType string)

RecordError marks the span as failed and stores `error.type` for the duration metric.

func (*EmbeddingSpan) SetDimensions 

func (s *EmbeddingSpan) SetDimensions(d int)

SetDimensions records the dimensionality of the resulting embedding vector(s). Emitted as `gen_ai.embeddings.dimension.count`.

func (*EmbeddingSpan) SetInputTokens 

func (s *EmbeddingSpan) SetInputTokens(n int64)

SetInputTokens records the number of input tokens consumed by the embedding call. Emitted as `gen_ai.usage.input_tokens` on the span and as the `gen_ai.client.token.usage` metric at End time.

type EvaluationResult 

type EvaluationResult struct {
	// Name is the evaluation metric — e.g. "relevance", "factuality",
	// "tool_calls_f1". Required.
	Name string

	// ScoreLabel is the human-readable verdict — e.g. "passed",
	// "failed", "satisfactory". Optional but commonly set.
	ScoreLabel string

	// ScoreValue is the numeric score (commonly 0.0–1.0). Optional.
	ScoreValue    float64
	HasScoreValue bool

	// Explanation is a free-form reason for the score. Optional.
	Explanation string

	// ErrorType is set when the evaluation itself failed (e.g. the
	// judge model errored out). Mirrors the spec's `error.type` field.
	ErrorType string
}

EvaluationResult describes one evaluation outcome that should be emitted as a `gen_ai.evaluation.result` log record per the OTel GenAI semconv (https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-events/).

type FallbackSpan 

type FallbackSpan struct {
	// contains filtered or unexported fields
}

FallbackSpan is the handle for an in-flight runtime.fallback span.

func StartFallback 

func StartFallback(ctx context.Context, agentName, primaryModel string, inCooldown bool) (context.Context, *FallbackSpan)

StartFallback begins a runtime.fallback span covering the whole fallback chain for one agent turn. Each per-model attempt produces its own `chat {model}` CLIENT child span (created by the provider decorator). Attributes set up front: primary model name, agent name, in-cooldown flag. The caller updates final model / attempts / outcome through the returned handle and calls End to flush.

func (*FallbackSpan) End 

func (s *FallbackSpan) End()

End closes the span and flushes accumulated attributes.

func (*FallbackSpan) IncrementAttempt 

func (s *FallbackSpan) IncrementAttempt()

IncrementAttempt counts one attempt against the chain. Called once per (model × retry) iteration so the final span carries the total count.

func (*FallbackSpan) RecordError 

func (s *FallbackSpan) RecordError(err error, errType string)

RecordError stores an error and an error.type label for the metric.

func (*FallbackSpan) SetFinalModel 

func (s *FallbackSpan) SetFinalModel(model string)

SetFinalModel records the model that ultimately served the response. Called on the success path; not called on full-failure paths so the attribute remains absent and dashboards can distinguish the cases.

func (*FallbackSpan) SetOutcome 

func (s *FallbackSpan) SetOutcome(outcome string)

SetOutcome records the terminal outcome of the chain. Use one of the FallbackOutcome* constants.

type KeyValue 

type KeyValue struct {
	Key   string
	Value any
}

KeyValue is a re-exported attribute key/value pair used by the optional StreamAttributer interface so providers can implement it without importing go.opentelemetry.io/otel/attribute directly. The decorator converts these back into OTel attributes before applying them to the span.

type RetrievalSpan 

type RetrievalSpan struct {
	// contains filtered or unexported fields
}

RetrievalSpan handles a retrieval-operation span lifecycle.

func StartRetrieval 

func StartRetrieval(ctx context.Context, providerName, dataSourceID string, captureQuery bool, queryText string) (context.Context, *RetrievalSpan)

StartRetrieval begins a `retrieval {data_source.id}` span per the OTel GenAI semconv. providerName identifies the retrieval backend ("sqlite", "rag", an embedding-provider name) and is Required by the spec for retrieval operations. dataSourceID identifies the corpus / index / collection being queried; queryText is captured only when the caller has confirmed the content-capture opt-in.

func (*RetrievalSpan) End 

func (s *RetrievalSpan) End()

End closes the retrieval span and flushes the result count.

func (*RetrievalSpan) RecordError 

func (s *RetrievalSpan) RecordError(err error, errType string)

RecordError marks the retrieval span as failed.

func (*RetrievalSpan) SetAttributes 

func (s *RetrievalSpan) SetAttributes(attrs ...attribute.KeyValue)

SetAttributes adds extra attributes to the retrieval span. Use for retrieval-specific extensions (corpus filter, category, fusion mode, etc.) that don't have a dedicated setter.

func (*RetrievalSpan) SetResultCount 

func (s *RetrievalSpan) SetResultCount(n int)

SetResultCount records how many documents the retrieval returned.

type SandboxOptions 

type SandboxOptions struct {
	// Runtime is a short label identifying the sandbox backend (e.g.
	// `"docker"`). Recorded as `cagent.sandbox.runtime` and used as a
	// histogram label, so callers should keep the set of values small
	// and stable.
	Runtime string

	// Image is the container/pod image when known.
	Image string

	// Container is the container/pod identifier when known.
	Container string

	// AgentName is the agent being executed in the sandbox.
	AgentName string
}

SandboxOptions configures the attributes set on a sandbox.exec span at creation time. All fields are optional except Runtime.

type SandboxSpan 

type SandboxSpan struct {
	// contains filtered or unexported fields
}

SandboxSpan handles the lifecycle of a sandbox.exec span and the matching sandbox.exec.duration histogram. Use to wrap the actual `docker sandbox exec` (or equivalent) subprocess invocation so the host side has timing, exit code, runtime kind, and image information alongside the inherited child trace from inside the sandbox.

func StartSandboxExec 

func StartSandboxExec(ctx context.Context, opts SandboxOptions) (context.Context, *SandboxSpan)

StartSandboxExec opens a `sandbox.exec` INTERNAL span. Runtime kind is set up front; exit code and error info attach via the returned handle.

func (*SandboxSpan) End 

func (s *SandboxSpan) End()

End closes the span and records the sandbox.exec.duration histogram.

func (*SandboxSpan) RecordError 

func (s *SandboxSpan) RecordError(err error, errType string)

RecordError marks the span as failed.

func (*SandboxSpan) SetExitCode 

func (s *SandboxSpan) SetExitCode(code int)

SetExitCode records the subprocess exit code as `cagent.sandbox.exit_code`. Set zero on success.

type Stability 

type Stability int

Stability identifies which version of attribute names a span should emit. 

const (
	// StabilityDualEmit is the default: emit both legacy attribute
	// names (`tool.name`, `agent`, `session.id`, ...) and the
	// `gen_ai.*` keys, so existing dashboards continue working while
	// spec-aware tooling sees the new values.
	StabilityDualEmit Stability = iota
	// StabilityGenAILatest is selected by
	// `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`. Only
	// the `gen_ai.*` attributes are emitted; the legacy keys are
	// dropped.
	StabilityGenAILatest
)

func CurrentStability 

func CurrentStability() Stability

CurrentStability returns the active stability mode. The result is computed once per process from the env var; tests that need to flip the mode at runtime should call ResetStabilityForTest first.

type StreamAttributer 

type StreamAttributer interface {
	GenAIStreamAttributes() []KeyValue
}

StreamAttributer is an optional interface that provider stream adapters may implement to surface provider-specific attributes to the chat span once the response is complete. The wrapper queries the underlying stream on Close (in addition to the per-chunk Recv path) and applies whatever attributes the provider chose to expose. Implementations are expected to be safe to call after Close.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.