feat(telemetry): initial stable release v0.9.0

Single-call OTel SDK bootstrap setting all three global providers (traces → Tempo, metrics → Mimir, logs → Loki) over OTLP gRPC.

What's included:
- New(ctx, Config): bootstraps TracerProvider, MeterProvider, and LoggerProvider with OTLP gRPC exporters; sets OTel globals
- W3C TraceContext + Baggage propagation set globally
- Resource tagging: service.name, service.version, deployment.environment merged with SDK defaults
- OTLPInsecure bool for development environments without TLS
- Sequential rollback on partial initialization failure — no dangling exporters on error
- Returns shutdown func(context.Context) error; caller defers in main or wires into launcher BeforeStop
- Tier 5 module: must be imported only by application main packages; zero micro-lib dependencies

Tested-via: todo-api POC integration
Reviewed-against: docs/adr/
This commit is contained in:
2026-03-18 14:13:29 -06:00
commit ed4e9ef161
14 changed files with 787 additions and 0 deletions

24
CHANGELOG.md Normal file
View File

@@ -0,0 +1,24 @@
# Changelog
All notable changes to this module will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this module adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [0.9.0] - 2026-03-18
### Added
- `Config` struct — holds OTel bootstrap configuration with env-tag support: `ServiceName` (`OTEL_SERVICE_NAME`, required), `ServiceVersion` (`OTEL_SERVICE_VERSION`, default `unknown`), `Environment` (`OTEL_ENVIRONMENT`, default `development`), `OTLPEndpoint` (`OTEL_EXPORTER_OTLP_ENDPOINT`, required), `OTLPInsecure` (`OTEL_EXPORTER_OTLP_INSECURE`, default `false`)
- `New(ctx context.Context, cfg Config) (func(context.Context) error, error)` — bootstraps the full OpenTelemetry SDK by creating three OTLP gRPC exporters and their corresponding SDK providers: `TracerProvider` (traces → Grafana Alloy → Tempo), `MeterProvider` (metrics → Grafana Alloy → Mimir), and `LoggerProvider` (logs → Grafana Alloy → Loki); sets all three OTel globals (`otel.SetTracerProvider`, `otel.SetMeterProvider`, `global.SetLoggerProvider`) and installs W3C TraceContext and Baggage as the global text map propagator; returns `(shutdown, nil)` on success or `(nil, error)` on failure with sequential rollback of any already-created providers
- Shutdown function `func(context.Context) error` — returned by `New`; flushes and shuts down all three providers using `errors.Join`, allowing deferred call in `main` or wiring into a launcher `BeforeStop` hook
- OTel resource construction — every signal is tagged with `service.name`, `service.version`, and `deployment.environment` attributes, merged with the OTel SDK default resource (SDK version, process info, etc.) using `resource.Merge`
- Sequential error rollback — if the metric exporter fails after the trace exporter is created, the trace provider is shut down before returning the error; if the log exporter fails, both the trace and metric providers are shut down; the process never runs with a partial telemetry state
### Design Notes
- This module is Tier 5 (application bootstrap only) and must never be imported by framework libraries; those libraries use only the OTel API, which defaults to no-ops until `New` is called and sets the global providers
- All three signals share a single OTLP gRPC endpoint, matching the standard Grafana LGTM stack topology where Grafana Alloy receives all signals and fans them out to Tempo, Mimir, and Loki
- The module intentionally does not implement `launcher.Component`; the returned shutdown function is deferred directly in `main`, keeping the dependency graph free of `launcher` and the interface as simple as a single function call
[0.9.0]: https://code.nochebuena.dev/go/telemetry/releases/tag/v0.9.0