go/telemetry
2
0
Fork 0
Code Issues Pull Requests Packages Releases 3 Activity

3 Releases 3 Tags

RSS Feed
  • v1.1.0 00d15bee8d
    Compare

    Release v1.1.0 Stable

    Rene Nochebuena released this 2026-05-12 13:20:22 -06:00 | 0 commits to main since this release

    v1.1.0

    code.nochebuena.dev/go/telemetry

    Overview

    v1.1.0 adds NewConsole — a logz-backed alternative to New for local development.
    All OTel signals (traces, metrics, OTel log records) are emitted as structured logz log
    lines instead of being forwarded to a Grafana Alloy collector. No infrastructure required.

    What Changed Since v1.0.0

    New: NewConsole

    func NewConsole(ctx context.Context, logger logz.Logger, cfg ConsoleConfig) (func(context.Context) error, error)

    Same shutdown pattern as New — drop-in swap for development environments.

    ConsoleConfig requires only service identity fields:

    Field Env var Required Default
    ServiceName OTEL_SERVICE_NAME yes —
    ServiceVersion OTEL_SERVICE_VERSION no unknown
    Environment OTEL_ENVIRONMENT no development

    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

    Signal details:

    • Traces — synchronous (WithSyncer): one log line immediately on span.End()
    • Metrics — periodic reader (60s interval), flushed on shutdown
    • OTel logs — batch processor, for third-party libs using the OTel log API

    Warning: do not wire the OTel slog bridge alongside NewConsole. It would create a
    feedback loop: logz → slog → OTel log API → logLogExporter → logz.

    Dependency update

    • logz v1.0.1 added as direct dependency; module tier bumped from 1 → 2

    Full API (stable)

    • Config — ServiceName, ServiceVersion, Environment, OTLPEndpoint, OTLPInsecure
    • ConsoleConfig — ServiceName, ServiceVersion, Environment
    • New(ctx, cfg) (func(context.Context) error, error)
    • NewConsole(ctx, logger, cfg) (func(context.Context) error, error)

    Installation

    go get code.nochebuena.dev/go/telemetry@v1.1.0

    Changelog

    See CHANGELOG.md.

    Downloads
  • v1.0.0 83ac0e3900
    Compare

    Release v1.0.0 Stable

    Rene Nochebuena released this 2026-05-12 12:25:25 -06:00 | 1 commits to main since this release

    v1.0.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.

    v1.0.0 adds named per-provider shutdown errors, bumps the Go directive to 1.26, and
    commits the API as stable.

    What Changed Since v0.9.0

    Named per-provider shutdown errors

    The shutdown function now labels each provider failure individually:

    telemetry: trace provider shutdown: <cause>
telemetry: metric provider shutdown: <cause>
telemetry: log provider shutdown: <cause>

    Errors are still joined with errors.Join; individual causes remain accessible via
    errors.As. Previously, provider shutdown failures were joined without labels, making
    it impossible to identify which signal pipeline failed.

    Go directive bumped to 1.26

    Full API (stable)

    • Config — ServiceName, ServiceVersion, Environment, OTLPEndpoint, OTLPInsecure
    • New(ctx, cfg) (func(context.Context) error, error)

    Installation

    go get code.nochebuena.dev/go/telemetry@v1.0.0

    Changelog

    See CHANGELOG.md.

    Downloads
  • v0.9.0 ed4e9ef161
    Compare

    Release 0.9.0 Stable

    Rene Nochebuena released this 2026-03-18 14:14:32 -06:00 | 3 commits to main since this release

    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