Monitoring Go

Supported runtimes

Go Collector v1.70 or later supports Go 1.24 and 1.25, and maintains compatibility with Go 1.23 (EOL).

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

Supported processor architectures and operating systems

The Go collector is compatible with and officially supported on the following environments:

Supported frameworks and libraries

To avoid adding unnecessary dependencies, Instana main github.com/instana/go-sensor module provides only instrumentation for packages that are a part of the Go standard library. Third-party package instrumentations are provided as separate modules found in github.com/instana/go-sensor/instrumentation/... and need to be added to go.mod separately.

Trace continuity is not applicable to database and logging libraries.

Runtime Metrics

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

• Memory usage
• Heap usage
• GC activity
• Goroutines

Health Signatures

The following key indicators determine the health of Go applications:

• Calls
• Response time
• Scaling

Tracers Logs

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)

	// ...
}

Generic serverless agent

To monitor Go applications in a serverless environment, such as AWS Lambda, or on a server without a host agent, instrument the application with the Instana Go Tracer SDK, deploy it, and set the INSTANA_ENDPOINT_URL and INSTANA_AGENT_KEY environment variables.

In this generic serverless agent setup, only traces are available, and not metrics. However, for specific serverless services, such as AWS Lambda or Fargate, Instana also collects metrics and correlates infrastructure.

For more information about particular serverless services, see the following list.

AWS Fargate

Instana Go collector automatically detects if a service is running on AWS Fargate when running in a serverless mode.

Google Cloud Run

Instana Go collector automatically detects if a service is running on Google Cloud Run when running in a serverless mode.

AWS Lambda

Instana Go Collector supports tracing AWS Lambda function written in Go starting from v1.23.0. Handlers need to be instrumented using the github.com/instana/go-sensor/instrumentation/instalambda package in order to collect and send trace data. Please refer to AWS Lambda Go documentation for details.

Azure function

Instana Go Collector supports the tracing of Azure functions that are written in Go. Handlers need to be instrumented by using the github.com/instana/go-sensor/instrumentation/instaazurefunction package to collect and send trace data. For more information, see Azure Functions Tracing for Go.

Azure Container Apps

The Instana Go Collector supports tracing of Go applications that are deployed in Azure Container Apps. To enable tracing, instrument your application with the Instana Go Tracer SDK, deploy it to Azure Container Apps, and ensure that the required environment variables are set. For more information, see Monitoring Azure Container Apps.

Kubernetes and OpenShift

If your Go application and the Instana agent run in a Kubernetes cluster, check the documentation on Kubernetes network access for information about the required configuration in this setup.

Outdated Go runtime

Monitoring issue type: outdated_go_runtime

To resolve this issue, update the Go runtime version to the latest one.