Skip to content

Latest commit

 

History

History
101 lines (72 loc) · 2.96 KB

README.md

File metadata and controls

101 lines (72 loc) · 2.96 KB
Raw

backtrace-go

Backtrace error reporting tool for Go.

Installation

go get github.com/backtrace-labs/backtrace-go

Usage

In Go there are three ways errors can happen:

  • An operation produces an error return value.
  • A goroutine calls panic.
  • A native library crashes or the Go runtime itself crashes.

backtrace-go handles error and panic situations. However, there are some caveats with handling panics:

  • In order to capture error reports in a panic scenario, every goroutine must make an API call to set up panic handling.
  • It's possible to forget to do this setup, and you might not know when a callback is executed as a goroutine.
  • If a Go application makes any calls into native libraries, a crash in a native library will crash without causing a panic.

Fortunately, there is a robust solution which can capture an error report in all of these circumstances. This is a Backtrace product called Coresnap which supports deep introspection into the state of Go applications.

The recommended way to capture error reports in a Go application is to use coresnap to handle panics and crashes, and to use backtrace-go to report non-fatal error conditions.

import (
    "http"

    "github.com/backtrace-labs/backtrace-go"
)

func init() {
    bt.Options.Endpoint = "https://console.backtrace.io"
    bt.Options.Token = "51cc8e69c5b62fa8c72dc963e730f1e8eacbd243aeafc35d08d05ded9a024121"
}

func foo() {
    response, err := http.Get("https://doesnotexistexample.com")
    if err != nil {
        bt.Report(err, nil)
    }
}

Documentation

bt.Report(msg interface{}, attributes map[string]string)

msg can be an error or something that can be converted to a string. attributes are added to the report.

bt.ReportPanic(attributes map[string]string)

Sends an error report in the event of a panic.

defer bt.ReportPanic(nil)
somethingThatMightPanic()

bt.ReportAndRecoverPanic(attributes map[string]string)

This is the same as bt.ReportPanic but it recovers from the panic and the goroutine lives on.

bt.FinishSendingReports()

backtrace-go sends reports in a goroutine to avoid blocking. When your application shuts down it will abort any ongoing sending of reports. Call this function to block until all queued reports are done sending.

bcd

Package provides integration with out of process tracers. Using the provided Tracer interface, applications may invoke tracer execution on demand. Panic and signal handling integrations are provided.

The Tracer interface is generic and will support any out of process tracer implementing it. A default Tracer implementation, which uses the Backtrace I/O platform, is provided.

Usage

See the godoc page for current documentation; see this for an example application.