Documentation
¶
Overview ¶
Package telemetry provides Prometheus and OpenTelemetry (OTel) metrics export for Relayer's supervised agent sessions, policy decisions, and guardrails.
Index ¶
- Constants
- Variables
- func BuildOTLPPayload(snap Snapshot, serviceName, environment string) ([]byte, error)
- func RenderPrometheus(snap Snapshot) []byte
- func Validate(cfg Config) error
- type Config
- type Engine
- type HistogramSample
- type MetricSample
- type OTLPConfig
- type OTLPExporter
- type PrometheusConfig
- type PrometheusServer
- type Registry
- type Snapshot
Constants ¶
const ( DefaultServiceName = "relayer" DefaultEnvironment = "production" DefaultPrometheusAddr = ":9090" DefaultPrometheusPath = "/metrics" DefaultExportInterval = 15 * time.Second DefaultExportTimeout = 5 * time.Second )
Variables ¶
var DefaultHistogramBuckets = []float64{0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0, 30.0, 60.0, 120.0, 300.0}
DefaultHistogramBuckets defines latency duration buckets in seconds.
Functions ¶
func BuildOTLPPayload ¶
BuildOTLPPayload constructs an OpenTelemetry Protocol (OTLP/HTTP JSON v1) metric payload.
func RenderPrometheus ¶
RenderPrometheus formats a Registry Snapshot into standard Prometheus text format (v0.0.4).
Types ¶
type Config ¶
type Config struct {
Enabled bool `json:"enabled" yaml:"enabled"`
ServiceName string `json:"service_name" yaml:"service_name"`
Environment string `json:"environment" yaml:"environment"`
Prometheus PrometheusConfig `json:"prometheus" yaml:"prometheus"`
OTLP OTLPConfig `json:"otlp" yaml:"otlp"`
}
Config controls Prometheus metrics serving and OTLP telemetry export.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns safe, production-grade telemetry settings (disabled by default).
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine is the central telemetry coordinator managing the metric registry, Prometheus HTTP server and the OTLP exporter worker.
func (*Engine) PrometheusAddress ¶
PrometheusAddress returns the listening address if Prometheus is enabled and started.
type HistogramSample ¶
type HistogramSample struct {
Labels map[string]string `json:"labels"`
Count uint64 `json:"count"`
Sum float64 `json:"sum"`
Buckets map[float64]uint64 `json:"buckets"`
}
HistogramSample represents the aggregated state of a histogram series.
type MetricSample ¶
MetricSample represents a single metric observation with key-value labels.
type OTLPConfig ¶
type OTLPConfig struct {
Enabled bool `json:"enabled" yaml:"enabled"`
Endpoint string `json:"endpoint" yaml:"endpoint"`
Headers map[string]string `json:"headers,omitempty" yaml:"headers,omitempty"`
ExportInterval time.Duration `json:"export_interval" yaml:"export_interval"`
Timeout time.Duration `json:"timeout" yaml:"timeout"`
}
OTLPConfig controls periodic pushing to an OpenTelemetry collector.
type OTLPExporter ¶
type OTLPExporter struct {
// contains filtered or unexported fields
}
OTLPExporter periodically exports metrics to an OTLP/HTTP collector.
func NewOTLPExporter ¶
func NewOTLPExporter(cfg OTLPConfig, reg *Registry, serviceName, environment string) *OTLPExporter
NewOTLPExporter builds an exporter for the configured endpoint.
func (*OTLPExporter) Close ¶
func (e *OTLPExporter) Close() error
Close terminates the background exporter and awaits completion.
func (*OTLPExporter) ExportOnce ¶
func (e *OTLPExporter) ExportOnce(ctx context.Context) error
ExportOnce sends an immediate snapshot of metrics to the OTLP endpoint.
func (*OTLPExporter) Start ¶
func (e *OTLPExporter) Start()
Start launches the background periodic exporter worker.
type PrometheusConfig ¶
type PrometheusConfig struct {
Enabled bool `json:"enabled" yaml:"enabled"`
Address string `json:"address" yaml:"address"`
Path string `json:"path" yaml:"path"`
}
PrometheusConfig controls the local HTTP scraper endpoint.
type PrometheusServer ¶
type PrometheusServer struct {
// contains filtered or unexported fields
}
PrometheusServer serves Prometheus metrics via HTTP.
func NewPrometheusServer ¶
func NewPrometheusServer(cfg PrometheusConfig, reg *Registry) *PrometheusServer
NewPrometheusServer creates a server configured to scrape metrics from the registry.
func (*PrometheusServer) Address ¶
func (s *PrometheusServer) Address() string
Address returns the effective network address of the listener (e.g. for testing with port :0).
func (*PrometheusServer) Close ¶
func (s *PrometheusServer) Close() error
Close gracefully stops the Prometheus HTTP server.
func (*PrometheusServer) Start ¶
func (s *PrometheusServer) Start() error
Start opens the TCP listener and begins serving HTTP requests.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry aggregates and tracks metrics from audit events in a thread-safe manner.
type Snapshot ¶
type Snapshot struct {
Timestamp time.Time `json:"timestamp"`
SessionsActive []MetricSample `json:"sessions_active"`
EventsPending int64 `json:"events_pending"`
SessionsTotal []MetricSample `json:"sessions_total"`
EventsDetectedTotal []MetricSample `json:"events_detected_total"`
EventsWithdrawnTotal []MetricSample `json:"events_withdrawn_total"`
DecisionsTotal []MetricSample `json:"decisions_total"`
OperatorInputsTotal []MetricSample `json:"operator_inputs_total"`
ControlEventsTotal []MetricSample `json:"control_events_total"`
RecordingEventsTotal []MetricSample `json:"recording_events_total"`
GuardrailsViolations []MetricSample `json:"guardrails_violations"`
DecisionDurations []HistogramSample `json:"decision_durations"`
}
Snapshot contains an immutable point-in-time capture of all registry metrics.
Source Files