Documentation
¶
Overview ¶
Package setup wires OpenTelemetry providers for long-running binaries: an SDK MeterProvider bridged into controller-runtime's Prometheus registry, a TracerProvider, and a LoggerProvider, each with optional OTLP gRPC export.
Only binary mains (agent, registrar, controller — via common/manager) may import this package: it drags in the OTel SDK and every exporter. Packages that merely instrument (spans, meters, attribute keys, gRPC stats handlers) must import the parent common/telemetry package instead.
Index ¶
- Constants
- func BestEffortShutdown(fn func(context.Context) error) func(context.Context) error
- func CacheSyncChecker(mgr ctrl.Manager) healthz.Checker
- func DetachedTimeout(parent context.Context, d time.Duration) (context.Context, context.CancelFunc)
- func ManagerMetricsOptions(enabled bool, bindAddress string) metricsserver.Options
- func NewResource(ctx context.Context, cfg Config) (*resource.Resource, error)
- func Setup(ctx context.Context, cfg Config) (shutdown func(context.Context) error, err error)
- func SetupLogs(ctx context.Context, cfg Config) (provider *sdklog.LoggerProvider, shutdown func(context.Context) error, ...)
- func SetupTracing(ctx context.Context, cfg Config) (shutdown func(context.Context) error, err error)
- type Config
Constants ¶
const DefaultMetricsBindAddress = ":8081"
DefaultMetricsBindAddress is the default address for the controller-runtime Prometheus metrics HTTP server.
const FlushTimeout = 5 * time.Second
FlushTimeout bounds the final flush of a telemetry provider on shutdown.
const SetupTimeout = 5 * time.Second
SetupTimeout bounds telemetry provider construction. Nothing in the current provider wiring dials a collector eagerly (the OTLP gRPC clients are lazy), but resource detection and any future exporter option could block, and telemetry must never be able to spend the caller's startup budget: a binary whose health probes only start answering after initialization is killed by the kubelet long before it serves anything (issue #662).
Variables ¶
This section is empty.
Functions ¶
func BestEffortShutdown ¶
BestEffortShutdown wraps a provider shutdown so the flush always runs on a detached, bounded context, and returns nil when fn is nil.
On SIGTERM the caller's context is ALREADY cancelled by the signal handler, so passing it straight through made every final flush a guaranteed no-op that failed with "context canceled" — the last records of a terminating process, which are exactly the ones worth having, were always dropped (issue #662).
func CacheSyncChecker ¶
CacheSyncChecker returns a healthz.Checker that reports healthy once the controller-runtime informer cache has synced, and reports unready promptly (rather than hanging the probe) while it has not.
func DetachedTimeout ¶
DetachedTimeout returns a context that keeps parent's values but neither observes its cancellation nor propagates cancellation back to it, bounded by d. Use it for telemetry work that must be immune to — and invisible to — the caller's lifecycle context.
func ManagerMetricsOptions ¶
func ManagerMetricsOptions(enabled bool, bindAddress string) metricsserver.Options
ManagerMetricsOptions returns controller-runtime metrics server options. When enabled is false, the metrics server is disabled. When enabled is true, it binds to bindAddress (defaulting to DefaultMetricsBindAddress if empty).
func NewResource ¶
NewResource builds the OTel Resource shared by the meter, tracer and logger providers so every signal carries identical service identity attributes. Who decides each attribute is serviceresource's rule, shared with the binaries that do not link this package (mesh-dns, the proxy supervisor, the prober).
It is exported so that each component can pin, in its own package, what the resource built from its own configuration carries (#1596).
func Setup ¶
Setup creates an OTel MeterProvider with a Prometheus exporter registered against controller-runtime's metrics registry. When OTLPEndpoint is non-empty, an OTLP gRPC periodic exporter is added as a second reader. A Resource with semantic convention attributes (service.name, service.version, deployment.environment.name) is attached to the provider. It sets the provider as the global OTel MeterProvider so any package can create meters via otel.Meter(). The returned shutdown function flushes and stops the provider.
func SetupLogs ¶
func SetupLogs(ctx context.Context, cfg Config) (provider *sdklog.LoggerProvider, shutdown func(context.Context) error, err error)
SetupLogs creates an OTel LoggerProvider exporting records to the OTLP gRPC collector at cfg.OTLPEndpoint via a batching processor, carrying the same Resource (service.name/version + env attributes) as metrics and traces. Unlike metrics and traces, the provider is NOT installed globally: the caller wires it into the zap logger via an otelzap Core (see common/manager.SetupLogging), which is the only place that emits records. The returned shutdown function flushes and stops the provider.
cfg.OTLPEndpoint must be non-empty: logs have no OTLP export path without a collector (stderr logging continues regardless via the tee'd zap core).
func SetupTracing ¶
func SetupTracing(ctx context.Context, cfg Config) (shutdown func(context.Context) error, err error)
SetupTracing installs a global OTel TracerProvider (parent-based head sampling at cfg.TraceSampleRate) plus the W3C TraceContext + Baggage propagators, so instrumentation anywhere (e.g. otelgrpc stats handlers) issues valid span contexts. That alone is what lets otelslog stamp trace_id/span_id onto logs emitted within a span — log↔request correlation needs no trace backend.
Span EXPORT is opt-in (cfg.TraceExport): only then is an OTLP batch exporter attached. Exporting to a collector with no traces pipeline just floods stderr with "Unimplemented TraceService" errors, so export stays off until a real trace backend (Tempo/VictoriaTraces) exists. The returned shutdown flushes and stops the provider.
Types ¶
type Config ¶
type Config struct {
// ServiceName identifies the service (e.g. "aether-agent", "aether-registrar").
ServiceName string
// ServiceVersion is the build version of the service.
ServiceVersion string
// OTLPEndpoint is the OTLP gRPC collector endpoint (e.g. "localhost:4317").
// Empty disables OTLP export.
OTLPEndpoint string
// TraceSampleRate is the head-sampling ratio for traces (0.0–1.0). Only
// used by SetupTracing.
TraceSampleRate float64
// TraceExport attaches the OTLP span exporter. When false, SetupTracing still
// installs a TracerProvider (so logs get trace_id) but exports no spans.
TraceExport bool
// SchedulerLatency adds the Go runtime's scheduler-latency histogram
// (go.schedule.duration: how long runnable goroutines waited to run) to
// every metric reader. It is one series of ~160 fixed buckets read from
// runtime/metrics at collection time, so it costs no timer; it is opt-in per
// component because only the node agent needs it (issue #1131).
SchedulerLatency bool
// WithoutHostName leaves host.name off the resource. This package is shared
// by components that run in the host's network namespace (the node agent,
// whose host.name is the node's) and components that do not (the registrar,
// the controller, the edge control plane, whose host.name would be their POD
// name, #1596), so the package cannot choose: the zero value keeps host.name,
// and each component that is not hostNetwork says so. See
// serviceresource.WithoutHost.
WithoutHostName bool
}
Config holds telemetry setup parameters.
Source Files