IBM Instana Go Tracer

![PkgGoDev][pkg.go.dev]

The IBM Instana Go Tracer is an SDK that collects traces, metrics, logs and provides profiling for Go applications. The tracer is part of the IBM Instana Observability tool set.

Compatibility

Supported Runtimes

• Go Collector v1.75 or later supports Go 1.27 and 1.26, and maintains compatibility with Go 1.25 (EOL) and Go 1.24 (EOL).

[!NOTE]

Make sure to always use the latest version of the tracer, as it provides new features, improvements, security updates and fixes.

Installation

To add the tracer to your project, run:

go get -u github.com/instana/go-sensor@latest

[!NOTE]

As a good practice, add this command to your CI pipeline or your automated tool before building the application to keep the tracer up to date.

Usage

Initial Setup

Once the tracer is added to the project, import the package into the entrypoint file of your application:

import (
  ...
  instana "github.com/instana/go-sensor"
)

Create a reference to the collector and initialize it with a service name:

var (
  ...
  col instana.TracerLogger
)
func init() {
  ...
  col = instana.InitCollector(&instana.Options{
    Service: "My app",
    Tracer:  instana.DefaultTracerOptions(),
  })
}

[!NOTE]

The tracer expects the Instana Agent to be up and running in the default port 42699. You can change the port with the environment variable `INSTANA_AGENT_PORT.

Once the collector has been initialized with instana.InitCollector, application metrics such as memory, CPU consumption, active goroutine count etc will be automatically collected and reported to the Agent without further actions or configurations to the SDK.

The interval is configured through the Instana Agent's configuration.yaml file.

In the agent's configuration.yaml:

# Configure metrics transmission interval for Go applications
com.instana.plugin.golang:
  poll_rate: 5  # seconds

The accepted values are: 1, 5, 10, 20, 30, 60, 120, 180, 240, 300, 360, 420, 480, 540, 600 (seconds).

• Default: 1 second (if not configured or if an invalid value is provided)

• If poll_rate is not configured or is <= 0, defaults to 1 second.
• If poll_rate is a positive value not in the canonical set above, a warning is logged and the value is used as-is. Range enforcement is the responsibility of the Instana Agent.
• Configuration is read from the agent once, during the initial handshake when the Go tracer starts up.

The poll_rate value is applied only at Go tracer startup. If you change poll_rate in the agent's configuration.yaml after the tracer is already running, the new value will not take effect until the Go application is restarted. This applies even if the Instana Agent itself is restarted — the tracer will continue using the interval it received during its own initial handshake.

In serverless environments, the Go tracer communicates directly with the Instana Serverless Acceptor and does not perform the host agent handshake. As a result, the poll_rate setting in configuration.yaml has no effect. The metrics transmission interval is fixed at 1 second and cannot be configured.

// endpointHandler is the standard http.Handler function
http.HandleFunc("/endpoint", endpointHandler)
log.Fatal(http.ListenAndServe(":9090", nil))

Wrap the endpointHandler function with instana.TracingHandlerFunc. Now your code should look like this:

// endpointHandler is now wrapped by instana.TracingHandlerFunc
http.HandleFunc("/endpoint", instana.TracingHandlerFunc(col, "/endpoint", endpointHandler))
log.Fatal(http.ListenAndServe(":9090", nil))

When running the application, every time /endpoint is called, the tracer will collect this data and send it to the Instana Agent. You can monitor traces to this endpoint in the Instana UI.

Unlike metrics, profiling needs to be enabled with the EnableAutoProfile option, as seen here:

col = instana.InitCollector(&instana.Options{
  Service: "My app",
  EnableAutoProfile: true,
  Tracer:  instana.DefaultTracerOptions(),
})

Instana Logs are spans of the type log.go that are rendered in a special format in the Instana dashboard under Analytics/Logs. You can create logs and report them to the agent or attach them as children of an existing span.

col := instana.InitCollector(&instana.Options{
  Service: "My Go App",
  Tracer:  instana.DefaultTracerOptions(),
})
col.StartSpan("log.go", []ot.StartSpanOption{
  ot.Tags{
    "log.level":   "error", // available levels: info, warn, error, debug
    "log.message": "error from log.go span",
  },
}...).Finish() // make sure to "finish" the span, so it's sent to the agent

The Go sensor provides an instrumentation library for Logrus, a popular structured logging library. The instalogrus hook automatically collects warning and error logs from your Logrus logger, associates them with the current span, and sends them to Instana.

Go tracer support the opt-in feature for the exit spans. When enabled, the collector can start capturing exit spans, even without an entry span. This capability is particularly useful for scenarios like cronjobs and other background tasks, enabling the users to tailor the tracing according to their specific requirements. By setting the INSTANA_ALLOW_ROOT_EXIT_SPAN variable, users can choose whether the tracer should start a trace with an exit span or not. The environment variable can have 2 values. (1: Tracer should record exit spans for the outgoing calls, when it has no active entry span. 0 or any other values: Tracer should not start a trace with an exit span).

export INSTANA_ALLOW_ROOT_EXIT_SPAN=1

package main

import (
  "log"
  "net/http"
instana "github.com/instana/go-sensor"
)
func main() {
  col := instana.InitCollector(&instana.Options{
    Service:           "Basic Usage",
    EnableAutoProfile: true,
    Tracer:  instana.DefaultTracerOptions(),
  })
http.HandleFunc("/endpoint", instana.TracingHandlerFunc(col, "/endpoint", func(w http.ResponseWriter, r *http.Request) {
    w.WriteHeader(http.StatusOK)
  }))
log.Fatal(http.ListenAndServe(":7070", nil))
}

1. We learned how to install, import and initialize the Instana Go Tracer.
2. Once the tracer is initialized, application metrics are collected out of the box.
3. Application profiling can be enabled via the EnableAutoProfile option.
4. Tracing incoming HTTP requests by wrapping the Go standard library http.Handler with instana.TracingHandlerFunc`.

The basic functionality covers tracing for the following standard Go features:

1. HTTP incoming requests
2. HTTP outgoing requests
3. SQL drivers

Another interesting feature is the usage of additional packages located under instrumentation. Each of these packages provide tracing for specific Go packages like the AWS SDK, Gorm and Fiber.

What's Next

1. Tracer Options
2. Tracing HTTP Outgoing Requests
3. Tracing SQL Driver Databases
4. Tracing an application running on Azure Container Apps
5. Tracing Other Go Packages
6. Instrumenting Code Manually
7. Disabling Spans by Category
8. Generic Serverless Agent

[godoc]: https://pkg.go.dev/github.com/instana/go-sensor/?tab=doc#pkg-examples [pkg.go.dev]: https://pkg.go.dev/github.com/instana/go-sensor [docs.autoprofile]: https://www.ibm.com/docs/en/obi/current?topic=technologies-monitoring-go#instana-autoprofile%E2%84%A2 [docs.configuration]: https://www.ibm.com/docs/en/obi/current?topic=go-collector-configuration [docs.installation]: https://www.ibm.com/docs/en/obi/current?topic=go-collector-installation [docs.howto.configuration]: https://www.ibm.com/docs/en/obi/current?topic=go-collector-common-operations#configuration [docs.howto.instrumentation]: https://www.ibm.com/docs/en/obi/current?topic=go-collector-common-operations#instrumentation [instana.DefaultOptions]: https://pkg.go.dev/github.com/instana/go-sensor#DefaultOptions