telemetry

package
v0.10.2 Latest Latest
Warning

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

 Go to latest Published: May 2, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Index

Constants

View Source 
const (

	// Standard OTel service key.
	KeyServiceName = "service.name"

	// DDX identity keys.
	KeyHarnessName           = "ddx.harness.name"
	KeyHarnessVersion        = "ddx.harness.version"
	KeySessionID             = "ddx.session.id"
	KeyParentSessionID       = "ddx.parent.session.id"
	KeyRequestedModelRef     = "ddx.request.model_ref"
	KeyTurnIndex             = "ddx.turn.index"
	KeyAttemptIndex          = "ddx.attempt.index"
	KeyToolExecutionIndex    = "ddx.tool.execution.index"
	KeyProviderSystem        = "ddx.provider.system"
	KeyProviderRoute         = "ddx.provider.route"
	KeyAttemptedProviders    = "ddx.routing.attempted_providers"
	KeyFailoverCount         = "ddx.routing.failover_count"
	KeyProviderModelResolved = "ddx.provider.model_resolved"
	KeyCostSource            = "ddx.cost.source"
	KeyCostCurrency          = "ddx.cost.currency"
	KeyCostAmount            = "ddx.cost.amount"
	KeyCostInputAmount       = "ddx.cost.input_amount"
	KeyCostOutputAmount      = "ddx.cost.output_amount"
	KeyCostCacheReadAmount   = "ddx.cost.cache_read_amount"
	KeyCostCacheWriteAmount  = "ddx.cost.cache_write_amount"
	KeyCostReasoningAmount   = "ddx.cost.reasoning_amount"
	KeyCostPricingRef        = "ddx.cost.pricing_ref"
	KeyCostRaw               = "ddx.cost.raw"
	KeyTimingFirstTokenMS    = "ddx.timing.first_token_ms"
	KeyTimingQueueMS         = "ddx.timing.queue_ms"
	KeyTimingPrefillMS       = "ddx.timing.prefill_ms"
	KeyTimingGenerationMS    = "ddx.timing.generation_ms"
	KeyTimingCacheReadMS     = "ddx.timing.cache_read_ms"
	KeyTimingCacheWriteMS    = "ddx.timing.cache_write_ms"

	// Standard OTel GenAI keys.
	KeyConversationID  = "gen_ai.conversation.id"
	KeyAgentName       = "gen_ai.agent.name"
	KeyAgentVersion    = "gen_ai.agent.version"
	KeyAgentID         = "gen_ai.agent.id"
	KeyOperationName   = "gen_ai.operation.name"
	KeyProviderName    = "gen_ai.provider.name"
	KeyRequestModel    = "gen_ai.request.model"
	KeyResponseModel   = "gen_ai.response.model"
	KeyToolName        = "gen_ai.tool.name"
	KeyToolType        = "gen_ai.tool.type"
	KeyToolCallID      = "gen_ai.tool.call.id"
	KeyUsageInput      = "gen_ai.usage.input_tokens"
	KeyUsageOutput     = "gen_ai.usage.output_tokens"
	KeyUsageCacheRead  = "gen_ai.usage.cache_read.input_tokens"
	KeyUsageCacheWrite = "gen_ai.usage.cache_creation.input_tokens"
	// #nosec G101 -- OTel semantic convention key, not a credential.
	KeyTokenType     = "gen_ai.token.type"
	KeyServerAddress = "server.address"
	KeyServerPort    = "server.port"
	KeyErrorType     = "error.type"
)

Variables

View Source 
var (
	// ProductName is the human-readable product identity used in telemetry.
	ProductName = productinfo.Name
	// ServiceName is the machine-readable service identity used in telemetry.
	ServiceName = productinfo.ConfigDir
	// InstrumentationName identifies this product in OTel tracer/meter setup.
	InstrumentationName = productinfo.ConfigDir
)

Functions

This section is empty.

Types

type ChatMetrics 

type ChatMetrics struct {
	ResponseModel string
	ResolvedModel string
	Usage         Usage
	Duration      time.Duration
	Err           error
}

ChatMetrics carries the completion-specific values needed to emit metrics.

type ChatMetricsRecorder 

type ChatMetricsRecorder interface {
	RecordChatMetrics(ctx context.Context, attrs ChatSpan, metrics ChatMetrics)
}

ChatMetricsRecorder records completed chat attempts into OTel metrics.

type ChatSpan 

type ChatSpan struct {
	HarnessName     string
	HarnessVersion  string
	SessionID       string
	ConversationID  string
	ParentSessionID string
	TurnIndex       int
	AttemptIndex    int
	StartTime       time.Time
	ProviderName    string
	ProviderSystem  string
	ProviderRoute   string
	RequestedModel  string
	ResponseModel   string
	ResolvedModel   string
	ServerAddress   string
	ServerPort      int
}

ChatSpan carries the attributes for a provider attempt span.

type Config 

type Config struct {
	// Enabled is a configuration switch that callers can use to decide whether
	// to wire a real exporter-backed runtime or a no-op runtime.
	Enabled bool `yaml:"enabled,omitempty"`
	// Pricing contains exact runtime-specific cost entries keyed by provider
	// system and resolved model.
	Pricing        RuntimePricing       `yaml:"pricing,omitempty"`
	TracerProvider trace.TracerProvider `yaml:"-"`
	MeterProvider  metric.MeterProvider `yaml:"-"`
	// Shutdown is called during best-effort shutdown if provided.
	Shutdown func(context.Context) error `yaml:"-"`
}

Config controls how a telemetry runtime is constructed.

type Cost 

type Cost struct {
	Source         string   `json:"source,omitempty" yaml:"-"`
	Amount         *float64 `json:"amount,omitempty"`
	Currency       string   `json:"currency,omitempty"`
	PricingRef     string   `json:"pricing_ref,omitempty"`
	InputPerMTok   float64  `json:"input_per_mtok,omitempty"    yaml:"input_per_mtok,omitempty"`
	OutputPerMTok  float64  `json:"output_per_mtok,omitempty"   yaml:"output_per_mtok,omitempty"`
	CacheReadPerM  float64  `json:"cache_read_per_m,omitempty"  yaml:"cache_read_per_m,omitempty"`
	CacheWritePerM float64  `json:"cache_write_per_m,omitempty" yaml:"cache_write_per_m,omitempty"`
}

Cost captures runtime-specific configured pricing for an exact model match. When Amount is set it represents a pre-computed total cost in Currency. When only InputPerMTok / OutputPerMTok are set, callers must multiply by the actual token usage to derive the total cost.

type ExecuteToolSpan 

type ExecuteToolSpan struct {
	HarnessName        string
	HarnessVersion     string
	SessionID          string
	ConversationID     string
	ParentSessionID    string
	TurnIndex          int
	ToolExecutionIndex int
	ToolName           string
	ToolType           string
	ToolCallID         string
}

ExecuteToolSpan carries the attributes for a tool execution span.

type InvokeAgentSpan 

type InvokeAgentSpan struct {
	HarnessName     string
	HarnessVersion  string
	SessionID       string
	ParentSessionID string
	ConversationID  string
	AgentName       string
	AgentVersion    string
	AgentID         string
}

InvokeAgentSpan carries the attributes for the root run span.

type RuntimePricing 

type RuntimePricing map[string]map[string]Cost

RuntimePricing maps provider system -> resolved model -> exact configured cost for that runtime/model pair.

type Telemetry 

type Telemetry interface {
	StartInvokeAgent(ctx context.Context, attrs InvokeAgentSpan) (context.Context, trace.Span)
	StartChat(ctx context.Context, attrs ChatSpan) (context.Context, trace.Span)
	StartExecuteTool(ctx context.Context, attrs ExecuteToolSpan) (context.Context, trace.Span)
	// ResolveCost returns the configured runtime-specific cost for an exact
	// provider system / resolved model match.
	ResolveCost(providerSystem, resolvedModel string) (Cost, bool)
	// Shutdown is best-effort. Exporter or flush failures are swallowed so
	// telemetry cannot break the agent loop.
	Shutdown(ctx context.Context)
}

Telemetry exposes the runtime-facing span scaffolding used by the agent loop. The returned context carries the started span and, for root spans, the run identity that child spans should inherit.

func New 

func New(cfg Config) Telemetry

New constructs a telemetry runtime. Nil providers fall back to no-op providers, making this safe to use as the default runtime.

func NewNoop 

func NewNoop() Telemetry

NewNoop returns the default no-op telemetry runtime.

type Usage 

type Usage struct {
	Input      int
	Output     int
	CacheRead  int
	CacheWrite int
	Total      int
}

Usage captures token counts for metric recording without depending on the agent package.

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.