Skip to content

Migration: pkg/telemetry/{otelcore,logs,metrics,tracing} → go/observability

The OpenTelemetry setup group has been extracted out of go-tool-base into the standalone module gitlab.com/phpboyscout/go/observability (v0.1.0). It carries the OTel SDK but is otherwise framework-free, so any service can adopt GTB's OTLP wiring without pulling in the framework.

What changed

  • The subpackages gitlab.com/phpboyscout/go-tool-base/pkg/telemetry/{otelcore,logs,metrics,tracing} no longer exist. They now live at gitlab.com/phpboyscout/go/observability/{otelcore,logs,metrics,tracing}.
  • The core API is unchanged. Package names stay the same; otelcore.Settings, otelcore.Resource, otelcore.ParseEndpoint, otelcore.ResolveSettings, otelcore.SettingsSource, and the tracing/metrics/logs NewProvider factories (with WithSampling/WithInterval) are identical.
  • The GTB config-key adapter moved, not deleted. otelcore.Resolve and otelcore.ObserveSettingsFromConfig read GTB config (config.Containable), so they cannot live in the framework-free module. They relocated into pkg/telemetry (package telemetry): the shared-plus-per-signal resolution is now an internal helper, and telemetry.ObserveSettingsFromConfig is the public config-observation seam.

How to migrate

If you consume the core packages directly (otelcore, tracing, metrics, logs), repoint the import paths — the symbols are unchanged:

grep -rlE 'go-tool-base/pkg/telemetry/(otelcore|logs|metrics|tracing)' --include='*.go' . \
  | xargs sed -i -E 's#go-tool-base/pkg/telemetry/(otelcore|logs|metrics|tracing)#go/observability/\1#g'
go get gitlab.com/phpboyscout/go/[email protected]
go mod tidy

If you called otelcore.Resolve or otelcore.ObserveSettingsFromConfig — the config-key adapter — use pkg/telemetry instead: telemetry.ObserveSettingsFromConfig (and, for a one-shot resolve, source your typed otelcore.Settings from your own config and call otelcore.ResolveSettings directly).

go mod tidy and genproto

The OTLP exporters pull a transitive gRPC graph that can surface the google.golang.org/genproto monolithic-vs-split ambiguous import. If tidy fails, pin the split modules (as go-tool-base and the module do):

google.golang.org/genproto/googleapis/api // indirect
google.golang.org/genproto/googleapis/rpc // indirect
google.golang.org/grpc

Notes

  • go-tool-base itself now consumes go/observability: pkg/telemetry's SetupFromProps/Setup builds the module's providers from GTB config, and the product-analytics half of pkg/telemetry is unchanged.
  • Keep the module's OTel versions in lockstep with go-tool-base's (see the module's compatibility note) so a service and the module share one OTel build graph.
  • Full documentation and the config model live at observability.go.phpboyscout.uk; the API reference is on pkg.go.dev.