Documentation
¶
Overview ¶
Package telemetry provides an opt-in OpenTelemetry SDK bootstrap for canary. It is DEFAULT OFF: nothing here talks to a network, allocates an exporter, or installs a global provider unless CANARY_OTEL is explicitly set truthy (and OTEL_SDK_DISABLED is not "true"). Exporters are OTLP/HTTP only (otlptracehttp, otlpmetrichttp): canary never imports or dials the OTLP/gRPC exporters, and no gRPC connection is ever opened at runtime. grpc itself still enters the build list transitively -- otlpmetrichttp's internal/oconf is a config package shared between that module's grpc and http drivers, and it unconditionally imports grpc.DialOption/ grpc.ClientConn types even though the http driver never uses them (see commit 2d84bde's analysis: `go list -deps ./cmd/canary` goes from 0 to 102 grpc/protobuf packages, and the binary grows from ~27.6MB to ~37.0MB with those symbols linked in). That is a static build-list/size cost, not a behavioral or security surface: no grpc dial ever happens.
All bootstrap diagnostics go to stderr (via slog's default handler, which canary already routes to stderr at LevelError) or are returned as errors. Nothing telemetry does may ever write to stdout: canary's stdout-purity contract depends on it.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Enabled ¶
func Enabled() bool
Enabled reports whether the OpenTelemetry SDK should be bootstrapped. Telemetry is opt-in: it is enabled only when CANARY_OTEL parses as a truthy bool (strconv.ParseBool: "1", "t", "T", "TRUE", "true", "True", and similarly for the numeric/letter forms) AND OTEL_SDK_DISABLED is not the literal string "true" (the OpenTelemetry spec's own kill switch). Any unset, empty, or unparsable CANARY_OTEL value defaults to disabled -- there is no way to end up enabled by accident, e.g. by setting an OTLP endpoint without also setting CANARY_OTEL.
func Flush ¶
func Flush()
Flush shuts down any telemetry providers installed by Setup, if any. It is a no-op when telemetry was never enabled (Setup was never called, or was called while disabled) and safe to call more than once -- the underlying shutdown is idempotent.
Call it immediately before any os.Exit that would otherwise skip a deferred `shutdown(ctx)`: os.Exit terminates the process without running deferred functions in the current goroutine, which would otherwise drop any buffered spans/metrics on the floor.
func Setup ¶
Setup bootstraps the OpenTelemetry SDK when Enabled() is true. When disabled it does nothing -- no exporters are constructed, no global providers are installed -- and returns a no-op shutdown so callers can unconditionally `defer shutdown(ctx)` regardless of whether telemetry is active.
version is threaded in by the caller (canary's resolveVersion()) so the service.version resource attribute matches whatever `canary --version` reports. service.name defaults to "canary" but, like every other resource attribute, is overridable via the standard OTEL_SERVICE_NAME / OTEL_RESOURCE_ATTRIBUTES environment variables -- resource.WithFromEnv applies after WithAttributes below, so an operator's explicit environment setting always wins over canary's default.
Exporters are OTLP/HTTP only (otlptracehttp, otlpmetrichttp): no OTLP/gRPC exporter is imported anywhere in this package, and no gRPC connection is ever opened. grpc and its protobuf-heavy closure still enter the build list transitively via otlpmetrichttp's shared config package (internal/ oconf) even though that package is never dialed -- see the package doc above for the measured build-list/binary-size impact.
Every failure here is returned as an error (never written to stdout); the caller decides whether a broken telemetry backend should also break the CLI invocation (it should not -- see cmd/canary/main.go).
Types ¶
This section is empty.
Source Files