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

feat(telemetry): add NewConsole — logz-backed OTel exporters for local dev (v1.1.0)

Browse Source 
NewConsole bootstraps the OTel SDK with three logz-backed exporters:
- Trace: WithSyncer, one log line per closed span (immediate, no batch)
- Metric: PeriodicReader (60s), flushed on shutdown
- OTel log: BatchProcessor, for third-party libs using OTel log API

ConsoleConfig requires only ServiceName — no OTLP endpoint needed.
Adds logz v1.0.1 as direct dependency; module tier bumped 1 → 2.
This commit is contained in:
Rene Nochebuena
2026-05-12 19:19:50 +00:00
parent 83ac0e3900
commit 00d15bee8d
8 changed files with 464 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
RELEASE.md
View File

@@ -1,46 +1,63 @@
# v1.0.0
# v1.1.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`.
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.
v1.0.0 adds named per-provider shutdown errors, bumps the Go directive to 1.26, and
commits the API as stable. No micro-lib dependencies are added.
## What Changed Since v1.0.0
## What Changed Since v0.9.0
### New: `NewConsole`
### 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>
```go
func NewConsole(ctx context.Context, logger logz.Logger, cfg ConsoleConfig) (func(context.Context) error, error)
```
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.
Same shutdown pattern as `New` — drop-in swap for development environments.
### Go directive bumped to 1.26
**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.0.0
go get code.nochebuena.dev/go/telemetry@v1.1.0
```
## Changelog
See [CHANGELOG.md](CHANGELOG.md#100---2026-05-12).
See [CHANGELOG.md](CHANGELOG.md#110---2026-05-12).