Go

This guide walks you through setting up Application Performance Monitoring (APM) on a Go application. You can also check the Installation page in your Middleware Account for these instructions. To test the Go APM feature, use this example code.

Prerequisites

Before you start, make sure you have:

go version

Installation steps

Step 1: Install the Middleware.io Go APM Tracker Package

This command fetches the core Middleware.io APM SDK for Go and adds it to your project's dependencies.

main.go

Go

go get github.com/middleware-labs/golang-apm@latest

Step 2: Import Tracker

Add the following lines to the entry point of your application, and as the first import.

main.go

Go

import (
    track "github.com/middleware-labs/golang-apm/tracker"
)

Add the following snippet to your main function. The accessToken is your account key, which will be pre-filled if you're logged into the documentation. It may also be found on the Installation page in the platform.

Step 3: Install framework-specific instrumentation (if applicable)

If your application uses a supported web framework, you should install the corresponding Middleware.io instrumentation package for automatic tracing of HTTP requests.

Gin/Gonic

Gorilla/Mux

The Middleware APM requires Gin v1.1.18 or higher. Install the Gin instrumentation package in three steps:

a. Install the Middleware APM Gin package.

main.go

Go

go get github.com/middleware-labs/golang-apm-gin@latest

b. Add the Middleware APM Gin package to the existing import statement from Step 2.

main.go

Go

import (
    track "github.com/middleware-labs/golang-apm/tracker"
    mwgin "github.com/middleware-labs/golang-apm-gin/gin"
)

c. Initialize the Middleware APM wherever the Gin package is initialized, typically in the main function.

Your API Keys

r := gin.Default()
config, _ := track.Track(
    track.WithConfigTag("service","<apm-service-name>"),
    track.WithConfigTag("accessToken","<MW_API_KEY>"),
)
r.Use(mwgin.Middleware(config))

The Middleware APM requires MUX v1.8.0. Install the Mux package in three steps:

a. Install the Middleware APM MUX package.

main.go

Go

go get github.com/middleware-labs/golang-apm-mux@latest

b. Add the Middleware APM MUX package to the existing import statement from Step 2.

main.go

Go

import (
    track "github.com/middleware-labs/golang-apm/tracker"
    mwmux "github.com/middleware-labs/golang-apm-mux/mux"
)

c. Initialize the Middleware APM wherever the MUX package is initialized, typically in the main function.

Your API Keys

r := mux.newRouter()
config, _ := track.Track(
    track.WithConfigTag("service", "<apm-service-name>"),
    track.WithConfigTag("accessToken", "<MW_API_KEY>"),
)
r.Use(mwmux.Middleware(config))

Step 4: Initialize the Middleware.io APM Tracker

You need to add code to your application's main function to initialize the Middleware.io APM tracker. This setup configures the global OpenTelemetry provider that the agent uses.

package main

import (
	"log"
	"net/http"
	"os" // Import os to read environment variables

	track "[github.com/middleware-labs/golang-apm/tracker](https://github.com/middleware-labs/golang-apm/tracker)"
	mwgin "[github.com/middleware-labs/golang-apm-gin/gin](https://github.com/middleware-labs/golang-apm-gin/gin)" // Only if using Gin
	"[github.com/gin-gonic/gin](https://github.com/gin-gonic/gin)"                           // Only if using Gin

track.Track(...) initializes the Middleware.io OpenTelemetry SDK. It must be called once at the very start of your application's main function, ideally before any other application logic that might generate telemetry. defer config.Shutdown() defers the Shutdown() method. This ensures that any buffered telemetry data is flushed to the Middleware.io backend before your application exits. Without this, some data might be lost.

Step 5: Build and Run Your Application

After making the code changes, build your Go application.

go build -o myapp .

go build compiles your Go source files and packages. -o myapp specifies the output file name for the executable. In this case, it will create an executable named myapp. . indicates that you want to build the package in the current directory.

Typically, go build produces no output on success. If there are compilation errors, they will be shown here.

Now, run your built application. Remember to set the required environment variables first.

export MW_SERVICE_NAME="my-go-gin-app"
export MW_API_KEY="your_actual_api_key_from_middleware_dashboard"
export MW_TARGET="https://your_middleware_uid.middleware.io:443"
export MW_ENVIRONMENT="development" # Optional
export MW_LOG_LEVEL="DEBUG" # Optional, for detailed agent logs
export MW_CONSOLE_EXPORTER=true # Optional, for seeing telemetry in console

./myapp

export MW_SERVICE_NAME=... sets environment variables that the Middleware.io Go agent will read during initialization. ./myapp executes the compiled application.

Expected Output (when running, especially with MW_LOG_LEVEL=DEBUG and MW_CONSOLE_EXPORTER=true):

# ... (standard Go application startup logs) ...
[DEBUG] Initializing Middleware APM Go Tracker...
[DEBUG] APM Tracker initialized successfully for service: my-go-gin-app
[DEBUG] OTLP Trace Exporter configured to: https://your_middleware_uid.middleware.io:443
[DEBUG] OTLP Metrics Exporter configured to: https://your_middleware_uid.middleware.io:443
[DEBUG] OTLP Log Exporter configured to: https://your_middleware_uid.middleware.io:443
[DEBUG] Continuous Profiling enabled.
[DEBUG] Console exporter enabled. Telemetry will be printed to stdout.
# ... (Gin startup logs) ...
[GIN-debug] GET    /hello                    --> main.func1 (3 handlers)

If you are deploying the host using Kubernetes or Docker, you will need to set the environment variable MW_AGENT_SERVICE. Ignore this variable if the agent is running on the same host as the application.

Docker

Kubernetes

Add MW_AGENT_SERVICE environment variable to your application:

Shell

docker run \
  -e MW_AGENT_SERVICE=<DOCKER_BRIDGE_GATEWAY_ADDRESS> \
  -p 8000:8000 -it --rm --name CONTAINER_NAME DOCKER_IMAGE:IMAGE_TAG

The DOCKER_BRIDGE_GATEWAY_ADDRESS is the IP address of the gateway between the Docker host and bridge network. This is 172.17.0.1 by default. Learn more about Docker bridge networking here

Identify the namespace where the Infra Agent is running:

Shell

kubectl get service --all-namespaces | grep mw-service

Then add the following environment variable to your application deployment YAML file:

Shell

MW_AGENT_SERVICE=mw-service.mw-agent-ns.svc.cluster.local

Step 6: Verifying Data Ingestion

Once your application is running with the Middleware.io agent and processing requests, allow a few minutes for the data to appear in your Middleware.io dashboard.

• Log in to your Middleware.io Dashboard.
• Navigate to the "APM" section.
• Find your application using the MW_SERVICE_NAME you configured (e.g., my-go-gin-app or my-docker-go-app).
• Explore the different views: Service Overview, Traces, Metrics, Logs, and Profiling (if enabled).

To further configure the installed Go APM (e.g., send custom traces and logs, and customize the APM's behaviour using environment variables), follow the steps in the configuration page.