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 CacheSyncChecker(mgr ctrl.Manager) healthz.Checker
- func ManagerMetricsOptions(enabled bool, bindAddress string) metricsserver.Options
- 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.
Variables ¶
This section is empty.
Functions ¶
func CacheSyncChecker ¶
CacheSyncChecker returns a healthz.Checker that reports healthy once the controller-runtime informer cache has synced.
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 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
}
Config holds telemetry setup parameters.
Source Files