编辑“︁Gin API监控”︁

{{DISPLAYTITLE:Gin API监控}}  
{{Note|本文适用于使用[[Gin框架]]开发REST API的开发者，涵盖基础监控原理到高级实践}}  

== 概述 ==  
'''Gin API监控'''是通过收集、分析和可视化API的运行指标（如请求延迟、错误率、吞吐量等），确保服务稳定性和性能优化的关键实践。监控系统通常包含以下核心组件：  
* **指标收集**：记录API的请求/响应数据  
* **存储与聚合**：使用时序数据库（如Prometheus）存储指标  
* **告警与可视化**：通过Grafana等工具展示数据并触发告警  

== 核心监控指标 ==  
以下是API监控的通用指标分类：  

{| class="wikitable"  
! 指标类型 !! 说明 !! 示例  
|-  
| 请求量 || 单位时间内的请求总数 || `requests_total{path="/users", method="GET"}`  
|-  
| 延迟 || 请求处理耗时（分位值） || `request_duration_seconds_bucket{le="0.1"}`  
|-  
| 错误率 || HTTP状态码≥400的比例 || `errors_total{status="500"}`  
|-  
| 资源使用 || CPU/内存占用 || `process_resident_memory_bytes`  
|}  

== 实现方案 ==  

=== 使用Prometheus监控 ===  
[[Prometheus]]是流行的开源监控系统，Gin可通过中间件集成其客户端库：  

<syntaxhighlight lang="go">  
import (  
    "github.com/gin-gonic/gin"  
    "github.com/prometheus/client_golang/prometheus"  
    "github.com/prometheus/client_golang/prometheus/promhttp"  
)  

// 定义指标  
var (  
    requestsTotal = prometheus.NewCounterVec(  
        prometheus.CounterOpts{  
            Name: "http_requests_total",  
            Help: "Total HTTP requests",  
        },  
        []string{"path", "method", "status"},  
    )  
    requestDuration = prometheus.NewHistogramVec(  
        prometheus.HistogramOpts{  
            Name:    "http_request_duration_seconds",  
            Help:    "Request latency distribution",  
            Buckets: []float64{0.1, 0.5, 1, 2},  
        },  
        []string{"path"},  
    )  
)  

func init() {  
    prometheus.MustRegister(requestsTotal, requestDuration)  
}  

// 监控中间件  
func MetricsMiddleware() gin.HandlerFunc {  
    return func(c *gin.Context) {  
        start := time.Now()  
        path := c.Request.URL.Path  

        defer func() {  
            duration := time.Since(start).Seconds()  
            status := fmt.Sprintf("%d", c.Writer.Status())  
            requestsTotal.WithLabelValues(path, c.Request.Method, status).Inc()  
            requestDuration.WithLabelValues(path).Observe(duration)  
        }()  

        c.Next()  
    }  
}  

func main() {  
    r := gin.Default()  
    r.Use(MetricsMiddleware())  
    r.GET("/metrics", gin.WrapH(promhttp.Handler()))  
    r.Run(":8080")  
}  
</syntaxhighlight>  

{{Tip|通过`/metrics`端点暴露数据，Prometheus可定期抓取}}  

=== 可视化与告警 ===  
配置Grafana连接Prometheus数据源后，可创建如下监控面板：  

<mermaid>  
graph LR  
    Gin[Gin应用] -->|暴露/metrics| Prometheus  
    Prometheus -->|查询数据| Grafana  
    Grafana -->|触发条件| AlertManager  
</mermaid>  

示例Grafana面板配置：  
* **QPS面板**：`sum(rate(http_requests_total[1m])) by (path)`  
* **P99延迟**：`histogram_quantile(0.99, sum(rate(http_request_duration_seconds_bucket[1m])) by (le, path))`  

== 高级技巧 ==  

=== 自定义业务指标 ===  
监控登录失败次数示例：  
<syntaxhighlight lang="go">  
var loginFailures = prometheus.NewCounter(  
    prometheus.CounterOpts{  
        Name: "login_failures_total",  
        Help: "Total failed login attempts",  
    },  
)  

// 在登录处理逻辑中  
if !authenticated {  
    loginFailures.Inc()  
}  
</syntaxhighlight>  

=== 分布式追踪 ===  
集成OpenTelemetry实现请求链路追踪：  
<syntaxhighlight lang="go">  
import (  
    "go.opentelemetry.io/otel"  
    "go.opentelemetry.io/otel/exporters/jaeger"  
)  

func initTracer() {  
    exporter, _ := jaeger.New(jaeger.WithCollectorEndpoint())  
    tp := trace.NewTracerProvider(  
        trace.WithBatcher(exporter),  
        trace.WithResource(resource.NewWithAttributes(  
            semconv.SchemaURL,  
            semconv.ServiceNameKey.String("gin-api"),  
        )),  
    )  
    otel.SetTracerProvider(tp)  
}  
</syntaxhighlight>  

== 性能考量 ==  
监控系统本身会带来约5%~10%的性能开销，建议：  
* 避免高频指标（如每个请求记录多个Histogram）  
* 使用批处理方式上报数据  
* 采样非关键路径数据  

== 故障排查案例 ==  
'''场景'''：API延迟突增  
'''排查步骤'''：  
1. 检查`request_duration_seconds`是否特定路径异常  
2. 关联`process_cpu_seconds_total`确认是否资源不足  
3. 通过日志定位慢查询或死锁  

{{Warning|生产环境应始终设置告警规则，如`rate(errors_total[5m]) > 0.1`}}  

== 延伸阅读 ==  
* Prometheus官方文档中的[[Histogram与Summary区别]]  
* 分布式追踪的[[上下文传播]]机制  
* Gin性能优化的[[中间件执行顺序]]影响

[[Category:后端框架]]
[[Category:Gin]]
[[Category:Gin REST API开发]]