telemetry

Documentation

Overview

Package telemetry implements the gateway's observability seam: a Prometheus registry for per-message counters/histograms and an optional OTLP trace exporter. It satisfies gateway.Observer structurally, so the gateway never imports this package.

Everything here is nil-safe by construction. A zero config yields a Telemetry whose ObserveMessage costs a nil check and whose Handler is nil, so a caller wires telemetry once and lets configuration decide whether anything gets recorded.

Index

• type Telemetry
  • func New(cfg config.Telemetry) (*Telemetry, error)
  • func (t *Telemetry) Handler() http.Handler
  • func (t *Telemetry) ObserveMessage(dir inspect.Direction, backendName, method, tool, decision string, ...)
  • func (t *Telemetry) Path() string
  • func (t *Telemetry) Registry() *prometheus.Registry
  • func (t *Telemetry) SessionEnded()
  • func (t *Telemetry) SessionStarted()
  • func (t *Telemetry) Shutdown(ctx context.Context) error

Types

type Telemetry

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

Telemetry records per-message metrics and (optionally) traces. The zero value and a nil pointer are both usable no-ops.

func New

func New(cfg config.Telemetry) (*Telemetry, error)

New builds telemetry from config. cfg.PrometheusPath enables metrics and cfg.OTLPEndpoint enables tracing; either, both, or neither may be set. The OTLP exporter connects in the background, so New never blocks on an unreachable collector.

func (*Telemetry) Handler

func (t *Telemetry) Handler() http.Handler

Handler serves the Prometheus exposition format, or nil when metrics are disabled. Callers must nil-check before mounting.

func (*Telemetry) ObserveMessage

func (t *Telemetry) ObserveMessage(dir inspect.Direction, backendName, method, tool, decision string, dur time.Duration)

ObserveMessage implements gateway.Observer: one call per message that completed the inspection pipeline.

The tool label sits on the counter alone. Tool names come from remote servers, so their cardinality is unbounded, and multiplying them by the bucket count would explode the series the registry holds. The histogram keeps direction, backend and method.

func (*Telemetry) Path

func (t *Telemetry) Path() string

Path is the HTTP path the caller should mount Handler at, or "" when metrics are disabled.

func (*Telemetry) Registry

func (t *Telemetry) Registry() *prometheus.Registry

Registry exposes the underlying registry so a host process can add its own collectors. Nil when metrics are disabled.

func (*Telemetry) SessionEnded

func (t *Telemetry) SessionEnded()

SessionEnded decrements the active-session gauge.

func (*Telemetry) SessionStarted

func (t *Telemetry) SessionStarted()

SessionStarted increments the active-session gauge.

func (*Telemetry) Shutdown

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

Shutdown flushes pending spans and releases the exporter. Safe on a nil or trace-less Telemetry.