observability

README

observability

Hardened OpenTelemetry setup for Go services — OTLP logs, metrics, and traces from one typed config, with graceful OTEL_* env fallback

Part of the phpboyscout Go toolkit — small, framework-free Go modules extracted from go-tool-base. Docs: observability.go.phpboyscout.uk

---

gitlab.com/phpboyscout/go/observability — opinionated OpenTelemetry wiring for Go services. Build hardened OTLP/HTTP providers for the three signals (logs, metrics, traces) from a single typed Settings, with a shared-plus-per-signal config resolution and graceful fallback to the standard OTEL_EXPORTER_OTLP_* environment variables.

It is the observability layer extracted from go-tool-base, which uses it for its service telemetry. It is framework-free: it carries the OpenTelemetry SDK (that is its job) but nothing else — no config framework, no TUI, no go-tool-base.

Design

• Framework-free, OTel-native. The only non-OTel dependency is cockroachdb/errors. A depfootprint_test.go guard allows go.opentelemetry.io but forbids go-tool-base, Viper/Cobra, Charm, and the cloud SDKs.
• Typed values in, providers out. otelcore works from a typed Settings; you own how those are sourced (flags, env, a config file). ResolveSettings merges a shared config with per-signal overrides so one endpoint can serve all three signals with targeted exceptions.
• Signal packages are independent. logs, metrics, and tracing each build their own exporter, so a service that only traces never links the log/metric exporters.
• Graceful env fallback. An empty Endpoint is intentional, not an error: the SDK then reads the standard OTEL_EXPORTER_OTLP_* variables.

Install

go get gitlab.com/phpboyscout/go/observability

Quick start

package main

import (
	"context"

	"gitlab.com/phpboyscout/go/observability/otelcore"
	"gitlab.com/phpboyscout/go/observability/tracing"
)

func main() {
	ctx := context.Background()
	res := otelcore.Resource("my-service", "1.4.0")

	settings := otelcore.Settings{
		Enabled:  true,
		Endpoint: "https://otel-collector.internal:4318", // empty ⇒ OTEL_* env fallback
	}

	tp, err := tracing.NewProvider(ctx, res, settings, tracing.WithSampling(0.1))
	if err != nil {
		panic(err)
	}
	defer tp.Shutdown(ctx)

	// otel.SetTracerProvider(tp) ...
}

What's inside

• otelcore — the transport-neutral core: Resource, ParseEndpoint, the typed Settings, and the shared-plus-per-signal ResolveSettings merge (Config + SignalConfig + SignalOverrides). No signal exporters.
• tracing — NewProvider(ctx, res, settings, WithSampling(ratio)) → *sdktrace.TracerProvider over the OTLP/HTTP trace exporter.
• metrics — NewProvider(ctx, res, settings, WithInterval(d)) → *sdkmetric.MeterProvider over the OTLP/HTTP metric exporter.
• logs — NewProvider(ctx, res, settings) → *sdklog.LoggerProvider, plus Handler(lp, name) for a ready slog.Handler bridged to OTel.

Compatibility

The OpenTelemetry dependency versions are pinned and kept in lockstep with go-tool-base (currently otel/sdk v1.44.0, the OTLP exporters, and contrib/bridges/otelslog v0.19.0) so a service and this module share one OTel build graph. Grouped Renovate updates keep them aligned.

Documentation

Full guides and the endpoint/config model: observability.go.phpboyscout.uk. API reference: pkg.go.dev.

License

See LICENSE.