Documentation ¶
Index ¶
- Constants
- func As(err error, target interface{}) bool
- func AssertionFailedWithDepthf(depth int, format string, args ...interface{}) error
- func AssertionFailedf(format string, args ...interface{}) error
- func BuildSentryReport(err error) (*sentry.Event, map[string]interface{})
- func Cause(err error) error
- func CombineErrors(err, otherErr error) error
- func DecodeError(ctx context.Context, enc EncodedError) error
- func EnsureNotInDomain(err error, constructor DomainOverrideFn, forbiddenDomains ...Domain) error
- func Errorf(format string, args ...interface{}) error
- func FlattenDetails(err error) string
- func FlattenHints(err error) string
- func FormatError(err error, s fmt.State, verb rune)
- func Formattable(err error) fmt.Formatter
- func GetAllDetails(err error) []string
- func GetAllHints(err error) []string
- func GetContextTags(err error) []*logtags.Buffer
- func GetOneLineSource(err error) (file string, line int, fn string, ok bool)
- func GetTelemetryKeys(err error) []string
- func HandleAsAssertionFailure(origErr error) error
- func HandleAsAssertionFailureDepth(depth int, origErr error) error
- func Handled(err error) error
- func HandledInDomain(err error, domain Domain) error
- func HandledInDomainWithMessage(err error, domain Domain, msg string) error
- func HandledWithMessage(err error, msg string) error
- func HasAssertionFailure(err error) bool
- func HasInterface(err error, referenceInterface interface{}) bool
- func HasIssueLink(err error) bool
- func HasType(err, referenceType error) bool
- func HasUnimplementedError(err error) bool
- func If(err error, pred func(err error) (interface{}, bool)) (interface{}, bool)
- func Is(err, reference error) bool
- func IsAny(err error, references ...error) bool
- func IsAssertionFailure(err error) bool
- func IsIssueLink(err error) bool
- func IsUnimplementedError(err error) bool
- func Join(errs ...error) error
- func JoinWithDepth(depth int, errs ...error) error
- func Mark(err error, reference error) error
- func New(msg string) error
- func NewAssertionErrorWithWrappedErrf(origErr error, format string, args ...interface{}) error
- func NewWithDepth(depth int, msg string) error
- func NewWithDepthf(depth int, format string, args ...interface{}) error
- func Newf(format string, args ...interface{}) error
- func NotInDomain(err error, doms ...Domain) bool
- func Opaque(err error) error
- func Redact(r interface{}) string
- func RegisterLeafDecoder(typeName TypeKey, decoder LeafDecoder)
- func RegisterLeafEncoder(typeName TypeKey, encoder LeafEncoder)
- func RegisterMultiCauseDecoder(theType TypeKey, decoder MultiCauseDecoder)
- func RegisterMultiCauseEncoder(typeName TypeKey, encoder MultiCauseEncoder)
- func RegisterTypeMigration(previousPkgPath, previousTypeName string, newType error)
- func RegisterWrapperDecoder(typeName TypeKey, decoder WrapperDecoder)
- func RegisterWrapperEncoder(typeName TypeKey, encoder WrapperEncoder)
- func RegisterWrapperEncoderWithMessageType(typeName TypeKey, encoder WrapperEncoderWithMessageType)
- func ReportError(err error) string
- func Safe(v interface{}) redact.SafeValue
- func SetWarningFn(fn func(context.Context, string, ...interface{}))
- func UnimplementedError(issueLink IssueLink, msg string) error
- func UnimplementedErrorf(issueLink IssueLink, format string, args ...interface{}) error
- func Unwrap(err error) error
- func UnwrapAll(err error) error
- func UnwrapOnce(err error) error
- func WithAssertionFailure(err error) error
- func WithContextTags(err error, ctx context.Context) error
- func WithDetail(err error, msg string) error
- func WithDetailf(err error, format string, args ...interface{}) error
- func WithDomain(err error, domain Domain) error
- func WithHint(err error, msg string) error
- func WithHintf(err error, format string, args ...interface{}) error
- func WithIssueLink(err error, issue IssueLink) error
- func WithMessage(err error, msg string) error
- func WithMessagef(err error, format string, args ...interface{}) error
- func WithSafeDetails(err error, format string, args ...interface{}) error
- func WithSecondaryError(err error, additionalErr error) error
- func WithStack(err error) error
- func WithStackDepth(err error, depth int) error
- func WithTelemetry(err error, keys ...string) error
- func Wrap(err error, msg string) error
- func WrapWithDepth(depth int, err error, msg string) error
- func WrapWithDepthf(depth int, err error, format string, args ...interface{}) error
- func Wrapf(err error, format string, args ...interface{}) error
- type Domain
- type DomainOverrideFn
- type EncodedError
- type ErrorDetailer
- type ErrorHinter
- type Formatter
- type IssueLink
- type LeafDecoder
- type LeafEncoder
- type MultiCauseDecoder
- type MultiCauseEncoder
- type Printer
- type ReportableStackTrace
- type SafeDetailPayload
- type SafeDetailer
- type SafeFormatter
- type SafeMessager
- type TypeKey
- type Wrapper
- type WrapperDecoder
- type WrapperEncoder
- type WrapperEncoderWithMessageType
Constants ¶
const UnimplementedErrorHint = issuelink.UnimplementedErrorHint
UnimplementedErrorHint is the hint emitted upon unimplemented errors.
Variables ¶
This section is empty.
Functions ¶
func As ¶ added in v1.2.0
As finds the first error in err's chain that matches the type to which target points, and if so, sets the target to its value and returns true. An error matches a type if it is assignable to the target type, or if it has a method As(interface{}) bool such that As(target) returns true. As will panic if target is not a non-nil pointer to a type which implements error or is of interface type.
The As method should set the target to its value and return true if err matches the type to which target points.
Note: this implementation differs from that of xerrors as follows: - it also supports recursing through causes with Cause(). - if it detects an API use error, its panic object is a valid error.
func AssertionFailedWithDepthf ¶
AssertionFailedWithDepthf creates an internal error with a stack trace collected at the specified depth. See the doc of `AssertionFailedf()` for more details.
func AssertionFailedf ¶
AssertionFailedf creates an internal error.
Detail is shown: - via `errors.GetSafeDetails()`, shows redacted strings. - when formatting with `%+v`. - in Sentry reports.
func BuildSentryReport ¶
BuildSentryReport builds the components of a sentry report. This can be used instead of ReportError() below to use additional custom conditions in the reporting or add additional reporting tags.
The Sentry Event is populated for maximal utility when exploited in the Sentry.io web interface and database.
A Sentry report is displayed visually in the Sentry UI as follows:
////////////// Title: (1) some prefix in bold (2) one line for a stack trace (3) a single-line subtitle
(4) the tags, as a tag soup (concatenated in a single paragraph, unsorted)
(5) a "message"
(6) zero or more "exceptions", each composed of:
(7) a bold title (8) some freeform text (9) a stack trace
(10) metadata fields: environment, arch, etc
(11) "Additional data" fields
(12) SDK version ///////////////
These visual items map to the Sentry Event object as follows:
(1) the Type field of the 1st Exception object, if any
otherwise the Message field
(2) the topmost entry from the Stacktrace field of the 1st Exception object, if any (3) the Value field of the 1st Exception object, if any, unwrapped as a single line (4) the Tags field (5) the Message field (7) the Type field (same as (1) for 1st exception) (8) the Value field (same as (3) for 1st exception) (9) the Stacktrace field (input to (2) on 1st exception) (10) the other fields on the Event object (11) the Extra field
(Note how the top-level title fields (1) (3) are unrelated to the Message field in the event, which is surprising!)
Given this mapping, an error object is decomposed as follows:
(1)/(7): <filename>:<lineno> (<functionname>) (3)/(8): <error type>: <first safe detail line, if any> (4): not populated in this function, caller is to manage this (5): detailed structure of the entire error object, with references to "additional data"
and additional "exception" objects
(9): generated from innermost stack trace (6): every exception object after the 1st reports additional stack trace contexts (11): "additional data" populated from safe detail payloads
If there is no stack trace in the error, a synthetic Exception object is still produced to provide visual detail in the Sentry UI.
Note that if a layer in the error has both a stack trace (ie provides the `StackTrace()` interface) and also safe details (`SafeDetails()`) other than the stack trace, only the stack trace is included in the Sentry report. This does not affect error types provided by the library, but could impact error types defined by 3rd parties. This limitation may be lifted in a later version.
func CombineErrors ¶ added in v1.1.0
CombineErrors returns err, or, if err is nil, otherErr. if err is non-nil, otherErr is attached as secondary error. See the documentation of `WithSecondaryError()` for details.
func DecodeError ¶
func DecodeError(ctx context.Context, enc EncodedError) error
DecodeError decodes an error.
func EnsureNotInDomain ¶
func EnsureNotInDomain(err error, constructor DomainOverrideFn, forbiddenDomains ...Domain) error
EnsureNotInDomain checks whether the error is in the given domain(s). If it is, the given constructor if provided is called to construct an alternate error. If no error constructor is provided, a new barrier is constructed automatically using the first provided domain as new domain. The original error message is preserved.
func FlattenDetails ¶
FlattenDetails retrieves the details as per GetAllDetails() and concatenates them into a single string.
func FlattenHints ¶
FlattenHints retrieves the hints as per GetAllHints() and concatenates them into a single string.
func FormatError ¶ added in v1.2.0
FormatError formats an error according to s and verb. This is a helper meant for use when implementing the fmt.Formatter interface on custom error objects.
If the error implements errors.Formatter, FormatError calls its FormatError method of f with an errors.Printer configured according to s and verb, and writes the result to s.
Otherwise, if it is a wrapper, FormatError prints out its error prefix, then recurses on its cause.
Otherwise, its Error() text is printed.
func Formattable ¶ added in v1.7.0
Formattable wraps an error into a fmt.Formatter which will provide "smart" formatting even if the outer layer of the error does not implement the Formatter interface.
func GetAllDetails ¶
GetAllDetails retrieves the details from the error using in post-order traversal.
func GetAllHints ¶
GetAllHints retrieves the hints from the error using in post-order traversal. The hints are de-duplicated. Assertion failures, issue links and unimplemented errors are detected and receive standard hints.
func GetContextTags ¶ added in v1.1.0
GetContextTags retrieves the k/v pairs stored in the error. The sets are returned from outermost to innermost level of cause. The returned logtags.Buffer only know about the string representation of the values originally captured by the error.
func GetOneLineSource ¶
GetOneLineSource extracts the file/line/function information of the topmost caller in the innermost recorded stack trace. The filename is simplified to remove the path prefix.
This is used e.g. to populate the "source" field in PostgreSQL errors in CockroachDB.
func GetTelemetryKeys ¶
GetTelemetryKeys retrieves the (de-duplicated) set of all telemetry keys present in the direct causal chain of the error. The keys may not be sorted.
func HandleAsAssertionFailure ¶ added in v1.2.3
HandleAsAssertionFailure hides an error and turns it into an assertion failure. Both details from the original error and the context of the caller are preserved. The original error is not visible as cause any more. The original error message is preserved. See the doc of `AssertionFailedf()` for more details.
func HandleAsAssertionFailureDepth ¶ added in v1.2.3
HandleAsAssertionFailureDepth is like HandleAsAssertionFailure but the depth at which the call stack is captured can be specified.
func Handled ¶
Handled swallows the provided error and hides it from the Cause()/Unwrap() interface, and thus the Is() facility that identifies causes. However, it retains it for the purpose of printing the error out (e.g. for troubleshooting). The error message is preserved in full.
Detail is shown: - via `errors.GetSafeDetails()`, shows details from hidden error. - when formatting with `%+v`. - in Sentry reports.
func HandledInDomain ¶
HandledInDomain creates an error in the given domain and retains the details of the given original error as context for debugging. The original error is hidden and does not become a "cause" for the new error. The original's error _message_ is preserved.
See the documentation of `WithDomain()` and `errors.Handled()` for details.
func HandledInDomainWithMessage ¶
HandledInDomainWithMessage is like HandledWithMessage but with a domain.
func HandledWithMessage ¶
HandledWithMessage is like Handled except the message is overridden. This can be used e.g. to hide message details or to prevent downstream code to make assertions on the message's contents.
func HasAssertionFailure ¶
HasAssertionFailure returns true if the error or any of its causes is an assertion failure annotation.
func HasInterface ¶ added in v1.5.0
HasInterface returns true if err contains an error which implements the interface pointed to by referenceInterface. The type of referenceInterface must be a pointer to an interface type. If referenceInterface is not a pointer to an interface, this function will panic.
func HasIssueLink ¶
HasIssueLink returns true iff the error or one of its causes has a linked issue payload.
func HasType ¶ added in v1.4.0
HasType returns true iff err contains an error whose concrete type matches that of referenceType.
func HasUnimplementedError ¶
HasUnimplementedError returns iff if err or its cause is an unimplemented error.
func If ¶
If iterates on the error's causal chain and returns a predicate's return value the first time the predicate returns true.
Note: if any of the error types has been migrated from a previous package location or a different type, ensure that RegisterTypeMigration() was called prior to If().
func Is ¶
Is determines whether one of the causes of the given error or any of its causes is equivalent to some reference error.
As in the Go standard library, an error is considered to match a reference error if it is equal to that target or if it implements a method Is(error) bool such that Is(reference) returns true.
Note: the inverse is not true - making an Is(reference) method return false does not imply that errors.Is() also returns false. Errors can be equal because their network equality marker is the same. To force errors to appear different to Is(), use errors.Mark().
Note: if any of the error types has been migrated from a previous package location or a different type, ensure that RegisterTypeMigration() was called prior to Is().
func IsAny ¶
IsAny is like Is except that multiple references are compared.
Note: if any of the error types has been migrated from a previous package location or a different type, ensure that RegisterTypeMigration() was called prior to IsAny().
func IsAssertionFailure ¶
IsAssertionFailure returns true if the error (not its causes) is an assertion failure annotation. Consider using markers.If or HasAssertionFailure to test both the error and its causes.
func IsIssueLink ¶
IsIssueLink returns true iff the error (not its causes) has a linked issue payload.
func IsUnimplementedError ¶
IsUnimplementedError returns iff if err is an unimplemented error.
func Join ¶ added in v1.10.1
Join returns an error that wraps the given errors. Any nil error values are discarded. Join returns nil if errs contains no non-nil values. The error formats as the concatenation of the strings obtained by calling the Error method of each element of errs, with a newline between each string. A stack trace is also retained.
func JoinWithDepth ¶ added in v1.10.1
JoinWithDepth is like Join but the depth at which the call stack is captured can be specified.
func Mark ¶
Mark creates an explicit mark for the given error, using the same mark as some reference error.
Note: if any of the error types has been migrated from a previous package location or a different type, ensure that RegisterTypeMigration() was called prior to Mark().
func New ¶
New creates an error with a simple error message. A stack trace is retained.
Note: the message string is assumed to not contain PII and is included in Sentry reports. Use errors.Newf("%s", <unsafestring>) for errors strings that may contain PII information.
Detail output: - message via `Error()` and formatting using `%v`/`%s`/`%q`. - everything when formatting with `%+v`. - stack trace and message via `errors.GetSafeDetails()`. - stack trace and message in Sentry reports.
func NewAssertionErrorWithWrappedErrf ¶
NewAssertionErrorWithWrappedErrf wraps an error and turns it into an assertion error. Both details from the original error and the context of the caller are preserved. The original error is not visible as cause any more. The original error message is preserved. See the doc of `AssertionFailedf()` for more details.
func NewWithDepth ¶
NewWithDepth is like New() except the depth to capture the stack trace is configurable. See the doc of `New()` for more details.
func NewWithDepthf ¶
NewWithDepthf is like Newf() except the depth to capture the stack trace is configurable. See the doc of `New()` for more details.
func Newf ¶
Newf creates an error with a formatted error message. A stack trace is retained.
Note: the format string is assumed to not contain PII and is included in Sentry reports. Use errors.Newf("%s", <unsafestring>) for errors strings that may contain PII information.
See the doc of `New()` for more details.
func NotInDomain ¶
NotInDomain returns true if and only if the error's domain is not one of the specified domains.
func Redact ¶
func Redact(r interface{}) string
Redact returns a redacted version of the supplied item that is safe to use in anonymized reporting.
NB: this interface is obsolete. Use redact.Sprint() directly.
func RegisterLeafDecoder ¶
func RegisterLeafDecoder(typeName TypeKey, decoder LeafDecoder)
RegisterLeafDecoder can be used to register new leaf error types to the library. Registered types will be decoded using their own Go type when an error is decoded. Wrappers that have not been registered will be decoded using the opaqueLeaf type.
Note: if the error type has been migrated from a previous location or a different type, ensure that RegisterTypeMigration() was called prior to RegisterLeafDecoder().
func RegisterLeafEncoder ¶
func RegisterLeafEncoder(typeName TypeKey, encoder LeafEncoder)
RegisterLeafEncoder can be used to register new leaf error types to the library. Registered types will be encoded using their own Go type when an error is encoded. Wrappers that have not been registered will be encoded using the opaqueLeaf type.
Note: if the error type has been migrated from a previous location or a different type, ensure that RegisterTypeMigration() was called prior to RegisterLeafEncoder().
func RegisterMultiCauseDecoder ¶ added in v1.10.1
func RegisterMultiCauseDecoder(theType TypeKey, decoder MultiCauseDecoder)
RegisterMultiCauseDecoder can be used to register new multi-cause wrapper types to the library. Registered wrappers will be decoded using their own Go type when an error is decoded. Multi-cause wrappers that have not been registered will be decoded using the opaqueWrapper type.
func RegisterMultiCauseEncoder ¶ added in v1.10.1
func RegisterMultiCauseEncoder(typeName TypeKey, encoder MultiCauseEncoder)
RegisterMultiCauseEncoder can be used to register new multi-cause error types to the library. Registered types will be encoded using their own Go type when an error is encoded. Multi-cause wrappers that have not been registered will be encoded using the opaqueWrapper type.
func RegisterTypeMigration ¶ added in v1.8.0
RegisterTypeMigration tells the library that the type of the error given as 3rd argument was previously known with type previousTypeName, located at previousPkgPath.
The value of previousTypeName must be the result of calling reflect.TypeOf(err).String() on the original error object. This is usually composed as follows:
[*]<shortpackage>.<errortype>
For example, Go's standard error type has name "*errors.errorString". The asterisk indicates that `errorString` implements the `error` interface via pointer receiver.
Meanwhile, the singleton error type context.DeadlineExceeded has name "context.deadlineExceededError", without asterisk because the type implements `error` by value.
Remember that the short package name inside the error type name and the last component of the package path can be different. This is why they must be specified separately.
func RegisterWrapperDecoder ¶
func RegisterWrapperDecoder(typeName TypeKey, decoder WrapperDecoder)
RegisterWrapperDecoder can be used to register new wrapper types to the library. Registered wrappers will be decoded using their own Go type when an error is decoded. Wrappers that have not been registered will be decoded using the opaqueWrapper type.
Note: if the error type has been migrated from a previous location or a different type, ensure that RegisterTypeMigration() was called prior to RegisterWrapperDecoder().
func RegisterWrapperEncoder ¶
func RegisterWrapperEncoder(typeName TypeKey, encoder WrapperEncoder)
RegisterWrapperEncoder can be used to register new wrapper types to the library. Registered wrappers will be encoded using their own Go type when an error is encoded. Wrappers that have not been registered will be encoded using the opaqueWrapper type.
Note: if the error type has been migrated from a previous location or a different type, ensure that RegisterTypeMigration() was called prior to RegisterWrapperEncoder().
func RegisterWrapperEncoderWithMessageType ¶ added in v1.10.1
func RegisterWrapperEncoderWithMessageType(typeName TypeKey, encoder WrapperEncoderWithMessageType)
RegisterWrapperEncoderWithMessageType can be used to register new wrapper types to the library. These wrappers can optionally override the child error messages with their own error string instead of relying on iterative concatenation. Registered wrappers will be encoded using their own Go type when an error is encoded. Wrappers that have not been registered will be encoded using the opaqueWrapper type.
Note: if the error type has been migrated from a previous location or a different type, ensure that RegisterTypeMigration() was called prior to RegisterWrapperEncoder().
func ReportError ¶
ReportError reports the given error to Sentry. The caller is responsible for checking whether telemetry is enabled, and calling the sentry.Flush() function to wait for the report to be uploaded. (By default, Sentry submits reports asynchronously.)
Note: an empty 'eventID' can be returned which signifies that the error was not reported. This can occur when Sentry client hasn't been properly configured or Sentry client decided to not report the error (due to configured sampling rate, callbacks, Sentry's event processors, etc).
func Safe ¶
Safe wraps the given object into an opaque struct that implements SafeMessager: its contents can be included as-is in PII-free strings in error objects and reports.
NB: this is obsolete. Use redact.Safe instead.
func SetWarningFn ¶ added in v1.2.2
SetWarningFn enables configuration of the warning function.
func UnimplementedError ¶
UnimplementedError creates a new leaf error that indicates that some feature was not (yet) implemented.
Detail is shown: - via `errors.GetSafeDetails()` - when formatting with `%+v`. - in Sentry reports. - via `errors.GetAllHints()` / `errors.FlattenHints()`
func UnimplementedErrorf ¶
UnimplementedErrorf creates a new leaf error that indicates that some feature was not (yet) implemented. The message is formatted.
func UnwrapAll ¶
UnwrapAll accesses the root cause object of the error. If the error has no cause (leaf error), it is returned directly.
func UnwrapOnce ¶
UnwrapOnce accesses the direct cause of the error if any, otherwise returns nil.
It supports both errors implementing causer (`Cause()` method, from github.com/pkg/errors) and `Wrapper` (`Unwrap()` method, from the Go 2 error proposal).
func WithAssertionFailure ¶
WithAssertionFailure decorates the error with an assertion failure marker. This is not intended to be used directly (see AssertionFailed() for further decoration).
Detail is shown: - when formatting with `%+v`. - in Sentry reports.
func WithContextTags ¶ added in v1.1.0
WithContextTags captures the k/v pairs stored in the context via the `logtags` package and annotates them on the error.
Only the strong representation of values remains available. This is because the library cannot guarantee that the underlying value is preserved across the network. To avoid creating a stateful interface (where the user code needs to know whether an error has traveled through the network or not), the library restricts access to the value part as strings. See GetContextTags() below.
Detail is shown: - via `errors.GetSafeDetails()`. - via `GetContextTags()` below. - when formatting with `%+v`. - in Sentry reports.
func WithDetail ¶
WithDetail decorates an error with a textual detail. The detail may contain PII and thus will not reportable. The suggested use case for detail is to augment errors with information useful for debugging.
Detail is shown: - when formatting with `%+v`. - with `GetAllDetails()` / `FlattenDetails()` below.
Note: the detail does not appear in the main error message returned with Error(). Use GetAllDetails() or FlattenDetails() to retrieve it.
func WithDetailf ¶
WithDetailf is a helper that formats the detail string. See the documentation of WithDetail() for details.
func WithDomain ¶
WithDomain wraps an error so that it appears to come from the given domain.
Domain is shown: - via `errors.GetSafeDetails()`. - when formatting with `%+v`. - in Sentry reports.
func WithHint ¶
WithHint decorates an error with a textual hint. The hint may contain PII and thus will not reportable. The suggested use case for hint is to relay information to end users.
Hint is shown: - when formatting with `%+v`. - with `GetAllHints()` / `FlattenHints()` below.
Note: the hint does not appear in the main error message returned with Error(). Use GetAllHints() or FlattenHints() to retrieve it.
func WithHintf ¶
WithHintf is a helper that formats the hint. See the documentation of WithHint() for details.
func WithIssueLink ¶
WithIssueLink adds an annotation to a know issue on a web issue tracker.
The url and detail strings may contain PII and will be considered reportable.
Detail is shown: - via `errors.GetSafeDetails()` - when formatting with `%+v`. - in Sentry reports. - via `errors.GetAllHints()` / `errors.FlattenHints()`
func WithMessage ¶
WithMessage annotates err with a new message. If err is nil, WithMessage returns nil. The message is considered safe for reporting and is included in Sentry reports.
func WithMessagef ¶
WithMessagef annotates err with the format specifier. If err is nil, WithMessagef returns nil. The message is formatted as per redact.Sprintf, to separate safe and unsafe strings for Sentry reporting.
func WithSafeDetails ¶
WithSafeDetails annotates an error with the given reportable details. The format is made available as a PII-free string, alongside with a PII-free representation of every additional argument. Arguments can be reported as-is (without redaction) by wrapping them using the Safe() function.
If the format is empty and there are no arguments, the error argument is returned unchanged.
Detail is shown: - via `errors.GetSafeDetails()` - when formatting with `%+v`. - in Sentry reports.
func WithSecondaryError ¶
WithSecondaryError enhances the error given as first argument with an annotation that carries the error given as second argument. The second error does not participate in cause analysis (Is, etc) and is only revealed when printing out the error or collecting safe (PII-free) details for reporting.
If additionalErr is nil, the first error is returned as-is.
Tip: consider using CombineErrors() below in the general case.
Detail is shown: - via `errors.GetSafeDetails()`, shows details from secondary error. - when formatting with `%+v`. - in Sentry reports.
func WithStack ¶
WithStack annotates err with a stack trace at the point WithStack was called.
Detail is shown: - via `errors.GetSafeDetails()` - when formatting with `%+v`. - in Sentry reports. - when innermost stack capture, with `errors.GetOneLineSource()`.
func WithStackDepth ¶
WithStackDepth annotates err with a stack trace starting from the given call depth. The value zero identifies the caller of WithStackDepth itself. See the documentation of WithStack() for more details.
func WithTelemetry ¶
WithTelemetry annotates err with the given telemetry key(s). The telemetry keys must be PII-free.
Detail is shown: - via `errors.GetSafeDetails()`. - via `GetTelemetryKeys()` below. - when formatting with `%+v`. - in Sentry reports.
func Wrap ¶
Wrap wraps an error with a message prefix. A stack trace is retained.
Note: the prefix string is assumed to not contain PII and is included in Sentry reports. Use errors.Wrapf(err, "%s", <unsafestring>) for errors strings that may contain PII information.
Detail output: - original error message + prefix via `Error()` and formatting using `%v`/`%s`/`%q`. - everything when formatting with `%+v`. - stack trace and message via `errors.GetSafeDetails()`. - stack trace and message in Sentry reports.
func WrapWithDepth ¶
WrapWithDepth is like Wrap except the depth to capture the stack trace is configurable. The the doc of `Wrap()` for more details.
func WrapWithDepthf ¶
WrapWithDepthf is like Wrapf except the depth to capture the stack trace is configurable. The the doc of `Wrapf()` for more details.
func Wrapf ¶
Wrapf wraps an error with a formatted message prefix. A stack trace is also retained. If the format is empty, no prefix is added, but the extra arguments are still processed for reportable strings.
Note: the format string is assumed to not contain PII and is included in Sentry reports. Use errors.Wrapf(err, "%s", <unsafestring>) for errors strings that may contain PII information.
Detail output: - original error message + prefix via `Error()` and formatting using `%v`/`%s`/`%q`. - everything when formatting with `%+v`. - stack trace, format, and redacted details via `errors.GetSafeDetails()`. - stack trace, format, and redacted details in Sentry reports.
Types ¶
type Domain ¶
Domain is the type of a domain annotation.
NoDomain is the domain of errors that don't originate from a barrier.
func GetDomain ¶
GetDomain extracts the domain of the given error, or NoDomain if the error's cause does not have a domain annotation.
func NamedDomain ¶
NamedDomain returns an error domain identified by the given string.
func PackageDomain ¶
func PackageDomain() Domain
PackageDomain returns an error domain that represents the package of its caller.
func PackageDomainAtDepth ¶
PackageDomainAtDepth returns an error domain that describes the package at the given call depth.
type DomainOverrideFn ¶
DomainOverrideFn is the type of the callback function passed to EnsureNotInDomain().
type EncodedError ¶
type EncodedError = errbase.EncodedError
EncodedError is the type of an encoded (and protobuf-encodable) error.
func EncodeError ¶
func EncodeError(ctx context.Context, err error) EncodedError
EncodeError encodes an error.
type ErrorDetailer ¶ added in v1.2.2
type ErrorDetailer = hintdetail.ErrorDetailer
ErrorDetailer is implemented by types that can provide user-informing detail strings.
type ErrorHinter ¶ added in v1.2.2
type ErrorHinter = hintdetail.ErrorHinter
ErrorHinter is implemented by types that can provide user-informing detail strings. This is implemented by withHint here, withIssueLink, assertionFailure and pgerror.Error.
type Formatter ¶ added in v1.2.0
A Formatter formats error messages.
NB: Consider implementing SafeFormatter instead. This will ensure that error displays can distinguish bits that are PII-safe.
type IssueLink ¶
IssueLink is the payload for a linked issue annotation.
func GetAllIssueLinks ¶
GetAllIssueLinks retrieves the linked issue carried by the error or its direct causes.
type LeafDecoder ¶
type LeafDecoder = errbase.LeafDecoder
LeafDecoder is to be provided (via RegisterLeafDecoder above) by additional wrapper types not yet known to this library. A nil return indicates that decoding was not successful.
type LeafEncoder ¶
type LeafEncoder = errbase.LeafEncoder
LeafEncoder is to be provided (via RegisterLeafEncoder above) by additional wrapper types not yet known to this library.
type MultiCauseDecoder ¶ added in v1.10.1
type MultiCauseDecoder = errbase.MultiCauseDecoder
MultiCauseDecoder is to be provided (via RegisterMultiCauseDecoder above) by additional multi-cause wrapper types not yet known by the library. A nil return indicates that decoding was not successful.
type MultiCauseEncoder ¶ added in v1.10.1
type MultiCauseEncoder = errbase.MultiCauseEncoder
MultiCauseEncoder is to be provided (via RegisterMultiCauseEncoder above) by additional multi-cause wrapper types not yet known to this library. The encoder will automatically extract and encode the causes of this error by calling `Unwrap()` and expecting a slice of errors.
type Printer ¶ added in v1.2.0
A Printer formats error messages.
The most common implementation of Printer is the one provided by package fmt during Printf (as of Go 1.13). Localization packages such as golang.org/x/text/message typically provide their own implementations.
type ReportableStackTrace ¶
type ReportableStackTrace = withstack.ReportableStackTrace
ReportableStackTrace aliases the type of the same name in the sentry package. This is used by SendReport().
func GetReportableStackTrace ¶
func GetReportableStackTrace(err error) *ReportableStackTrace
GetReportableStackTrace extracts a stack trace embedded in the given error in the format suitable for Sentry reporting.
This supports:
- errors generated by github.com/pkg/errors (either generated locally or after transfer through the network),
- errors generated with WithStack() in this package,
- any other error that implements a StackTrace() method returning a StackTrace from github.com/pkg/errors.
Note: Sentry wants the oldest call frame first, so the entries are reversed in the result.
type SafeDetailPayload ¶
type SafeDetailPayload = errbase.SafeDetailPayload
SafeDetailPayload captures the safe strings for one level of wrapping.
func GetAllSafeDetails ¶
func GetAllSafeDetails(err error) []SafeDetailPayload
GetAllSafeDetails collects the safe details from the given error object and all its causes. The details are collected from outermost to innermost level of cause.
func GetSafeDetails ¶
func GetSafeDetails(err error) (payload SafeDetailPayload)
GetSafeDetails collects the safe details from the given error object. If it is a wrapper, only the details from the wrapper are returned.
type SafeDetailer ¶
type SafeDetailer = errbase.SafeDetailer
SafeDetailer is an interface that can be implemented by errors that can provide PII-free additional strings suitable for reporting or telemetry.
type SafeFormatter ¶ added in v1.7.0
type SafeFormatter = errbase.SafeFormatter
SafeFormatter is implemented by error leaf or wrapper types that want to separate safe and non-safe information when printed out.
When multiple errors are chained (e.g. via errors.Wrap), intermediate layers in the error that do not implement SafeError are considered “unsafe”
type SafeMessager ¶
type SafeMessager = redact.SafeMessager
SafeMessager aliases redact.SafeMessager.
NB: this is obsolete. Use redact.SafeFormatter or errors.SafeFormatter instead.
type TypeKey ¶
TypeKey identifies an error for the purpose of looking up decoders. It is equivalent to the "family name" in ErrorTypeMarker.
func GetTypeKey ¶ added in v1.2.2
GetTypeKey retrieve the type key for a given error object. This is meant for use in combination with the Register functions.
type Wrapper ¶ added in v1.1.0
type Wrapper interface {
Unwrap() error
}
Wrapper is the type of an error wrapper.
type WrapperDecoder ¶
type WrapperDecoder = errbase.WrapperDecoder
WrapperDecoder is to be provided (via RegisterWrapperDecoder above) by additional wrapper types not yet known to this library. A nil return indicates that decoding was not successful.
type WrapperEncoder ¶
type WrapperEncoder = errbase.WrapperEncoder
WrapperEncoder is to be provided (via RegisterWrapperEncoder above) by additional wrapper types not yet known to this library.
type WrapperEncoderWithMessageType ¶ added in v1.10.1
type WrapperEncoderWithMessageType = errbase.WrapperEncoderWithMessageType
WrapperEncoderWithMessageType is to be provided (via RegisterWrapperEncoderWithMessageType) by additional wrapper types not yet known to this library.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
Package errutil combines primitives from the library, the Go errors package and github.com/pkg/errors.
|
Package errutil combines primitives from the library, the Go errors package and github.com/pkg/errors. |