Documentation
¶
Overview ¶
Package errors wires OpenTelemetry global error handling into an independent stdout diagnostic sink.
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 private log/slog.Logger that writes to os.Stdout and mirrors the configured logger format (json, text, or tint). Errors are logged at error level using a consistent message and attribute key ("error").
This diagnostic sink is intentionally independent of the configured application logger and its OTLP export pipeline. It ensures OpenTelemetry export failures remain locally visible without feeding their own diagnostics back into a failing exporter.
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 github.com/alexfalkowski/go-service/v2/telemetry/errors.Module (or the top-level github.com/alexfalkowski/go-service/v2/telemetry.Module) wires this handler into your service, so OpenTelemetry internal errors are written to the handler's private stdout sink regardless of the application logger configuration.
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 on stdout.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Module = di.Module( di.Constructor(NewHandler), di.Register(Register), )
Module wires OpenTelemetry global error handling into go.uber.org/fx.
Including this module in an Fx application provides:
- NewHandler: constructs a *Handler that logs OpenTelemetry internal/SDK errors through a private stdout logger which mirrors the configured logger format (json, text, or tint). This sink is independent of the configured application logger and its OTLP export pipeline.
- 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 on stdout so that export failures cannot feed their own diagnostics back into a failing exporter.
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 go.opentelemetry.io/otel.SetErrorHandler. 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 surfaced through the handler's independent diagnostic sink.
If handler is nil, Register leaves the current global OpenTelemetry error handler unchanged.
func SetHandler ¶ added in v2.497.0
func SetHandler(handler ErrorHandler)
SetHandler installs the global OpenTelemetry error handler.
Types ¶
type ErrorHandler ¶ added in v2.497.0
type ErrorHandler = otel.ErrorHandler
ErrorHandler is an alias for otel.ErrorHandler.
func GetHandler ¶ added in v2.497.0
func GetHandler() ErrorHandler
GetHandler returns the global OpenTelemetry error handler.
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler routes OpenTelemetry SDK/internal errors into a private diagnostic logger.
Handler is intended to be registered via Register so that OpenTelemetry errors are visible on stdout independently of the configured application logger. It logs a consistent message and includes a standardized "error" attribute produced by logger.Error.
func NewHandler ¶
NewHandler constructs a Handler that logs OpenTelemetry internal errors.
The returned Handler implements the OpenTelemetry error handler interface and owns a private stdout logger built by logger.NewDiagnosticLogger. That sink mirrors the configured logger format (json, text, or tint) while remaining independent of the configured application logger and its OTLP export pipeline, so OpenTelemetry export failures cannot feed their own diagnostics back into a failing exporter. A nil cfg, the "otlp" kind, or an unknown kind fall back to JSON on stdout.
func (*Handler) Handle ¶
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 handler's private logger, attaching the error under the "error" key.
Handle is nil-safe. If the receiver or its logger is nil, the error is ignored.
Source Files