telemetry/CHANGELOG.md

Changelog

All notable changes to this module will be documented in this file.

The format is based on Keep a Changelog, and this module adheres to Semantic Versioning.

1.1.0 - 2026-05-12

Added

• ConsoleConfig — service identity configuration for console/dev mode (only ServiceName, ServiceVersion, Environment; no OTLP endpoint required)
• NewConsole(ctx, logger logz.Logger, cfg ConsoleConfig) (func(context.Context) error, error) — bootstraps the OTel SDK with logz-backed exporters for local development. Traces are exported synchronously via WithSyncer (one log line per closed span); metrics via PeriodicReader (flushed on shutdown); OTel log records via BatchProcessor. No collector needed.
• logz v1.0.1 added as direct dependency (tier bumped from 1 → 2).

Output format

INFO  otel: span    name=GET /api/v1/permisos  trace_id=3f2a9c...  duration_ms=18  status=Ok
INFO  otel: metric  name=http.server.duration  kind=histogram  count=5  sum=87.3  unit=ms
INFO  otel: log     body=cache miss  severity=INFO

1.0.0 - 2026-05-12

Changed

• Go directive bumped from 1.25 to 1.26
• Shutdown function now wraps each provider error with a providerErr type that prefixes the signal name ("telemetry: trace provider shutdown: …", "telemetry: metric provider shutdown: …", "telemetry: log provider shutdown: …"). The combined error is still joined with errors.Join; individual causes remain unwrappable via errors.As. Previously, the three errors were joined without labels.

Stabilization

• API committed as stable. Config, New, and the shutdown function signature (func(context.Context) error) are unchanged from v0.9.0.

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 1 (no micro-lib dependencies) 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