metrics

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Feb 27, 2026 License: MIT Imports: 7 Imported by: 0

README

metrics — 指标收集

提供内存型指标收集器，支持 Counter（计数器）、Gauge（仪表盘）、Histogram（直方图）三种指标类型，并内置 Prometheus 格式导出与 HTTP 中间件。

指标类型

类型 说明 使用场景
Counter 单调递增计数 请求总数、错误次数
Gauge 任意值，可升可降 当前连接数、内存用量
Histogram 观测值分布，保留历史 请求耗时、响应大小

快速开始

import "github.com/leeforge/framework/metrics"

collector := metrics.NewCollector()

// Counter：请求计数
collector.IncCounter("http_requests_total", map[string]string{
    "method": "GET",
    "path":   "/users",
    "status": "200",
})

// Gauge：当前连接数
collector.SetGauge("active_connections", 42, map[string]string{
    "service": "api",
})

// Histogram：记录请求耗时（秒）
collector.ObserveHistogram("request_duration_seconds", 0.023, map[string]string{
    "handler": "listUsers",
})

HTTP 指标中间件

manager := metrics.NewMetricsManager(metrics.DefaultMetricsConfig())

// 在 Chi Router 上注册中间件
r.Use(manager.GetHTTPMiddleware().Middleware)

// 暴露 /metrics 端点
r.Handle("/metrics", manager.GetMetricsHandler())

内置快捷方法

// 记录 HTTP 请求（自动处理计数+耗时）
collector.RecordRequest("GET", "/users", 200, 0.015)

// 记录数据库查询
collector.RecordDBQuery("SELECT * FROM users", 0.003)

// 记录缓存命中
collector.RecordCacheHit("redis", true)  // hit
collector.RecordCacheHit("redis", false) // miss

// 记录错误
collector.RecordError("POST", "/users", err)

业务指标

biz := metrics.NewBusinessMetrics(collector)

biz.RecordUserAction("user-123", "login")
biz.RecordOrder("user-123", 99.99, true)
biz.RecordAPICall("payment-service", "Charge", 200, 0.05)

系统仪表

gauge := metrics.NewGaugeManager(collector)

gauge.SetSystemMetrics(cpu, memory, goroutines)
gauge.SetQueueMetrics("email-queue", 100, 10)
gauge.SetConnectionMetrics(dbConns, redisConns)

指标摘要与健康检查

dashboard := metrics.NewMetricsDashboard(collector)
summary := dashboard.GetSummary()
// 返回：http_requests_total, db_queries_total, cache_hit_rate 等汇总数据

// 基于阈值的健康检查
healthCheck := metrics.NewMetricsHealthCheck(collector, metrics.MetricsHealthThreshold{
    MaxErrorRate:     0.05,   // 错误率不超过 5%
    MaxAvgDuration:   0.5,    // 平均耗时不超过 500ms
    MaxCacheMissRate: 0.3,    // 缓存未命中率不超过 30%
})

result := healthCheck.Check()
if !result.Healthy {
    log.Warn("metrics health check failed", result.Issues)
}

Prometheus 格式导出

exporter := metrics.NewPrometheusExporter(collector)
prometheusText := exporter.GetPrometheusFormat()
// 输出标准 Prometheus 文本格式

注意事项

  • 当前 Histogram 最多保留 100 个历史观测值，旧值会被丢弃
  • 指标 Key 使用 name:label=value 格式，标签顺序可能影响 Key 的一致性（建议使用固定顺序）
  • 生产环境建议配合 Prometheus + Grafana 使用

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func RegisterMetricsRoutes 

func RegisterMetricsRoutes(mux *http.ServeMux, exporter *MetricsHTTPExporter)

RegisterMetricsRoutes 注册指标路由

Types

type BusinessMetrics 

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

BusinessMetrics 业务指标

func NewBusinessMetrics 

func NewBusinessMetrics(collector *Collector) *BusinessMetrics

NewBusinessMetrics 创建业务指标

func (*BusinessMetrics) RecordAPICall 

func (b *BusinessMetrics) RecordAPICall(service, method string, status int, duration float64)

RecordAPICall 记录 API 调用

func (*BusinessMetrics) RecordOrder 

func (b *BusinessMetrics) RecordOrder(userID string, amount float64, success bool)

RecordOrder 记录订单

func (*BusinessMetrics) RecordUserAction 

func (b *BusinessMetrics) RecordUserAction(userID, action string)

RecordUserAction 记录用户行为

type Collector 

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

Collector 指标收集器

func NewCollector 

func NewCollector() *Collector

NewCollector 创建指标收集器

func (*Collector) AddCounter 

func (c *Collector) AddCounter(name string, value float64, labels map[string]string)

AddCounter 增加计数器值

func (*Collector) GetMetric 

func (c *Collector) GetMetric(name string, labels map[string]string) *Metric

GetMetric 获取单个指标

func (*Collector) GetMetrics 

func (c *Collector) GetMetrics() map[string]*Metric

GetMetrics 获取所有指标

func (*Collector) IncCounter 

func (c *Collector) IncCounter(name string, labels map[string]string)

IncCounter 增加计数器

func (*Collector) ObserveHistogram 

func (c *Collector) ObserveHistogram(name string, value float64, labels map[string]string)

ObserveHistogram 观察直方图

func (*Collector) RecordCacheHit 

func (c *Collector) RecordCacheHit(cacheType string, hit bool)

RecordCacheHit 记录缓存命中

func (*Collector) RecordDBQuery 

func (c *Collector) RecordDBQuery(query string, duration float64)

RecordDBQuery 记录数据库查询

func (*Collector) RecordError 

func (c *Collector) RecordError(method, path string, err error)

RecordError 记录错误

func (*Collector) RecordRequest 

func (c *Collector) RecordRequest(method, path string, status int, duration float64)

RecordRequest 记录 HTTP 请求

func (*Collector) Reset 

func (c *Collector) Reset()

Reset 重置指标

func (*Collector) SetGauge 

func (c *Collector) SetGauge(name string, value float64, labels map[string]string)

SetGauge 设置仪表值

type GaugeManager 

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

GaugeManager 仪表管理器

func NewGaugeManager 

func NewGaugeManager(collector *Collector) *GaugeManager

NewGaugeManager 创建仪表管理器

func (*GaugeManager) SetConnectionMetrics 

func (g *GaugeManager) SetConnectionMetrics(db, redis int)

SetConnectionMetrics 设置连接指标

func (*GaugeManager) SetQueueMetrics 

func (g *GaugeManager) SetQueueMetrics(queueName string, size, processing int)

SetQueueMetrics 设置队列指标

func (*GaugeManager) SetSystemMetrics 

func (g *GaugeManager) SetSystemMetrics(cpu, memory, goroutines int)

SetSystemMetrics 设置系统指标

type HealthResult 

type HealthResult struct {
	Healthy bool
	Details map[string]interface{}
	Issues  []string
}

type Metric 

type Metric struct {
	Type      string            `json:"type"`
	Value     float64           `json:"value"`
	Labels    map[string]string `json:"labels,omitempty"`
	History   []float64         `json:"history,omitempty"`
	Timestamp int64             `json:"timestamp"`
}

Metric 指标

type MetricsAggregator 

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

func NewMetricsAggregator 

func NewMetricsAggregator(collectors ...*Collector) *MetricsAggregator

func (*MetricsAggregator) Aggregate 

func (a *MetricsAggregator) Aggregate() map[string]*Metric

type MetricsCollector 

type MetricsCollector struct {
	*Collector
	*MetricsManager
	*BusinessMetrics
	*GaugeManager
	*MetricsRecorder
}

func DefaultMetricsCollector 

func DefaultMetricsCollector() *MetricsCollector

func NewMetricsCollector 

func NewMetricsCollector(config MetricsConfig) *MetricsCollector

type MetricsCollectorFactory 

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

func NewMetricsCollectorFactory 

func NewMetricsCollectorFactory() *MetricsCollectorFactory

func (*MetricsCollectorFactory) GetAllCollectors 

func (f *MetricsCollectorFactory) GetAllCollectors() map[string]*Collector

func (*MetricsCollectorFactory) GetCollector 

func (f *MetricsCollectorFactory) GetCollector(name string) *Collector

func (*MetricsCollectorFactory) ResetAll 

func (f *MetricsCollectorFactory) ResetAll()

func (*MetricsCollectorFactory) ResetCollector 

func (f *MetricsCollectorFactory) ResetCollector(name string)

type MetricsConfig 

type MetricsConfig struct {
	EnableHTTPMetrics     bool
	EnableDBMetrics       bool
	EnableCacheMetrics    bool
	EnableBusinessMetrics bool
}

MetricsConfig 指标配置

func DefaultMetricsConfig 

func DefaultMetricsConfig() MetricsConfig

DefaultMetricsConfig 默认配置

type MetricsDashboard 

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

MetricsDashboard 指标仪表板

func NewMetricsDashboard 

func NewMetricsDashboard(collector *Collector) *MetricsDashboard

NewMetricsDashboard 创建指标仪表板

func (*MetricsDashboard) GetSlowQueries 

func (d *MetricsDashboard) GetSlowQueries(threshold float64) []string

GetSlowQueries 获取慢查询

func (*MetricsDashboard) GetSummary 

func (d *MetricsDashboard) GetSummary() map[string]interface{}

GetSummary 获取指标摘要

type MetricsEventForwarder 

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

func NewMetricsEventForwarder 

func NewMetricsEventForwarder(collector *Collector, forwarder func(string, map[string]interface{}) error) *MetricsEventForwarder

func RegisterMetricsEventForwarder 

func RegisterMetricsEventForwarder(collector *Collector, forwarder func(string, map[string]interface{}) error) *MetricsEventForwarder

func (*MetricsEventForwarder) Forward 

func (f *MetricsEventForwarder) Forward() error

type MetricsExporter 

type MetricsExporter interface {
	Export(metrics map[string]*Metric) error
}

type MetricsExporterConfig 

type MetricsExporterConfig struct {
	Endpoint   string
	EnableAuth bool
	Username   string
	Password   string
}

MetricsExporterConfig 指标导出器配置

type MetricsExporterRegistry 

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

func NewMetricsExporterRegistry 

func NewMetricsExporterRegistry() *MetricsExporterRegistry

func (*MetricsExporterRegistry) ExportAll 

func (r *MetricsExporterRegistry) ExportAll(collector *Collector) error

func (*MetricsExporterRegistry) GetExporter 

func (r *MetricsExporterRegistry) GetExporter(name string) MetricsExporter

func (*MetricsExporterRegistry) Register 

func (r *MetricsExporterRegistry) Register(name string, exporter MetricsExporter)

type MetricsHTTPExporter 

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

MetricsHTTPExporter HTTP 指标导出器

func NewMetricsHTTPExporter 

func NewMetricsHTTPExporter(collector *Collector, config MetricsExporterConfig) *MetricsHTTPExporter

NewMetricsHTTPExporter 创建 HTTP 指标导出器

func (*MetricsHTTPExporter) ServeHTTP 

func (e *MetricsHTTPExporter) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP 实现 http.Handler

type MetricsHandler 

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

MetricsHandler 指标处理器

func NewMetricsHandler 

func NewMetricsHandler(collector *Collector) *MetricsHandler

NewMetricsHandler 创建指标处理器

func (*MetricsHandler) ServeHTTP 

func (h *MetricsHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP 实现 http.Handler

type MetricsHealthCheck 

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

func NewMetricsHealthCheck 

func NewMetricsHealthCheck(collector *Collector, threshold MetricsHealthThreshold) *MetricsHealthCheck

func (*MetricsHealthCheck) Check 

func (h *MetricsHealthCheck) Check() HealthResult

type MetricsHealthThreshold 

type MetricsHealthThreshold struct {
	MaxErrorRate     float64
	MaxAvgDuration   float64
	MaxCacheMissRate float64
}

type MetricsManager 

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

MetricsManager 指标管理器

func NewMetricsManager 

func NewMetricsManager(config MetricsConfig) *MetricsManager

NewMetricsManager 创建指标管理器

func (*MetricsManager) GetCollector 

func (m *MetricsManager) GetCollector() *Collector

GetCollector 获取收集器

func (*MetricsManager) GetHTTPMiddleware 

func (m *MetricsManager) GetHTTPMiddleware() *MetricsMiddleware

GetHTTPMiddleware 获取 HTTP 中间件

func (*MetricsManager) GetMetricsHandler 

func (m *MetricsManager) GetMetricsHandler() http.Handler

GetMetricsHandler 获取指标处理器

type MetricsMiddleware 

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

MetricsMiddleware 指标中间件

func NewMetricsMiddleware 

func NewMetricsMiddleware(collector *Collector) *MetricsMiddleware

NewMetricsMiddleware 创建指标中间件

func (*MetricsMiddleware) Middleware 

func (m *MetricsMiddleware) Middleware(next http.Handler) http.Handler

Middleware HTTP 指标中间件

type MetricsRateLimiter 

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

func NewMetricsRateLimiter 

func NewMetricsRateLimiter(collector *Collector, limit int64, window time.Duration) *MetricsRateLimiter

func (*MetricsRateLimiter) Allow 

func (l *MetricsRateLimiter) Allow(key string) bool

func (*MetricsRateLimiter) GetUsage 

func (l *MetricsRateLimiter) GetUsage(key string) int

type MetricsRecorder 

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

MetricsRecorder 指标记录器

func NewMetricsRecorder 

func NewMetricsRecorder(collector *Collector) *MetricsRecorder

func (*MetricsRecorder) RecordDuration 

func (r *MetricsRecorder) RecordDuration(name string, labels map[string]string, fn func() error) error

func (*MetricsRecorder) RecordFailure 

func (r *MetricsRecorder) RecordFailure(name string, labels map[string]string)

func (*MetricsRecorder) RecordSuccess 

func (r *MetricsRecorder) RecordSuccess(name string, labels map[string]string)

type MetricsSampler 

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

func NewMetricsSampler 

func NewMetricsSampler(collector *Collector, interval time.Duration) *MetricsSampler

func (*MetricsSampler) Start 

func (s *MetricsSampler) Start(sampler func() map[string]float64)

func (*MetricsSampler) Stop 

func (s *MetricsSampler) Stop()

type MetricsSnapshot 

type MetricsSnapshot struct {
	Timestamp time.Time              `json:"timestamp"`
	Metrics   map[string]*Metric     `json:"metrics"`
	Summary   map[string]interface{} `json:"summary"`
}

func TakeSnapshot 

func TakeSnapshot(collector *Collector) MetricsSnapshot

type PrometheusExporter 

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

func NewPrometheusExporter 

func NewPrometheusExporter(collector *Collector) *PrometheusExporter

func (*PrometheusExporter) Export 

func (e *PrometheusExporter) Export(metrics map[string]*Metric) error

func (*PrometheusExporter) GetPrometheusFormat 

func (e *PrometheusExporter) GetPrometheusFormat() string

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.