Metrics

Monitor your application with Prometheus-compatible metrics. Track HTTP requests, custom counters, gauges, histograms, and Go runtime stats — all without external dependencies.

Prometheus Metrics

Nimbus includes a full Prometheus-compatible metrics system with Counter, Gauge, and Histogram types. Metrics are exposed in the standard Prometheus text format at /metrics.

Counter

A monotonically increasing value (e.g. total requests, errors):

import "github.com/CodeSyncr/nimbus/metrics"

// Create and register a counter
requestCounter := metrics.NewCounter("http_requests_total", "Total HTTP requests")
metrics.DefaultRegistry.Register(requestCounter)

// Increment (no labels)
requestCounter.Inc(nil)

// Increment with labels
requestCounter.Inc(metrics.Labels{"method": "GET", "path": "/api/users"})

// Add arbitrary value
requestCounter.Add(5, metrics.Labels{"method": "POST"})

Gauge

A value that can go up or down (e.g. active connections, queue depth):

inFlight := metrics.NewGauge("http_requests_in_flight", "Active HTTP requests")
metrics.DefaultRegistry.Register(inFlight)

inFlight.Inc(nil)   // +1
inFlight.Dec(nil)   // -1
inFlight.Set(42, nil) // Set exact value
inFlight.Add(10, metrics.Labels{"handler": "api"})

Histogram

Tracks distribution of values (e.g. request duration, response sizes):

duration := metrics.NewHistogram("http_request_duration_seconds", "Request duration",
    metrics.DefaultBuckets, // {0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10}
)
metrics.DefaultRegistry.Register(duration)

// Observe a value
duration.Observe(0.042, metrics.Labels{"method": "GET", "path": "/api/users"})

Exposing /metrics endpoint

Mount the built-in handler to serve Prometheus text format:

import "github.com/CodeSyncr/nimbus/metrics"

// Use the default registry handler
app.Router.Handle("/metrics", metrics.Handler())

HTTP Metrics Middleware

Automatically track request count, duration, in-flight requests, and response size:

import "github.com/CodeSyncr/nimbus/middleware"

app.Router.Use(middleware.Metrics())

// This automatically registers and tracks:
// - http_requests_total (counter) — labels: method, path, status
// - http_request_duration_seconds (histogram) — labels: method, path, status
// - http_requests_in_flight (gauge)
// - http_response_size_bytes (counter) — labels: method, path, status

Runtime Metrics

Read Go runtime stats for goroutines, heap, and GC:

import "github.com/CodeSyncr/nimbus/metrics"

stats := metrics.ReadRuntimeStats()
// stats.Goroutines  — Active goroutine count
// stats.HeapAlloc   — Current heap allocation (bytes)
// stats.HeapSys     — Total heap obtained from OS (bytes)
// stats.NumGC       — Completed GC cycles
// stats.HeapObjects — Allocated heap objects

Available Runtime Metrics

Real-Life Example: Custom Business Metrics

// Track business metrics alongside HTTP metrics
var (
    ordersCreated = metrics.NewCounter("orders_created_total", "Total orders created")
    orderRevenue  = metrics.NewCounter("order_revenue_dollars", "Total revenue in dollars")
    cartSize      = metrics.NewGauge("cart_items_current", "Current items in all carts")
)

func init() {
    metrics.DefaultRegistry.Register(ordersCreated)
    metrics.DefaultRegistry.Register(orderRevenue)
    metrics.DefaultRegistry.Register(cartSize)
}

func CreateOrder(c *http.Context) error {
    // ... create order ...
    ordersCreated.Inc(metrics.Labels{"type": order.Type})
    orderRevenue.Add(order.Total, metrics.Labels{"currency": "USD"})
    return c.JSON(201, order)
}

Integration with Monitoring

Expose the /metrics endpoint and configure your monitoring tool to scrape it:

• Prometheus — Add a scrape target pointing to /metrics (native text format)
• Grafana — Create dashboards from Prometheus data sources
• Datadog/New Relic — Use the Prometheus endpoint or JSON runtime stats
• Uptime monitors — Use alongside /health for full observability