telemetry

Documentation

Overview

Package telemetry provides OpenTelemetry-compatible telemetry export for covo-agent. It bridges the existing audit log to OTLP-compatible traces and metrics, allowing users to monitor token usage, tool call latency, and agent performance in standard observability platforms (Jaeger, Grafana, Datadog, etc.).

Configuration via environment variables:

COVO_OTEL_ENDPOINT=https://otel-collector.example.com:4318
COVO_OTEL_SERVICE_NAME=covo-agent
COVO_OTEL_ENABLED=true
COVO_OTEL_EXPORT_INTERVAL=30s

Index

• func AgentTracer() agentcore.Tracer
• func FlushOtel(ctx context.Context)
• func InitOtel(ctx context.Context, logger *slog.Logger) *otelHandle
• func ShutdownOtel(ctx context.Context)
• func StartEvent(ctx context.Context, component, name string, attrs ...agentcore.SpanAttribute) (context.Context, agentcore.Span)
• type Config
  • func ConfigFromEnv() Config
• type Exporter
  • func New(cfg Config, store *audit.Store) *Exporter
  • func (e *Exporter) ExportNow(ctx context.Context) error
  • func (e *Exporter) SetLogger(l *slog.Logger)
  • func (e *Exporter) SetRedactor(redact func(string) string)
  • func (e *Exporter) Start(ctx context.Context)
  • func (e *Exporter) Stop()
• type ModelMetricsRecorder
  • func MetricsRecorder() *ModelMetricsRecorder
  • func (r *ModelMetricsRecorder) RecordCost(ctx context.Context, model string, amountUSD float64, status, source string)
  • func (r *ModelMetricsRecorder) RecordError(ctx context.Context, component string, _ error)
  • func (r *ModelMetricsRecorder) RecordModelCall(ctx context.Context, req *agentcore.ProviderRequest, ...)

Functions

func AgentTracer

func AgentTracer() agentcore.Tracer

AgentTracer returns the agentcore.Tracer adapter backed by the process-wide OpenTelemetry pipeline, or nil when tracing is disabled or not initialized. Callers pass the result to agentcore Config.Tracer; nil is safe (noop).

func FlushOtel

func FlushOtel(ctx context.Context)

FlushOtel force-flushes buffered spans and metrics without shutting the pipelines down. Safe to call multiple times; no-op when disabled. Use this in long-lived processes (background tasks, cron jobs) where ShutdownOtel would tear down the pipelines for the rest of the process.

func InitOtel

func InitOtel(ctx context.Context, logger *slog.Logger) *otelHandle

InitOtel initializes the OpenTelemetry SDK from environment configuration (see ConfigFromEnv). Idempotent: subsequent calls return the existing handle. The returned handle is always non-nil; call Shutdown on it to flush buffered spans/metrics and release resources.

func ShutdownOtel

func ShutdownOtel(ctx context.Context)

ShutdownOtel flushes and shuts down the process-wide OpenTelemetry pipelines. Safe to call multiple times; no-op when telemetry was never initialized.

func StartEvent

func StartEvent(ctx context.Context, component, name string, attrs ...agentcore.SpanAttribute) (context.Context, agentcore.Span)

StartEvent opens a named component span for a business event (guardrail decisions, compaction retries, approvals). The span is a child of any span already carried in ctx and becomes a root span otherwise. Returns a no-op span when tracing is disabled, so callers can safely End() it.

Types

type Config

type Config struct {
	Enabled        bool
	Endpoint       string            // OTLP HTTP endpoint, e.g. "http://localhost:4318"
	ServiceName    string            // service.name attribute
	ExportInterval time.Duration     // how often to flush
	Headers        map[string]string // extra HTTP headers, e.g. Authorization for Langfuse

	// Metrics controls OTLP metrics export (gen_ai.* counters/histograms).
	// Metrics are opt-in via COVO_OTEL_METRICS_ENABLED and sent to
	// COVO_OTEL_METRICS_ENDPOINT (falling back to Endpoint). Langfuse only
	// ingests traces, so leave metrics disabled when targeting it directly.
	MetricsEnabled  bool
	MetricsEndpoint string
}

Config holds the telemetry exporter configuration.

func ConfigFromEnv

func ConfigFromEnv() Config

ConfigFromEnv reads telemetry config from environment variables.

type Exporter

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

Exporter bridges audit log entries to OpenTelemetry-compatible export.

func New

func New(cfg Config, store *audit.Store) *Exporter

New creates a telemetry exporter. If the config is disabled, the exporter is a no-op.

func (*Exporter) ExportNow

func (e *Exporter) ExportNow(ctx context.Context) error

ExportNow triggers an immediate export of buffered telemetry data.

func (*Exporter) SetLogger

func (e *Exporter) SetLogger(l *slog.Logger)

SetLogger sets the logger for exporter diagnostics.

func (*Exporter) SetRedactor

func (e *Exporter) SetRedactor(redact func(string) string)

SetRedactor configures mandatory sanitization before audit data is exported.

func (*Exporter) Start

func (e *Exporter) Start(ctx context.Context)

Start begins periodic export of telemetry data. Call Stop() to clean up.

func (*Exporter) Stop

func (e *Exporter) Stop()

Stop gracefully stops the exporter and flushes remaining data.

type ModelMetricsRecorder

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

ModelMetricsRecorder records per-call model metrics using OTel GenAI semantic conventions, plus cost, error, and process-level gauges. Instruments are created once against the process-wide meter, so the recorder is safe for concurrent use.

func MetricsRecorder

func MetricsRecorder() *ModelMetricsRecorder

MetricsRecorder returns the process-wide model metrics recorder, or nil when metrics are disabled. The recorder is safe for concurrent use.

func (*ModelMetricsRecorder) RecordCost

func (r *ModelMetricsRecorder) RecordCost(ctx context.Context, model string, amountUSD float64, status, source string)

RecordCost records the USD cost of a completed LLM call. status and source describe how the cost was derived (e.g. "actual"/"official_docs/0.1").

func (*ModelMetricsRecorder) RecordError

func (r *ModelMetricsRecorder) RecordError(ctx context.Context, component string, _ error)

RecordError counts a failed operation (model call, tool execution, agent run) by component, mirroring the trace span component attribute. It satisfies agentcore.Metrics so the recorder can back the library's metrics middleware. err is recorded for interface compatibility; only the component dimension is counted.

func (*ModelMetricsRecorder) RecordModelCall

func (r *ModelMetricsRecorder) RecordModelCall(ctx context.Context, req *agentcore.ProviderRequest, usage *agentcore.TokenUsage, start time.Time)

RecordModelCall records token usage and duration for a completed LLM call. usage may be nil for calls that did not report usage.