Getting Started - Go Language Integration with Go-BCD

Welcome to Backtrace! This section will get you started with integrating Backtrace into your Go application.

Here we will walk you through installing the Backtrace packages, some simple queries into the coronerd object store, then show you how to integrate your Go application via the Backtrace go-bcd package with a simple example.


These steps require a license number from Backtrace to install the necessary packages. Please contact us to receive a license number before proceeding.

Package Installation

Common

Install the backtrace-morgue object store client using Node Package Manager (npm). This requires the latest version of Node.JS:

npm install backtrace-morgue -g

RHEL


To install Backtrace's RPM mirror, run:

$ wget https://packages.backtrace.io/<LICENSE>/stork/el/<RELEASE>/backtrace.repo -O /etc/yum.repos.d/backtrace.repo

This will configure yum to pull from Backtrace's RPM mirror. To verify proper yum configuration, run:

# Clean and update yum package listing
$ sudo yum clean; sudo yum update

# Confirm that the backtrace-* packages are available
$ yum list ^backtrace-*
backtrace-coronerd
backtrace-coroner
backtrace-ptrace
backtrace-hydra
[...]

Then install the packages:

# Install packages (on machines which submit snapshots)
$ yum install backtrace-ptrace

# Install packages (on developers machines)
$ yum install backtrace-hydra

Ubuntu/Debian


To install Backtrace's APT mirror, run:

$ wget https://packages.backtrace.io/<LICENSE>/stork/<DISTRO>/<RELEASE>/backtrace.list -O /etc/apt/sources.list.d/backtrace.list

This will configure apt to pull from Backtrace's APT mirror. To verify proper apt configuration, run:

# Clean and update apt package listing
$ apt-get clean; apt-get update

# Confirm that backtrace-* packages are available
$ apt-cache search ^backtrace-*
backtrace-coronerd
backtrace-coroner
backtrace-ptrace
backtrace-hydra
[...]

Then install the packages:

# Install packages (on machines which submit snapshots)
$ apt-get install backtrace-ptrace

# Install packages (on developers machines)
$ apt-get install backtrace-hydra

Morgue Client

Now we will run a basic test to ensure connectivity to the object store before continuing.

Morgue Login & Test

Login to the object store with morgue by issuing the login command with your credentials:

$ morgue login https://yourcompany.sp.backtrace.io
Username: jdoe
Password:

Finally, have morgue list the contents of a project (blackhole should already be created by default).

# Your results may vary
$ morgue list blackhole
mbreaux: yourcompany/blackhole as of 1M ago [145 us]

Troubleshooting

If you run into any issues querying the object store with morgue at this point, please ensure that your machine is able to communicate with .sp.backtrace.io via the following TCP ports:

Integrate Go-BCD

First, you will need to import the go-bcd package into your Go project:

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

Example Go Application with Backtrace integration

Below, we have a simple example application with usage notes inline:

package main

import (
  "github.com/backtrace-labs/go-bcd"
)

func main() {
  // This is optional.
  // Call this if kernel.yama.ptrace_scope will prevent child processes
  // from tracing their parents and other means of adjustment are not
  // preferred.
  if err := bcd.EnableTracing(); err != nil {
      panic(err)
  }

  // Create a new tracer using the default implementation, which uses
  // the Backtrace I/O suite of tools.
  // The first argument indicates whether system goroutines should be
  // included.
  tracer := bcd.New(true)

  // Enable automatic uploads of generated snapshots to a remote coronerd
  // object store for aggregation and querying. 
  if err := tracer.EnablePut("https://yourcompany.sp.backtrace.io:6098",
      "projecttoken",
      bcd.PutOptions{Unlink: true}); err != nil {
      fmt.Printf("Failed to enable put: %v\n", err)
  }

  // Synchronously request a trace. This may also be called from a newly
  // spawned goroutine.
  bcd.Trace(tracer, nil, nil)
}

In the EnablePut call, note that the "projecttoken" here is the token for your blackhole project. This is available via the Web UI: Click Configuration in the top menu, then Projects, then select the project from the list, then Tokens:

For more details on the on the bcd tracer object and its interface, see the GoDoc for go-bcd

Go Integration References

Useful Links
go-bcd Git Repository: link
Backtrace Go Support Announcement link
Example Application: link
GoDoc page for go-bcd: link

Advanced

Now that the Backtrace components are up and running on a basic level, we can begin making customizations.

Web UI: Additional Projects or Users

By default, you start off configured with a project called blackhole. But it's really more useful to sort your applications' snapshots into their own projects in the object store.

Return to the Web UI, click the Menu Icon on the top right, and select Configuration. You may be prompted to enter your credentials again.

On top of the project listing, you have the option to Create a new project. Click this, type in a name, and your new project will be created.

Before you can use this project, you need to configure the project's token:

Select the project in the project listing, click the Tokens option in the menu on the left, and click the green "Create a new token" button, select your user, then click Create.

Now click the clipboard icon to the left of the newly created token - this will copy that long token string to your clipboard.

In your Go application, paste this token into the second parameter of the EnablePut invocation. You'll need to repeat this process for each new project you create.

In your Go integration, the token you use in EnablePut determines which project the snapshot is sent to.

While you're in the Web UI, you have the option of creating additional users for those you wish to grant UI access. Simply return to the first configuration screen, click Users in the left-hand menu, and click "Create a new User" and follow the prompts.

Workflow Integrations

With your Backtrace integration up and running, now Backtrace can assist you with setting up alerting to your favorite third-party ticketing or messaging services. Presently, we support the following integrations:

..with more on the way!

At the moment, assistance from your Backtrace support representative is required to configure your workflow integrations on the object store. Please let us know which ones you're interested in using, and we can work together to get these up and running in just a few minutes!

Attach Attributes

Finally, you can add custom attributes to your snapshots to assist with querying and grouping in both the Web UI and via the morgue command-line tool.

Backtrace automatically populates the following attributes to your snapshots:

To add additional key-value pairs to your snapshots, you'll need to populate the BACKTRACE_DEFAULTS environment variable. This variable contains line-delimited key-value pairs, like:

version=1.2.3
dc=newyork

Alternatively, you can attach attributes directly from your Go application by using the AddKV method of your tracer object:

tracer.AddKV(nil, "version", "1.2.3")

Finally, return to the configuration section of the Web UI, select your project, then select Histograms in the left-hand menu. Click "Create a new histogram" and type in the name of the attribute, and click Create.

Make sure the histogram name is identical to the key that you set in the BACKTRACE_DEFAULTS.

Display Attributes

Attributes that you have attached to your snapshots will appear in the Attributes section when you view that snapshot in the Web Debugger UI.

To display attributes in your morgue list queries, you can add a --select or an aggregation to your morgue query:

$ morgue list blackhole --select=fingerprint --select=hostname
*                               
#9be8    
  fingerprint: 231522a86239d057ce087223397e28c837e1d8d3d4d720433d098ed179d9e0f3
  hostname: skylake
#9be9    
  fingerprint: bf0ab6d7cf0d185be679d04f7820c0ff20de70d4d540c015b97d60f94492e848
  hostname: skylake
# etc

For more details on morgue querying options, please see Backtrace Morgue.