telemetry

Documentation

Overview

Package telemetry wires traces, metrics and logs to an OTLP endpoint (ADR-008: "OTLP everywhere, no proprietary protocol").

The endpoint can come from the standard OTEL_* variables (the one deliberate exception to the AKERDOCK_* prefix, instance-config §2.4) OR from the instance settings stored in the database (encrypted, §14.2). The caller resolves which and hands a Config to Init; the settings-driven config takes effect at the next restart, since Init runs once at boot.

With no endpoint and no Prometheus scrape, nothing is exported and nothing is attempted — no background retry, no repeated warning in the logs of the (many) instances that will never run a collector.

Index

• func ScopeName() string
• func SpanError(span trace.Span, err error)
• type Config
  • func EnvConfig() Config
• type Metrics
  • func NewMetrics(m metric.Meter) *Metrics
  • func (m *Metrics) RecordAction(ctx context.Context, action, actor, result string)
  • func (m *Metrics) RecordDeployment(ctx context.Context, status string, seconds float64)
  • func (m *Metrics) RecordDockerOp(ctx context.Context, method, outcome string)
  • func (m *Metrics) RecordJob(ctx context.Context, jobType, status string, seconds float64)
• type Telemetry
  • func Init(ctx context.Context, version string, cfg Config, logger *slog.Logger) *Telemetry
  • func (t *Telemetry) Enabled() bool
  • func (t *Telemetry) Shutdown(ctx context.Context)

Functions

func ScopeName

func ScopeName() string

ScopeName is the instrumentation scope, shared with the slog bridge.

func SpanError

func SpanError(span trace.Span, err error)

SpanError marks a span as failed with a message that must never carry a secret — spans leave the instance.

Types

type Config

type Config struct {
	// Endpoint is the OTLP collector URL (scheme decides TLS); empty disables OTLP.
	Endpoint string `json:"endpoint"`
	// Protocol is "http" (default) or "grpc".
	Protocol string `json:"protocol"`
	// Headers are sent on every export (e.g. an auth token).
	Headers map[string]string `json:"headers,omitempty"`
	// Which signals to export.
	Traces  bool `json:"traces"`
	Metrics bool `json:"metrics"`
	Logs    bool `json:"logs"`
	// PromEnabled exposes the local /metrics scrape; from env, never persisted.
	PromEnabled bool `json:"-"`
}

Config is the resolved OTLP export configuration handed to Init. It carries json tags because it is exactly what the instance settings persist (encrypted).

func EnvConfig

func EnvConfig() Config

EnvConfig reads the fallback configuration from the standard OTEL_* variables. Used when no OTLP config is stored in the database. All three signals are on when an endpoint is present — env users opt in by setting the endpoint at all.

type Metrics

type Metrics struct {
	JobsCompleted     metric.Int64Counter
	JobDuration       metric.Float64Histogram
	DeploymentsTotal  metric.Int64Counter
	DeploymentLatency metric.Float64Histogram
	// ActionsTotal counts every audited action (the chokepoint every mutation
	// passes through), by action name, actor kind and result — the product-wide
	// "what happened" counter.
	ActionsTotal metric.Int64Counter
	// DockerOps counts every typed command sent on an agent channel
	// (ADR-052), by method and outcome — the migration's health signal.
	DockerOps metric.Int64Counter
}

Metrics are the instruments the control plane reports. They are created once and reused: a metric created per call would leak an instrument per call.

func NewMetrics

func NewMetrics(m metric.Meter) *Metrics

NewMetrics builds the instruments. Errors are folded into no-ops rather than returned: a broken instrument must not break a deployment.

func (*Metrics) RecordAction

func (m *Metrics) RecordAction(ctx context.Context, action, actor, result string)

RecordAction reports one audited action — the single instrument behind "instrument every AkerDock action", fed from the audit chokepoint.

func (*Metrics) RecordDeployment

func (m *Metrics) RecordDeployment(ctx context.Context, status string, seconds float64)

RecordDeployment reports one terminal deployment.

func (*Metrics) RecordDockerOp

func (m *Metrics) RecordDockerOp(ctx context.Context, method, outcome string)

RecordDockerOp reports one typed command sent on an agent channel (ADR-052): the migration's health signal, by method and outcome ("ok" or the wire error code).

func (*Metrics) RecordJob

func (m *Metrics) RecordJob(ctx context.Context, jobType, status string, seconds float64)

RecordJob reports one terminal job.

type Telemetry

type Telemetry struct {
	Tracer trace.Tracer
	Meter  metric.Meter
	// PromHandler serves /metrics when the scrape endpoint is enabled; nil
	// otherwise, and the route stays unmounted.
	PromHandler http.Handler
	// contains filtered or unexported fields
}

Telemetry owns the providers and shuts them down cleanly.

func Init

func Init(ctx context.Context, version string, cfg Config, logger *slog.Logger) *Telemetry

Init builds the providers. It never fails the boot: an unreachable collector must not stop a PaaS from deploying — telemetry is how you watch the system, not part of what the system does.

func (*Telemetry) Enabled

func (t *Telemetry) Enabled() bool

Enabled reports whether any exporter was configured.

func (*Telemetry) Shutdown

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

Shutdown flushes what is buffered. Bounded: a collector that has gone away must not hold the process on its way out.