mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
45 lines
2.6 KiB
Go
45 lines
2.6 KiB
Go
// Package errutil provides utilities for working with errors in Grafana.
|
|
//
|
|
// Idiomatic errors in Grafana provides a combination of static and
|
|
// dynamic information that is useful to developers, system
|
|
// administrators and end users alike.
|
|
//
|
|
// Grafana itself can use the static information to infer the general
|
|
// category of error, retryability, log levels, and similar. A developer
|
|
// can combine static and dynamic information from logs to determine
|
|
// what went wrong and where even when access to the runtime environment
|
|
// is impossible. Server admins can use the information from the logs to
|
|
// monitor the health of their Grafana instance. End users will receive
|
|
// an appropriate amount of information to be able to correctly
|
|
// determine the best course of action when receiving an error.
|
|
//
|
|
// It is also important that implementing errors idiomatically comes
|
|
// naturally to experienced and beginner Go developers alike and is
|
|
// compatible with standard library features such as the ones in
|
|
// the errors package. To achieve this, Grafana's errors are divided
|
|
// into the Base and Error types, where the Base contains static
|
|
// information about a category of errors that may occur within a
|
|
// service and Error contains the combination of static and dynamic
|
|
// information for a particular instance of an error.
|
|
//
|
|
// A Base would typically be provided as a package-level variable for a
|
|
// service using the NewBase constructor with a CoreStatus and a unique
|
|
// static message ID that identifies the general structure of the public
|
|
// message attached to the specific error.
|
|
// var errNotFound = errutil.NewBase(errutil.StatusNotFound, "service.not-found")
|
|
// This Base can now be used to construct a regular Go error with the
|
|
// Base.Errorf method using the same structure as fmt.Errorf:
|
|
// return errNotFound.Errorf("looked for thing with ID %d, but it wasn't there: %w", id, err)
|
|
//
|
|
// By default, the end user will be sent the static message ID and a
|
|
// message which is the string representation of the CoreStatus. It is
|
|
// possible to override the message sent to the end user by using
|
|
// the WithPublicMessage functional option when creating a new Base
|
|
// var errNotFound = errutil.NewBase(errutil.StatusNotFound "service.not-found", WithPublicMessage("The thing is missing."))
|
|
// If a dynamic message is needed, the Template type extends Base with a
|
|
// Go template using text/template from the standard library, refer to
|
|
// the documentation related to the Template type for usage examples.
|
|
// It is also possible, but discouraged, to manually edit the fields of
|
|
// an Error.
|
|
package errutil
|