Help us shape the future of Go! Take the 2026 Go Developer Survey

observability

package
v1.41.2 Latest Latest
Warning

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

 Go to latest Published: May 6, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Package observability provides OpenTelemetry tracing and Prometheus metrics.

This package combines the production-tested foundation from legacy Hector with GenAI semantic conventions from adk-go for ecosystem compatibility.

Architecture

The observability system has three main components:

  1. Tracing: OpenTelemetry spans with OTLP export
  2. Metrics: Prometheus counters and histograms
  3. Debug: In-memory span capture for web UI inspection

Configuration

Configure observability in your hector.yaml: 

server:
  observability:
    tracing:
      enabled: true
      exporter: otlp
      endpoint: localhost:4317
      sampling_rate: 1.0
      service_name: my-agent
    metrics:
      enabled: true
      endpoint: /metrics

Index

Constants

View Source 
const (
	// AttrServiceName is the logical name of the service.
	AttrServiceName = "service.name"

	// AttrServiceVersion is the version of the service.
	AttrServiceVersion = "service.version"

	// AttrServiceInstance is the instance ID of the service.
	AttrServiceInstance = "service.instance.id"
)
View Source 
const (
	// AttrGenAISystem identifies the GenAI system (e.g., "hector", "openai").
	AttrGenAISystem = "gen_ai.system"

	// AttrGenAIOperationName is the operation being performed.
	// Values: "chat", "text_completion", "embeddings"
	AttrGenAIOperationName = "gen_ai.operation.name"

	// AttrGenAIRequestModel is the name of the model being used.
	AttrGenAIRequestModel = "gen_ai.request.model"

	// AttrGenAIRequestTemperature is the temperature parameter.
	AttrGenAIRequestTemperature = "gen_ai.request.temperature"

	// AttrGenAIRequestTopP is the top_p parameter.
	AttrGenAIRequestTopP = "gen_ai.request.top_p"

	// AttrGenAIRequestMaxTokens is the maximum tokens requested.
	AttrGenAIRequestMaxTokens = "gen_ai.request.max_tokens"

	// AttrGenAIResponseFinishReason is why generation stopped.
	// Values: "stop", "length", "tool_calls", "content_filter"
	AttrGenAIResponseFinishReason = "gen_ai.response.finish_reason"

	// AttrGenAIUsageInputTokens is the number of input tokens.
	AttrGenAIUsageInputTokens = "gen_ai.usage.input_tokens"

	// AttrGenAIUsageOutputTokens is the number of output tokens.
	AttrGenAIUsageOutputTokens = "gen_ai.usage.output_tokens"

	// AttrGenAIToolName is the name of the tool being called.
	AttrGenAIToolName = "gen_ai.tool.name"

	// AttrGenAIToolDescription is the description of the tool.
	AttrGenAIToolDescription = "gen_ai.tool.description"

	// AttrGenAIToolCallID is the unique ID of the tool call.
	AttrGenAIToolCallID = "gen_ai.tool.call.id"
)
View Source 
const (
	// AttrHectorAgentName is the name of the agent.
	AttrHectorAgentName = "hector.agent.name"

	// AttrHectorAgentType is the type of agent (llm, workflow, remote).
	AttrHectorAgentType = "hector.agent.type"

	// AttrHectorInvocationID is the unique ID for this agent invocation.
	AttrHectorInvocationID = "hector.invocation_id"

	// AttrHectorSessionID is the session ID.
	AttrHectorSessionID = "hector.session_id"

	// AttrHectorUserID is the user ID.
	AttrHectorUserID = "hector.user_id"

	// AttrHectorEventID is the event ID within a session.
	AttrHectorEventID = "hector.event_id"

	// AttrHectorLLMRequest is the serialized LLM request (optional, for debugging).
	AttrHectorLLMRequest = "hector.llm.request"

	// AttrHectorLLMResponse is the serialized LLM response (optional, for debugging).
	AttrHectorLLMResponse = "hector.llm.response"

	// AttrHectorToolArgs is the serialized tool arguments (optional, for debugging).
	AttrHectorToolArgs = "hector.tool.args"

	// AttrHectorToolResponse is the serialized tool response (optional, for debugging).
	AttrHectorToolResponse = "hector.tool.response"

	// AttrHectorThinkingBlocks is the number of thinking blocks in response.
	AttrHectorThinkingBlocks = "hector.llm.thinking.blocks"

	// AttrHectorThinkingLength is the total length of thinking content (chars).
	AttrHectorThinkingLength = "hector.llm.thinking.length"
)
View Source 
const (
	// AttrHTTPMethod is the HTTP method.
	AttrHTTPMethod = "http.method"

	// AttrHTTPPath is the HTTP path (route pattern, not raw path).
	AttrHTTPPath = "http.route"

	// AttrHTTPStatusCode is the HTTP response status code.
	AttrHTTPStatusCode = "http.status_code"

	// AttrHTTPRequestSize is the request body size in bytes.
	AttrHTTPRequestSize = "http.request.body.size"

	// AttrHTTPResponseSize is the response body size in bytes.
	AttrHTTPResponseSize = "http.response.body.size"
)
View Source 
const (
	// AttrErrorType is the type of error that occurred.
	AttrErrorType = "error.type"

	// AttrErrorMessage is the error message.
	AttrErrorMessage = "error.message"
)
View Source 
const (
	// AttrRAGStoreName is the name of the document store.
	AttrRAGStoreName = "hector.rag.store.name"

	// AttrRAGQuery is the search query.
	AttrRAGQuery = "hector.rag.query"

	// AttrRAGResultCount is the number of search results.
	AttrRAGResultCount = "hector.rag.result_count"

	// AttrRAGTopK is the requested number of results.
	AttrRAGTopK = "hector.rag.top_k"

	// AttrRAGDocumentCount is the number of documents indexed.
	AttrRAGDocumentCount = "hector.rag.document_count"

	// AttrRAGChunkCount is the number of chunks indexed.
	AttrRAGChunkCount = "hector.rag.chunk_count"

	// AttrRAGSourceType is the data source type (directory, sql, api).
	AttrRAGSourceType = "hector.rag.source_type"

	// AttrRAGChunkerStrategy is the chunking strategy used.
	AttrRAGChunkerStrategy = "hector.rag.chunker_strategy"

	// AttrRAGHyDEEnabled indicates if HyDE was used.
	AttrRAGHyDEEnabled = "hector.rag.hyde_enabled"

	// AttrRAGRerankEnabled indicates if reranking was used.
	AttrRAGRerankEnabled = "hector.rag.rerank_enabled"

	// AttrRAGMultiQueryEnabled indicates if multi-query was used.
	AttrRAGMultiQueryEnabled = "hector.rag.multiquery_enabled"

	// AttrRAGEmbeddingModel is the embedding model used.
	AttrRAGEmbeddingModel = "hector.rag.embedding_model"

	// AttrRAGVectorProvider is the vector database provider.
	AttrRAGVectorProvider = "hector.rag.vector_provider"
)
View Source 
const (
	// SpanAgentRun is the top-level span for an agent invocation.
	SpanAgentRun = "hector.agent.run"

	// SpanLLMCall is a span for an LLM API call.
	SpanLLMCall = "hector.llm.call"

	// SpanToolExecution is a span for tool execution.
	SpanToolExecution = "hector.tool.execute"

	// SpanMemorySearch is a span for memory/index search.
	SpanMemorySearch = "hector.memory.search"

	// SpanSessionLoad is a span for loading session data.
	SpanSessionLoad = "hector.session.load"

	// SpanHTTPRequest is a span for HTTP request handling.
	SpanHTTPRequest = "hector.http.request"

	// SpanRAGSearch is a span for RAG search operations.
	SpanRAGSearch = "hector.rag.search"

	// SpanRAGIndex is a span for RAG indexing operations.
	SpanRAGIndex = "hector.rag.index"

	// SpanRAGEmbed is a span for embedding generation.
	SpanRAGEmbed = "hector.rag.embed"

	// SpanRAGChunk is a span for document chunking.
	SpanRAGChunk = "hector.rag.chunk"

	// SpanRAGRerank is a span for result reranking.
	SpanRAGRerank = "hector.rag.rerank"

	// SpanRAGHyDE is a span for HyDE hypothetical document generation.
	SpanRAGHyDE = "hector.rag.hyde"
)
View Source 
const (
	// DefaultServiceName is the default service name for tracing.
	DefaultServiceName = "hector"

	// DefaultSamplingRate is the default trace sampling rate.
	DefaultSamplingRate = 1.0

	// DefaultOTLPEndpoint is the default OTLP endpoint.
	DefaultOTLPEndpoint = "localhost:4317"

	// DefaultMetricsPath is the default Prometheus metrics endpoint.
	DefaultMetricsPath = "/metrics"
)
View Source 
const (
	// OpChat is a chat completion operation.
	OpChat = "chat"

	// OpTextCompletion is a text completion operation.
	OpTextCompletion = "text_completion"

	// OpEmbeddings is an embeddings generation operation.
	OpEmbeddings = "embeddings"

	// OpToolCall is a tool execution operation.
	OpToolCall = "execute_tool"
)

Variables

This section is empty.

Functions

func HTTPMiddleware 

func HTTPMiddleware(tracer *Tracer, metrics *Metrics) func(http.Handler) http.Handler

HTTPMiddleware creates HTTP middleware that records both traces and metrics.

func MetricsMiddleware 

func MetricsMiddleware(metrics *Metrics) func(http.Handler) http.Handler

MetricsMiddleware creates HTTP middleware that only records metrics.

func TracingMiddleware 

func TracingMiddleware(tracer *Tracer) func(http.Handler) http.Handler

TracingMiddleware creates HTTP middleware that only records traces.

Types

type Config 

type Config struct {
	// Tracing configures OpenTelemetry distributed tracing.
	Tracing TracingConfig `yaml:"tracing,omitempty"`

	// Metrics configures Prometheus metrics collection.
	Metrics MetricsConfig `yaml:"metrics,omitempty"`
}

Config configures the observability system.

func (*Config) SetDefaults 

func (c *Config) SetDefaults()

SetDefaults applies default values to Config.

func (*Config) Validate 

func (c *Config) Validate() error

Validate checks the Config for errors.

type DebugExporter 

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

DebugExporter is a custom SpanExporter that stores span data in memory for web UI inspection and debugging.

Inspired by adk-go's APIServerSpanExporter, this exporter captures relevant span attributes (LLM calls, tool executions, agent runs) keyed by event ID for easy lookup.

Thread-safe for concurrent reads and writes.

func NewDebugExporter 

func NewDebugExporter() *DebugExporter

NewDebugExporter creates a new DebugExporter.

func (*DebugExporter) Clear 

func (e *DebugExporter) Clear()

Clear removes all captured spans.

func (*DebugExporter) Count 

func (e *DebugExporter) Count() int

Count returns the number of captured spans.

func (*DebugExporter) ExportSpans 

func (e *DebugExporter) ExportSpans(ctx context.Context, spans []sdktrace.ReadOnlySpan) error

ExportSpans implements sdktrace.SpanExporter. It captures span data for relevant spans (LLM calls, tool executions, etc.).

func (*DebugExporter) GetAllSpans 

func (e *DebugExporter) GetAllSpans() []*DebugSpan

GetAllSpans returns all captured spans.

func (*DebugExporter) GetByEventID 

func (e *DebugExporter) GetByEventID(eventID string) *DebugSpan

GetByEventID returns a span by its hector.event_id attribute.

func (*DebugExporter) GetSpan 

func (e *DebugExporter) GetSpan(spanID string) *DebugSpan

GetSpan returns a span by its span ID.

func (*DebugExporter) GetSpansByName 

func (e *DebugExporter) GetSpansByName(name string) []*DebugSpan

GetSpansByName returns all spans with the given name.

func (*DebugExporter) GetSpansByTrace 

func (e *DebugExporter) GetSpansByTrace(traceID string) []*DebugSpan

GetSpansByTrace returns all spans for a given trace ID.

func (*DebugExporter) Shutdown 

func (e *DebugExporter) Shutdown(ctx context.Context) error

Shutdown implements sdktrace.SpanExporter.

func (*DebugExporter) WithMaxSize 

func (e *DebugExporter) WithMaxSize(size int) *DebugExporter

WithMaxSize sets the maximum number of spans to retain.

type DebugSpan 

type DebugSpan struct {
	TraceID      string            `json:"trace_id"`
	SpanID       string            `json:"span_id"`
	ParentSpanID string            `json:"parent_span_id,omitempty"`
	Name         string            `json:"name"`
	StartTime    int64             `json:"start_time_unix_nano"`
	EndTime      int64             `json:"end_time_unix_nano"`
	DurationMs   float64           `json:"duration_ms"`
	Attributes   map[string]string `json:"attributes"`
	Events       []SpanEvent       `json:"events,omitempty"`
	Status       string            `json:"status"`
	StatusMsg    string            `json:"status_message,omitempty"`
}

DebugSpan contains captured span information for debugging.

type Manager 

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

Manager manages the lifecycle of all observability components. It provides a unified interface for initializing, accessing, and shutting down tracing and metrics systems.

func MustNewManager 

func MustNewManager(ctx context.Context, cfg *Config) *Manager

MustNewManager creates a Manager and panics on error. Useful for initialization in main() when errors are fatal.

func NewFromConfig 

func NewFromConfig(ctx context.Context, cfg *Config) (*Manager, error)

NewFromConfig creates a Manager with defaults from a configuration pointer. This is useful when the config might be nil.

func NewManager 

func NewManager(ctx context.Context, cfg *Config) (*Manager, error)

NewManager creates a new observability Manager from configuration.

func NoopManager 

func NoopManager() *Manager

NoopManager returns a no-operation Manager that does nothing. Use this when observability is completely disabled.

func (*Manager) DebugExporter 

func (m *Manager) DebugExporter() *DebugExporter

DebugExporter returns the debug span exporter, or nil if not enabled.

func (*Manager) Metrics 

func (m *Manager) Metrics() *Metrics

Metrics returns the metrics instance, or nil if metrics are disabled.

func (*Manager) MetricsEnabled 

func (m *Manager) MetricsEnabled() bool

MetricsEnabled returns whether metrics are enabled.

func (*Manager) MetricsEndpoint 

func (m *Manager) MetricsEndpoint() string

MetricsEndpoint returns the configured metrics endpoint path.

func (*Manager) MetricsHandler 

func (m *Manager) MetricsHandler() http.Handler

MetricsHandler returns an HTTP handler for the metrics endpoint.

func (*Manager) Shutdown 

func (m *Manager) Shutdown(ctx context.Context) error

Shutdown gracefully shuts down all observability components.

func (*Manager) Tracer 

func (m *Manager) Tracer() *Tracer

Tracer returns the tracer instance, or nil if tracing is disabled.

func (*Manager) TracingEnabled 

func (m *Manager) TracingEnabled() bool

TracingEnabled returns whether tracing is enabled.

type Metrics 

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

Metrics provides Prometheus metrics collection for Hector.

func NewMetrics 

func NewMetrics(cfg *MetricsConfig) (*Metrics, error)

NewMetrics creates a new Metrics instance from configuration.

func (*Metrics) DecAgentActiveRuns 

func (m *Metrics) DecAgentActiveRuns(agentName string)

DecAgentActiveRuns decrements the active runs counter.

func (*Metrics) Handler 

func (m *Metrics) Handler() http.Handler

Handler returns an HTTP handler for the Prometheus metrics endpoint.

func (*Metrics) IncAgentActiveRuns 

func (m *Metrics) IncAgentActiveRuns(agentName string)

IncAgentActiveRuns increments the active runs counter.

func (*Metrics) RecordAgentCall 

func (m *Metrics) RecordAgentCall(agentName, agentType string, duration time.Duration)

RecordAgentCall records an agent invocation.

func (*Metrics) RecordAgentError 

func (m *Metrics) RecordAgentError(agentName, agentType, errorType string)

RecordAgentError records an agent error.

func (*Metrics) RecordAppLoad added in v1.21.0 

func (m *Metrics) RecordAppLoad(appName, status string, duration time.Duration)

func (*Metrics) RecordAppUnload added in v1.21.0 

func (m *Metrics) RecordAppUnload(appName string)

func (*Metrics) RecordHTTPRequest 

func (m *Metrics) RecordHTTPRequest(method, path string, statusCode int, duration time.Duration, reqSize, respSize int64)

RecordHTTPRequest records an HTTP request.

func (*Metrics) RecordLLMCall 

func (m *Metrics) RecordLLMCall(model, provider string, duration time.Duration)

RecordLLMCall records an LLM API call.

func (*Metrics) RecordLLMError 

func (m *Metrics) RecordLLMError(model, provider, errorType string)

RecordLLMError records an LLM error.

func (*Metrics) RecordLLMTokens 

func (m *Metrics) RecordLLMTokens(model, provider string, inputTokens, outputTokens int)

RecordLLMTokens records token usage.

func (*Metrics) RecordMemoryIndexed 

func (m *Metrics) RecordMemoryIndexed(indexType string, count int)

RecordMemoryIndexed records items being indexed.

func (*Metrics) RecordMemorySearch 

func (m *Metrics) RecordMemorySearch(indexType string, duration time.Duration)

RecordMemorySearch records a memory search operation.

func (*Metrics) RecordNotificationRetry added in v1.21.0 

func (m *Metrics) RecordNotificationRetry(agentName, notifType string)

func (*Metrics) RecordNotificationSent added in v1.21.0 

func (m *Metrics) RecordNotificationSent(agentName, notifType, status string, duration time.Duration)

func (*Metrics) RecordQueueLatency added in v1.21.0 

func (m *Metrics) RecordQueueLatency(appName, agentName string, duration time.Duration)

func (*Metrics) RecordQueueProcessingDuration added in v1.21.0 

func (m *Metrics) RecordQueueProcessingDuration(appName, agentName string, duration time.Duration)

func (*Metrics) RecordRAGDocError 

func (m *Metrics) RecordRAGDocError(storeName string)

RecordRAGDocError records a document indexing error.

func (*Metrics) RecordRAGDocIndexed 

func (m *Metrics) RecordRAGDocIndexed(storeName string, duration time.Duration)

RecordRAGDocIndexed records a document being indexed.

func (*Metrics) RecordRAGDocSkipped 

func (m *Metrics) RecordRAGDocSkipped(storeName string)

RecordRAGDocSkipped records a document being skipped.

func (*Metrics) RecordRAGSearch 

func (m *Metrics) RecordRAGSearch(storeName string, duration time.Duration, resultCount int)

RecordRAGSearch records a RAG search operation.

func (*Metrics) RecordSchedulerError added in v1.21.0 

func (m *Metrics) RecordSchedulerError(appName, agentName, errorType string)

func (*Metrics) RecordSchedulerTrigger added in v1.21.0 

func (m *Metrics) RecordSchedulerTrigger(appName, agentName string)

func (*Metrics) RecordSessionCreated 

func (m *Metrics) RecordSessionCreated(appName string)

RecordSessionCreated records a session creation.

func (*Metrics) RecordSessionEvent 

func (m *Metrics) RecordSessionEvent(appName, eventType string)

RecordSessionEvent records a session event.

func (*Metrics) RecordToolCall 

func (m *Metrics) RecordToolCall(toolName string, duration time.Duration)

RecordToolCall records a tool invocation.

func (*Metrics) RecordToolError 

func (m *Metrics) RecordToolError(toolName, errorType string)

RecordToolError records a tool error.

func (*Metrics) Registry 

func (m *Metrics) Registry() *prometheus.Registry

Registry returns the Prometheus registry.

func (*Metrics) SetQueueDepth added in v1.21.0 

func (m *Metrics) SetQueueDepth(appName, status string, count float64)

func (*Metrics) SetSessionsActive 

func (m *Metrics) SetSessionsActive(appName string, count int)

SetSessionsActive sets the number of active sessions.

type MetricsConfig 

type MetricsConfig struct {
	// Enabled turns on metrics collection.
	// Default: false
	Enabled bool `yaml:"enabled,omitempty"`

	// Endpoint is the path to expose metrics on.
	// Default: "/metrics"
	Endpoint string `yaml:"endpoint,omitempty"`

	// Namespace prefixes all metric names.
	// Default: "hector"
	Namespace string `yaml:"namespace,omitempty"`

	// Subsystem is added between namespace and metric name.
	// Example: With namespace="hector" and subsystem="agent":
	//          metric name becomes "hector_agent_calls_total"
	Subsystem string `yaml:"subsystem,omitempty"`

	// ConstLabels are labels added to all metrics.
	ConstLabels map[string]string `yaml:"const_labels,omitempty"`
}

MetricsConfig configures Prometheus metrics.

func (*MetricsConfig) SetDefaults 

func (c *MetricsConfig) SetDefaults()

SetDefaults applies default values to MetricsConfig.

func (*MetricsConfig) Validate 

func (c *MetricsConfig) Validate() error

Validate checks MetricsConfig for errors.

type NoopMetrics 

type NoopMetrics struct{}

NoopMetrics is a metrics implementation that does nothing.

func (NoopMetrics) DecAgentActiveRuns 

func (NoopMetrics) DecAgentActiveRuns(_ string)

func (NoopMetrics) Handler 

func (NoopMetrics) Handler() http.Handler

Handler returns a handler that returns 503 Service Unavailable.

func (NoopMetrics) IncAgentActiveRuns 

func (NoopMetrics) IncAgentActiveRuns(_ string)

func (NoopMetrics) RecordAgentCall 

func (NoopMetrics) RecordAgentCall(_, _ string, _ time.Duration)

Agent metrics - no-op

func (NoopMetrics) RecordAgentError 

func (NoopMetrics) RecordAgentError(_, _, _ string)

func (NoopMetrics) RecordHTTPRequest 

func (NoopMetrics) RecordHTTPRequest(_, _ string, _ int, _ time.Duration, _, _ int64)

HTTP metrics - no-op

func (NoopMetrics) RecordLLMCall 

func (NoopMetrics) RecordLLMCall(_, _ string, _ time.Duration)

LLM metrics - no-op

func (NoopMetrics) RecordLLMError 

func (NoopMetrics) RecordLLMError(_, _, _ string)

func (NoopMetrics) RecordLLMTokens 

func (NoopMetrics) RecordLLMTokens(_, _ string, _, _ int)

func (NoopMetrics) RecordMemoryIndexed 

func (NoopMetrics) RecordMemoryIndexed(_ string, _ int)

func (NoopMetrics) RecordMemorySearch 

func (NoopMetrics) RecordMemorySearch(_ string, _ time.Duration)

Memory metrics - no-op

func (NoopMetrics) RecordRAGDocError 

func (NoopMetrics) RecordRAGDocError(_ string)

func (NoopMetrics) RecordRAGDocIndexed 

func (NoopMetrics) RecordRAGDocIndexed(_ string, _ time.Duration)

RAG metrics - no-op

func (NoopMetrics) RecordRAGDocSkipped 

func (NoopMetrics) RecordRAGDocSkipped(_ string)

func (NoopMetrics) RecordRAGSearch 

func (NoopMetrics) RecordRAGSearch(_ string, _ time.Duration, _ int)

func (NoopMetrics) RecordSessionCreated 

func (NoopMetrics) RecordSessionCreated(_ string)

Session metrics - no-op

func (NoopMetrics) RecordSessionEvent 

func (NoopMetrics) RecordSessionEvent(_, _ string)

func (NoopMetrics) RecordToolCall 

func (NoopMetrics) RecordToolCall(_ string, _ time.Duration)

Tool metrics - no-op

func (NoopMetrics) RecordToolError 

func (NoopMetrics) RecordToolError(_, _ string)

func (NoopMetrics) SetSessionsActive 

func (NoopMetrics) SetSessionsActive(_ string, _ int)

type NoopTracer 

type NoopTracer struct{}

NoopTracer returns a no-operation Tracer.

func (NoopTracer) AddLLMFinishReason 

func (NoopTracer) AddLLMFinishReason(_ trace.Span, _ string)

AddLLMFinishReason is a no-op.

func (NoopTracer) AddLLMUsage 

func (NoopTracer) AddLLMUsage(_ trace.Span, _, _ int)

AddLLMUsage is a no-op.

func (NoopTracer) AddPayload 

func (NoopTracer) AddPayload(_ trace.Span, _, _ string)

AddPayload is a no-op.

func (NoopTracer) AddToolPayload 

func (NoopTracer) AddToolPayload(_ trace.Span, _, _ string)

AddToolPayload is a no-op.

func (NoopTracer) DebugExporter 

func (NoopTracer) DebugExporter() *DebugExporter

DebugExporter returns nil.

func (NoopTracer) RecordError 

func (NoopTracer) RecordError(_ trace.Span, _ error)

RecordError is a no-op.

func (NoopTracer) Shutdown 

func (NoopTracer) Shutdown(_ context.Context) error

Shutdown is a no-op.

func (NoopTracer) Start 

func (NoopTracer) Start(ctx context.Context, _ string, _ ...trace.SpanStartOption) (context.Context, trace.Span)

Start returns a no-op span.

func (NoopTracer) StartAgentRun 

func (NoopTracer) StartAgentRun(ctx context.Context, _, _, _, _, _ string) (context.Context, trace.Span)

StartAgentRun returns a no-op span.

func (NoopTracer) StartLLMCall 

func (NoopTracer) StartLLMCall(ctx context.Context, _ string, _ int, _, _ float64) (context.Context, trace.Span)

StartLLMCall returns a no-op span.

func (NoopTracer) StartMemorySearch 

func (NoopTracer) StartMemorySearch(ctx context.Context, _ string, _ int) (context.Context, trace.Span)

StartMemorySearch returns a no-op span.

func (NoopTracer) StartToolExecution 

func (NoopTracer) StartToolExecution(ctx context.Context, _, _, _ string) (context.Context, trace.Span)

StartToolExecution returns a no-op span.

type Recorder 

type Recorder interface {
	// Agent metrics
	RecordAgentCall(agentName, agentType string, duration time.Duration)
	RecordAgentError(agentName, agentType, errorType string)
	IncAgentActiveRuns(agentName string)
	DecAgentActiveRuns(agentName string)

	// LLM metrics
	RecordLLMCall(model, provider string, duration time.Duration)
	RecordLLMTokens(model, provider string, inputTokens, outputTokens int)
	RecordLLMError(model, provider, errorType string)

	// Tool metrics
	RecordToolCall(toolName string, duration time.Duration)
	RecordToolError(toolName, errorType string)

	// Memory metrics
	RecordMemorySearch(indexType string, duration time.Duration)
	RecordMemoryIndexed(indexType string, count int)

	// Session metrics
	RecordSessionCreated(appName string)
	SetSessionsActive(appName string, count int)
	RecordSessionEvent(appName, eventType string)

	// HTTP metrics
	RecordHTTPRequest(method, path string, statusCode int, duration time.Duration, reqSize, respSize int64)

	// RAG metrics
	RecordRAGDocIndexed(storeName string, duration time.Duration)
	RecordRAGDocSkipped(storeName string)
	RecordRAGDocError(storeName string)
	RecordRAGSearch(storeName string, duration time.Duration, resultCount int)
}

Recorder defines the interface for recording metrics. This allows for dependency injection and easier testing.

type SpanEvent 

type SpanEvent struct {
	Name       string            `json:"name"`
	TimeUnix   int64             `json:"time_unix_nano"`
	Attributes map[string]string `json:"attributes,omitempty"`
}

SpanEvent represents an event recorded on a span.

type Tracer 

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

Tracer wraps the OpenTelemetry tracer with Hector-specific helpers.

func NewTracer 

func NewTracer(ctx context.Context, cfg *TracingConfig, opts ...TracerOption) (*Tracer, error)

NewTracer creates a new Tracer from configuration.

func (*Tracer) AddLLMFinishReason 

func (t *Tracer) AddLLMFinishReason(span trace.Span, reason string)

AddLLMFinishReason adds the finish reason to a span.

func (*Tracer) AddLLMUsage 

func (t *Tracer) AddLLMUsage(span trace.Span, inputTokens, outputTokens int)

AddLLMUsage adds token usage information to a span.

func (*Tracer) AddPayload 

func (t *Tracer) AddPayload(span trace.Span, request, response string)

AddPayload adds serialized request/response to a span (if capture is enabled).

func (*Tracer) AddRAGIndexStats 

func (t *Tracer) AddRAGIndexStats(span trace.Span, chunkCount int)

AddRAGIndexStats adds indexing statistics to a span.

func (*Tracer) AddRAGSearchResults 

func (t *Tracer) AddRAGSearchResults(span trace.Span, resultCount int)

AddRAGSearchResults adds search result count to a span.

func (*Tracer) AddToolPayload 

func (t *Tracer) AddToolPayload(span trace.Span, args, response string)

AddToolPayload adds serialized tool args/response to a span (if capture is enabled).

func (*Tracer) DebugExporter 

func (t *Tracer) DebugExporter() *DebugExporter

DebugExporter returns the debug exporter if configured.

func (*Tracer) RecordError 

func (t *Tracer) RecordError(span trace.Span, err error)

RecordError records an error on a span.

func (*Tracer) Shutdown 

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

Shutdown gracefully shuts down the tracer.

func (*Tracer) Start 

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

Start begins a new span with the given name.

func (*Tracer) StartAgentRun 

func (t *Tracer) StartAgentRun(ctx context.Context, agentName, agentType, sessionID, userID, invocationID string) (context.Context, trace.Span)

StartAgentRun begins a span for an agent invocation.

func (*Tracer) StartLLMCall 

func (t *Tracer) StartLLMCall(ctx context.Context, model string, maxTokens int, temperature, topP float64) (context.Context, trace.Span)

StartLLMCall begins a span for an LLM API call.

func (*Tracer) StartMemorySearch 

func (t *Tracer) StartMemorySearch(ctx context.Context, query string, limit int) (context.Context, trace.Span)

StartMemorySearch begins a span for memory search operations.

func (*Tracer) StartRAGChunk 

func (t *Tracer) StartRAGChunk(ctx context.Context, strategy string, documentSize int) (context.Context, trace.Span)

StartRAGChunk begins a span for document chunking.

func (*Tracer) StartRAGEmbed 

func (t *Tracer) StartRAGEmbed(ctx context.Context, model string, textLength int) (context.Context, trace.Span)

StartRAGEmbed begins a span for embedding generation.

func (*Tracer) StartRAGHyDE 

func (t *Tracer) StartRAGHyDE(ctx context.Context, query string) (context.Context, trace.Span)

StartRAGHyDE begins a span for HyDE hypothetical document generation.

func (*Tracer) StartRAGIndex 

func (t *Tracer) StartRAGIndex(ctx context.Context, storeName, sourceType string, documentCount int) (context.Context, trace.Span)

StartRAGIndex begins a span for RAG indexing operations.

func (*Tracer) StartRAGRerank 

func (t *Tracer) StartRAGRerank(ctx context.Context, inputCount int) (context.Context, trace.Span)

StartRAGRerank begins a span for result reranking.

func (*Tracer) StartRAGSearch 

func (t *Tracer) StartRAGSearch(ctx context.Context, storeName, query string, topK int, hydeEnabled, rerankEnabled, multiQueryEnabled bool) (context.Context, trace.Span)

StartRAGSearch begins a span for RAG search operations.

func (*Tracer) StartToolExecution 

func (t *Tracer) StartToolExecution(ctx context.Context, toolName, toolDescription, callID string) (context.Context, trace.Span)

StartToolExecution begins a span for tool execution.

type TracerOption 

type TracerOption func(*Tracer)

TracerOption configures the Tracer.

func WithCapturePayloads 

func WithCapturePayloads(capture bool) TracerOption

WithCapturePayloads enables capturing full LLM request/response in spans.

func WithDebugExporter 

func WithDebugExporter(exporter *DebugExporter) TracerOption

WithDebugExporter adds a debug exporter for web UI inspection.

type TracingConfig 

type TracingConfig struct {
	// Enabled turns on distributed tracing.
	// Default: false
	Enabled bool `yaml:"enabled,omitempty"`

	// Exporter specifies the trace exporter type.
	// Values: "otlp" (default), "jaeger", "zipkin", "stdout"
	Exporter string `yaml:"exporter,omitempty"`

	// Endpoint is the collector endpoint.
	// For OTLP: "localhost:4317" (gRPC) or "localhost:4318" (HTTP)
	// For Jaeger: "http://localhost:14268/api/traces"
	// For Zipkin: "http://localhost:9411/api/pkg/spans"
	Endpoint string `yaml:"endpoint,omitempty"`

	// SamplingRate controls what fraction of traces are sampled.
	// Range: 0.0 (none) to 1.0 (all)
	// Default: 1.0
	SamplingRate float64 `yaml:"sampling_rate,omitempty"`

	// ServiceName identifies this service in traces.
	// Default: "hector"
	ServiceName string `yaml:"service_name,omitempty"`

	// ServiceVersion is the version of this service.
	ServiceVersion string `yaml:"service_version,omitempty"`

	// Insecure disables TLS for the exporter connection.
	// Default: true (for local development)
	Insecure *bool `yaml:"insecure,omitempty"`

	// Headers are additional headers to send with export requests.
	Headers map[string]string `yaml:"headers,omitempty"`

	// CapturePayloads enables capturing full LLM request/response in spans.
	// Warning: This can produce large spans. Use only for debugging.
	// Default: false
	CapturePayloads bool `yaml:"capture_payloads,omitempty"`

	// DebugExporter enables the in-memory span exporter for web UI.
	// Default: true (when tracing is enabled)
	DebugExporter *bool `yaml:"debug_exporter,omitempty"`

	// Timeout for exporter operations.
	// Default: 10s
	Timeout time.Duration `yaml:"timeout,omitempty"`
}

TracingConfig configures OpenTelemetry tracing.

func (*TracingConfig) IsDebugExporterEnabled 

func (c *TracingConfig) IsDebugExporterEnabled() bool

IsDebugExporterEnabled returns whether the debug exporter should be enabled.

func (*TracingConfig) IsInsecure 

func (c *TracingConfig) IsInsecure() bool

IsInsecure returns whether to use insecure connection.

func (*TracingConfig) SetDefaults 

func (c *TracingConfig) SetDefaults()

SetDefaults applies default values to TracingConfig.

func (*TracingConfig) Validate 

func (c *TracingConfig) Validate() error

Validate checks TracingConfig for errors.

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.