metrics

package
v0.0.22 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 20, 2024 License: Apache-2.0 Imports: 14 Imported by: 0

README

Metrics Package

The metrics package provides a quick and dirty way to collect and monitor application metrics in Go applications using the hop framework. It includes HTTP middleware for request metrics, memory statistics tracking, and a built-in metrics visualization dashboard. It's not meant to be a full-fledged monitoring solution but rather a simple way to get started with metrics collection. For more advanced use cases, consider using a dedicated monitoring tool like Prometheus or Grafana.

Features

  • Real-time metrics collection and monitoring
  • Built-in metrics dashboard with auto-refresh capabilities
  • HTTP middleware for request metrics
  • Memory, CPU, and disk usage tracking
  • Configurable thresholds for alerts
  • Optional pprof endpoints integration
  • JSON and HTML visualization formats

Quick Start

// Create a new metrics collector
collector := metrics.NewStandardCollector(
    metrics.WithServerName("MyApp"),
    metrics.WithThresholds(metrics.Thresholds{
        CPUPercent: 80.0,
        MemoryPercent: 85.0,
    }),
)

// Create and configure the metrics module
metricsMod := metrics.NewModule(collector, &metrics.Config{
    EnablePprof: !app.Config().IsProduction(),
    MetricsPath: "/metrics",  // Default path
    CollectionInterval: 15 * time.Second,  // Default interval
})

// Register with your application
app.RegisterModule(metricsMod)

// Add the middleware to collect HTTP metrics
app.Router().Use(metricsMod.Middleware())

Default Thresholds

The package comes with pre-configured default thresholds that can be customized:

var DefaultThresholds = metrics.Thresholds{
    CPUPercent:              75.0,  // Warning at 75% CPU usage
    ClientErrorRatePercent:  40.0,  // Higher threshold for 4xx errors
    DiskPercent:             85.0,  // Warning at 85% disk usage
    GCPauseMs:              100.0,  // 100ms pause time warning
    GoroutineCount:         1000,   // Warning at 1000 goroutines
    MaxGCFrequency:         100.0,  // Warning at >100 GCs/minute
    MemoryGrowthRatePercent: 20.0,  // Warning at 20% growth/minute
    MemoryPercent:           80.0,  // Warning at 80% memory usage
    ServerErrorRatePercent:   1.0,  // Very low tolerance for 5xx errors
}
Customizing Thresholds

You can customize thresholds when creating the collector:

collector := metrics.NewStandardCollector(
    metrics.WithThresholds(metrics.Thresholds{
        CPUPercent: 90.0,                // More lenient CPU threshold
        MemoryPercent: 90.0,             // More lenient memory threshold
        ServerErrorRatePercent: 0.5,     // Stricter error threshold
        GoroutineCount: 2000,            // Allow more goroutines
    }),
)

Metrics Dashboard

The metrics dashboard is available at /metrics by default (configurable via MetricsPath). It provides:

HTTP Metrics
  • Total request count
  • Recent and overall request rates
  • Client (4xx) and Server (5xx) error rates
  • Response time percentiles (P95, P99)
  • Average response time
Memory Metrics
  • Application memory usage
  • Memory growth rate
  • Garbage collection statistics
  • Heap usage and utilization
Runtime Metrics
  • Active goroutine count
  • GC pause times
  • CPU thread count
  • Application uptime
CPU Metrics
  • User CPU time
  • System CPU time
  • Idle CPU time
Disk I/O Metrics
  • Total disk space
  • Used space
  • Space growth metrics
Features of the Dashboard
  • Auto-refresh capabilities (configurable intervals)
  • Color-coded thresholds for quick status checks
  • Detailed descriptions for each metric
  • Raw JSON data access
  • Mobile-responsive design

Debug/Development Features

When EnablePprof is set to true (recommended for non-production environments), additional debug endpoints are available:

  • /debug/pprof/ - Index of pprof endpoints
  • /debug/pprof/cmdline - Command line arguments
  • /debug/pprof/profile - CPU profile
  • /debug/pprof/symbol - Symbol lookup
  • /debug/pprof/trace - Execution trace

Metrics Levels

Metrics are displayed with different levels based on their thresholds:

  • Info (Blue) - General information
  • OK (Green) - Within normal range
  • Warning (Yellow) - Approaching threshold
  • Critical (Red) - Exceeded threshold

Best Practices

  1. Production Setup

    metricsMod := metrics.NewModule(collector, &metrics.Config{
    EnablePprof: false,  // Disable pprof in production
    CollectionInterval: 30 * time.Second,  // Adjust based on needs
})

  2. Development Setup

    metricsMod := metrics.NewModule(collector, &metrics.Config{
    EnablePprof: true,  // Enable debugging tools
    CollectionInterval: 5 * time.Second,  // More frequent updates
})

  3. Custom Thresholds: Adjust thresholds based on your application's characteristics and requirements.

  4. Security: Consider adding authentication middleware for the metrics endpoint in production environments.

Implementation Details

The package uses:

  • expvar for metrics storage
  • runtime package for memory statistics
  • syscall for CPU and disk metrics
  • Standard library's HTTP server for the dashboard

Notes

  • The metrics dashboard is designed to be lightweight and doesn't require external dependencies
  • All metrics are collected in-memory
  • The dashboard uses vanilla JavaScript for auto-refresh functionality
  • Metric collection has minimal performance impact
  • The middleware automatically tracks HTTP request metrics

Documentation

Overview

Package metrics provides standardized metrics collection for hop applications

Index

Constants

This section is empty.

Variables

View Source 
var DefaultThresholds = Thresholds{
	CPUPercent:              75.0,
	ClientErrorRatePercent:  40.0,
	DiskPercent:             85.0,
	GCPauseMs:               100.0,
	GoroutineCount:          1000,
	MaxGCFrequency:          100.0,
	MemoryGrowthRatePercent: 20.0,
	MemoryPercent:           80.0,
	ServerErrorRatePercent:  1.0,
}

DefaultThresholds provides default threshold values

Functions

This section is empty.

Types

type Collector 

type Collector interface {

	// Counter is for cumulative metrics that only increase
	Counter(name string) Counter
	// Gauge is for metrics that can go up and down
	Gauge(name string) Gauge
	// Histogram tracks the distribution of a metric
	Histogram(name string) Histogram

	// RecordMemStats records memory statistics
	RecordMemStats()
	// RecordGoroutineCount records the number of goroutines
	RecordGoroutineCount()

	// RecordHTTPRequest records an HTTP request
	RecordHTTPRequest(method, path string, duration time.Duration, statusCode int)

	// Handler returns an http.Handler for the metrics endpoint
	Handler() http.Handler
}

Collector defines the interface for metrics collection

type Config 

type Config struct {
	// Path where metrics are exposed
	MetricsPath string
	// Enable pprof endpoints
	EnablePprof bool
	// How often to collect system metrics
	CollectionInterval time.Duration
}

type Counter 

type Counter interface {
	Inc()
	Add(delta float64)
	Value() float64
}

Counter is for cumulative metrics that only increase

type Gauge 

type Gauge interface {
	Set(value float64)
	Add(delta float64)
	Sub(delta float64)
	Value() float64
}

Gauge is for metrics that can go up and down

type Histogram 

type Histogram interface {
	Observe(value float64)
	Count() uint64
	Sum() float64
}

Histogram tracks the distribution of a metric

type Labels 

type Labels map[string]string

Labels represents a set of metric labels/tags

type MemoryStatus 

type MemoryStatus struct {
	Level     ThresholdLevel
	Reason    string
	Current   float64
	Threshold float64
	TrendInfo string // Additional information about trends
}

MemoryStatus represents the status of a specific memory metric

type Module 

type Module struct {
	// contains filtered or unexported fields
}

Module implements hop.Module for metrics collection

func NewModule 

func NewModule(collector Collector, config *Config) *Module

func (*Module) ID 

func (m *Module) ID() string

func (*Module) Init 

func (m *Module) Init() error

func (*Module) Middleware 

func (m *Module) Middleware() route.Middleware

Middleware creates route.Middleware for collecting HTTP metrics

func (*Module) RegisterRoutes 

func (m *Module) RegisterRoutes(router *route.Mux)

func (*Module) Start 

func (m *Module) Start(ctx context.Context) error

Start begins periodic collection of system metrics

func (*Module) Stop 

func (m *Module) Stop(ctx context.Context) error

Stop halts metric collection

type StandardCollector 

type StandardCollector struct {
	// contains filtered or unexported fields
}

StandardCollector implements Collector using the standard library

func NewStandardCollector 

func NewStandardCollector(opts ...StandardCollectorOption) *StandardCollector

NewStandardCollector creates a new StandardCollector

func (*StandardCollector) Counter 

func (c *StandardCollector) Counter(name string) Counter

Counter returns a counter metric

func (*StandardCollector) Gauge 

func (c *StandardCollector) Gauge(name string) Gauge

Gauge returns a gauge metric

func (*StandardCollector) Handler 

func (c *StandardCollector) Handler() http.Handler

Handler returns an http.Handler for the metrics endpoint as an HTML page

func (*StandardCollector) Histogram 

func (c *StandardCollector) Histogram(name string) Histogram

Histogram returns a histogram metric

func (*StandardCollector) RecordCPUStats 

func (c *StandardCollector) RecordCPUStats()

RecordCPUStats collects CPU usage statistics

func (*StandardCollector) RecordDiskStats 

func (c *StandardCollector) RecordDiskStats()

RecordDiskStats collects disk space usage statistics

func (*StandardCollector) RecordGoroutineCount 

func (c *StandardCollector) RecordGoroutineCount()

RecordGoroutineCount captures the number of goroutines

func (*StandardCollector) RecordHTTPRequest 

func (c *StandardCollector) RecordHTTPRequest(method, path string, duration time.Duration, statusCode int)

RecordHTTPRequest records metrics about an HTTP request

func (*StandardCollector) RecordMemStats 

func (c *StandardCollector) RecordMemStats()

RecordMemStats captures memory statistics

type StandardCollectorOption 

type StandardCollectorOption func(*StandardCollector)

StandardCollectorOption is a functional option for configuring a StandardCollector

func WithServerName 

func WithServerName(name string) StandardCollectorOption

WithServerName sets the server name for the collector

func WithThresholds 

func WithThresholds(thresholds Thresholds) StandardCollectorOption

WithThresholds sets the alert thresholds for the collector

type ThresholdLevel 

type ThresholdLevel int

ThresholdLevel is an enumeration of threshold levels 

const (
	// ThresholdInfo indicates a threshold is informational
	ThresholdInfo ThresholdLevel = iota
	// ThresholdOK indicates a threshold is within acceptable limits
	ThresholdOK
	// ThresholdWarning indicates a threshold is approaching a warning level
	ThresholdWarning
	// ThresholdCritical indicates a threshold has exceeded a critical level
	ThresholdCritical
)

type Thresholds 

type Thresholds struct {
	CPUPercent              float64 // CPU usage percentage
	ClientErrorRatePercent  float64 // Higher threshold for 4xx errors
	DiskPercent             float64 // Percentage of disk space used
	GCPauseMs               float64 // Warning when GC pauses exceed this duration
	GoroutineCount          int     // Number of goroutines
	MaxGCFrequency          float64 // Warning when GC runs too frequently (times per minute)
	MemoryGrowthRatePercent float64 // Warning when memory grows too fast (percent per minute)
	MemoryPercent           float64 // Percentage of total memory used
	ServerErrorRatePercent  float64 // Lower threshold for 5xx errors
}

Thresholds configuration

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.