Instana Go Collector

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.

Dependency

• 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.

Installation

To add Instana Go Collector to your service run:

$ go get github.com/instana/go-sensor

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.

Configuration

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.

Usage

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.

Features

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 github.com/instana/go-sensor 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.

OpenTracing

Instana Go Collector provides an interface compatible with github.com/opentracing/opentracing-go 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.

Examples

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 github.com/julienschmidt/httprouter 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.