v0.9.0

code.nochebuena.dev/go/telemetry

Overview

telemetry bootstraps the full OpenTelemetry SDK with OTLP gRPC exporters targeting
a Grafana Alloy collector. A single call to New sets all three OTel global providers
(traces → Tempo, metrics → Mimir, logs → Loki) and returns a shutdown function the
caller defers in main. All other micro-lib modules use only the OTel API with
zero-overhead no-op defaults; importing telemetry activates the real SDK across the
entire process without requiring any changes to those libraries.

This release reflects an API designed through multiple architecture reviews and
validated end-to-end via the todo-api POC. It is versioned at v0.9.0 rather than
v1.0.0 because it has not yet been exercised in production workloads across all edge
cases, preserving the option for minor API refinements before committing to full
stability.

What's Included

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

Initializes three OTLP gRPC exporters and their corresponding SDK providers:

TracerProvider → OTLP gRPC → Grafana Alloy → Tempo
MeterProvider → OTLP gRPC → Grafana Alloy → Mimir
LoggerProvider → OTLP gRPC → Grafana Alloy → Loki

Sets the three OTel globals: otel.SetTracerProvider, otel.SetMeterProvider, and
global.SetLoggerProvider. Sets W3C TraceContext and Baggage as the global
text map propagator.

Returns (shutdown, nil) on success. If any exporter fails to initialize, all
previously created providers are shut down before the error is returned. The process
never runs with a partial telemetry state.

Config struct

Field	Env var	Required	Default
`ServiceName`	`OTEL_SERVICE_NAME`	yes	—
`ServiceVersion`	`OTEL_SERVICE_VERSION`	no	`unknown`
`Environment`	`OTEL_ENVIRONMENT`	no	`development`
`OTLPEndpoint`	`OTEL_EXPORTER_OTLP_ENDPOINT`	yes	—
`OTLPInsecure`	`OTEL_EXPORTER_OTLP_INSECURE`	no	`false`

Resource attributes

Every signal is tagged with service.name, service.version, and
deployment.environment, merged with the OTel SDK default resource (SDK version,
process info, etc.).

Propagation

W3C TraceContext and Baggage propagation is enabled globally, enabling distributed
trace context to flow across HTTP boundaries when used with compatible instrumentation.

Installation

go get code.nochebuena.dev/go/telemetry@v0.9.0

This module has no micro-lib dependencies. It requires only the OpenTelemetry SDK and
exporter packages. It must be imported only by application main packages.

Design Highlights

Tier 5 — app-only. Framework libraries (Tiers 0–4) use only the OTel API, which
defaults to no-ops. telemetry activates the real SDK by setting global providers.
Importing it from a library module is a mistake that would couple the library to a
specific backend and force all importers to pull in the full OTLP SDK.

Single OTLP endpoint, three signals. All three exporters share one endpoint
(OTLPEndpoint). The Grafana Alloy collector fans out to Tempo, Mimir, and Loki.
This matches the standard Grafana LGTM stack topology and keeps the config surface
minimal.

Not a launcher.Component. Telemetry has no OnInit/OnStart/OnStop lifecycle.
The caller defers the shutdown function directly in main. This keeps the module
dependency graph minimal and the interface maximally simple. If wired with launcher,
use lc.BeforeStop(func() error { return shutdown(ctx) }).

Sequential error rollback. If the metric exporter fails after the trace exporter
succeeds, the trace provider is shut down before returning the error. The process
never exits with dangling exporters.

Known Limitations & Edge Cases

A single shared OTLP endpoint is used for all three signals. Per-signal endpoint
configuration (e.g., separate trace and metrics collectors) is not supported in
this release.
No sampling configuration is exposed. The SDK uses the default sampler (always-on).
Applications requiring head-based sampling must configure the OTel SDK directly
after calling New.
The shutdown function joins errors from all three provider shutdowns with
errors.Join. Individual provider shutdown failures are not distinguished — callers
receive a combined error.
OTLPInsecure: true disables TLS for the OTLP gRPC connection. Do not use in
production environments unless the transport is already secured at the network layer.

v0.9.0 → v1.0.0 Roadmap

Add per-signal endpoint configuration (separate TraceEndpoint, MetricEndpoint, LogEndpoint fields)
Expose a sampling configuration option (e.g., WithSampler(sdktrace.Sampler))
Surface individual shutdown errors from each provider distinctly rather than joining them
Validate behavior under OTLP collector unavailability and reconnection scenarios
Production hardening across multiple deployed services with real Grafana stacks

Downloads

1 Release 1 Tag

Release 0.9.0 Stable