Articles in this section

Go Integration Guide

  • Updated

The following integration paths depend on client tools which require a Backtrace license. If you have not yet received a license, please contact support@backtrace.io before proceeding.

backtrace-go

backtrace-go  is the easiest to integrate but least advanced (and least feature-rich) integration mechanism into Go. The package consists of a Go-only library that allows for fast and efficient capture of fatal and non-fatal errors in Go applications.

Learn more at https://github.com/backtrace-labs/backtrace-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. When handling panic  situation, consider the following:

  • 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://your_universe_submission_point"
    bt.Options.Token = "you_token_goes_here"
}

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.

 

Related articles