telemetry

Documentation

Overview

Package telemetry initializes OpenTelemetry tracing and metrics for one process and provides W3C trace-context propagation helpers. Every binary (controlplane, brain, executor, worker) starts through Run, which calls Init for it and owns the exit sequence that Init's shutdown has to come last in; the event log later emits span.* domain events from the same spans started here, so the two views never drift.

Index

• func Extract(ctx context.Context, carrier map[string]string) context.Context
• func Init(ctx context.Context, cfg Config) (func(context.Context) error, error)
• func Inject(ctx context.Context, carrier map[string]string)
• func Run(ctx context.Context, cfg Config, body func(context.Context) error) (ok bool)
• type Config

Functions

func Extract

func Extract(ctx context.Context, carrier map[string]string) context.Context

Extract returns a copy of ctx carrying the remote span context found in carrier, or ctx unchanged when carrier holds no valid traceparent.

func Init

func Init(ctx context.Context, cfg Config) (func(context.Context) error, error)

Init installs the global W3C trace-context propagator and, when an endpoint is configured, global OTLP-exporting tracer and meter providers. On error no global state has been touched. The returned shutdown flushes buffered telemetry; call it once at process exit.

func Inject

func Inject(ctx context.Context, carrier map[string]string)

Inject writes the trace context from ctx into carrier as W3C traceparent / tracestate entries, replacing existing entries in any key casing. carrier is any string map — HTTP headers and a work item's stored trace context both flatten to this shape. A nil carrier, or a ctx without a span context, leaves everything untouched.

func Run

func Run(ctx context.Context, cfg Config, body func(context.Context) error) (ok bool)

Run initializes telemetry from cfg, runs body as the process's main body, and flushes on the way out. It reports whether the process should exit zero: a nil error and a context.Canceled (how a signal-stopped process reports its own clean shutdown) are clean; anything else is logged as fatal and reports false.

The fatal log belongs here, in the same sequence as the flush, rather than in each main() after this returns. The telemetry shutdown stops the log processor, and sdk/log's BatchProcessor drops records once stopped — silently, since the fan-out's console half still prints. A binary that logged its own exit after Run therefore reached stderr and never the collector, leaving the one line that explains why the process died as the only one missing from the backend an operator was looking at. Owning init, body, log and flush together is what keeps that ordering in one place a test can reach; Init stays exported for the suite, so this is the shape to use rather than a shape it enforces.

A body that panics is outside all of this: the fatal log below never runs, and the panic reaches stderr through the runtime. The deferred flush still ships whatever was already queued, and a panic in a goroutine the body started takes the process without reaching even that. #93 is about the errors a body returns.

Init runs before body rather than partway through it for the same reason: every failure a service can report — a missing DATABASE_URL, a sandbox backend that will not construct — is then already inside the bridge's lifetime. Only Init's own failure escapes, and it can only reach stderr, there being no bridge yet to carry it.

Types

type Config

type Config struct {
	// ServiceName identifies the process in traces and metrics
	// (e.g. "controlplane", "brain", "executor", "worker"). Required.
	ServiceName string
	// Endpoint is the OTLP/gRPC collector address (host:port). Empty
	// disables export entirely — no dialing, no background workers — so a
	// deployment without a collector runs offline by default.
	Endpoint string
	// Insecure dials the collector without TLS (local dev, in-cluster
	// collectors behind the service mesh).
	Insecure bool
	// SampleRatio is the fraction of new root traces sampled, in [0, 1];
	// 0 samples nothing (metrics still flow). nil defaults to 1 (sample
	// everything). Child spans always follow their parent's decision, so
	// a trace is never torn.
	SampleRatio *float64
}

Config controls telemetry for one process. Each binary maps its own environment / Helm values onto this struct.