Docs » µAPM Instrumentation Guide » Go Instrumentation

Go Instrumentation

Important

Before you start instrumenting your applications, review the information in Instrumentation Overview.

For Go, we recommend using the Jaeger Go Tracer, which implements the OpenTracing Go interface.

You will need to create the tracer instance in your application and register it as the GlobalTracer instance. For example:

import (
     "io"

     opentracing "github.com/opentracing/opentracing-go"
     jaegercfg "github.com/uber/jaeger-client-go/config"
)

func createTracer() (opentracing.Tracer, io.Closer, error) {
     cfg, err := jaegercfg.FromEnv()
     if err != nil {
             return nil, nil, err
     }

     // Here we are configuring span sampling so that all spans are sampled and
     // sent. The standard deployment model for SignalFx sends all spans from the
     // application to the Smart Agent and Gateway.
     cfg.Sampler = &jaegercfg.SamplerConfig{
             Type:  "const",
             Param: 1,
     }

     // This creates the Jaeger tracer from the configuration, using the Thrift
     // HTTP transport.
     tracer, closer, err := cfg.NewTracer()
     if err != nil {
             return nil, nil, err
     }

     // Set the tracer as the global tracer in case you want to start a span
     // without having a direct reference to the tracer. The use of the global
     // tracer actually appears to be the best-practice in Golang but we show an
     // explicit invocation of the tracer in the example above to make it more
     // obvious what is going on.
     opentracing.SetGlobalTracer(tracer)

     return tracer, closer, nil
}

You should do this somewhere early in your application startup. You should call the closer returned from that function upon application shutdown to ensure any pending spans are sent. There are other ways to configure the tracer if you don’t wish to use environment variables. See the jaeger-go godocs.

Note about realms

A realm is a self-contained deployment of SignalFx in which your organization is hosted. Different realms have different API endpoints (e.g. the endpoint for sending data is ingest.us1.signalfx.com for the us1 realm, and ingest.eu0.signalfx.com for the eu0 realm).

Various statements in the instructions below include a YOUR_SIGNALFX_REALM placeholder that you should replace with the actual name of your realm. This realm name is shown on your profile page in SignalFx. If you do not include the realm name when specifying an endpoint, SignalFx will interpret it as pointing to the us0 realm.

If you use environment variables to configure your tracer, set the following environment variables in your application’s environment:

# Change this to the logical name of your application
JAEGER_SERVICE_NAME=my-app

# Change this to http://localhost:9080/v1/trace if using the Smart Agent
# and Gateway deployment model.
JAEGER_ENDPOINT=https://ingest.YOUR_SIGNALFX_REALM.signalfx.com/v1/trace

# Setting authentication is not required when using the Smart Agent and
# Gateway deployment model.
JAEGER_USER=auth
JAEGER_PASSWORD=<YOUR_SIGNALFX_ORG_TOKEN>

It is generally easiest to use the GlobalTracer, which is what the standard opentracing-go helpers will use to obtain the tracer. This means that you can usually “throw away” the returned tracer instance from the createTracer helper.

See opentracing-go’s README for usage instructions and information on how to propagate context. Also check out our example app, which shows a full application using the Jaeger Go tracer.