Go APM configuration

This guide shows you how to control the Middleware.io Go APM's behavior and extend its observability capabilities through configuration options and manual instrumentation.

Telemetry-related configuration

The Pause* options allow you to disable specific telemetry data (metrics, traces, logs) and profiling. Use these to reduce overhead by pausing unnecessary data collection.

PauseMetrics

If you want to disable metrics, you can use PauseMetrics, or you can set the environment variable MW_APM_COLLECT_METRICS to false.

track.WithConfigTag(track.PauseMetrics,true),

PauseDefaultMetrics

If you want to disable only default runtime metrics.

track.WithConfigTag(track.PauseDefaultMetrics,true),

PauseTraces

If you want to disable traces, you can use PauseTraces, or you can set the environment variable MW_APM_COLLECT_TRACES to false.

track.WithConfigTag(track.PauseTraces,true),

PauseLogs

If you want to disable logs, you can use PauseLogs, or you can set the environment variable MW_APM_COLLECT_LOGS to false.

track.WithConfigTag(track.PauseLogs,true),

PauseProfiling

If you want to disable Profiling, you can use PauseProfiling, or you can set the environment variable MW_APM_COLLECT_PROFILING to false.

track.WithConfigTag(track.PauseProfiling,true),

Debugging the Middleware Go APM

The debug option enables detailed logging of metrics, traces, and logs by printing structured telemetry data directly to the standard output. This mode is ideal for local development and troubleshooting, providing real-time insights into the application's execution and performance.

track.WithConfigTag(track.Debug,true),

Debug Log File

When DebugLogFile is enabled, structured telemetry data (metrics, traces, logs) is saved to files instead of being printed to the standard output. This allows for easier storage, analysis, and sharing of debug information without cluttering the console during development.

track.WithConfigTag(track.Debug,true),
track.WithConfigTag(track.DebugLogFile,true),

Sending Custom Data

You can manually create custom spans and transactions to capture more granular details of your application's operations.

Custom Logs

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

otellog "github.com/middleware-labs/golang-apm/mwotellogrus"
track "github.com/middleware-labs/golang-apm/tracker"
log "github.com/sirupsen/logrus"

....

config, _ := track.Track(
		track.WithConfigTag("service", "your-service-name"),
		track.WithConfigTag("accessToken", "access_token"),
  )

"log/slog"
"github.com/middleware-labs/golang-apm/mwotelslog"
track "github.com/middleware-labs/golang-apm/tracker"
....

config, _ := track.Track(
		track.WithConfigTag("service", "your-service-name"),
		track.WithConfigTag("accessToken", "access_token"),
  )
defer func() {

mwotelzap "github.com/middleware-labs/golang-apm/mwotelzap"
track "github.com/middleware-labs/golang-apm/tracker"

"go.uber.org/zap"
"go.uber.org/zap/zapcore"
....

config, _ := track.Track(
		track.WithConfigTag("service", "your-service-name"),
		track.WithConfigTag("accessToken", "access_token"),

Record Error

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

err := errors.New("something went wrong")
track.ErrorRecording(ctx, err)

Get Current Span

To get the current span, you’ll need to pull it out of a context.Context you have a handle on:

track.SpanFromContext(ctx)

Custom Spans

To create a span with a tracer, you'll need a context.Context instance, usually derived from a request object. This context may already carry a parent span from an existing instrumentation.

config,err := track.Track(
    track.WithConfigTag("service", {APM-SERVICE-NAME}),
    track.WithConfigTag("accessToken", "your-initial-token"),
)
tp := 	config.Tp
_,span := tp.Tracer("example-tracer").Start(ctx,"example-span")
defer span.End()

Custom Events

span.AddEvent("Starting to find books")

Custom Attributes

Attributes are keys and values that are applied as metadata to your spans and are useful for aggregating, filtering, and grouping traces. Attributes can be added at span creation, or at any other time during the lifecycle of a span before it has completed.

ctx := c.Request.Context()
track.SetAttribute(ctx, "user.id", "1")

Custom Resource Attributes

Resource attributes are key-value pairs that describe specific characteristics of a service or system component, like its name, version, or environment. These attributes help in tracking and analyzing the behavior of the resource in logs, metrics, or traces.

customResourceAttributes = map[string]interface{}{
		"key1": "value1",
		"key2": 42,
		"key3": true,
}

track.WithConfigTag(track.CustomResourceAttributes,customResourceAttributes),

Framework-specific configuration

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

go-chi

Middleware APM requires go-chi/chi v1.5.4 or higher.

Install the Middleware APM go-chi package.

main.go

Go

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

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

main.go

Go

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.

Your API Keys

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

go-chi/v5

Middleware APM requires go-chi/chi/v5 v5.0.8 or higher.

Install the Middleware APM go-chi package.

main.go

Go

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

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

main.go

Go

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.

Your API Keys

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

astaxie-beego

Middleware APM requires astaxie/beego v1.12.3 or higher.

Install the Middleware APM astaxie-beego package.

main.go

Go

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

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

main.go

Go

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.

Your API Keys

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

beego/v2

Middleware APM requires beego/v2 v2.0.7 or higher.

Install the Middleware APM astaxie-beego package.

main.go

Go

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

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

main.go

Go

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.

Your API Keys

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

database/sql

Middleware APM requires go-sql-driver/mysql v1.7.1 or higher.

Install the Middleware APM SQL package.

main.go

Go

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

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

main.go

Go

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.

Your API Keys

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

go-pg/pg

Middleware APM requires go-pg/pg v10.11.1 or higher.

Install the Middleware APM PG package.

main.go

Go

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

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

main.go

Go

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.

Your API Keys

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

View more

jinzhu/gorm

Middleware APM requires jinzhu/gorm v1.9.16 or higher.

Install the Middleware APM SQL package.

main.go

Go

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

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

main.go

Go

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.

Your API Keys

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

gorm.io/gorm

Middleware APM requires gorm.io/gorm v1.25.1 or higher.

Install the Middleware APM GORM package.

main.go

Go

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

To instrument GORM, you need to install the plugin

main.go

Go

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

track.Track(
    track.WithConfigTag("service", "<apm-service-name>"),
    track.WithConfigTag("accessToken", "<MW_API_KEY>"),

View more

Your API Keys

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

main.go

Go

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

mongo

Middleware APM requires go.mongodb.org/mongo-driver v1.12.1 or higher.

Install the Middleware APM Mongo package.

main.go

Go

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

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

main.go

Go

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.

Your API Keys

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

gRPC

Middleware APM requires google.golang.org/grpc v1.53.0 or higher.

Install the Middleware APM gRPC package.

main.go

Go

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

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

main.go

Go

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

Initialize the Middleware APM wherever the grpc server is initialized, typically in the main function.

Your API Keys

track.Track(
    track.WithConfigTag("service", "<apm-service-name>"),
    track.WithConfigTag("accessToken", "<MW_API_KEY>"),
)
server := grpc.NewServer(
		grpc.UnaryInterceptor(mw_grpc.UnaryServerInterceptor()),
		grpc.StreamInterceptor(mw_grpc.StreamServerInterceptor()))

Initialize the Middleware APM wherever the grpc client is initialized, typically in the main function.

Your API Keys

config, err := track.Track(
    track.WithConfigTag("service", "<apm-service-name>"),
    track.WithConfigTag("accessToken", "<MW_API_KEY>"),
)
if err != nil {
   fmt.Println("err", err)
}
	
defer func() {
	if err := config.Tp.Shutdown(context.Background()); err != nil {

View more

net/http

Install the Middleware APM net/http package.

main.go

Go

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

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

main.go

Go

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

The code snippet below initializes Middleware Go APM package and shows how to use it with net/http.

Your API Keys

go track.Track(
    track.WithConfigTag(track.Service, "your service name"),
    track.WithConfigTag(track.Token, "your access token"),
)
http.Handle("/hello", mwhttp.MiddlewareHandler(http.HandlerFunc(hello), "hello"))