wonder/cs-note

Fork 0

Files

T

wonder b5d9e44f0b vault backup: 2026-06-03 10:30:42

2026-06-03 10:30:42 +08:00

7.2 KiB

Raw Blame History

tags, create time

07. 可观测性

概述

35 个 Prometheus 指标 + 3 个 Grafana 仪表盘 + 10 条告警规则，覆盖全栈，让系统运行状态一目了然。

正文

指标体系总览

Gen2D 遵循 Prometheus 命名最佳实践，所有指标使用 gen2d_ 前缀，共 35 个指标，分为 6 大组：

组	指标数	采集方式	侵入性
HTTP 层	5	Gin 中间件自动采集	零侵入
限流层	2	限流中间件自动采集	零侵入
队列层	5	队列实现内部埋点	低
协程池层	6	池内部埋点	低
Pipeline 层	5	管线节点回调	低
基础设施层	5	连接状态监控	低

五大指标组详解

HTTP 层指标

Gin 中间件自动采集，零业务代码侵入。

指标名	类型	标签	说明
`gen2d_http_requests_total`	Counter	method, path, status	请求总量
`gen2d_http_request_duration_seconds`	Histogram	method, path	请求延迟分布
`gen2d_http_request_size_bytes`	Histogram	method, path	请求体大小
`gen2d_http_response_size_bytes`	Histogram	method, path	响应体大小
`gen2d_http_requests_in_flight`	Gauge	—	当前并发请求数

[!tip] FullPath() 的关键作用使用路由模板 /api/v1/tasks/:taskId 而非实际路径 /api/v1/tasks/abc123，避免高基数标签导致 Prometheus 内存爆炸。

限流层指标

指标名	类型	标签	说明
`gen2d_ratelimit_requests_total`	Counter	scope, endpoint, result	限流决策总量
`gen2d_ratelimit_remaining_tokens`	Gauge	scope, endpoint	剩余令牌数

scope：user / global
result：allowed / denied

任务队列层指标

指标名	类型	标签	说明
`gen2d_queue_depth`	Gauge	driver	当前队列积压深度
`gen2d_queue_submitted_total`	Counter	driver	入队总量
`gen2d_queue_consumed_total`	Counter	driver	出队总量
`gen2d_queue_submit_duration_seconds`	Histogram	driver	入队耗时
`gen2d_queue_errors_total`	Counter	driver, error_type	队列错误总量

driver：memory / rabbitmq

协程池层指标

指标名	类型	标签	说明
`gen2d_pool_active_workers`	Gauge	—	活跃 worker 数
`gen2d_pool_queued_tasks`	Gauge	—	池内排队任务数
`gen2d_pool_submitted_total`	Counter	—	提交到池的任务总量
`gen2d_pool_completed_total`	CounterVec	result	完成的任务总量
`gen2d_pool_rejected_total`	Counter	—	被拒绝的任务
`gen2d_pool_task_duration_seconds`	Histogram	—	任务执行耗时

Pipeline 业务层指标

指标名	类型	标签	说明
`gen2d_pipeline_total`	CounterVec	status	Pipeline 执行总量
`gen2d_pipeline_duration_seconds`	HistogramVec	status	端到端耗时
`gen2d_pipeline_stage_duration_seconds`	HistogramVec	stage	各阶段耗时
`gen2d_pipeline_retries_total`	CounterVec	stage	各阶段重试次数
`gen2d_pipeline_tasks_active`	Gauge	—	当前执行中的 Pipeline 数

[!tip] stage_duration 定位瓶颈通过 stage 标签（如 asset_generator、quality_check）可以精确定位哪个阶段是性能瓶颈。

基础设施层指标

指标名	类型	标签	说明
`gen2d_redis_operations_total`	CounterVec	op, result	Redis 操作总量
`gen2d_redis_operation_duration_seconds`	HistogramVec	op	Redis 操作延迟
`gen2d_redis_connection_pool_size`	Gauge	—	Redis 连接池大小
`gen2d_rabbitmq_connection_status`	Gauge	—	RabbitMQ 连接状态
`gen2d_rabbitmq_reconnect_total`	Counter	—	RabbitMQ 重连次数

中间件集成

Metrics 中间件工作流程

func Metrics() gin.HandlerFunc {
    return func(c *gin.Context) {
        path := c.FullPath()           // 路由模板，避免高基数
        HTTPRequestsInFlight.Inc()     // 进入时 +1
        defer HTTPRequestsInFlight.Dec() // 离开时 -1

        reqSize := c.Request.ContentLength  // 请求体大小 before
        c.Next()                            // 执行后续链
        elapsed := time.Since(start)        // 耗时 after
        HTTPRequestsTotal.WithLabelValues(...).Inc()
    }
}

关键设计：

in_flight 使用 defer 保证异常退出也能正确递减
请求体大小在 c.Next() 之前采集（此时 Content-Length 已知）
响应体大小在 c.Next() 之后采集（此时 Writer 已写入）

Grafana 仪表盘

仪表盘	用途	关键面板
Overview	全局概览	请求量、错误率、延迟 P50/P95/P99、活跃连接
Pipeline	管线监控	成功率、各阶段耗时、重试率、活跃任务数
Infrastructure	基础设施	Redis/RabbitMQ 状态、队列深度、池饱和度

告警规则

共 10 条告警规则，覆盖限流、队列、协程池、管线和基础设施：

告警名	级别	条件	说明
`RateLimitHighDenialRate`	⚠️	限流拒绝率 > 5%（持续 5m）	可能遭受攻击或配置过严
`QueueBacklog`	⚠️	队列深度 > 50（持续 2m）	消费能力不足
`QueueErrors`	🔴	5 分钟内错误 > 5 次	队列服务异常
`PoolSaturation`	⚠️	活跃 worker 占比 > 90%（持续 5m）	考虑扩容
`PoolTaskRejected`	⚠️	5 分钟内拒绝 > 5 个	池容量不足
`PipelineSuccessRateLow`	🔴	成功率 < 90%（持续 10m）	生成服务异常
`RedisDown`	🔴	连接池大小 = 0（持续 1m）	Redis 不可用
`RabbitMQDisconnected`	🔴	连接状态 = 0（持续 1m）	RabbitMQ 断连
`HighErrorRate`	🔴	5xx 错误率 > 5%（持续 5m）	服务异常
`HighLatency`	⚠️	P95 延迟 > 5s（持续 5m）	影响用户体验

[!note] 告警级别说明 Critical 表示需要立即处理，Warning 表示需要关注但不紧急。

基础设施指标

除业务指标外，Gen2D 还监控外部依赖的健康状态：

flowchart LR
    subgraph "基础设施监控"
        R["Redis"] -->|"operations_total"| M["Prometheus"]
        R -->|"connection_pool_size"| M
        Q["RabbitMQ"] -->|"connection_status"| M
        Q -->|"reconnect_total"| M
    end
    M --> G["Grafana"]
    M --> A["AlertManager"]

    style R fill:#fce4ec,stroke:#c62828
    style Q fill:#fff3e0,stroke:#f57c00
    style M fill:#e8f5e9,stroke:#388e3c
    style G fill:#e8eaf6,stroke:#303f9f
    style A fill:#ffebee,stroke:#b71c1c

Redis：操作延迟、成功率、连接池大小
RabbitMQ：连接状态（1=connected, 0=disconnected）、重连次数

关联文档

10-中间件链 — Metrics 中间件的挂载位置
09-限流 — 限流指标的采集方式
14-部署架构 — Prometheus + Grafana 的部署配置

7.2 KiB Raw Blame History Unescape Escape