Documentation
¶
Overview ¶
Package telemetry provides observability infrastructure for the evaluation framework.
Overview ¶
The telemetry package implements the Three Pillars of Observability:
- Traces: Distributed tracing with OpenTelemetry
- Metrics: Prometheus-compatible metrics collection
- Logs: Structured logging with trace context
Architecture ¶
┌─────────────────────────────────────────────────────────────────────────────┐ │ TELEMETRY PACKAGE │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ Application Code │ │ │ │ │ ▼ │ │ ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ Sink Interface │ │ │ │ RecordBenchmark() │ RecordComparison() │ RecordError() │ Flush() │ │ │ └───────────────────────────────────────────────────────────────────────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌───────────┐ ┌───────────────┐ ┌───────────┐ │ │ │ Prometheus│ │ OpenTelemetry │ │ Composite│ │ │ │ Sink │ │ Sink │ │ Sink │ │ │ └─────┬─────┘ └───────┬───────┘ └─────┬─────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌───────────┐ ┌───────────────┐ ┌───────────┐ │ │ │ /metrics │ │ Jaeger │ │ Multi- │ │ │ │ endpoint │ │ Exporter │ │ Backend │ │ │ └───────────┘ └───────────────┘ └───────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────┘
Sink Interface ¶
The Sink interface is the primary abstraction for telemetry collection:
sink := telemetry.NewPrometheusSink(telemetry.PrometheusConfig{
Namespace: "trace",
Subsystem: "eval",
})
// Record benchmark results
sink.RecordBenchmark(ctx, result)
// Record comparison results
sink.RecordComparison(ctx, comparison)
Composite Sink ¶
Multiple sinks can be combined for multi-backend export:
composite := telemetry.NewCompositeSink(
promSink,
otelSink,
)
OpenTelemetry Integration ¶
The OTel sink provides distributed tracing and metric export:
otelSink, shutdown, err := telemetry.NewOTelSink(ctx, telemetry.OTelConfig{
ServiceName: "code-buddy-eval",
OTLPEndpoint: "localhost:4317",
MetricInterval: 15 * time.Second,
})
defer shutdown(ctx)
Thread Safety ¶
All Sink implementations are safe for concurrent use from multiple goroutines.
Metric Naming Convention ¶
Metrics follow the pattern: <namespace>_<subsystem>_<metric>_<unit>
Examples:
- trace_eval_benchmark_duration_seconds
- trace_eval_benchmark_iterations_total
- trace_eval_comparison_speedup_ratio
- trace_eval_errors_total
Index ¶
- Variables
- type BenchmarkData
- type ComparisonData
- type CompositeSink
- func (c *CompositeSink) Close() error
- func (c *CompositeSink) Flush(ctx context.Context) error
- func (c *CompositeSink) RecordBenchmark(ctx context.Context, data *BenchmarkData) error
- func (c *CompositeSink) RecordComparison(ctx context.Context, data *ComparisonData) error
- func (c *CompositeSink) RecordError(ctx context.Context, data *ErrorData) error
- type ErrorData
- type LatencyData
- type MemoryData
- type NoOpSink
- func (n *NoOpSink) Close() error
- func (n *NoOpSink) Flush(ctx context.Context) error
- func (n *NoOpSink) RecordBenchmark(ctx context.Context, data *BenchmarkData) error
- func (n *NoOpSink) RecordComparison(ctx context.Context, data *ComparisonData) error
- func (n *NoOpSink) RecordError(ctx context.Context, data *ErrorData) error
- type OTelConfig
- type OTelSink
- func (s *OTelSink) AddBenchmarkEvent(ctx context.Context, eventName string, attrs ...attribute.KeyValue)
- func (s *OTelSink) Close() error
- func (s *OTelSink) Flush(ctx context.Context) error
- func (s *OTelSink) RecordBenchmark(ctx context.Context, data *BenchmarkData) error
- func (s *OTelSink) RecordComparison(ctx context.Context, data *ComparisonData) error
- func (s *OTelSink) RecordError(ctx context.Context, data *ErrorData) error
- func (s *OTelSink) StartBenchmarkSpan(ctx context.Context, name string) (context.Context, trace.Span)
- type PrometheusConfig
- type PrometheusSink
- func (s *PrometheusSink) Close() error
- func (s *PrometheusSink) Flush(ctx context.Context) error
- func (s *PrometheusSink) RecordBenchmark(ctx context.Context, data *BenchmarkData) error
- func (s *PrometheusSink) RecordComparison(ctx context.Context, data *ComparisonData) error
- func (s *PrometheusSink) RecordError(ctx context.Context, data *ErrorData) error
- type Sink
- type ThroughputData
Constants ¶
This section is empty.
Variables ¶
View Source
var ( // ErrOTelInitFailed is returned when OpenTelemetry initialization fails. ErrOTelInitFailed = errors.New("opentelemetry initialization failed") // ErrInvalidOTelConfig is returned when the OTel configuration is invalid. ErrInvalidOTelConfig = errors.New("invalid opentelemetry configuration") )
View Source
var ( // ErrInvalidConfig is returned when the Prometheus configuration is invalid. ErrInvalidConfig = errors.New("invalid prometheus configuration") // ErrRegistrationFailed is returned when metric registration fails. ErrRegistrationFailed = errors.New("metric registration failed") )
View Source
var ( // ErrNilContext is returned when a nil context is provided. ErrNilContext = errors.New("context must not be nil") // ErrNilData is returned when nil data is provided to a recording method. ErrNilData = errors.New("data must not be nil") // ErrSinkClosed is returned when attempting to use a closed sink. ErrSinkClosed = errors.New("sink has been closed") // ErrNoSinks is returned when creating a composite sink with no children. ErrNoSinks = errors.New("at least one sink is required") // ErrFlushTimeout is returned when flush exceeds the timeout. ErrFlushTimeout = errors.New("flush operation timed out") )
Functions ¶
This section is empty.
Types ¶
type BenchmarkData ¶
type BenchmarkData struct {
// Name is the benchmark/component identifier.
Name string
// Timestamp is when the benchmark was recorded.
Timestamp time.Time
// Duration is the total benchmark duration.
Duration time.Duration
// Iterations is the number of iterations executed.
Iterations int
// Latency contains latency statistics.
Latency LatencyData
// Throughput contains throughput metrics.
Throughput ThroughputData
// Memory contains memory statistics (optional).
Memory *MemoryData
// Labels are additional key-value pairs for filtering.
Labels map[string]string
// ErrorCount is the number of errors during the benchmark.
ErrorCount int
// ErrorRate is the proportion of iterations that failed (0.0-1.0).
ErrorRate float64
}
BenchmarkData contains data for a benchmark result recording.
Description:
BenchmarkData captures all metrics from a single benchmark run, including latency statistics, throughput, memory usage, and metadata.
Thread Safety: Immutable after creation; safe for concurrent read access.
type ComparisonData ¶
type ComparisonData struct {
// Timestamp is when the comparison was recorded.
Timestamp time.Time
// Components lists the compared component names.
Components []string
// Winner is the name of the best-performing component (empty if no winner).
Winner string
// Speedup is the performance ratio (winner vs runner-up).
Speedup float64
// Significant indicates if the difference is statistically significant.
Significant bool
// PValue is the statistical p-value.
PValue float64
// ConfidenceLevel is the confidence level used (e.g., 0.95).
ConfidenceLevel float64
// EffectSize is Cohen's d effect size.
EffectSize float64
// EffectSizeCategory is the effect size interpretation.
EffectSizeCategory string
// Labels are additional key-value pairs for filtering.
Labels map[string]string
}
ComparisonData contains data for a benchmark comparison recording.
Description:
ComparisonData captures the results of comparing two or more benchmark runs, including statistical analysis.
Thread Safety: Immutable after creation; safe for concurrent read access.
type CompositeSink ¶
type CompositeSink struct {
// contains filtered or unexported fields
}
CompositeSink multiplexes telemetry to multiple sinks.
Description:
CompositeSink allows sending telemetry data to multiple backends simultaneously (e.g., Prometheus and OpenTelemetry).
Thread Safety: Safe for concurrent use.
Example:
composite := telemetry.NewCompositeSink(promSink, otelSink) defer composite.Close() // Records to both Prometheus and OpenTelemetry composite.RecordBenchmark(ctx, data)
func NewCompositeSink ¶
func NewCompositeSink(sinks ...Sink) (*CompositeSink, error)
NewCompositeSink creates a new composite sink.
Description:
Creates a sink that forwards all telemetry to multiple child sinks. Errors from individual sinks are collected and returned as a combined error.
Inputs:
- sinks: Child sinks to forward to. At least one required.
Outputs:
- *CompositeSink: The created composite sink. Never nil on success.
- error: ErrNoSinks if no sinks provided.
Thread Safety: The returned sink is safe for concurrent use.
Example:
composite, err := telemetry.NewCompositeSink(promSink, otelSink)
if err != nil {
return fmt.Errorf("create composite sink: %w", err)
}
Limitations:
- All child sinks receive all data; no filtering per sink.
- Errors from multiple sinks are joined; individual failures don't stop others.
Assumptions:
- Child sinks are properly initialized.
- Child sinks remain valid for the lifetime of the composite.
func (*CompositeSink) Close ¶
func (c *CompositeSink) Close() error
Close closes all child sinks.
Description:
Closes all child sinks and releases resources. Idempotent.
Outputs:
- error: Combined errors from child sinks, or nil if all succeed.
Thread Safety: Safe for concurrent use. Idempotent.
func (*CompositeSink) Flush ¶
func (c *CompositeSink) Flush(ctx context.Context) error
Flush flushes all child sinks.
Description:
Flushes all child sinks concurrently. Waits for all to complete or context cancellation.
Inputs:
- ctx: Context for cancellation and timeout. Must not be nil.
Outputs:
- error: Combined errors from child sinks, or nil if all succeed.
Thread Safety: Safe for concurrent use.
func (*CompositeSink) RecordBenchmark ¶
func (c *CompositeSink) RecordBenchmark(ctx context.Context, data *BenchmarkData) error
RecordBenchmark records a benchmark result to all child sinks.
Description:
Forwards the benchmark data to all child sinks. Errors from individual sinks are collected and returned as a combined error; one sink's failure does not prevent others from receiving the data.
Inputs:
- ctx: Context for cancellation. Must not be nil.
- data: Benchmark data to record. Must not be nil.
Outputs:
- error: Combined errors from child sinks, or nil if all succeed.
Thread Safety: Safe for concurrent use.
func (*CompositeSink) RecordComparison ¶
func (c *CompositeSink) RecordComparison(ctx context.Context, data *ComparisonData) error
RecordComparison records a comparison result to all child sinks.
Description:
Forwards the comparison data to all child sinks. Errors from individual sinks are collected and returned as a combined error.
Inputs:
- ctx: Context for cancellation. Must not be nil.
- data: Comparison data to record. Must not be nil.
Outputs:
- error: Combined errors from child sinks, or nil if all succeed.
Thread Safety: Safe for concurrent use.
func (*CompositeSink) RecordError ¶
func (c *CompositeSink) RecordError(ctx context.Context, data *ErrorData) error
RecordError records an error to all child sinks.
Description:
Forwards the error data to all child sinks. Errors from individual sinks are collected and returned as a combined error.
Inputs:
- ctx: Context for cancellation. Must not be nil.
- data: Error data to record. Must not be nil.
Outputs:
- error: Combined errors from child sinks, or nil if all succeed.
Thread Safety: Safe for concurrent use.
type ErrorData ¶
type ErrorData struct {
// Timestamp is when the error occurred.
Timestamp time.Time
// Component is the component that produced the error.
Component string
// Operation is the operation that failed.
Operation string
// ErrorType categorizes the error (e.g., "timeout", "validation", "internal").
ErrorType string
// Message is the error message (should not contain PII).
Message string
// Labels are additional key-value pairs for filtering.
Labels map[string]string
}
ErrorData contains data for an error recording.
Description:
ErrorData captures error events for alerting and debugging.
Thread Safety: Immutable after creation; safe for concurrent read access.
type LatencyData ¶
type LatencyData struct {
// Min is the minimum observed latency.
Min time.Duration
// Max is the maximum observed latency.
Max time.Duration
// Mean is the arithmetic mean latency.
Mean time.Duration
// Median is the 50th percentile latency.
Median time.Duration
// StdDev is the standard deviation.
StdDev time.Duration
// P50 is the 50th percentile.
P50 time.Duration
// P90 is the 90th percentile.
P90 time.Duration
// P95 is the 95th percentile.
P95 time.Duration
// P99 is the 99th percentile.
P99 time.Duration
// P999 is the 99.9th percentile.
P999 time.Duration
}
LatencyData contains latency statistics.
Description:
LatencyData captures the full distribution of latency measurements including min, max, mean, standard deviation, and percentiles.
Thread Safety: Immutable after creation; safe for concurrent read access.
type MemoryData ¶
type MemoryData struct {
// HeapAllocBefore is heap allocation before the benchmark.
HeapAllocBefore uint64
// HeapAllocAfter is heap allocation after the benchmark.
HeapAllocAfter uint64
// HeapAllocDelta is the change in heap allocation.
HeapAllocDelta int64
// GCPauses is the number of GC pauses during the benchmark.
GCPauses uint32
// GCPauseTotal is the total time spent in GC pauses.
GCPauseTotal time.Duration
}
MemoryData contains memory statistics.
Description:
MemoryData captures heap allocation and GC metrics.
Thread Safety: Immutable after creation; safe for concurrent read access.
type NoOpSink ¶
type NoOpSink struct{}
NoOpSink is a sink that discards all data.
Description:
NoOpSink is useful for testing and as a default when no telemetry is configured.
Thread Safety: Safe for concurrent use.
func NewNoOpSink ¶
func NewNoOpSink() *NoOpSink
NewNoOpSink creates a new no-op sink.
Description:
Creates a sink that accepts but discards all telemetry data.
Outputs:
- *NoOpSink: The created sink. Never nil.
Thread Safety: The returned sink is safe for concurrent use.
func (*NoOpSink) RecordBenchmark ¶
func (n *NoOpSink) RecordBenchmark(ctx context.Context, data *BenchmarkData) error
RecordBenchmark discards the benchmark data.
Thread Safety: Safe for concurrent use.
func (*NoOpSink) RecordComparison ¶
func (n *NoOpSink) RecordComparison(ctx context.Context, data *ComparisonData) error
RecordComparison discards the comparison data.
Thread Safety: Safe for concurrent use.
type OTelConfig ¶
type OTelConfig struct {
// ServiceName is the service name for telemetry.
// Required.
ServiceName string
// ServiceVersion is the service version for telemetry.
// Optional.
ServiceVersion string
// TracerProvider is the tracer provider to use.
// If nil, uses the global tracer provider.
TracerProvider trace.TracerProvider
// MeterProvider is the meter provider to use.
// If nil, uses the global meter provider.
MeterProvider metric.MeterProvider
// TraceEnabled enables trace span creation.
// Default: true.
TraceEnabled bool
// MetricsEnabled enables metric recording.
// Default: true.
MetricsEnabled bool
}
OTelConfig configures the OpenTelemetry sink.
Description:
OTelConfig specifies service name, instrumentation scope, and optional providers for tracing and metrics.
Thread Safety: Immutable after creation; safe for concurrent read access.
func DefaultOTelConfig ¶
func DefaultOTelConfig() *OTelConfig
DefaultOTelConfig returns a configuration with sensible defaults.
Description:
Returns an OTelConfig with default service name and both tracing and metrics enabled.
Outputs:
- *OTelConfig: Configuration with defaults applied.
Thread Safety: Stateless function; safe for concurrent use.
Example:
config := telemetry.DefaultOTelConfig() config.ServiceName = "my-service" sink, err := telemetry.NewOTelSink(config)
func (*OTelConfig) Validate ¶
func (c *OTelConfig) Validate() error
Validate checks that the configuration is valid.
Description:
Validates that required fields are set.
Outputs:
- error: Non-nil if configuration is invalid.
Thread Safety: Safe for concurrent use.
type OTelSink ¶
type OTelSink struct {
// contains filtered or unexported fields
}
OTelSink exports telemetry via OpenTelemetry.
Description:
OTelSink creates trace spans for operations and records metrics using the OpenTelemetry SDK. It integrates with the standard OTel providers for flexible backend configuration.
Thread Safety: Safe for concurrent use.
Example:
config := telemetry.DefaultOTelConfig()
config.ServiceName = "code-buddy-eval"
sink, err := telemetry.NewOTelSink(config)
if err != nil {
return fmt.Errorf("create otel sink: %w", err)
}
defer sink.Close()
sink.RecordBenchmark(ctx, data)
func NewOTelSink ¶
func NewOTelSink(config *OTelConfig) (*OTelSink, error)
NewOTelSink creates a new OpenTelemetry telemetry sink.
Description:
Creates a sink that exports telemetry via OpenTelemetry traces and metrics. Uses global providers if not specified in config.
Inputs:
- config: OpenTelemetry configuration. Must not be nil.
Outputs:
- *OTelSink: The created sink. Never nil on success.
- error: Non-nil if configuration is invalid or initialization fails.
Thread Safety: The returned sink is safe for concurrent use.
Example:
config := telemetry.DefaultOTelConfig()
config.ServiceName = "my-service"
sink, err := telemetry.NewOTelSink(config)
if err != nil {
return fmt.Errorf("create sink: %w", err)
}
Limitations:
- Requires OpenTelemetry providers to be configured for actual export.
- Without providers, telemetry is discarded (no-op).
Assumptions:
- TracerProvider and MeterProvider are properly initialized.
- Caller is responsible for shutting down providers.
func (*OTelSink) AddBenchmarkEvent ¶
func (s *OTelSink) AddBenchmarkEvent(ctx context.Context, eventName string, attrs ...attribute.KeyValue)
AddBenchmarkEvent adds an event to the current span.
Description:
Adds a timestamped event to the span in the context with the given name and attributes.
Inputs:
- ctx: Context containing the span.
- eventName: Name of the event.
- attrs: Event attributes.
Thread Safety: Safe for concurrent use.
func (*OTelSink) Close ¶
Close releases resources.
Description:
Marks the sink as closed. Does not shut down the providers as they may be shared and should be managed by the caller.
Outputs:
- error: Always nil.
Thread Safety: Safe for concurrent use. Idempotent.
func (*OTelSink) Flush ¶
Flush forces export of any buffered telemetry.
Description:
For OTel sink, this is a no-op as the SDK handles batching and export. The actual flush happens via the providers' ForceFlush methods.
Inputs:
- ctx: Context for cancellation. Must not be nil.
Outputs:
- error: Non-nil if sink is closed or context is nil.
Thread Safety: Safe for concurrent use.
func (*OTelSink) RecordBenchmark ¶
func (s *OTelSink) RecordBenchmark(ctx context.Context, data *BenchmarkData) error
RecordBenchmark records benchmark telemetry.
Description:
Creates a trace span for the benchmark operation and records metrics for duration, iterations, latency, throughput, and errors.
Inputs:
- ctx: Context for tracing. Must not be nil.
- data: Benchmark data to record. Must not be nil.
Outputs:
- error: Non-nil if sink is closed or inputs are invalid.
Thread Safety: Safe for concurrent use.
func (*OTelSink) RecordComparison ¶
func (s *OTelSink) RecordComparison(ctx context.Context, data *ComparisonData) error
RecordComparison records comparison telemetry.
Description:
Creates a trace span for the comparison operation and records metrics for speedup and statistical significance.
Inputs:
- ctx: Context for tracing. Must not be nil.
- data: Comparison data to record. Must not be nil.
Outputs:
- error: Non-nil if sink is closed or inputs are invalid.
Thread Safety: Safe for concurrent use.
func (*OTelSink) RecordError ¶
RecordError records error telemetry.
Description:
Creates a trace span for the error event and increments the error counter metric.
Inputs:
- ctx: Context for tracing. Must not be nil.
- data: Error data to record. Must not be nil.
Outputs:
- error: Non-nil if sink is closed or inputs are invalid.
Thread Safety: Safe for concurrent use.
func (*OTelSink) StartBenchmarkSpan ¶
func (s *OTelSink) StartBenchmarkSpan(ctx context.Context, name string) (context.Context, trace.Span)
StartBenchmarkSpan creates a trace span for a benchmark operation.
Description:
Creates a new span with benchmark attributes. The returned span must be ended by the caller.
Inputs:
- ctx: Context for tracing. Must not be nil.
- name: Benchmark name.
Outputs:
- context.Context: Context with the span.
- trace.Span: The created span. Must be ended by caller.
Thread Safety: Safe for concurrent use.
Example:
ctx, span := sink.StartBenchmarkSpan(ctx, "my_benchmark")
defer span.End()
// ... run benchmark ...
span.SetAttributes(attribute.Int("iterations", 1000))
type PrometheusConfig ¶
type PrometheusConfig struct {
// Namespace is the metrics namespace (e.g., "trace").
// Required.
Namespace string
// Subsystem is the metrics subsystem (e.g., "eval").
// Required.
Subsystem string
// Registry is the Prometheus registry to use.
// If nil, uses prometheus.DefaultRegisterer.
Registry prometheus.Registerer
// LatencyBuckets defines histogram buckets for latency metrics (seconds).
// If nil, uses default buckets.
LatencyBuckets []float64
// ThroughputBuckets defines histogram buckets for throughput metrics (ops/sec).
// If nil, uses default buckets.
ThroughputBuckets []float64
// MemoryBuckets defines histogram buckets for memory metrics (bytes).
// If nil, uses default buckets.
MemoryBuckets []float64
// MaxLabelCardinality is the maximum number of unique label values to track.
// When exceeded, new label values are mapped to "_other".
// Default: 1000
MaxLabelCardinality int
}
PrometheusConfig configures the Prometheus sink.
Description:
PrometheusConfig specifies namespace, subsystem, and bucket configuration for Prometheus metrics.
Thread Safety: Immutable after creation; safe for concurrent read access.
func DefaultPrometheusConfig ¶
func DefaultPrometheusConfig() *PrometheusConfig
DefaultPrometheusConfig returns a configuration with sensible defaults.
Description:
Returns a PrometheusConfig with default namespace, subsystem, and buckets.
Outputs:
- *PrometheusConfig: Configuration with defaults applied.
Thread Safety: Stateless function; safe for concurrent use.
Example:
config := telemetry.DefaultPrometheusConfig() config.Namespace = "my_service" sink, err := telemetry.NewPrometheusSink(config)
func (*PrometheusConfig) Validate ¶
func (c *PrometheusConfig) Validate() error
Validate checks that the configuration is valid.
Description:
Validates that required fields are set and bucket arrays are non-empty.
Outputs:
- error: Non-nil if configuration is invalid.
Thread Safety: Safe for concurrent use.
type PrometheusSink ¶
type PrometheusSink struct {
// contains filtered or unexported fields
}
PrometheusSink exports telemetry as Prometheus metrics.
Description:
PrometheusSink collects benchmark, comparison, and error telemetry and exposes them as Prometheus metrics. Metrics are registered on creation and deregistered on Close().
Thread Safety: Safe for concurrent use.
Example:
sink, err := telemetry.NewPrometheusSink(telemetry.DefaultPrometheusConfig())
if err != nil {
return fmt.Errorf("create prometheus sink: %w", err)
}
defer sink.Close()
sink.RecordBenchmark(ctx, data)
func NewPrometheusSink ¶
func NewPrometheusSink(config *PrometheusConfig) (*PrometheusSink, error)
NewPrometheusSink creates a new Prometheus telemetry sink.
Description:
Creates a sink that exports telemetry as Prometheus metrics. Registers all metrics collectors on creation.
Inputs:
- config: Prometheus configuration. Must not be nil.
Outputs:
- *PrometheusSink: The created sink. Never nil on success.
- error: Non-nil if configuration is invalid or registration fails.
Thread Safety: The returned sink is safe for concurrent use.
Example:
config := telemetry.DefaultPrometheusConfig()
config.Namespace = "my_service"
sink, err := telemetry.NewPrometheusSink(config)
if err != nil {
return fmt.Errorf("create sink: %w", err)
}
Limitations:
- Metric names cannot be changed after creation.
- Uses global default registry if none specified.
Assumptions:
- Registry allows duplicate registration (or collector not previously registered).
- Labels do not contain high-cardinality values.
func (*PrometheusSink) Close ¶
func (s *PrometheusSink) Close() error
Close unregisters all metrics and releases resources.
Description:
Unregisters all Prometheus collectors from the registry. After Close(), all recording methods return ErrSinkClosed.
Outputs:
- error: Non-nil if unregistration fails.
Thread Safety: Safe for concurrent use. Idempotent.
func (*PrometheusSink) Flush ¶
func (s *PrometheusSink) Flush(ctx context.Context) error
Flush is a no-op for Prometheus sink.
Description:
Prometheus metrics are available immediately via scraping. This method exists for interface compliance.
Inputs:
- ctx: Context for cancellation. Must not be nil.
Outputs:
- error: Non-nil if sink is closed or context is nil.
Thread Safety: Safe for concurrent use.
func (*PrometheusSink) RecordBenchmark ¶
func (s *PrometheusSink) RecordBenchmark(ctx context.Context, data *BenchmarkData) error
RecordBenchmark records benchmark metrics.
Description:
Records duration, iterations, latency percentiles, throughput, memory allocation, GC pauses, and error counts from a benchmark run.
Inputs:
- ctx: Context for cancellation. Must not be nil.
- data: Benchmark data to record. Must not be nil.
Outputs:
- error: Non-nil if sink is closed or inputs are invalid.
Thread Safety: Safe for concurrent use.
func (*PrometheusSink) RecordComparison ¶
func (s *PrometheusSink) RecordComparison(ctx context.Context, data *ComparisonData) error
RecordComparison records comparison metrics.
Description:
Records speedup ratio, p-value, effect size, and comparison count.
Inputs:
- ctx: Context for cancellation. Must not be nil.
- data: Comparison data to record. Must not be nil.
Outputs:
- error: Non-nil if sink is closed or inputs are invalid.
Thread Safety: Safe for concurrent use.
func (*PrometheusSink) RecordError ¶
func (s *PrometheusSink) RecordError(ctx context.Context, data *ErrorData) error
RecordError records error metrics.
Description:
Increments the error counter with component, operation, and error type labels.
Inputs:
- ctx: Context for cancellation. Must not be nil.
- data: Error data to record. Must not be nil.
Outputs:
- error: Non-nil if sink is closed or inputs are invalid.
Thread Safety: Safe for concurrent use.
type Sink ¶
type Sink interface {
// RecordBenchmark records a single benchmark result.
//
// Description:
// Records latency, throughput, memory, and error metrics from a benchmark run.
//
// Inputs:
// - ctx: Context for cancellation. Must not be nil.
// - data: Benchmark data to record. Must not be nil.
//
// Outputs:
// - error: Non-nil if recording fails or sink is closed.
//
// Thread Safety: Safe for concurrent use.
RecordBenchmark(ctx context.Context, data *BenchmarkData) error
// RecordComparison records a benchmark comparison result.
//
// Description:
// Records comparison metrics including speedup, statistical significance,
// and effect size.
//
// Inputs:
// - ctx: Context for cancellation. Must not be nil.
// - data: Comparison data to record. Must not be nil.
//
// Outputs:
// - error: Non-nil if recording fails or sink is closed.
//
// Thread Safety: Safe for concurrent use.
RecordComparison(ctx context.Context, data *ComparisonData) error
// RecordError records an error event.
//
// Description:
// Records error occurrences for alerting and debugging.
//
// Inputs:
// - ctx: Context for cancellation. Must not be nil.
// - data: Error data to record. Must not be nil.
//
// Outputs:
// - error: Non-nil if recording fails or sink is closed.
//
// Thread Safety: Safe for concurrent use.
RecordError(ctx context.Context, data *ErrorData) error
// Flush ensures all buffered data is exported.
//
// Description:
// Forces export of any buffered telemetry data. Called automatically
// on Close(), but can be called explicitly for immediate export.
//
// Inputs:
// - ctx: Context for cancellation and timeout. Must not be nil.
//
// Outputs:
// - error: Non-nil if flush fails or times out.
//
// Thread Safety: Safe for concurrent use.
Flush(ctx context.Context) error
// Close releases resources and flushes pending data.
//
// Description:
// Gracefully shuts down the sink, flushing any buffered data.
// After Close(), all recording methods return ErrSinkClosed.
//
// Outputs:
// - error: Non-nil if shutdown fails.
//
// Thread Safety: Safe for concurrent use. Idempotent.
Close() error
}
Sink defines the interface for telemetry data collection.
Description:
Sink is the primary abstraction for recording evaluation telemetry. Implementations handle the specific export format (Prometheus, OTel, etc.).
Thread Safety: All implementations must be safe for concurrent use.
Example:
sink := telemetry.NewPrometheusSink(config)
defer sink.Close()
if err := sink.RecordBenchmark(ctx, result); err != nil {
log.Printf("telemetry error: %v", err)
}
type ThroughputData ¶
type ThroughputData struct {
// OpsPerSecond is the operations per second.
OpsPerSecond float64
}
ThroughputData contains throughput metrics.
Description:
ThroughputData captures the rate of operations.
Thread Safety: Immutable after creation; safe for concurrent read access.
Source Files
Click to show internal directories.
Click to hide internal directories.