Golang - Middleware Docs

Traces	Metrics	App Logs	Custom Logs	Profiling
✅	✅	✖️	✅	✅

This guide walks you through setting up Application Performance Monitoring (APM) on a Go programming language (Golang) application. These instructions can also be found on the Installation page in your Middleware Account. View example code here.

Prerequisites

The Middleware Host Agent (MW Agent). To install the MW Agent please see our installation guides .
One of the two latest Golang stable releases. Check Golang’s docs for details. You can check your Golang version with the following command.

Shell

go version

Step 1: Install Golang package

Run the following command in your terminal.

Golang

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

Step 2: Import Tracker

Add the following lines to the beginning of your application code base.

Golang

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

Add the following snippet to your main function. The access token is your account key, which can be found on the Installation page. If using a Golang web framework, additional code may be required, see Step 3.

Golang

go track.Track(
    track.WithConfigTag("service", {APM-SERVICE-NAME}),
    track.WithConfigTag("projectName", {APM-PROJECT-NAME}),
    track.WithConfigTag("accessToken", "<xxxxxxxxxx>"),
)

Step 3: Framework-Specific Configuration

If any of the following Golang web frameworks are used in your application additional configuration is required. View additional configuration steps per framework below.

Framework
gin/gonic	gorilla/mux	go-chi	go-chi/v5	astaxie-beego	beego/v2	database/sql
go-pg/pg	GORM 1	GORM 2	go-pg/mongo	gRPC

gin/gonic

Middleware APM requires Gin version 1.1.18 or higher.

Install the Middleware APM Gin package.

Golang

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

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

Golang

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

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

Golang

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

gorilla/mux

Middleware APM requires MUX version 1.8.0

Install the Middleware APM MUX package.

Golang

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

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

Golang

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

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

Golang

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

go-chi

Middleware APM requires go-chi/chi version 1.5.4 or higher.

Install the Middleware APM go-chi package.

Golang

go get github.com/middleware-labs/agent-apm-go-chi-legacy

Add the Middleware APM go-chi package to the existing import statement from Step 2.

Golang

import (
     track "github.com/middleware-labs/golang-apm/tracker"
     mwchi "github.com/middleware-labs/agent-apm-go-chi-legacy"
)

Initialize the Middleware APM wherever the go-chi package is initialized, typically in the main function.

Golang

config, _ := track.Track(
     track.WithConfigTag("service", "<apm-service-name>"),
     track.WithConfigTag("projectName", "<apm-service-name>"),
     track.WithConfigTag("accessToken", "<xxxxxxxxxx>"),
)
r := chi.NewRouter()
r.Use(mwchi.Middleware("<my-server>", mwchi.WithChiRoutes(r)))

go-chi/v5

Middleware APM requires go-chi/chi/v5 version 5.0.8 or higher.

Install the Middleware APM go-chi package.

Golang

go get github.com/middleware-labs/agent-apm-go-chi

Add the Middleware APM go-chi package to the existing import statement from Step 2.

Golang

import (
     track "github.com/middleware-labs/golang-apm/tracker"
     mwchi "github.com/middleware-labs/agent-apm-go-chi"
)

Initialize the Middleware APM wherever the go-chi package is initialized, typically in the main function.

Golang

config, _ := track.Track(
     track.WithConfigTag("service", "<apm-service-name>"),
     track.WithConfigTag("projectName", "<apm-service-name>"),
     track.WithConfigTag("accessToken", "<xxxxxxxxxx>"),
)
r := chi.NewRouter()
r.Use(mwchi.Middleware("<my-server>", mwchi.WithChiRoutes(r)))

astaxie-beego

Middleware APM requires astaxie/beego version 1.12.3 or higher.

Install the Middleware APM astaxie-beego package.

Golang

go get github.com/middleware-labs/golang-apm-beego

Add the Middleware APM astaxie-beego package to the existing import statement from Step 2.

Golang

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

Initialize the Middleware APM wherever the astaxie-beego package is initialized, typically in the main function.

Golang

config, _ := track.Track(_
     track.WithConfigTag("service", "<apm-service-name>"),
     track.WithConfigTag("projectName", "<apm-service-name>"),
     track.WithConfigTag("accessToken", "<xxxxxxxxxx>"),
)
mware := mw_beego.Middleware(config)

beego/v2

Middleware APM requires beego/v2 version 2.0.7 or higher.

Install the Middleware APM astaxie-beego package.

Golang

go get github.com/middleware-labs/golang-apm-beego

Add the Middleware APM astaxie-beego package to the existing import statement from Step 2.

Golang

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

Initialize the Middleware APM wherever the astaxie-beego package is initialized, typically in the main function.

Golang

config, _ := track.Track(_
     track.WithConfigTag("service", "<apm-service-name>"),
     track.WithConfigTag("projectName", "<apm-service-name>"),
     track.WithConfigTag("accessToken", "<xxxxxxxxxx>"),
)
mware := mw_beego.Middleware(config)

database/sql

Middleware APM requires go-sql-driver/mysql version 1.7.1 or higher.

Install the Middleware APM SQL package.

Golang

go get github.com/middleware-labs/golang-apm-sql

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

Golang

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

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

Golang

config, _ := track.Track(
     track.WithConfigTag("service", "<apm-service-name>"),
     track.WithConfigTag("projectName", "<apm-service-name>"),
     track.WithConfigTag("accessToken", "<xxxxxxxxxx>"),
)
db, err := mw_sql.Open("mysql", "uname:password@tcp(127.0.0.1:3306)/todo")

go-pg/pg

Middleware APM requires go-pg/pg version 10.11.1 or higher.

Install the Middleware APM PG package.

Golang

go get github.com/middleware-labs/golang-apm-pg

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

Golang

import (
     "github.com/go-pg/pg/v10"
          track "github.com/middleware-labs/golang-apm/tracker"
          mw_pg "github.com/middleware-labs/golang-apm-pg/pg"
)

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

Golang

config, _ := track.Track(_
     track.WithConfigTag("service", "<apm-service-name>"),
     track.WithConfigTag("projectName", "<apm-service-name>"),
     track.WithConfigTag("accessToken", "<xxxxxxxxxx>"),
)
db := pg.Connect(&pg.Options{
               Addr:      ":5432",
               User:      "postgres",
               Password:  "postgres",
               Database:  "dbname",
          })
mw_pg.AddQueryHook(db)

GORM 1

Middleware APM requires jinzhu/gorm version 1.9.16 or higher.

Install the Middleware APM SQL package.

Golang

go get github.com/middleware-labs/golang-apm-sql

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

Golang

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

Initialize the Middleware APM inside the main function.

Golang

config, _ := track.Track(_
     track.WithConfigTag("service", "<apm-service-name>"),
     track.WithConfigTag("projectName", "<apm-service-name>"),
     track.WithConfigTag("accessToken", "<xxxxxxxxxx>"),
)
db, err := mw_sql.Open(driverName, dataSourceName, mw_sql.WithDBName(dbname), mw_sql.WithAttributes(tracker.String("db.system","mysql")))

GORM 2

Middleware APM requires gorm.io/gorm version 1.25.1 or higher.

Install the Middleware APM GORM package.

Golang

go get github.com/middleware-labs/go-agent-gorm

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

Golang

import (
     "gorm.io/gorm"
     "gorm.io/driver/mysql"
          track "github.com/middleware-labs/golang-apm/tracker"
          mw_gorm "github.com/middleware-labs/go-agent-gorm/gorm"
)

Initialize the Middleware APM inside the main function.

Golang

config, _ := track.Track(_
     track.WithConfigTag("service", "<apm-service-name>"),
     track.WithConfigTag("projectName", "<apm-service-name>"),
     track.WithConfigTag("accessToken", "<xxxxxxxxxx>"),
)
db, err := gorm.Open(mysql.Open("username:password@tcp(127.0.0.1:3306)/dbname"), &gorm.Config{})
if err != nil {
     panic(err)
}
if err := db.Use(mw_gorm.NewPlugin(mw.gorm.WithDBName("dbname"), mw_gorm.WithAttributes(track.String("db.system", "mysql")))); err != nil {
     panic(err)
}

Then use db.WithContext(ctx) to propagate the active span.

Golang

var num int
if err := db.WithContext(ctx).Raw("SELECT 42").Scan(&num).Error; err != nil {
     panic(err)
}

go-pg/mongo

Middleware APM requires go.mongodb.org/mongo-driver version 1.12.1 or higher.

Install the Middleware APM Mongo package.

Golang

go get github.com/middleware-labs/golang-apm-mongo

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

Golang

import (
     "go.mongodb.org/mongo-driver/mongo/options"

     track "github.com/middleware-labs/golang-apm/tracker"
     mw_mongo "github.com/middleware-labs/golang-apm-mongo/mongo"
)

Initialize the Middleware APM inside the main function.

Golang

config, _ := track.Track(_
     track.WithConfigTag("service", "<apm-service-name>"),
     track.WithConfigTag("projectName", "<apm-service-name>"),
     track.WithConfigTag("accessToken", "<xxxxxxxxxx>"),
)
opts := options.Client()
opts.Monitor = mw_mongo.NewMonitor()

gRPC

Middleware APM requires google.golang.org/grpc version 1.53.0 or higher.

Install the Middleware APM gRPC package.

Golang

go get github.com/middleware-labs/golang-apm-grpc

Add the Middleware APM astaxie-beego package to the existing import statement from Step 2.

Golang

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

Initialize the Middleware APM wherever the astaxie-beego package is initialized, typically in the main function.

Golang

config, _ := track.Track(_
     track.WithConfigTag("service", "<apm-service-name>"),
     track.WithConfigTag("projectName", "<apm-service-name>"),
     track.WithConfigTag("accessToken", "<xxxxxxxxxx>"),
)
mware := mwbeego.MiddleWare(config.ServiceName)

Step 4: Container Variables

Applications running in a container require an additional environment variable. If your application is not running in a container, move to Step 5.

For Docker containers, add the following environment variable to your application.

Shell

MW_AGENT_SERVICE=DOCKER_BRIDGE_GATEWAY_ADDRESS

docker bridge gateway address is the IP address of the gateway between the Docker host and the bridge network, which is 172.17.0.1 by default. Refer more about Docker bridge networking here

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 5: Capture Application Data

Traces

Distributed tracing is automatically enabled upon completion of Step 2.

Custom Logs

To ingest custom logs into Middleware, utilize the following functions inside your logging method based on desired log severity levels.

Golang

"github.com/middleware-labs/golang-apm/logger"

....

logger.Error("Error")
logger.Info("Info")
logger.Warn("Warn")

Profiling

Application Profiling is auto-configured upon completing Step 2.

Stack Traces

Use the track.RecordError(ctx,error) method to record a stack trace when an error occurs. See an example of this method below.

Golang

app.get("/hello", (req, res) => {
    ctx := req.Context()
    try {
        throw ("error");
    } catch (error) {
        track.RecordError(ctx, error)
    }
})

Need assistance or want to learn more about Middleware? Contact us at support[at]middleware.io.

Middleware Docs

​Prerequisites

​Step 1: Install Golang package

​Step 2: Import Tracker

​Step 3: Framework-Specific Configuration

​gin/gonic

​gorilla/mux

​go-chi

​go-chi/v5

​astaxie-beego

​beego/v2

​database/sql

​go-pg/pg

​GORM 1

​GORM 2

​go-pg/mongo

​gRPC

​Step 4: Container Variables

​Step 5: Capture Application Data

​Traces

​Custom Logs

​Profiling

​Stack Traces

Prerequisites

Step 1: Install Golang package

Step 2: Import Tracker

Step 3: Framework-Specific Configuration

gin/gonic

gorilla/mux

go-chi

go-chi/v5

astaxie-beego

beego/v2

database/sql

go-pg/pg

GORM 1

GORM 2

go-pg/mongo

gRPC

Step 4: Container Variables

Step 5: Capture Application Data

Traces

Custom Logs

Profiling

Stack Traces