Go (Golang) Monitoring Guide: Metrics, Tracing & Alerts (2026)

// go.mod
// require github.com/prometheus/client_golang v1.19.0

package main

import (
    "net/http"
    "github.com/prometheus/client_golang/prometheus"
    "github.com/prometheus/client_golang/prometheus/promhttp"
    "github.com/prometheus/client_golang/prometheus/promauto"
)

var (
    httpRequestsTotal = promauto.NewCounterVec(
        prometheus.CounterOpts{
            Name: "http_requests_total",
            Help: "Total HTTP requests",
        },
        []string{"method", "path", "status"},
    )

    httpRequestDuration = promauto.NewHistogramVec(
        prometheus.HistogramOpts{
            Name:    "http_request_duration_seconds",
            Help:    "HTTP request latency",
            Buckets: []float64{.005, .01, .025, .05, .1, .25, .5, 1, 2.5, 5},
        },
        []string{"method", "path"},
    )

    goroutineCount = promauto.NewGaugeFunc(
        prometheus.GaugeOpts{
            Name: "go_goroutine_count",
            Help: "Current number of goroutines",
        },
        func() float64 { return float64(runtime.NumGoroutine()) },
    )
)

func metricsMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        start := time.Now()
        rw := &statusRecorder{ResponseWriter: w, status: 200}
        next.ServeHTTP(rw, r)
        duration := time.Since(start).Seconds()
        httpRequestsTotal.WithLabelValues(r.Method, r.URL.Path, strconv.Itoa(rw.status)).Inc()
        httpRequestDuration.WithLabelValues(r.Method, r.URL.Path).Observe(duration)
    })
}

func main() {
    mux := http.NewServeMux()
    mux.Handle("/metrics", promhttp.Handler())
    mux.Handle("/", metricsMiddleware(yourHandler))
    http.ListenAndServe(":8080", mux)
}

import _ "net/http/pprof"
// This registers /debug/pprof/* routes on the default ServeMux

// Available profiles:
// /debug/pprof/           — index
// /debug/pprof/goroutine  — all goroutine stacks
// /debug/pprof/heap       — heap memory allocations
// /debug/pprof/profile    — 30s CPU profile
// /debug/pprof/allocs     — memory allocation trace
// /debug/pprof/threadcreate — OS thread creation
// /debug/pprof/block      — goroutine blocking

// Capture and analyze a heap profile:
go tool pprof http://localhost:6060/debug/pprof/heap

# Inside pprof interactive mode:
(pprof) top10          # top 10 allocating functions
(pprof) web            # open flame graph in browser
(pprof) list main.Foo  # show source-level allocation detail

# Capture a 30-second CPU profile:
go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30

# Capture all goroutine stacks (great for leak diagnosis):
curl http://localhost:6060/debug/pprof/goroutine?debug=2 > goroutines.txt

// Prometheus alert rule for goroutine leak
groups:
  - name: golang
    rules:
      - alert: GoroutineLeak
        expr: |
          rate(go_goroutines[30m]) > 10
        for: 30m
        labels:
          severity: warning
        annotations:
          summary: "Goroutine count growing — possible goroutine leak"
          description: "{{ $value }} goroutines/min growth rate"

      - alert: GoroutinesHigh
        expr: go_goroutines > 10000
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "Goroutine count above 10,000"

# When this fires, capture a goroutine dump:
# curl http://internal-host:6060/debug/pprof/goroutine?debug=2 > dump.txt
# grep -c "goroutine" dump.txt  # count
# grep -A 20 "goroutine 12345"  # inspect specific goroutine

// go get go.uber.org/goleak
package mypackage_test

import (
    "testing"
    "go.uber.org/goleak"
)

func TestMain(m *testing.M) {
    // Assert no goroutines leak after tests complete
    goleak.VerifyTestMain(m)
}

func TestMyHandler(t *testing.T) {
    defer goleak.VerifyNone(t)  // Check at end of this specific test
    // ... your test code
}

// go get go.opentelemetry.io/otel
// go get go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp

package main

import (
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
    "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

func initTracer(ctx context.Context) func() {
    exporter, _ := otlptracehttp.New(ctx,
        otlptracehttp.WithEndpoint("otel-collector:4318"),
        otlptracehttp.WithInsecure(),
    )
    tp := sdktrace.NewTracerProvider(
        sdktrace.WithBatcher(exporter),
        sdktrace.WithSampler(sdktrace.AlwaysSample()), // 100% in dev; use ParentBased in prod
    )
    otel.SetTracerProvider(tp)
    return func() { tp.Shutdown(ctx) }
}

// Auto-instrument HTTP server:
mux.Handle("/api/", otelhttp.NewHandler(yourHandler, "api"))

// Manual span for a critical operation:
tracer := otel.Tracer("myapp")
ctx, span := tracer.Start(ctx, "database.Query")
defer span.End()
span.SetAttributes(attribute.String("db.query", query))
rows, err := db.QueryContext(ctx, query)
if err != nil {
    span.RecordError(err)
    span.SetStatus(codes.Error, err.Error())
}

groups:
  - name: go-app
    rules:
      # Service is down
      - alert: GoServiceDown
        expr: up{job="myapp"} == 0
        for: 1m
        labels: { severity: critical }
        annotations:
          summary: "Go service {{ $labels.instance }} is down"

      # High error rate
      - alert: GoHighErrorRate
        expr: |
          rate(http_requests_total{status=~"5.."}[5m]) /
          rate(http_requests_total[5m]) > 0.01
        for: 5m
        labels: { severity: critical }
        annotations:
          summary: "HTTP error rate > 1%"

      # Slow p95 latency
      - alert: GoSlowP95Latency
        expr: |
          histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m])) > 2
        for: 5m
        labels: { severity: warning }
        annotations:
          summary: "p95 request latency > 2 seconds"

      # GC taking too long
      - alert: GoGCPauseHigh
        expr: |
          histogram_quantile(0.99, rate(go_gc_duration_seconds_bucket[5m])) > 0.01
        for: 5m
        labels: { severity: warning }
        annotations:
          summary: "GC p99 pause > 10ms — check allocation rate"

      # Goroutine leak
      - alert: GoGoroutineLeak
        expr: go_goroutines > 10000
        for: 5m
        labels: { severity: critical }
        annotations:
          summary: "Goroutine count > 10,000 — investigate for leaks"

      # Memory pressure
      - alert: GoHighMemory
        expr: process_resident_memory_bytes > 1e9  # 1GB
        for: 5m
        labels: { severity: warning }
        annotations:
          summary: "Go process using > 1GB RSS"