observability

module
v0.6.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: MIT

README

observability

OpenTelemetry providers for Go services: OTLP logs, metrics and traces from one typed config, with validated endpoints and a fallback to the standard OTEL_* variables

Go Reference Pipeline Coverage phpboyscout Go toolkit

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


gitlab.com/phpboyscout/go/observability builds OpenTelemetry providers for Go services. You give it one typed Settings and it returns an OTLP/HTTP provider for logs, metrics or traces. One shared config can serve all three signals with per-signal overrides, and an empty endpoint falls back 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, because that is its job, and no config framework, no TUI and no go-tool-base.

Design

  • Framework-free, OTel-native. Apart from the OpenTelemetry modules, the only module the library packages import is go/errors. A depfootprint_test.go guard allows go.opentelemetry.io but forbids go-tool-base, Viper, Cobra, pflag, Charm and the AWS, GCP and Azure 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.
  • Telemetry goes where you point it. otelcore.Settings carries an Exporter: a Collector over OTLP/HTTP, Slog for readable lines through any slog.Logger, or Writer for OTLP JSON lines in a file. Config only ever describes a collector.
  • Errors render onto spans without the SDK. spanerr records a go/errors error on the active span with its kind, origin stack and hints. It imports the OpenTelemetry APIs only, so a library can call it without linking an exporter.
  • Env fallback. An empty Endpoint is intentional, not an error. The SDK then reads the standard OTEL_EXPORTER_OTLP_* variables. Configured Headers and Insecure are still applied on this path, and they are applied after the env vars, so they replace them rather than merge. An endpoint supplied through OTEL_EXPORTER_OTLP_ENDPOINT therefore keeps the auth token from your config. The catch is that a configured Headers map discards OTEL_EXPORTER_OTLP_HEADERS entirely. See Environment variables.
  • Validated endpoints. A configured Endpoint is checked when the provider is built, not at the first export. It must be http or https with a host, and a URL carrying credentials is rejected (they belong in Headers). A trailing slash (https://collector:4318/) is trimmed before the per-signal suffix is joined, so the exported path is /v1/logs, never //v1/logs (which strict collectors 404).

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,
		Exporter: otelcore.Collector{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) ...
}

No collector to hand? Exporter: otelcore.Slog(slog.Default()) prints every metric data point, span and log record as a log line instead. See Send telemetry to the terminal or a file.

What's inside

  • otelcore is the shared core: the Exporter interface with Collector, Slog and Writer, Resource, ParseEndpoint, the typed Settings, and the shared-plus-per-signal ResolveSettings merge (Config + SignalConfig + SignalOverrides), which always yields a Collector.
  • tracing: NewProvider(ctx, res, settings, WithSampling(ratio)) returns a *sdktrace.TracerProvider over the OTLP/HTTP trace exporter.
  • metrics: NewProvider(ctx, res, settings, WithInterval(d)) returns a *sdkmetric.MeterProvider over the OTLP/HTTP metric exporter.
  • logs: NewProvider(ctx, res, settings) returns a *sdklog.LoggerProvider, and Handler(lp, name) turns it into a slog.Handler bridged to OTel.
  • instrument: RED and USE helpers on a metric.Meter, the OpenTelemetry counterpart of go/transport-metrics' domain helpers. See Metric names.
  • spanerr: RecordFailure(ctx, err) records err as an exception event on the span in ctx and fails the span. Record and Fail do each half. With OTEL_SEMCONV_EXCEPTION_SIGNAL_OPT_IN set, the exception also goes out as a log-based event. See Record an error on a span.

What it does not do

It speaks OTLP/HTTP only. There is no gRPC exporter, and a grpc:// endpoint is rejected at startup. There is no Prometheus or Jaeger exporter either, though you can implement otelcore.Exporter and pass your own. It starts no spans and records no metrics of its own (no HTTP, gRPC, runtime or database instrumentation), registers nothing globally, and does not act on Settings.Enabled. OTEL_TRACES_SAMPLER and OTEL_METRIC_EXPORT_INTERVAL have no effect, because the corresponding SDK option is always passed.

Full list with reasoning: What this module does not do.

Compatibility

The OpenTelemetry dependency versions are pinned to the ones go-tool-base uses, so a service built on both resolves one OTel build graph. The pins are in go.mod: otel/sdk, the three OTLP/HTTP exporters and contrib/bridges/otelslog. Grouped Renovate updates keep them aligned, and gRPC plus the split genproto modules are pinned for the same reason. Why, and what it costs: OTel version lockstep.

Documentation

Tutorials, how-to guides, the reference tier and the config model: observability.go.phpboyscout.uk. API reference: pkg.go.dev.

License

See LICENSE.

Directories

Path Synopsis
Package instrument provides RED and USE instrument sets on an OpenTelemetry go.opentelemetry.io/otel/metric.Meter, the push-side counterpart of the domain helpers in gitlab.com/phpboyscout/go/transport-metrics.
Package instrument provides RED and USE instrument sets on an OpenTelemetry go.opentelemetry.io/otel/metric.Meter, the push-side counterpart of the domain helpers in gitlab.com/phpboyscout/go/transport-metrics.
Package logs builds an OpenTelemetry LoggerProvider that batches log records to the exporter in a resolved otelcore.Settings, and an slog.Handler bridge so an application's slog logger can emit OTel records alongside its usual output.
Package logs builds an OpenTelemetry LoggerProvider that batches log records to the exporter in a resolved otelcore.Settings, and an slog.Handler bridge so an application's slog logger can emit OTel records alongside its usual output.
Package metrics builds an OpenTelemetry MeterProvider that pushes metrics on a periodic interval to the exporter in a resolved otelcore.Settings: a collector, a slog logger or a writer.
Package metrics builds an OpenTelemetry MeterProvider that pushes metrics on a periodic interval to the exporter in a resolved otelcore.Settings: a collector, a slog logger or a writer.
mocks
Package otelcore holds the export plumbing shared by the observability signals: the Exporter that says where a signal goes, the service Resource, the typed per-signal Settings, OTLP/HTTP endpoint parsing, and the shared-plus-per-signal ResolveSettings merge.
Package otelcore holds the export plumbing shared by the observability signals: the Exporter that says where a signal goes, the service Resource, the typed per-signal Settings, OTLP/HTTP endpoint parsing, and the shared-plus-per-signal ResolveSettings merge.
Package spanerr records an error from gitlab.com/phpboyscout/go/errors on the active span: its kind, message, origin stack, hints, details and attributes.
Package spanerr records an error from gitlab.com/phpboyscout/go/errors on the active span: its kind, message, origin stack, hints, details and attributes.
Package tracing builds an OpenTelemetry TracerProvider that batches spans to the exporter in a resolved otelcore.Settings: a collector, a slog logger or a writer.
Package tracing builds an OpenTelemetry TracerProvider that batches spans to the exporter in a resolved otelcore.Settings: a collector, a slog logger or a writer.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL