Documentation
¶
Overview ¶
OpenTelemetry provider initialization and configuration.
Package telemetry provides telemetry export functionality.
OpenTelemetry tracing support for distributed agent observability.
Index ¶
- func ExtractContext(ctx context.Context, carrier propagation.TextMapCarrier) context.Context
- func InjectContext(ctx context.Context, carrier propagation.TextMapCarrier)
- func SetGlobalTracer(t *Tracer)
- type Event
- type Exporter
- type FileExporter
- type HTTPExporter
- type LLMSpanOptions
- type MCPSpanOptions
- type MapCarrier
- type Message
- type NoopExporter
- type PolicySpanOptions
- type Provider
- type ProviderConfig
- type SecuritySpanOptions
- type TokenCount
- type ToolSpanOptions
- type Tracer
- func (t *Tracer) Debug() bool
- func (t *Tracer) EndLLMSpan(span trace.Span, opts LLMSpanOptions, err error)
- func (t *Tracer) EndMCPSpan(span trace.Span, opts MCPSpanOptions, err error)
- func (t *Tracer) EndPolicySpan(span trace.Span, opts PolicySpanOptions, err error)
- func (t *Tracer) EndSecuritySpan(span trace.Span, opts SecuritySpanOptions, err error)
- func (t *Tracer) EndToolSpan(span trace.Span, opts ToolSpanOptions, err error)
- func (t *Tracer) SetDebug(debug bool)
- func (t *Tracer) StartLLMSpan(ctx context.Context, name string) (context.Context, trace.Span)
- func (t *Tracer) StartMCPSpan(ctx context.Context, server, tool string) (context.Context, trace.Span)
- func (t *Tracer) StartPolicySpan(ctx context.Context, name string) (context.Context, trace.Span)
- func (t *Tracer) StartSecuritySpan(ctx context.Context, name string) (context.Context, trace.Span)
- func (t *Tracer) StartSpan(ctx context.Context, name string, opts ...trace.SpanStartOption) (context.Context, trace.Span)
- func (t *Tracer) StartToolSpan(ctx context.Context, toolName string) (context.Context, trace.Span)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ExtractContext ¶
func ExtractContext(ctx context.Context, carrier propagation.TextMapCarrier) context.Context
ExtractContext extracts trace context from a carrier.
func InjectContext ¶
func InjectContext(ctx context.Context, carrier propagation.TextMapCarrier)
InjectContext injects trace context into a carrier for cross-process propagation.
func SetGlobalTracer ¶
func SetGlobalTracer(t *Tracer)
SetGlobalTracer sets the global tracer instance.
Types ¶
type Event ¶
type Event struct {
Name string `json:"name"`
Timestamp time.Time `json:"timestamp"`
Data map[string]interface{} `json:"data"`
}
Event represents a telemetry event.
type Exporter ¶
type Exporter interface {
// LogEvent logs an event with the given name and data.
LogEvent(name string, data map[string]interface{})
// LogMessage logs an LLM message.
LogMessage(msg Message)
// Flush sends any buffered data.
Flush() error
// Close closes the exporter.
Close() error
}
Exporter is the interface for telemetry exporters.
func NewExporter ¶
NewExporter creates a new exporter based on protocol.
type FileExporter ¶
type FileExporter struct {
// contains filtered or unexported fields
}
FileExporter writes telemetry to a file.
func NewFileExporter ¶
func NewFileExporter(path string) (*FileExporter, error)
NewFileExporter creates a new file exporter.
func (*FileExporter) Close ¶
func (e *FileExporter) Close() error
func (*FileExporter) Flush ¶
func (e *FileExporter) Flush() error
func (*FileExporter) LogEvent ¶
func (e *FileExporter) LogEvent(name string, data map[string]interface{})
func (*FileExporter) LogMessage ¶
func (e *FileExporter) LogMessage(msg Message)
type HTTPExporter ¶
type HTTPExporter struct {
// contains filtered or unexported fields
}
HTTPExporter sends telemetry to an HTTP endpoint.
func NewHTTPExporter ¶
func NewHTTPExporter(endpoint string) *HTTPExporter
NewHTTPExporter creates a new HTTP exporter.
func (*HTTPExporter) Close ¶
func (e *HTTPExporter) Close() error
func (*HTTPExporter) Flush ¶
func (e *HTTPExporter) Flush() error
func (*HTTPExporter) LogEvent ¶
func (e *HTTPExporter) LogEvent(name string, data map[string]interface{})
func (*HTTPExporter) LogMessage ¶
func (e *HTTPExporter) LogMessage(msg Message)
type LLMSpanOptions ¶
type LLMSpanOptions struct {
Model string
Provider string
TokensIn int
TokensOut int
Prompt string // Only included if debug=true
Response string // Only included if debug=true
Thinking string // Only included if debug=true
}
LLMSpanOptions contains options for LLM call spans.
type MCPSpanOptions ¶
type MCPSpanOptions struct {
Server string
Tool string
Args map[string]interface{}
Result string // Only included if debug=true
}
MCPSpanOptions contains options for MCP tool call spans.
type MapCarrier ¶
MapCarrier is a simple map-based TextMapCarrier for context propagation.
func (MapCarrier) Get ¶
func (c MapCarrier) Get(key string) string
func (MapCarrier) Keys ¶
func (c MapCarrier) Keys() []string
func (MapCarrier) Set ¶
func (c MapCarrier) Set(key, value string)
type Message ¶
type Message struct {
SessionID string `json:"session_id"`
WorkflowName string `json:"workflow_name"`
Goal string `json:"goal"`
Role string `json:"role"`
Agent string `json:"agent,omitempty"`
Content string `json:"content"`
ToolCalls []interface{} `json:"tool_calls,omitempty"`
Tokens TokenCount `json:"tokens"`
Latency time.Duration `json:"latency"`
Model string `json:"model"`
Iteration int `json:"iteration,omitempty"`
Timestamp time.Time `json:"timestamp"`
Extra map[string]interface{} `json:"extra,omitempty"`
}
Message represents an LLM message for telemetry.
type NoopExporter ¶
type NoopExporter struct{}
NoopExporter discards all telemetry.
func NewNoopExporter ¶
func NewNoopExporter() *NoopExporter
NewNoopExporter creates a new noop exporter.
func (*NoopExporter) Close ¶
func (e *NoopExporter) Close() error
func (*NoopExporter) Flush ¶
func (e *NoopExporter) Flush() error
func (*NoopExporter) LogEvent ¶
func (e *NoopExporter) LogEvent(name string, data map[string]interface{})
func (*NoopExporter) LogMessage ¶
func (e *NoopExporter) LogMessage(msg Message)
type PolicySpanOptions ¶
type PolicySpanOptions struct {
Step string // deterministic, llm
Allowed bool
Reason string
Command string // Only in debug mode
}
PolicySpanOptions contains options for policy check spans.
type Provider ¶
type Provider struct {
// contains filtered or unexported fields
}
Provider wraps the OpenTelemetry TracerProvider with cleanup.
func InitProvider ¶
func InitProvider(ctx context.Context, cfg ProviderConfig) (*Provider, error)
InitProvider initializes OpenTelemetry with the given configuration. Returns a Provider that must be shut down when done.
func (*Provider) ForceFlush ¶
ForceFlush forces a flush of all pending spans.
type ProviderConfig ¶
type ProviderConfig struct {
// ServiceName is the name of the service (required).
ServiceName string
// ServiceVersion is the version of the service.
ServiceVersion string
// Endpoint is the OTLP endpoint (e.g., "localhost:4317").
// If empty, uses OTEL_EXPORTER_OTLP_ENDPOINT env var.
Endpoint string
// Protocol is "grpc" or "http". Default is "grpc".
Protocol string
// Insecure disables TLS. Default is false.
Insecure bool
// Debug enables content in span attributes.
Debug bool
// Headers are additional headers to send with requests.
Headers map[string]string
// BatchTimeout is the maximum time to wait before sending a batch.
BatchTimeout time.Duration
// ExportTimeout is the timeout for exporting spans.
ExportTimeout time.Duration
}
ProviderConfig configures the OpenTelemetry provider.
type SecuritySpanOptions ¶
type SecuritySpanOptions struct {
CheckPath string // static, static→triage, static→triage→supervisor
Verdict string // allow, deny, modify
BlockID string
Flags []string
Prompt string // Only in debug mode
Response string // Only in debug mode
}
SecuritySpanOptions contains options for security check spans.
type TokenCount ¶
TokenCount represents token usage.
type ToolSpanOptions ¶
type ToolSpanOptions struct {
Tool string
Args map[string]interface{} // Always included (agent-controlled)
Result string // Only included if debug=true
}
ToolSpanOptions contains options for tool execution spans.
type Tracer ¶
type Tracer struct {
// contains filtered or unexported fields
}
Tracer wraps OpenTelemetry tracing with agent-specific helpers.
func GetTracer ¶
func GetTracer() *Tracer
GetTracer returns the global tracer, or a no-op tracer if not set.
func (*Tracer) EndLLMSpan ¶
func (t *Tracer) EndLLMSpan(span trace.Span, opts LLMSpanOptions, err error)
EndLLMSpan ends an LLM span with attributes.
func (*Tracer) EndMCPSpan ¶
func (t *Tracer) EndMCPSpan(span trace.Span, opts MCPSpanOptions, err error)
EndMCPSpan ends an MCP span with attributes.
func (*Tracer) EndPolicySpan ¶
func (t *Tracer) EndPolicySpan(span trace.Span, opts PolicySpanOptions, err error)
EndPolicySpan ends a policy span with attributes.
func (*Tracer) EndSecuritySpan ¶
func (t *Tracer) EndSecuritySpan(span trace.Span, opts SecuritySpanOptions, err error)
EndSecuritySpan ends a security span with attributes.
func (*Tracer) EndToolSpan ¶
func (t *Tracer) EndToolSpan(span trace.Span, opts ToolSpanOptions, err error)
EndToolSpan ends a tool span with attributes.
func (*Tracer) StartLLMSpan ¶
StartLLMSpan starts a span for an LLM call.
func (*Tracer) StartMCPSpan ¶
func (t *Tracer) StartMCPSpan(ctx context.Context, server, tool string) (context.Context, trace.Span)
StartMCPSpan starts a span for an MCP tool call.
func (*Tracer) StartPolicySpan ¶
StartPolicySpan starts a span for a policy check.
func (*Tracer) StartSecuritySpan ¶
StartSecuritySpan starts a span for a security check.