errors

Documentation

Overview

Package errors wires OpenTelemetry global error handling into go-service logging.

OpenTelemetry SDKs and instrumentations may emit internal errors (for example exporter failures, dropped data warnings, or other SDK/runtime issues). The OpenTelemetry API provides a global error handler hook (see go.opentelemetry.io/otel.ErrorHandler) that applications can set to control how these errors are surfaced.

This package provides a go-service implementation of the OpenTelemetry error handler interface and helpers to register it.

Handler

Handler implements the OpenTelemetry error handler interface by logging errors through a go-service `*telemetry/logger.Logger`. Errors are logged at error level using a consistent message and attribute key ("error").

When logging is disabled and no `*telemetry/logger.Logger` is available, NewHandler returns nil so callers can keep the OpenTelemetry default global error handler.

Registration

Register installs a provided Handler as the process-wide OpenTelemetry error handler by calling:

otel.SetErrorHandler(handler)

This affects all OpenTelemetry components in the process that report errors via the global handler.

If Register is called with nil, it is a no-op and the current global handler is preserved.

Dependency injection (Fx)

This package also exports `Module`, which wires:

• construction of the Handler (NewHandler), and
• registration of the handler (Register)

into an Fx application.

Including `telemetry/errors.Module` (or the top-level `telemetry.Module`) wires this handler into your service. When a go-service logger is configured, OpenTelemetry internal errors are routed into service logging. When logging is disabled, NewHandler returns nil and Register preserves the OpenTelemetry default global error handler instead.

Notes

The OpenTelemetry error handler is global and should typically be configured once at startup. If you install multiple handlers, the last one set wins.

This package only handles OpenTelemetry internal errors; it does not affect how spans, metrics, or logs are exported beyond ensuring SDK errors are visible in logs.

Index

• Variables
• func Register(handler *Handler)
• type Handler
  • func NewHandler(logger *logger.Logger) *Handler
  • func (e *Handler) Handle(err error)

Variables

var Module = di.Module(
	di.Constructor(NewHandler),
	di.Register(Register),
)

Module wires OpenTelemetry global error handling into Fx.

Including this module in an Fx application provides:

• NewHandler: constructs a *Handler that logs OpenTelemetry internal/SDK errors through the go-service telemetry logger when logging is enabled. If no go-service logger is available, NewHandler returns nil.
• Register: installs that handler as the process-wide OpenTelemetry error handler via otel.SetErrorHandler. If the constructed handler is nil, Register leaves the current global handler unchanged.

This surfaces OpenTelemetry exporter/SDK errors in service logs when logging is configured, while preserving the OpenTelemetry default error handling when it is not.

Note: the OpenTelemetry error handler is global; the last handler registered wins.

Functions

func Register

func Register(handler *Handler)

Register installs handler as the global OpenTelemetry error handler.

This function forwards to otel.SetErrorHandler(handler). The OpenTelemetry error handler is process-wide; the last handler registered wins.

Register is typically invoked once during service startup (for example via an Fx module) so that OpenTelemetry SDK/internal errors (exporter failures, dropped data warnings, etc.) are routed into application logging.

If handler is nil, Register leaves the current global OpenTelemetry error handler unchanged.

Types

type Handler

type Handler struct {
	// contains filtered or unexported fields
}

Handler routes OpenTelemetry SDK/internal errors into a go-service logger.

Handler is intended to be registered via Register so that OpenTelemetry errors are visible in service logs. It logs a consistent message and includes a standardized "error" attribute produced by logger.Error.

func NewHandler

func NewHandler(logger *logger.Logger) *Handler

NewHandler constructs a Handler that logs OpenTelemetry internal errors.

The returned Handler implements the OpenTelemetry error handler interface and writes errors using the provided go-service *logger.Logger.

If logger is nil, NewHandler returns nil so callers can preserve the OpenTelemetry default global error handler when logging is disabled.

func (*Handler) Handle

func (e *Handler) Handle(err error)

Handle logs an OpenTelemetry internal error.

This method is called by the OpenTelemetry SDK when it encounters an internal error. It logs at error level using the go-service logger, attaching the error under the "error" key.

Handle is nil-safe. If the receiver or its logger is nil, the error is ignored.