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 ¶
- func EnvironmentConfigured() bool
- func ObserveOutputChunk(ctx context.Context)
- func ObserveResponseChunk(ctx context.Context)
- func StructuredObjectValue(value any) (attribute.Value, bool)
- func StructuredValue(value any) (attribute.Value, bool)
- type AgentInvocation
- type AgentRequest
- type ContentCaptureMode
- type Inference
- type InferenceContent
- type InferenceRequest
- type InferenceResult
- type MCPClientOperation
- type MCPClientRequest
- type MCPClientResult
- type MCPOperation
- type MCPSession
- type MCPSessionRequest
- type MCPTransport
- type Options
- type Outcome
- type Telemetry
- func (t *Telemetry) CapturesMessageContent() bool
- func (t *Telemetry) ExtractMCPContext(ctx context.Context, meta map[string]any) context.Context
- func (t *Telemetry) ForceFlush(ctx context.Context) error
- func (t *Telemetry) InjectMCPContext(ctx context.Context, meta map[string]any) map[string]any
- func (t *Telemetry) Shutdown(ctx context.Context) error
- func (t *Telemetry) StartAgent(ctx context.Context, req AgentRequest) (context.Context, *AgentInvocation)
- func (t *Telemetry) StartInference(ctx context.Context, req InferenceRequest) (context.Context, *Inference)
- func (t *Telemetry) StartMCPClient(ctx context.Context, req MCPClientRequest) (context.Context, *MCPOperation)
- func (t *Telemetry) StartMCPServer(ctx context.Context, req MCPClientRequest) (context.Context, *MCPOperation)
- func (t *Telemetry) StartMCPSession(ctx context.Context, req MCPSessionRequest) *MCPSession
- func (t *Telemetry) StartTool(ctx context.Context, req ToolRequest) (context.Context, *ToolExecution)
- type TokenUsage
- type ToolExecution
- type ToolRequest
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 ¶
ObserveOutputChunk records time between model-output chunks for the active inference operation. The first output chunk establishes the baseline.
func ObserveResponseChunk ¶
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 ¶
StructuredObjectValue converts an object-like JSON value for semantic convention fields whose schema requires an object.
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 ¶
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 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 ¶
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 ¶
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 ¶
CapturesMessageContent reports whether structured message content will be recorded on an enabled GenAI inference span or inference-detail event.
func (*Telemetry) ExtractMCPContext ¶
ExtractMCPContext extracts configured propagation fields from MCP params._meta before a receiver span is started.
func (*Telemetry) ForceFlush ¶
ForceFlush immediately exports all telemetry owned by t.
func (*Telemetry) InjectMCPContext ¶
InjectMCPContext injects the configured propagator into an MCP params._meta map. The default is W3C Trace Context plus W3C Baggage.
func (*Telemetry) Shutdown ¶
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.