Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Failed to load latest commit information.
Latest commit message
Commit time

Instana Go Collector

Instana, an IBM company

Build Status PkgGoDev OpenTracing Go Report Card

The Go Collector is a runtime metrics collector, code execution tracer and profiler for applications and services written in Go. This module is a part of Instana APM solution.


  • Since version 1.47 the Go Collector requires Go version 1.13 or later.
  • Since version 1.53.0, the Go Collector uses fsm v1.0.1 internally. Customers using fsm version prior to v1 in their projects may face compilation issues and will need to update the fsm version to v1.


To add Instana Go Collector to your service run:

$ go get

You might also consider installing supplemental modules that provide instrumentation for most popular 3rd-party packages.

Please refer to Instana Go Collector documentation for further details on how to activate Go Collector and use it to instrument your application code.


The Go Collector accepts both configuration from within the application code and via environment variables. The values provided via enironment variables take precedence. In case is no specific configuration provided, the values returned by instana.DefaultOptions() will be used.

Please refer to Go Collector Configuration page for detailed instructions. There is also the Go Collector How To page that covers the most common configuration use cases.


In order to trace the code execution, a few minor changes to your app's source code is needed. Please check the examples section and the Go Collector How To guide to learn about common instrumentation patterns.


Runtime metrics collection

Once initialized, the Go Collector starts automatically collecting and sending the following runtime metrics to Instana in background:

  • Memory usage
  • Heap usage
  • GC activity
  • Goroutines

Code execution tracing

Instana Go Collector provides an API to instrument function and method calls from within the application code to trace its execution.

The core package is shipped with instrumentation wrappers for the standard library, including HTTP client and server, as well as SQL database drivers compatible with database/sql. There are also supplemental instrumentation modules provide code wrappers to instrument the most popular 3rd-party libraries.

Please check the examples section and the Go Collector How To guide to learn about common instrumentation patterns.


Instana Go Collector provides an interface compatible with and thus can be used as a global tracer. However, the recommended approach is to use the Instana wrapper packages/functions provided in the library. They set up a lot of semantic information which helps Instana get the best picture of the application possible. Sending proper tags is especially important when it comes to correlating calls to infrastructure and since they are strings mostly, there is a large room for making a mistake.

The Go Collector will remap OpenTracing HTTP headers into Instana headers, so parallel use with some other OpenTracing model is not possible. The Instana tracer is based on the OpenTracing Go basictracer with necessary modifications to map to the Instana tracing model.

Trace continuation and propagation

Instana Go Collector ensures that application trace context will continued and propagated beyond the service boundaries using various methods, depending on the technology being used. Alongside with Instana-specific HTTP headers or message attributes, a number of open standards are supported, such as W3C Trace Context and OpenTelemetry.

W3C Trace Context & OpenTelemetry

The instrumentation wrappers provided with Go Collector automatically inject and extract trace context provided via W3C Trace Context HTTP headers.

Continuous profiling

Instana AutoProfileā„¢ generates and reports process profiles to Instana. Unlike development-time and on-demand profilers, where a user must manually initiate profiling, AutoProfileā„¢ automatically schedules and continuously performs profiling appropriate for critical production environments.

Please refer to the Instana Go Collector docs to learn how to activate and use continuous profiling for your applications and services.

Sending custom events

The Go Collector, be it instantiated explicitly or implicitly through the tracer, provides a simple wrapper API to send events to Instana as described in its documentation.

To learn more, see the Events API document in this repository.


Following examples are included in the example folder:

  • Greeter - an instrumented HTTP server that queries a database
  • Doubler - an instrumented Kafka processor, that consumes and produces messages
  • Event - Demonstrates usage of the Events API
  • Autoprofile - Demonstrates usage of the AutoProfileā„¢
  • OpenTracing - an example of usage of Instana tracer in an app instrumented with OpenTracing
  • gRPC - an example of usage of Instana tracer in an app instrumented with gRPC
  • Gin - an example of usage of Instana tracer instrumenting a Gin application
  • httprouter - an example of usage of Instana tracer instrumenting a router

For more examples please consult the godoc and the Go Collector How To page.

Filing Issues

If something is not working as expected or you have a question, instead of opening an issue in this repository, please open a ticket at Instana Support portal instead.