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

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.