Documentation
¶
Overview ¶
Package errors is a Google Stackdriver Error Reporting library.
This package is still experimental and subject to change.
See https://cloud.google.com/error-reporting/ for more information.
To initialize a client, use the NewClient function. Generally you will want to do this on program initialization. The NewClient function takes as arguments a context, the project name, a service name, and a version string. The service name and version string identify the running program, and are included in error reports. The version string can be left empty. NewClient also takes a bool that indicates whether to report errors using Stackdriver Logging, which will result in errors appearing in both the logs and the error dashboard. This is useful if you are already a user of Stackdriver Logging.
import "cloud.google.com/go/errors" ... errorsClient, err = errors.NewClient(ctx, projectID, "myservice", "v1.0", true)
The client can recover panics in your program and report them as errors. To use this functionality, defer its Catch method, as you would any other function for recovering panics.
func foo(ctx context.Context, ...) {
defer errorsClient.Catch(ctx)
...
}
Catch writes an error report containing the recovered value and a stack trace to Stackdriver Error Reporting.
There are various options you can add to the call to Catch that modify how panics are handled.
WithMessage and WithMessagef add a custom message after the recovered value, using fmt.Sprint and fmt.Sprintf respectively.
defer errorsClient.Catch(ctx, errors.WithMessagef("x=%d", x))
WithRequest fills in various fields in the error report with information about an http.Request that's being handled.
defer errorsClient.Catch(ctx, errors.WithRequest(httpReq))
By default, after recovering a panic, Catch will panic again with the recovered value. You can turn off this behavior with the Repanic option.
defer errorsClient.Catch(ctx, errors.Repanic(false))
You can also change the default behavior for the client by changing the RepanicDefault field.
errorsClient.RepanicDefault = false
It is also possible to write an error report directly without recovering a panic, using Report or Reportf.
if err != nil {
errorsClient.Reportf(ctx, r, "unexpected error %v", err)
}
If you try to write an error report with a nil client, or if the client fails to write the report to the server, the error report is logged using log.Println.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// RepanicDefault determines whether Catch will re-panic after recovering a
// panic. This behavior can be overridden for an individual call to Catch using
// the Repanic option.
RepanicDefault bool
// contains filtered or unexported fields
}
func (*Client) Catch ¶
Catch tries to recover a panic; if it succeeds, it writes an error report. It should be called by deferring it, like any other function for recovering panics.
Catch can be called concurrently with other calls to Catch, Report or Reportf.
func (*Client) Close ¶ added in v0.8.0
Close closes any resources held by the client. Close should be called when the client is no longer needed. It need not be called at program exit.
func (*Client) Report ¶
Report writes an error report unconditionally, instead of only when a panic occurs. If r is non-nil, information from the Request is included in the error report.
Report can be called concurrently with other calls to Catch, Report or Reportf.
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
An Option is an optional argument to Catch.
func PanicFlag ¶
PanicFlag returns an Option that can inform Catch that a panic has occurred. If *p is true when Catch is called, an error report is made even if recover returns nil. This allows Catch to report an error for panic(nil). If p is nil, the option is ignored.
Here is an example of how to use PanicFlag:
func foo(ctx context.Context, ...) {
hasPanicked := true
defer errorsClient.Catch(ctx, errors.PanicFlag(&hasPanicked))
...
...
// We have reached the end of the function, so we're not panicking.
hasPanicked = false
}
func Repanic ¶
Repanic returns an Option that determines whether Catch will re-panic after it reports an error. This overrides the default in the client.
func WithMessage ¶
func WithMessage(v ...interface{}) Option
WithMessage returns an Option that sets a message to be included in the error report, if one is made. v is converted to a string with fmt.Sprint.
func WithMessagef ¶
WithMessagef returns an Option that sets a message to be included in the error report, if one is made. format and v are converted to a string with fmt.Sprintf.
func WithRequest ¶
WithRequest returns an Option that informs Catch or Report of an http.Request that is being handled. Information from the Request is included in the error report, if one is made.
Source Files