Monitoring Go

Edit online

Monitor your Go applications by installing the Instana Go Collector (also referred to as Go Tracer or in process collector) after setting up the Instana host agent.

For more information, see Instana host agent.

The Go Collector provides instrumentation for Supported Go libraries and platforms, zero configuration health monitoring of Go services, and end-to-end traces of requests across all systems. You can view the collected metrics and traces in the Instana UI.

For more information, see the following sections:

Installation

Edit online

The installation of the Instana Go collector is a simple two-step process. First, add github.com/instana/go-sensor module to your go.mod file:

go get github.com/instana/go-sensor

After the go-sensor module is added to your application dependencies, you can use the go-sensor module to instrument your application code. For more information, see Installation.

Note: Starting from version 1.53.0, Go Collector uses fsm v1.0.1 internally. If you are using fsm version before v1 in your projects, you might face compilation issues, and you need to update fsm version to v1.

Support

Edit online

The Go Collector is compatible with specific Go runtimes, processor architectures, operating systems, and provides instrumentation for various libraries and platforms. The collector supports Go 1.24 and 1.25, maintaining compatibility with Go 1.23 (EOL), and runs on multiple architectures including x86_64, AArch64, IBM Power, and IBM Z across various operating systems.

Instana provides instrumentation for numerous libraries across categories such as HTTP, RPC, databases, messaging, GraphQL, and more. The collector also supports serverless environments including AWS Lambda, Azure Functions, and Azure Container Apps.

For detailed information about supported runtimes and environments, see Support information.

For a comprehensive list of supported libraries and platforms, see Supported Go libraries and platforms.

Configuration

Edit online

The Go collector accepts configuration in two formats: within the application code by using an instana.Options configuration object or by using environment variables. The in-app configuration takes precedence over environment variables except for the following settings:

  • INSTANA_SERVICE_NAME: Allows to override the service name set in the code.
  • INSTANA_PROCESS_NAME: Allows to override the name for the infrastructure entity that represents the Go process.
  • INSTANA_DEBUG: Enables debug logs even if the app code configuration defines a higher logging level.
  • INSTANA_AUTO_PROFILE: Enables continuous profiling with AutoProfile™.
  • INSTANA_LOG_LEVEL: Allows specifying the log level. Possible values are debug, error, warn, and info. The INSTANA_DEBUG environment variable takes precedence if set.
  • INSTANA_KAFKA_HEADER_FORMAT: Enables users to specify the format of Kafka headers propagated by Instana. Possible values are binary (legacy), string (new format) and both.
  • INSTANA_ALLOW_ROOT_EXIT_SPAN: Determines whether the tracer starts a trace with an exit span or not.
    • If you set the value to 1, the tracer records exit spans for the outgoing calls in instances with no parent entry span.
    • If you set 0 or any other value, the tracer does not start a trace with an exit span.
  • INSTANA_TRACING_DISABLE: Disables the span collection for the specified category (currently only logging category is supported).
  • INSTANA_CONFIG_PATH: Enables the user to specify the path for the configuration file to disable the collection of categories of spans (currently only logging category is supported).

For more information, see Configuration.

Features

Edit online

Runtime metrics

Edit online

The following metrics are collected and displayed on the Go process dashboard:

  • Memory usage
  • Heap usage
  • GC activity
  • Goroutines

Health signatures

Edit online

The following key indicators determine the health of Go applications:

  • Calls
  • Response time
  • Scaling

Tracers logs

Edit online

The Go Collector uses a leveled logger to log internal errors and diagnostic information. The default logger.Logger uses log.Logger configured with log.Lstdflags as a backend and writes messages to os.Stderr. By default, this logger only prints out the ERROR level messages unless the environment variable INSTANA_DEBUG is set.

To change the min log level in runtime it is recommended to configure and inject an instance of instana.LeveledLogger:

l := logger.New(log.New(os.Stderr, "", os.Lstdflags))
instana.SetLogger(l)

// ...

l.SetLevel(logger.WarnLevel)

The logger.LeveledLogger interface is implemented by such popular logging libraries as github.com/sirupsen/logrus and go.uber.org/zap , so they can be used as a replacement.

Alternatively, since version 1.39.0 of the Go sensor, the INSTANA_LOG_LEVEL environment variable can be used to set the log level.

Note: the value of INSTANA_DEBUG environment variable does not affect custom loggers. You'd need to explicitly check whether it's set and enable the debug logging while configuring your logger:

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

func main() {
        // initialize Instana sensor
        instana.InitSensor(&instana.Options{Service: SERVICE})

        // initialize and configure the logger
        logger := logrus.New()
        logger.Level = logrus.InfoLevel

        // check if INSTANA_DEBUG is set and set the log level to DEBUG if needed
        if _, ok := os.LookupEnv("INSTANA_DEBUG"); ok {
                logger.Level = logrus.DebugLevel
        }

        // use logrus to log the Instana Go Collector messages
        instana.SetLogger(logger)

        // ...
}

Disabling spans

Edit online

The Go collector supports disabling collection of spans at the tracer level. This feature helps to reduce the volume of span data that is collected and processed.

Note: Currently, this feature supports only the disabling of log spans through configuration.

You can disable collection of spans in four ways, and they are applied in the following decreasing order of precedence:

  1. Configuration file (INSTANA_CONFIG_PATH)
  2. Environment variable (INSTANA_TRACING_DISABLE)
  3. Code-level configuration
  4. Agent configuration

For more information about disabling spans, see Disabling spans.

Instana AutoProfile™

Edit online

Profiles are essential for locating performance hot spots and bottlenecks at the code level. They are instrumental in reducing resource consumption and improving performance.

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.

To enable AutoProfile™ add EnableAutoProfile: true option in instana.InitSensor(opt). For detailed instructions, see github.com/instana/go-sensor. If you need to enable profiling for an app instrumented with Instana without changing the instana.InitSensor() config, set INSTANA_AUTO_PROFILE=true env variable. Note that this value takes precedence and overrides any attempt to disable profiling from inside the application code.

For more information, see our Instana AutoProfile™ docs.

Troubleshooting

Edit online

The Go Collector might encounter issues during operation that can affect monitoring capabilities. Common problems include outdated Go runtimes and configuration issues.

For detailed information on diagnosing and resolving issues with the Go Collector, see Troubleshooting.