genai

package
v0.3.1 Latest Latest
Warning

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

 Go to latest Published: Apr 6, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package genai defines GenAI semantic-convention constants and helpers for metry.

Index

Constants

View Source 
const (
	ProviderName             = "gen_ai.provider.name"
	OperationName            = "gen_ai.operation.name"
	RequestModel             = "gen_ai.request.model"
	ResponseModel            = "gen_ai.response.model"
	SystemInstructions       = "gen_ai.system_instructions"
	InputMessages            = "gen_ai.input.messages"
	OutputMessages           = "gen_ai.output.messages"
	InputTokens              = "gen_ai.usage.input_tokens"                // #nosec G101 -- OTel semantic convention name
	OutputTokens             = "gen_ai.usage.output_tokens"               // #nosec G101 -- OTel semantic convention name
	CacheCreationInputTokens = "gen_ai.usage.cache_creation.input_tokens" // #nosec G101 -- OTel semantic convention name
	CacheReadInputTokens     = "gen_ai.usage.cache_read.input_tokens"     // #nosec G101 -- OTel semantic convention name
	TokenType                = "gen_ai.token.type"                        // #nosec G101 -- OTel semantic convention name
	ToolName                 = "gen_ai.tool.name"
	ToolCallID               = "gen_ai.tool.call.id"
	ToolCallArguments        = "gen_ai.tool.call.arguments"
	ToolCallResult           = "gen_ai.tool.call.result"
	ToolError                = "gen_ai.tool.error"
	EvaluationScore          = "gen_ai.evaluation.score"
	EvaluationText           = "gen_ai.evaluation.text"
	EvaluationMetricName     = "gen_ai.evaluation.metric"
	EvaluationReasoning      = "gen_ai.evaluation.reasoning"
	ServerAddress            = "server.address"
	ServerPort               = "server.port"
	ErrorType                = "error.type"

	UsageCost                  = "gen_ai.usage.cost"
	CostCurrency               = "gen_ai.cost.currency"
	UsageReasoningOutputTokens = "gen_ai.usage.reasoning.output_tokens" // #nosec G101 -- custom semantic convention name
	UsageVideoSeconds          = "gen_ai.usage.video.seconds"
	UsageVideoFrames           = "gen_ai.usage.video.frames"
	AudioSeconds               = "gen_ai.usage.audio_seconds"
	ImageCount                 = "gen_ai.usage.image_count"
	OperationPurpose           = "ai.operation.purpose"

	RetrievalSource         = "gen_ai.retrieval.source"
	RetrievalProvider       = "gen_ai.retrieval.provider"
	RetrievalQuery          = "gen_ai.retrieval.query"
	RetrievalTopK           = "gen_ai.retrieval.top_k"
	RetrievalReturnedChunks = "gen_ai.retrieval.returned_chunks"
	RetrievalDistances      = "gen_ai.retrieval.distances"
	SamplingKeep            = "gen_ai.sampling.keep"
	CacheHit                = "gen_ai.cache.hit"
	EmbeddingModel          = "gen_ai.embedding.model"

	AgentName      = "gen_ai.agent.name"
	AgentRole      = "gen_ai.agent.role"
	WorkflowStep   = "gen_ai.workflow.step"
	AgentStepEvent = "gen_ai.agent.step"
)

GenAI attribute names emitted by metry.

View Source 
const (
	TokenUsageMetricName          = "gen_ai.client.token.usage"                 // #nosec G101 -- OTel metric name
	TokenComponentUsageMetricName = "metry.gen_ai.client.token.component.usage" // #nosec G101 -- custom metric name
	OperationDurationMetricName   = "gen_ai.client.operation.duration"
	CostMetricName                = "gen_ai.cost"
	TTFTMetricName                = "metry.gen_ai.client.ttft"
	StreamingTPSMetricName        = "metry.gen_ai.client.tps"
	StreamingTBTMetricName        = "metry.gen_ai.client.tbt"
	VideoSecondsMetricName        = "metry.gen_ai.client.video.seconds"
	VideoFramesMetricName         = "metry.gen_ai.client.video.frames"
)

GenAI metric names emitted by metry.

View Source 
const (
	TokenTypeInput              = "input"                // #nosec G101 -- token type label
	TokenTypeOutput             = "output"               // #nosec G101 -- token type label
	TokenTypeInputCacheCreation = "input_cache_creation" // #nosec G101 -- custom token type label
	TokenTypeInputCacheRead     = "input_cache_read"     // #nosec G101 -- custom token type label
	TokenTypeOutputReasoning    = "output_reasoning"     // #nosec G101 -- custom token type label
)

Well-known and custom token-type values for the token usage histogram.

View Source 
const (
	PurposeGeneration        = "generation"
	PurposeGuardEvaluation   = "guard_evaluation"
	PurposeQualityEvaluation = "quality_evaluation"
)

Standard metry values for custom operation purpose.

Variables

View Source 
var (
	ProviderNameKey               = attribute.Key(ProviderName)
	OperationNameKey              = attribute.Key(OperationName)
	RequestModelKey               = attribute.Key(RequestModel)
	ResponseModelKey              = attribute.Key(ResponseModel)
	SystemInstructionsKey         = attribute.Key(SystemInstructions)
	InputMessagesKey              = attribute.Key(InputMessages)
	OutputMessagesKey             = attribute.Key(OutputMessages)
	InputTokensKey                = attribute.Key(InputTokens)
	OutputTokensKey               = attribute.Key(OutputTokens)
	CacheCreationInputTokensKey   = attribute.Key(CacheCreationInputTokens)
	CacheReadInputTokensKey       = attribute.Key(CacheReadInputTokens)
	TokenTypeKey                  = attribute.Key(TokenType)
	ToolNameKey                   = attribute.Key(ToolName)
	ToolCallIDKey                 = attribute.Key(ToolCallID)
	ToolCallArgumentsKey          = attribute.Key(ToolCallArguments)
	ToolCallResultKey             = attribute.Key(ToolCallResult)
	ToolErrorKey                  = attribute.Key(ToolError)
	EvaluationScoreKey            = attribute.Key(EvaluationScore)
	EvaluationTextKey             = attribute.Key(EvaluationText)
	EvaluationMetricNameKey       = attribute.Key(EvaluationMetricName)
	EvaluationReasoningKey        = attribute.Key(EvaluationReasoning)
	ServerAddressKey              = attribute.Key(ServerAddress)
	ServerPortKey                 = attribute.Key(ServerPort)
	ErrorTypeKey                  = attribute.Key(ErrorType)
	UsageCostKey                  = attribute.Key(UsageCost)
	CostCurrencyKey               = attribute.Key(CostCurrency)
	UsageReasoningOutputTokensKey = attribute.Key(UsageReasoningOutputTokens)
	UsageVideoSecondsKey          = attribute.Key(UsageVideoSeconds)
	UsageVideoFramesKey           = attribute.Key(UsageVideoFrames)
	AudioSecondsKey               = attribute.Key(AudioSeconds)
	ImageCountKey                 = attribute.Key(ImageCount)
	OperationPurposeKey           = attribute.Key(OperationPurpose)
	RetrievalSourceKey            = attribute.Key(RetrievalSource)
	RetrievalProviderKey          = attribute.Key(RetrievalProvider)
	RetrievalQueryKey             = attribute.Key(RetrievalQuery)
	RetrievalTopKKey              = attribute.Key(RetrievalTopK)
	RetrievalReturnedChunksKey    = attribute.Key(RetrievalReturnedChunks)
	RetrievalDistancesKey         = attribute.Key(RetrievalDistances)
	SamplingKeepKey               = attribute.Key(SamplingKeep)
	CacheHitKey                   = attribute.Key(CacheHit)
	EmbeddingModelKey             = attribute.Key(EmbeddingModel)
	AgentNameKey                  = attribute.Key(AgentName)
	AgentRoleKey                  = attribute.Key(AgentRole)
	WorkflowStepKey               = attribute.Key(WorkflowStep)
)

Attribute keys derived from the string constants above.

View Source 
var (
	// ErrMeterRequired is returned when NewTracker is called with a nil meter.
	ErrMeterRequired = errors.New("genai: meter is required")
	// ErrTracerRequired is returned when NewTracker is called with a nil tracer.
	ErrTracerRequired = errors.New("genai: tracer is required")
)
View Source 
var (
	// ErrParentSpanContextRequired is returned when async feedback is recorded without a valid parent.
	ErrParentSpanContextRequired = errors.New("genai: valid parent span context is required")
)

Functions

func NewHintSampler added in v0.2.5 

func NewHintSampler(base sdktrace.Sampler) sdktrace.Sampler

NewHintSampler wraps a base sampler with explicit keep-hint support. Sampling order: 1) keep hint at span start forces sampling; 2) otherwise, valid parent sampling decision is inherited; 3) otherwise, base sampler decides.

func RecordAgentStep added in v0.1.2 

func RecordAgentStep(span trace.Span, agentName, agentRole, step string)

RecordAgentStep appends one agent-step event on the provided span.

func RecordCacheHit 

func RecordCacheHit(span trace.Span, hit bool, source string)

RecordCacheHit records cache metadata on the provided span.

Types

type ContentPart added in v0.2.5 

type ContentPart struct {
	Type      string          `json:"type"`
	Content   string          `json:"content,omitempty"`
	ID        string          `json:"id,omitempty"`
	Name      string          `json:"name,omitempty"`
	Arguments json.RawMessage `json:"arguments,omitempty"`
	Result    json.RawMessage `json:"result,omitempty"`
}

ContentPart is one structured content block inside a system instruction or message.

type Evaluation added in v0.2.5 

type Evaluation struct {
	Metric    EvaluationMetric
	Score     float64
	Reasoning string
}

Evaluation is one LLM-judge evaluation result.

type EvaluationMetric added in v0.2.5 

type EvaluationMetric string

EvaluationMetric is a typed machine-evaluation metric name. 

const (
	EvaluationFaithfulness       EvaluationMetric = "faithfulness"
	EvaluationAnswerRelevance    EvaluationMetric = "answer_relevance"
	EvaluationContextPrecision   EvaluationMetric = "context_precision"
	EvaluationHallucinationIndex EvaluationMetric = "hallucination_index"
)

type Message added in v0.2.5 

type Message struct {
	Role         string        `json:"role"`
	Parts        []ContentPart `json:"parts"`
	FinishReason string        `json:"finish_reason,omitempty"`
}

Message is one structured GenAI message emitted on spans as JSON payload.

type Meta added in v0.2.5 

type Meta struct {
	Provider      string
	Operation     string
	RequestModel  string
	ResponseModel string
	ServerAddress string
	ServerPort    int
	Duration      time.Duration
	ErrorType     string
}

Meta describes operation-level metadata used for official GenAI semconv.

type Option added in v0.2.5 

type Option func(*runtimeConfig)

Option configures tracker runtime behavior.

func WithMaxContextLength added in v0.2.5 

func WithMaxContextLength(bytes int) Option

WithMaxContextLength sets the payload truncation limit for this tracker.

func WithMaxEventLength added in v0.2.6 

func WithMaxEventLength(bytes int) Option

WithMaxEventLength sets the max byte length for text stored on span events (e.g. LLM-judge reasoning on evaluation events). Backends and collectors often apply tighter limits to event attributes than to span attributes (commonly on the order of 4–8KB); the default is 4096 bytes. Values <= 0 are replaced with that default during config build.

func WithRecordPayloads added in v0.2.5 

func WithRecordPayloads(enabled bool) Option

WithRecordPayloads enables payload recording on spans for this tracker.

type Payload added in v0.2.5 

type Payload struct {
	SystemInstructions []ContentPart
	InputMessages      []Message
	OutputMessages     []Message
}

Payload captures structured system/input/output content for one interaction.

type RetrievalRequest added in v0.2.5 

type RetrievalRequest struct {
	Provider string
	Source   string
	Query    string
	TopK     int
}

RetrievalRequest describes one retrieval operation at span start.

type RetrievalResult added in v0.2.5 

type RetrievalResult struct {
	ReturnedChunks int
	Distances      []float64
}

RetrievalResult describes retrieval outputs available after I/O completes.

type Tracker added in v0.2.5 

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

Tracker owns GenAI runtime config, metric instruments, and the tracer used for tool spans.

func NewTracker added in v0.2.5 

func NewTracker(meter metric.Meter, tracer trace.Tracer, opts ...Option) (*Tracker, error)

NewTracker creates an explicit GenAI tracker with its own config, instruments, and tracer.

func (*Tracker) RecordAsyncFeedback added in v0.2.5 

func (t *Tracker) RecordAsyncFeedback(
	ctx context.Context,
	parent trace.SpanContext,
	score float64,
	feedbackText string,
	opts ...trace.SpanStartOption,
) error

RecordAsyncFeedback records delayed user feedback with an explicit tracker.

func (*Tracker) RecordEvaluations added in v0.2.5 

func (t *Tracker) RecordEvaluations(
	ctx context.Context,
	parent trace.SpanContext,
	evaluations []Evaluation,
	opts ...trace.SpanStartOption,
) error

RecordEvaluations records LLM-judge evaluations on a child span.

func (*Tracker) RecordInteraction added in v0.2.5 

func (t *Tracker) RecordInteraction(
	ctx context.Context,
	span trace.Span,
	meta Meta,
	payload Payload,
	usage Usage,
)

RecordInteraction records one GenAI interaction on an explicit tracker.

func (*Tracker) RecordRetrievalResult added in v0.2.5 

func (t *Tracker) RecordRetrievalResult(span trace.Span, result RetrievalResult)

RecordRetrievalResult writes retrieval result attributes on the retrieval span.

func (*Tracker) RecordStreamingCompletion added in v0.2.5 

func (t *Tracker) RecordStreamingCompletion(
	ctx context.Context,
	meta Meta,
	outputTokens int,
	ttft time.Duration,
	totalDuration time.Duration,
)

RecordStreamingCompletion records custom streaming quality metrics on an explicit tracker.

func (*Tracker) RecordTTFT added in v0.2.5 

func (t *Tracker) RecordTTFT(ctx context.Context, meta Meta, duration time.Duration)

RecordTTFT records custom client-side time-to-first-token on an explicit tracker.

func (*Tracker) RecordToolResult added in v0.2.5 

func (t *Tracker) RecordToolResult(span trace.Span, resultJSON string, isError bool)

RecordToolResult records tool output and status using an explicit tracker config.

func (*Tracker) StartRetrievalSpan added in v0.2.5 

func (t *Tracker) StartRetrievalSpan(
	ctx context.Context,
	name string,
	req RetrievalRequest,
	startOpts ...trace.SpanStartOption,
) (context.Context, trace.Span)

StartRetrievalSpan starts a child span for retrieval I/O and writes request attributes. Extra start options allow callers to add start-time sampling hints or attributes.

func (*Tracker) StartToolSpan added in v0.2.5 

func (t *Tracker) StartToolSpan(
	ctx context.Context,
	toolName, toolCallID, argsJSON string,
	startOpts ...trace.SpanStartOption,
) (context.Context, trace.Span)

StartToolSpan creates a child span for a tool execution using an explicit tracker. Extra start options allow callers to add start-time sampling hints or attributes.

type Usage added in v0.2.5 

type Usage struct {
	InputTokens              int
	OutputTokens             int
	CacheCreationInputTokens int
	CacheReadInputTokens     int
	ReasoningOutputTokens    int
	Cost                     float64
	Currency                 string
	AudioSeconds             float64
	ImageCount               int
	VideoSeconds             float64
	VideoFrames              int
	Purpose                  string
}

Usage captures billable and multimodal usage for one interaction.

Flat design: fields are kept in one struct (no nested DTOs or pointers to sub-structs), which minimizes allocations and GC work on hot paths compared to nested DTOs (zero-allocation-oriented layout, not a guarantee that the surrounding call path allocates nothing). The shape maps 1:1 to flat OpenTelemetry GenAI semantic attributes without embedding nested JSON. Zero values (0, "") mean "not set" and are the fastest idiom for presence checks.

InputTokens should include cached input tokens when the provider exposes a total. OutputTokens should include reasoning output tokens when the provider exposes a total. Cost must be non-negative; negative values are treated as invalid input and ignored.

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.