Documentation
¶
Overview ¶
Package metrics 收集 dmwork 进程级 Prometheus 指标。
HTTP 中间件提供 per-route 的延迟直方图、并发请求计数, 以及"业务错误"计数 —— 后者通过解析响应 body 的 envelope `status` 字段 来识别,而不是依赖 HTTP status code(详见 BusinessError 字段的注释)。
path label 用 gin.Context.FullPath() 取路由模板而非真实 URI, 防止 uid/orderID 这类高基数值打爆 Prometheus 内存。
与 modules/oidc/metrics.go 不同: 那里用全局默认 Registry (promauto), 本文件让调用方注入 Registerer, 便于测试隔离和未来按需迁移到独立 registry。
Index ¶
- Constants
- func AddAvatarRenderInflight(delta float64)
- func KnownSessionRolloutBootOutcome(outcome string) bool
- func NewScrapeServer(addr string) *http.Server
- func ObserveAvatarCacheHit()
- func ObserveAvatarCacheMiss()
- func ObserveAvatarNotModified()
- func ObserveAvatarRender(dur time.Duration, err error)
- func ObserveAvatarSemaphoreWait(dur time.Duration)
- func ObserveAvatarSingleflightShared()
- func ObserveBotRateLimitDecision(class, outcome string)
- func ObserveDB(op string, dur time.Duration, err error)
- func ObserveObjectStore(op, backend string, start time.Time, err error)
- func ObservePersistentSession()
- func ObserveRedisCmd(op string, dur time.Duration, err error)
- func ObserveSessionFloorAdvance(to, actor string)
- func ObserveSessionOperation(operation string, started time.Time, err error)
- func ObserveSessionReconcileBlocked(reason string)
- func ObserveSessionReconcileScan()
- func ObserveSessionRevocationRetry(reason string)
- func ObserveSessionValidationReject(reason string)
- func ObserveSessionWriterFence()
- func ObserveStickerRegister(result string)
- func ObserveStickerUploadHandleIssued()
- func RegisterPoolCollectors(reg prometheus.Registerer, db *sql.DB, redisClients map[string]*rd.Client)
- func SetSessionEffectiveTTL(ttl time.Duration)
- func SetSessionLiveWriters(count int)
- func SetSessionRevocationBacklog(count int64)
- func SetSessionRolloutBootOutcome(current string)
- func SetSessionRolloutMode(current string)
- func SetSessionUndecodableRecords(count int64)
- func SetStickerHandlePolicy(enabled, required bool)
- type AvatarMetrics
- type BotRateLimitMetrics
- type DependencyMetrics
- type HTTPMetrics
- type SessionMetrics
- type StickerMetrics
Constants ¶
const ( // DependencyObjectStore 是对象存储类依赖的 dependency label 值。 DependencyObjectStore = "objectstore" // DependencyMySQL / DependencyRedis 是 DB / 缓存依赖的 dependency label 值, // 由 octo-lib 客户端接缝(db.SetDBObserver / redis.SetRedisObserver)灌入。 DependencyMySQL = "mysql" DependencyRedis = "redis" // OpUploadFile / OpGetFile 是对象存储上「真正发生网络 I/O」的两个操作的 op // label 值:上传(PutObject 等)与读取对象(GetObject+Stat 等)。 // 注意:不为 DownloadURL 打点 —— 各后端的 DownloadURL 只是从 config 本地拼出 // 公开/CDN URL,不触达对象存储,给它打 latency 会产生误导性指标(见 #442 P1-1)。 OpUploadFile = "upload_file" OpGetFile = "get_file" )
const ( // StickerRegisterOK 通过:路径形状校验过,且(有能力时)handle 校验通过, // 或裸跑无能力时路径形状校验过。 StickerRegisterOK = "ok" // StickerRegisterCompatMissing 兼容模式(required=false)下缺 handle 被放行。 // 这是上线观测的核心指标:其占比归零表示老客户端基本退场,可切 required=true。 StickerRegisterCompatMissing = "compat_missing" // StickerRegisterRejectedMissing required=true 下缺 handle 被拒。 StickerRegisterRejectedMissing = "rejected_missing" // StickerRegisterRejectedInvalid handle 非法/错配被拒(与 required 无关,恒拒)。 StickerRegisterRejectedInvalid = "rejected_invalid" // StickerRegisterRejectedPath 路径形状校验失败被拒(先于 handle 判定)。 StickerRegisterRejectedPath = "rejected_path" // StickerRegisterRejectedNoCapability 配置冲突被拒(fail-closed):策略要求 handle // (sticker.handle_required=true)但服务端无有效 OCTO_MASTER_KEY 提供校验能力,无法 // 兑现强制,故拒绝而非静默放行。这条与 ok 区分开,dashboard 才能看出「声称强制却 // 因缺能力在异常拒绝」的 misconfig,而不是被计成正常成功掩盖。 StickerRegisterRejectedNoCapability = "rejected_no_capability" )
注册结果枚举(Register 的 result label)。任何新增分支都应回到这里加常量, 并在 NewStickerMetrics 预热里补一行,Grafana dashboard 才能稳定区分「零次」 与「序列不存在」。
Variables ¶
This section is empty.
Functions ¶
func AddAvatarRenderInflight ¶ added in v1.7.0
func AddAvatarRenderInflight(delta float64)
AddAvatarRenderInflight 调整正在进行的渲染数(+1 开始 / -1 结束)。
func KnownSessionRolloutBootOutcome ¶ added in v1.15.0
KnownSessionRolloutBootOutcome reports whether an outcome has a label.
Exported so pkg/auth can assert that every outcome it defines is listed here. This list is hand-maintained because pkg/metrics deliberately does not import pkg/auth, so a contract test must keep the two lists aligned.
func NewScrapeServer ¶
NewScrapeServer 构造一个仅暴露 /metrics 的 http.Server。
设计取舍:
- 独立端口(默认 :9090),不挂业务端口 — 业务限流/CORS/Recovery 不影响 scrape, 业务挂掉时 scrape 还能拉到最后状态;同时不会经 CLB 暴露到公网。
- 默认 promhttp.Handler() 走全局 DefaultGatherer — 与 modules/oidc/metrics.go 的 promauto 注册到 default registry 一致,一次抓取拿全所有指标。
- ReadHeaderTimeout 防 slow-header DoS;Listen 路径上 G112 静态检查也要求设。
调用方负责 ListenAndServe / Shutdown 生命周期。
func ObserveAvatarCacheHit ¶ added in v1.7.0
func ObserveAvatarCacheHit()
ObserveAvatarCacheHit 记录一次 LRU 命中。
func ObserveAvatarCacheMiss ¶ added in v1.7.0
func ObserveAvatarCacheMiss()
ObserveAvatarCacheMiss 记录一次 LRU 未命中。
func ObserveAvatarNotModified ¶ added in v1.7.0
func ObserveAvatarNotModified()
ObserveAvatarNotModified 记录一次 304 响应。
func ObserveAvatarRender ¶ added in v1.7.0
ObserveAvatarRender 记录一次真实渲染的耗时与结果。
func ObserveAvatarSemaphoreWait ¶ added in v1.7.0
ObserveAvatarSemaphoreWait 记录一次渲染信号量等待耗时。
func ObserveAvatarSingleflightShared ¶ added in v1.7.0
func ObserveAvatarSingleflightShared()
ObserveAvatarSingleflightShared 记录一次被 singleflight 合并的请求。
func ObserveBotRateLimitDecision ¶ added in v1.14.0
func ObserveBotRateLimitDecision(class, outcome string)
ObserveBotRateLimitDecision 记录一次限流判定。 class 与 outcome 必须来自固定枚举——这是 label 基数有界的前提, 调用方不得把任意字符串(尤其是 path 或 robot_id)透传进来。
func ObserveDB ¶ added in v1.7.0
ObserveDB 是 MySQL 客户端调用的包级入口,签名精确匹配 octo-lib 的 db.DBObserver。 在 main 里用 db.SetDBObserver(metrics.ObserveDB) 注入。op 取值 "connect" / "query"。 未初始化默认实例时为 no-op。
func ObserveObjectStore ¶ added in v1.7.0
ObserveObjectStore 是对象存储调用的包级便捷入口,供 modules/file 等调用方使用, 无需把 *DependencyMetrics 实例穿透到业务层。未初始化默认实例时为 no-op。
用法:
start := time.Now() res, err := backend.UploadFile(...) metrics.ObserveObjectStore(metrics.OpUploadFile, backendLabel, start, err) return res, err
func ObservePersistentSession ¶ added in v1.14.0
func ObservePersistentSession()
func ObserveRedisCmd ¶ added in v1.7.0
ObserveRedisCmd 是 Redis 命令的包级入口,签名精确匹配 octo-lib 的 redis.RedisObserver。 在 main 里用 redis.SetRedisObserver(metrics.ObserveRedisCmd) 注入。op 为命令名(已小写)。 未初始化默认实例时为 no-op。
func ObserveSessionFloorAdvance ¶ added in v1.15.0
func ObserveSessionFloorAdvance(to, actor string)
ObserveSessionFloorAdvance records a floor transition. actor is "reconciler" or "operator" so an automatic advance is distinguishable during an incident.
func ObserveSessionOperation ¶ added in v1.14.0
func ObserveSessionReconcileBlocked ¶ added in v1.15.0
func ObserveSessionReconcileBlocked(reason string)
ObserveSessionReconcileBlocked counts a cycle that could not advance.
func ObserveSessionReconcileScan ¶ added in v1.15.0
func ObserveSessionReconcileScan()
ObserveSessionReconcileScan counts a keyspace scan by the reconciler, so the backoff can be verified from metrics rather than trusted.
func ObserveSessionRevocationRetry ¶ added in v1.15.0
func ObserveSessionRevocationRetry(reason string)
func ObserveSessionValidationReject ¶ added in v1.14.0
func ObserveSessionValidationReject(reason string)
func ObserveSessionWriterFence ¶ added in v1.15.0
func ObserveSessionWriterFence()
ObserveSessionWriterFence counts a lost write lease. A sustained non-zero rate means replicas are refusing new logins, which is the intended degradation but still wants an alert.
func ObserveStickerRegister ¶ added in v1.8.0
func ObserveStickerRegister(result string)
ObserveStickerRegister 记录一次注册结果。result 应取 StickerRegister* 常量。
func ObserveStickerUploadHandleIssued ¶ added in v1.8.0
func ObserveStickerUploadHandleIssued()
ObserveStickerUploadHandleIssued 记录一次上传成功并签发 handle。
func RegisterPoolCollectors ¶ added in v1.7.0
func RegisterPoolCollectors(reg prometheus.Registerer, db *sql.DB, redisClients map[string]*rd.Client)
RegisterPoolCollectors 把 DB 与 Redis 连接池 Collector 注册到 reg。
- DB 复用 client_golang 自带的 DBStatsCollector,暴露标准 go_sql_* 序列 (open/in_use/idle/wait_count/wait_duration_seconds_total),社区 Grafana dashboard 开箱即用。db 为 nil 时跳过。
- Redis 用下方自定义 Collector 读 *redis.Client.PoolStats()(lib 的 GetRedisConn() 返回 *redis.Conn 不暴露 PoolStats,够不到,不在此列)。 clients 为空时跳过。
注册契约与其它指标一致:同一 reg 只应调用一次,重复注册触发 MustRegister 的 panic(prometheus 库契约)。
func SetSessionEffectiveTTL ¶ added in v1.14.0
func SetSessionLiveWriters ¶ added in v1.15.0
func SetSessionLiveWriters(count int)
SetSessionLiveWriters records how many writers hold a live lease.
func SetSessionRevocationBacklog ¶ added in v1.15.0
func SetSessionRevocationBacklog(count int64)
func SetSessionRolloutBootOutcome ¶ added in v1.15.0
func SetSessionRolloutBootOutcome(current string)
SetSessionRolloutBootOutcome records how boot resolved the mode.
func SetSessionRolloutMode ¶ added in v1.15.0
func SetSessionRolloutMode(current string)
func SetSessionUndecodableRecords ¶ added in v1.15.0
func SetSessionUndecodableRecords(count int64)
SetSessionUndecodableRecords tracks records that cannot be decoded as any token version. They no longer block the floor — they were never usable credentials — but nothing clears them either, so a keyspace can sit at enforce with N of them and this is the only thing that says so.
func SetStickerHandlePolicy ¶ added in v1.8.0
func SetStickerHandlePolicy(enabled, required bool)
SetStickerHandlePolicy 在启动时设置部署姿态 gauge(enabled = 是否有 master key 能力,required = 是否强制)。两者正交,便于 dashboard 对「required 但无能力」 的配置冲突告警。
Types ¶
type AvatarMetrics ¶ added in v1.7.0
type AvatarMetrics struct {
// CacheEvents 按 result(hit/miss)计数 LRU 命中情况;命中率 = hit/(hit+miss)。
CacheEvents *prometheus.CounterVec
SingleflightShared prometheus.Counter
// NotModified 计数 If-None-Match 命中返回 304 的请求(客户端缓存生效的体现)。
NotModified prometheus.Counter
// RenderDuration 按 status(ok/error)切分的单次真实渲染耗时直方图。
RenderDuration *prometheus.HistogramVec
// RenderInflight 当前正在进行的真实渲染数(gauge)。
RenderInflight prometheus.Gauge
// SemaphoreWait 获取渲染信号量的等待耗时直方图(>0 表示渲染并发饱和、排队)。
SemaphoreWait prometheus.Histogram
}
AvatarMetrics 持有头像渲染缓存指标。每进程一个实例,注册到一个 Registerer。
func NewAvatarMetrics ¶ added in v1.7.0
func NewAvatarMetrics(reg prometheus.Registerer) *AvatarMetrics
NewAvatarMetrics 在 reg 上注册头像渲染缓存指标,并登记为包级默认。 调用契约同 NewDependencyMetrics:同一 Registerer 只应调用一次。
type BotRateLimitMetrics ¶ added in v1.14.0
type BotRateLimitMetrics struct {
// Decisions 按 class(business/heartbeat/register) 与
// outcome(bypassed/no_key/allowed/would_deny/denied/degraded) 计数每次判定。
//
// would_deny 与 denied 刻意分开:影子模式(dry-run)下判定为拒绝但不拦截,
// 「关掉 dry-run 会多拒多少」正是靠这两个值的对比来回答的——合并就等于
// 放弃了影子模式的全部意义。
//
// degraded 单列:它表示 Redis 故障导致限流层 fail-open,
// 即「限流实际上没在工作」,这必须能在监控上一眼看出来,不能混进 allowed。
//
// no_key 与 bypassed 分开:bypassed 是「这条通道被显式关闭」(预期状态),
// no_key 是「通道开着但取不到限流维度」(配置或中间件顺序出了问题,
// 桶实际没生效)。两者都不拦截,混在一起就看不出后者。
Decisions *prometheus.CounterVec
}
BotRateLimitMetrics 持有 bot 限流判定指标。每进程一个实例,注册到一个 Registerer。
func NewBotRateLimitMetrics ¶ added in v1.14.0
func NewBotRateLimitMetrics(reg prometheus.Registerer) *BotRateLimitMetrics
NewBotRateLimitMetrics 在 reg 上注册指标并登记为包级默认。 调用契约同 NewDependencyMetrics:同一 Registerer 只应调用一次。
type DependencyMetrics ¶ added in v1.7.0
type DependencyMetrics struct {
// Duration 按 dependency/op/backend/status 切分的依赖调用延迟直方图。
// Buckets 比 HTTP 入口更细、低段下探到 1ms —— 依赖调用(签名 URL、池内
// 查询)正常应在毫秒级,粗桶会把"正常"和"偶发抖动"糊在一起。
Duration *prometheus.HistogramVec
}
DependencyMetrics 持有依赖调用指标。每进程一个实例,注册到一个 Registerer。
func NewDependencyMetrics ¶ added in v1.7.0
func NewDependencyMetrics(reg prometheus.Registerer) *DependencyMetrics
NewDependencyMetrics 在传入的 Registerer 上注册依赖调用指标,并把实例登记为 包级默认(供 ObserveObjectStore 等自由函数使用)。
调用契约同 NewHTTPMetrics:同一 Registerer 只应调用一次,重复注册会触发 MustRegister 的 panic(prometheus 库契约)。生产传 DefaultRegisterer; 测试传 prometheus.NewRegistry() 隔离,并可用返回值直接断言。
func (*DependencyMetrics) Observe ¶ added in v1.7.0
func (m *DependencyMetrics) Observe(dependency, op, backend string, start time.Time, err error)
Observe 记录一次依赖调用。status 由 err 是否为 nil 决定。
func (*DependencyMetrics) ObserveDuration ¶ added in v1.7.0
func (m *DependencyMetrics) ObserveDuration(dependency, op, backend string, dur time.Duration, err error)
ObserveDuration 同 Observe,但直接接收耗时而非起始时间。用于适配 octo-lib 客户端 接缝的 observer 回调签名(dbr 给的是纳秒耗时,而非 start time)。
type HTTPMetrics ¶
type HTTPMetrics struct {
// Duration 按 method/path/status 切分的请求延迟直方图。
// Buckets 覆盖 5ms ~ 10s, 匹配 IM 业务的真实 P99 区间。
Duration *prometheus.HistogramVec
// InFlight 当前并发处理中的请求数, 用于发现 hang 或慢请求堆积。
InFlight prometheus.Gauge
// BusinessError 业务层显式返回错误的次数, 按 path/code 切分。
//
// 背景: 业务约定(octo-lib/pkg/wkhttp.ResponseError 与本仓库同名实现)
// 把绝大多数服务端错误统一返回 HTTP 400, 导致 Duration{status=~"5.."}
// 看到的 5xx 率几乎恒为 0, 无法反映真实故障率。
//
// 采集方式: 中间件在响应体内解析 envelope JSON 的 `status` 字段
// (即 wkhttp 写入的语义错误码) — 与 HTTP status code 解耦,无需要求
// handler 显式调用埋点 API,任何 wkhttp 变体(local / octo-lib)只要遵循
// `{"status": N, "msg": ...}` 信封就都能采到。
// 当未来把服务端错误改回 HTTP 5xx 时(参见 upstream issue #140 阶段 2),
// code label 自然反映新分布,不需要再改 dashboard 名字。
BusinessError *prometheus.CounterVec
}
HTTPMetrics 持有所有 HTTP 入口指标。每进程一个实例。
func NewHTTPMetrics ¶
func NewHTTPMetrics(reg prometheus.Registerer) *HTTPMetrics
NewHTTPMetrics 在传入的 Registerer 上注册所有 HTTP 指标。
调用契约: 同一个 Registerer 只能调用一次。重复注册触发 MustRegister 的 panic (这是 prometheus 库的契约,不是本函数的 bug)。
- 生产代码: 在 main.go 启动时一次性传入 prometheus.DefaultRegisterer。
- 测试代码: 每个用例传入 prometheus.NewRegistry() 以隔离全局状态。
func (*HTTPMetrics) GinMiddleware ¶
func (m *HTTPMetrics) GinMiddleware() gin.HandlerFunc
GinMiddleware 返回一个 gin 中间件, 在 c.Next() 前后记录延迟、状态码、并发计数和业务错误。
panic 处理: 上层 gin.Recovery() 是最外层中间件, 它的 defer recover 在本中间件 defer 之后才会执行 — 直接读 c.Writer.Status() 会拿到 200。 因此本中间件自己 recover 一次记录 status=500, 再 re-panic 让外层 Recovery 完成最终响应写出。
业务错误识别: 包一层 ResponseWriter 抓前 1 KiB 响应 body,defer 中解析 JSON envelope 的 `status` 字段;若 >= 400 累加 BusinessError。解析失败时退回 HTTP status code(覆盖 AbortWithStatusJSON / 静态文件等非 envelope 的错误)。
type SessionMetrics ¶ added in v1.14.0
type SessionMetrics struct {
Operations *prometheus.CounterVec
OperationLatency *prometheus.HistogramVec
ValidationReject *prometheus.CounterVec
PersistentSeen prometheus.Counter
EffectiveTTL prometheus.Gauge
RolloutMode *prometheus.GaugeVec
RevocationBacklog prometheus.Gauge
RevocationRetries *prometheus.CounterVec
LiveWriters prometheus.Gauge
WriterFences prometheus.Counter
FloorAdvances *prometheus.CounterVec
ReconcileBlocked *prometheus.CounterVec
ReconcileScans prometheus.Counter
RolloutBootOutcome *prometheus.GaugeVec
UndecodableRecords prometheus.Gauge
// contains filtered or unexported fields
}
func NewSessionMetrics ¶ added in v1.14.0
func NewSessionMetrics(reg prometheus.Registerer) *SessionMetrics
type StickerMetrics ¶ added in v1.8.0
type StickerMetrics struct {
// UploadHandleIssued 计数 /v1/file/upload?type=sticker 成功并签发 sticker_handle
// 的次数(仅在 Enabled 且签发成功时 +1)。
UploadHandleIssued prometheus.Counter
// Register 按 result 计数 POST /v1/sticker/user 的注册结果(见 StickerRegister* 常量)。
Register *prometheus.CounterVec
// HandlePolicy 反映启动时的部署姿态:setting=enabled(master key 能力)/
// setting=required(强制策略)各置 0/1,便于 dashboard 确认配置并对
// 「required 但无能力」的冲突态告警。
HandlePolicy *prometheus.GaugeVec
}
StickerMetrics 持有自定义贴纸 handle 的上线观测指标。每进程一个实例,注册到 一个 Registerer。
func NewStickerMetrics ¶ added in v1.8.0
func NewStickerMetrics(reg prometheus.Registerer) *StickerMetrics
NewStickerMetrics 在 reg 上注册贴纸 handle 指标,并登记为包级默认。 调用契约同 NewAvatarMetrics:同一 Registerer 只应调用一次。