telemetry

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Feb 24, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

OpenTelemetry provider initialization and configuration.

Package telemetry provides telemetry export functionality.

OpenTelemetry tracing support for distributed agent observability.

Index

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

func NewExporter(protocol, endpoint string) (Exporter, error)

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

type MapCarrier map[string]string

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

func (p *Provider) ForceFlush(ctx context.Context) error

ForceFlush forces a flush of all pending spans.

func (*Provider) SetDebug

func (p *Provider) SetDebug(debug bool)

SetDebug enables or disables debug mode.

func (*Provider) Shutdown

func (p *Provider) Shutdown(ctx context.Context) error

Shutdown gracefully shuts down the provider.

func (*Provider) Tracer

func (p *Provider) Tracer() *Tracer

Tracer returns the tracer for this provider.

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

type TokenCount struct {
	Input  int `json:"input"`
	Output int `json:"output"`
}

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 NewTracer

func NewTracer(name string, debug bool) *Tracer

NewTracer creates a new tracer with the given name.

func (*Tracer) Debug

func (t *Tracer) Debug() bool

Debug returns whether debug mode is enabled.

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) SetDebug

func (t *Tracer) SetDebug(debug bool)

SetDebug enables or disables debug mode (content in spans).

func (*Tracer) StartLLMSpan

func (t *Tracer) StartLLMSpan(ctx context.Context, name string) (context.Context, trace.Span)

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

func (t *Tracer) StartPolicySpan(ctx context.Context, name string) (context.Context, trace.Span)

StartPolicySpan starts a span for a policy check.

func (*Tracer) StartSecuritySpan

func (t *Tracer) StartSecuritySpan(ctx context.Context, name string) (context.Context, trace.Span)

StartSecuritySpan starts a span for a security check.

func (*Tracer) StartSpan

func (t *Tracer) StartSpan(ctx context.Context, name string, opts ...trace.SpanStartOption) (context.Context, trace.Span)

StartSpan starts a new span with the given name.

func (*Tracer) StartToolSpan

func (t *Tracer) StartToolSpan(ctx context.Context, toolName string) (context.Context, trace.Span)

StartToolSpan starts a span for a tool execution.

Jump to

Keyboard shortcuts

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