telemetry

Documentation

Overview

instrument.go is the small, typed instrumentation API the rest of visor calls. Every span and metric is attributed per org+project through ONE attribute builder (orgProjectAttrs), so the whole fleet — provision, list, delete, meter, and all three fleet-billing tiers — reports on the same two dimensions the architecture threads everywhere. Instruments are created lazily from the global providers, so a helper works whether telemetry is enabled (real OTLP export) or disabled (global no-op) with no caller-side branching.

Package telemetry is visor's OpenTelemetry seam: ONE place that wires OTel traces + metrics to the o11y collector over ZAP (the same OTEL_EXPORTER_OTLP_* contract zen-gateway uses to emit GenAI telemetry), and ONE small API the rest of visor calls to attribute spans/metrics per org+project.

It is a leaf package — it imports only the OpenTelemetry SDK and visor's own logs (which is log/slog), so service/ and controllers/ can instrument the provision/list/delete/meter paths without an import cycle. When O11Y_ENDPOINT is unset the pipeline is a no-op (disabled): the global no-op providers back every span and counter, so instrumentation stays branch-free and a local/dev run never spams a nonexistent collector. Setup is best-effort — a failure logs and disables telemetry, never breaks visor.

Index

• func ContextFromRequest(r *http.Request) context.Context
• func CountBillingSkip(ctx context.Context, sweep string)
• func CountDelete(ctx context.Context, org, project, result string)
• func CountLaunch(ctx context.Context, org, project, size, result string)
• func CountList(ctx context.Context, org, project string, n int)
• func CountMetered(ctx context.Context, org, project, tier string, cents int64)
• func Enabled() bool
• func Init(ctx context.Context) func(context.Context) error
• func Span(ctx context.Context, name, org, project string, extra ...attribute.KeyValue) (context.Context, trace.Span)

Functions

func ContextFromRequest

func ContextFromRequest(r *http.Request) context.Context

ContextFromRequest extracts any inbound W3C trace context from the request headers so a span started for this request continues the caller's (gateway's) trace instead of beginning an orphan root. Safe when telemetry is disabled — the global no-op propagator returns the request context unchanged.

func CountBillingSkip

func CountBillingSkip(ctx context.Context, sweep string)

CountBillingSkip records one billing sweep that could NOT debit because metering is unconfigured. It carries no org — the whole point is that no org was billed. This is the series "the sweep did not run this hour" alerts on: the failure it names is silent everywhere else, because unbilled resources keep running perfectly.

func CountDelete

func CountDelete(ctx context.Context, org, project, result string)

CountDelete records one compute delete with its result, attributed to org+project.

func CountLaunch

func CountLaunch(ctx context.Context, org, project, size, result string)

CountLaunch records one compute launch attempt with its result ("launched" or an error class) and size, attributed to org+project.

func CountList

func CountList(ctx context.Context, org, project string, n int)

CountList records how many machines a list returned for org+project.

func CountMetered

func CountMetered(ctx context.Context, org, project, tier string, cents int64)

CountMetered records cents debited to commerce for org+project under a billing tier ("compute", "byoc", "device"). It is the metric mirror of a commerce debit, so o11y shows real, per-tier, per-project spend as it is billed.

func Enabled

func Enabled() bool

Enabled reports whether visor is exporting real OTel data to an OTLP collector.

func Init

func Init(ctx context.Context) func(context.Context) error

Init builds the OTel trace + metric pipelines and installs them as the process global providers, returning a shutdown that flushes the last batch. With no OTLP endpoint configured it is a no-op and returns a no-op shutdown, so the disabled path costs nothing. The HTTP exporters self-configure from the standard OTEL_EXPORTER_OTLP_* env vars (endpoint / headers / protocol), matching the zen-gateway contract, so the operator wires one endpoint and traces + metrics both flow.

func Span

func Span(ctx context.Context, name, org, project string, extra ...attribute.KeyValue) (context.Context, trace.Span)

Span starts a span named name, attributed to org+project. When telemetry is disabled the global no-op tracer returns a no-op span, so the caller uses the returned span unconditionally (always defer span.End()).