Documentation
¶
Overview ¶
Package telemetry initializes OpenTelemetry for the agent loop.
Telemetry is off by default — no exporter is configured — so a fresh invocation makes zero outbound network calls. Consumers opt in by setting one of:
- "console" — writes spans to stderr; useful for local debug
- "otlp" — honors standard OTEL env vars (OTEL_EXPORTER_OTLP_ENDPOINT, etc.) to ship to a collector
- "none" — the default; no spans leave
The mode is normally set via cfg.OTEL.Exporter in .agents/config.json, but the standard OpenTelemetry SDK env var `OTEL_TRACES_EXPORTER` overrides when set (matches the OTel spec's env-var-wins convention). This is the load-bearing knob for multi-daemon k8s deployments where the base ConfigMap is shared across Pods but each Pod's exporter target differs — operators wire it via a per-Deployment env-var patch instead of duplicating config.json per daemon.
ADK's telemetry.New constructs providers but does NOT install them as OTEL globals; you must call SetGlobalOtelProviders explicitly or ADK's instrumentation will run against the noop tracer. This package handles that.
Index ¶
Constants ¶
const ( MetricsModeNone = "none" MetricsModeOTLP = "otlp" MetricsModePrometheus = "prometheus" MetricsModeBoth = "both" )
Metric mode names accepted by SetupMetrics. See OTELMetricsConfig in pkg/config for the config-file surface.
const ( ModeNone = "none" // default; no spans exported ModeConsole = "console" // stdout exporter; for local dev ModeOTLP = "otlp" // honors OTEL_EXPORTER_OTLP_ENDPOINT etc. )
Mode names recognized by Setup.
const DefaultPrometheusAddr = ":9464"
DefaultPrometheusAddr is used when Prometheus mode is selected but neither cfg.PrometheusAddr nor opts.PrometheusAddr is set. Matches the OTel-conventional Prometheus reader port so tooling that auto-discovers it (kube-prometheus PodMonitor selectors, etc.) works out of the box.
const MetricsExporterEnvVar = "OTEL_METRICS_EXPORTER"
MetricsExporterEnvVar overrides cfg.OTEL.Metrics.Exporter when set. Matches the OTEL_TRACES_EXPORTER convention (#315) — operators running multi-Pod K8s Deployments with a shared ConfigMap flip the metrics surface per-Pod via env instead of duplicating config.json.
const TracesExporterEnvVar = "OTEL_TRACES_EXPORTER"
TracesExporterEnvVar names the OTel-standard env var that overrides the config-file exporter mode. Same shape as the mode arg: "none", "console", or "otlp". Unknown values fall through to the mode switch below and return the same error the config-file path does.
Variables ¶
This section is empty.
Functions ¶
func Setup ¶
Setup configures OpenTelemetry. Returns a shutdown function the caller MUST call (typically deferred) so buffered spans get flushed.
When mode is "" or "none", no providers are constructed and the shutdown returns nil — call sites stay clean either way.
The OTel-standard env var `OTEL_TRACES_EXPORTER` overrides the passed mode when set. This is the load-bearing knob for k8s deployments with shared ConfigMaps but per-Pod exporter targets: operators patch the Deployment env instead of forking config.json. The override runs before the mode-validation switch, so an invalid env-var value produces the same clear error as an invalid config value.
func SetupMetrics ¶ added in v2.8.0
func SetupMetrics(ctx context.Context, cfg config.OTELMetricsConfig, opts MetricsOptions) (shutdown func(context.Context) error, err error)
SetupMetrics installs a global MeterProvider based on cfg. Returns a shutdown function the caller MUST call (typically deferred) so buffered metric points get flushed and the Prometheus listener stops cleanly.
When cfg.Exporter is "" or "none" (and OTEL_METRICS_EXPORTER is unset), no provider is installed and shutdown returns nil — call sites stay clean either way.
Errors are returned, not swallowed. The daemon entrypoint fails loudly on init failure to catch misconfigurations in dev rather than silently shipping a binary that emits no metrics. Callers preferring graceful degradation can inspect and continue.
Types ¶
type MetricsOptions ¶ added in v2.8.0
type MetricsOptions struct {
// PrometheusAddr overrides cfg.PrometheusAddr when non-empty.
// Threaded from --metrics-addr in the CLI so operators can
// override the config-file bind without editing JSON.
PrometheusAddr string
// ServiceName is stamped as the OTel service.name resource
// attribute. Empty falls back to whatever OTEL_SERVICE_NAME
// contributes via resource.Default(), then to "core-agent".
ServiceName string
}
MetricsOptions carries deployment overrides. All fields may be zero — SetupMetrics fills in defaults from cfg + env.
Source Files