telemetry

package
v0.16.8 Latest Latest
Warning

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

Go to latest
Published: Sep 8, 2026 License: MIT Imports: 28 Imported by: 0

Documentation

Overview

Package telemetry configures slim OTLP HTTP/protobuf OpenTelemetry exporters and instruments the built-in GenAI agent and MCP client according to the latest OpenTelemetry GenAI semantic conventions. Environment-based setup is a no-op unless an enabled signal has OTLP exporter configuration.

Prompts, model responses, tool arguments, and tool results are omitted by default. They can be routed to inference spans, inference-detail log events, or both through ContentCaptureMode. This opt-in data can contain source code, credentials, or other sensitive user data.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func EnvironmentConfigured

func EnvironmentConfigured() bool

EnvironmentConfigured reports whether a trace, metric, or log exporter is configured with standard OpenTelemetry environment variables.

func ObserveOutputChunk

func ObserveOutputChunk(ctx context.Context)

ObserveOutputChunk records time between model-output chunks for the active inference operation. The first output chunk establishes the baseline.

func ObserveResponseChunk

func ObserveResponseChunk(ctx context.Context)

ObserveResponseChunk records streaming time-to-first-chunk for the active inference operation. Call it for every response-stream event; only the first event is recorded.

func StructuredObjectValue

func StructuredObjectValue(value any) (attribute.Value, bool)

StructuredObjectValue converts an object-like JSON value for semantic convention fields whose schema requires an object.

func StructuredValue

func StructuredValue(value any) (attribute.Value, bool)

StructuredValue converts a JSON-compatible Go value into OpenTelemetry's structured attribute representation. Unsupported and non-finite values are omitted rather than serialized as misleading strings.

Types

type AgentInvocation

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

AgentInvocation represents one in-process invocation and owns its per-turn inference/tool call counters.

func (*AgentInvocation) End

func (invocation *AgentInvocation) End(outcome Outcome)

End completes the agent span and records its duration and per-invocation inference/tool call distributions.

type AgentRequest

type AgentRequest struct {
	Name           string
	ConversationID string
}

AgentRequest contains attributes available when an in-process agent starts.

type ContentCaptureMode

type ContentCaptureMode string

ContentCaptureMode controls where potentially sensitive GenAI message content is recorded. The values match the OpenTelemetry GenAI utilities convention and OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT.

const (
	ContentCaptureNoContent    ContentCaptureMode = "NO_CONTENT"
	ContentCaptureSpanOnly     ContentCaptureMode = "SPAN_ONLY"
	ContentCaptureEventOnly    ContentCaptureMode = "EVENT_ONLY"
	ContentCaptureSpanAndEvent ContentCaptureMode = "SPAN_AND_EVENT"
)

type Inference

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

Inference represents one logical GenAI client operation, including any transparent retries.

func (*Inference) End

func (inference *Inference) End(result InferenceResult)

End completes an inference span and records duration and token usage.

func (*Inference) SetContent

func (inference *Inference) SetContent(content InferenceContent)

SetContent replaces request content for the active logical inference. This is useful when an automatic retry changes the effective prompt.

type InferenceContent

type InferenceContent struct {
	InputMessages      attribute.Value
	SystemInstructions attribute.Value
	ToolDefinitions    attribute.Value
}

InferenceContent contains structured, potentially sensitive attributes used on inference spans and by the standard inference-details event. Values must follow the GenAI semantic-convention JSON schemas.

type InferenceRequest

type InferenceRequest struct {
	Operation      string
	Model          string
	ConversationID string
	Streaming      bool
	ReasoningLevel string
	Content        InferenceContent
}

InferenceRequest contains the stable attributes of one logical model call.

type InferenceResult

type InferenceResult struct {
	Outcome
	ResponseID     string
	ResponseModel  string
	FinishReasons  []string
	OutputMessages attribute.Value
	Usage          *TokenUsage
}

InferenceResult contains provider metadata and billable usage available at the end of a logical model call.

type MCPClientOperation

type MCPClientOperation = MCPOperation

MCPClientOperation is kept as a descriptive alias for outbound operations.

type MCPClientRequest

type MCPClientRequest struct {
	MCPTransport

	Method          string
	ProtocolVersion string
	SessionID       string
	ToolName        string
	PromptName      string
	PromptVariables map[string]string
	ResourceURI     string
	Arguments       any
}

MCPClientRequest contains attributes known when an outbound MCP request or notification starts. Method is required. ResourceURI and content fields are excluded from metrics to avoid high-cardinality metric dimensions.

type MCPClientResult

type MCPClientResult struct {
	Outcome
	ProtocolVersion   string
	StatusCode        string
	StatusDescription string
	ToolError         bool
	Result            any
}

MCPClientResult contains attributes available when an outbound MCP request or notification ends. ToolError represents CallToolResult.isError=true.

type MCPOperation

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

MCPOperation represents one MCP request or notification. A tools/call operation reuses an active GenAI tool span when one is present, as required by the MCP semantic-convention deduplication guidance.

func (*MCPOperation) End

func (operation *MCPOperation) End(result MCPClientResult)

End completes an MCP operation and records its role-specific duration.

type MCPSession

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

MCPSession observes one connected MCP client session.

func (*MCPSession) End

func (session *MCPSession) End(outcome Outcome)

End records mcp.client.session.duration. It is safe to call more than once.

type MCPSessionRequest

type MCPSessionRequest struct {
	MCPTransport
	ProtocolVersion string
}

MCPSessionRequest contains stable attributes for an MCP client session.

type MCPTransport

type MCPTransport struct {
	NetworkTransport       string
	NetworkProtocolName    string
	NetworkProtocolVersion string
	ServerAddress          string
	ServerPort             int
}

MCPTransport describes the transport used for an MCP client operation or session. NetworkTransport is normally "pipe" for stdio or "tcp" for HTTP.

type Options

type Options struct {
	ServiceName string
	AgentName   string

	// ProviderName identifies the model service as observed by this client.
	// Well-known values include "openai" and "anthropic"; custom providers are
	// allowed by the GenAI semantic conventions.
	ProviderName  string
	ServerAddress string
	ServerPort    int

	TracerProvider trace.TracerProvider
	MeterProvider  metric.MeterProvider
	LoggerProvider otellog.LoggerProvider
	Propagator     propagation.TextMapPropagator

	DisableTraces  bool
	DisableMetrics bool

	// EmitEvents emits the standard gen_ai.client.inference.operation.details
	// log event and gen_ai.client.operation.exception for failed operations.
	// Events contain operation metadata and usage, but no message content in
	// ContentCaptureNoContent or ContentCaptureSpanOnly mode.
	EmitEvents bool

	// CaptureMessageContent controls whether structured input/output messages,
	// system instructions, and tool definitions are included on inference spans,
	// inference-detail events, both, or neither. The zero value reads
	// OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT and otherwise defaults
	// to ContentCaptureNoContent. Captured content can contain source code,
	// credentials, and other sensitive information.
	CaptureMessageContent ContentCaptureMode
}

Options configures a Telemetry pipeline. New creates OTLP HTTP/protobuf exporters from standard OpenTelemetry environment variables when providers are not supplied. Injected providers are owned by the caller and are not shut down by Telemetry.

type Outcome

type Outcome struct {
	Err       error
	ErrorType string
}

Outcome describes whether an instrumented operation succeeded.

type Telemetry

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

Telemetry owns the GenAI instruments and any SDK providers it created. It is safe for concurrent use.

func New

func New(ctx context.Context, opts Options) (*Telemetry, error)

New creates explicitly enabled GenAI telemetry. Unless disabled, traces and metrics use injected providers or OTLP HTTP/protobuf exporters. The exporter defaults and options are read from standard OTEL_EXPORTER_OTLP_* variables.

func NewFromEnvironment

func NewFromEnvironment(ctx context.Context, opts Options) (*Telemetry, error)

NewFromEnvironment creates telemetry only for signals configured through standard OpenTelemetry exporter variables. A nil result means no enabled signal has an exporter configured, or OTEL_SDK_DISABLED is true. Log events additionally require OTEL_INSTRUMENTATION_GENAI_EMIT_EVENT=true (or an event capture mode), so exporter configuration alone never enables them.

func (*Telemetry) CapturesMessageContent

func (t *Telemetry) CapturesMessageContent() bool

CapturesMessageContent reports whether structured message content will be recorded on an enabled GenAI inference span or inference-detail event.

func (*Telemetry) ExtractMCPContext

func (t *Telemetry) ExtractMCPContext(ctx context.Context, meta map[string]any) context.Context

ExtractMCPContext extracts configured propagation fields from MCP params._meta before a receiver span is started.

func (*Telemetry) ForceFlush

func (t *Telemetry) ForceFlush(ctx context.Context) error

ForceFlush immediately exports all telemetry owned by t.

func (*Telemetry) InjectMCPContext

func (t *Telemetry) InjectMCPContext(ctx context.Context, meta map[string]any) map[string]any

InjectMCPContext injects the configured propagator into an MCP params._meta map. The default is W3C Trace Context plus W3C Baggage.

func (*Telemetry) Shutdown

func (t *Telemetry) Shutdown(ctx context.Context) error

Shutdown flushes and stops SDK providers created by t. It is idempotent and does not shut down providers injected through Options.

func (*Telemetry) StartAgent

func (t *Telemetry) StartAgent(ctx context.Context, req AgentRequest) (context.Context, *AgentInvocation)

StartAgent starts an invoke_agent INTERNAL span and returns a context that must be used for all model and tool operations in the invocation.

func (*Telemetry) StartInference

func (t *Telemetry) StartInference(ctx context.Context, req InferenceRequest) (context.Context, *Inference)

StartInference starts a CLIENT inference span. The returned context should cover every transport retry belonging to the same logical operation.

func (*Telemetry) StartMCPClient

func (t *Telemetry) StartMCPClient(ctx context.Context, req MCPClientRequest) (context.Context, *MCPOperation)

StartMCPClient starts a CLIENT span for an outbound MCP operation, or enriches an active execute_tool span for tools/call. The returned context carries the span that should be propagated to the MCP peer.

func (*Telemetry) StartMCPServer

func (t *Telemetry) StartMCPServer(ctx context.Context, req MCPClientRequest) (context.Context, *MCPOperation)

StartMCPServer starts a SERVER span for an MCP operation initiated by the peer and processed by this endpoint.

func (*Telemetry) StartMCPSession

func (t *Telemetry) StartMCPSession(ctx context.Context, req MCPSessionRequest) *MCPSession

StartMCPSession begins an MCP client-session duration observation.

func (*Telemetry) StartTool

func (t *Telemetry) StartTool(ctx context.Context, req ToolRequest) (context.Context, *ToolExecution)

StartTool starts an execute_tool INTERNAL span. Potentially sensitive arguments are recorded only when span content capture is enabled.

type TokenUsage

type TokenUsage struct {
	InputTokens           int64
	CacheReadInputTokens  int64
	CacheWriteInputTokens int64
	OutputTokens          int64
	ReasoningOutputTokens int64
}

TokenUsage is the provider-reported token breakdown. A nil Usage on InferenceResult means the provider did not report usage; a non-nil all-zero value is still a valid report. InputTokens and OutputTokens are the aggregate counts and already include their respective detail fields.

type ToolExecution

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

ToolExecution represents one bounded agent-side tool execution.

func (*ToolExecution) End

func (execution *ToolExecution) End(outcome Outcome)

End completes a tool span and records its duration.

func (*ToolExecution) SetResult

func (execution *ToolExecution) SetResult(result any)

SetResult associates a successful tool result with the active execution. The value is emitted only when span content capture is enabled and End is called without an error outcome.

type ToolRequest

type ToolRequest struct {
	Name               string
	Description        string
	CallID             string
	Type               string
	AgentName          string
	MCPMethod          string
	MCPProtocolVersion string
	Arguments          any
}

ToolRequest contains metadata about a tool execution. Arguments are captured only when GenAI message-content capture is enabled.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL