metrics

package
v1.24.0 Latest Latest
Warning

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

Go to latest
Published: Oct 25, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

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

View Source
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"
)
View Source
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

func KnownSessionRolloutBootOutcome(outcome string) bool

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

func NewScrapeServer(addr string) *http.Server

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

func ObserveAvatarRender(dur time.Duration, err error)

ObserveAvatarRender 记录一次真实渲染的耗时与结果。

func ObserveAvatarSemaphoreWait added in v1.7.0

func ObserveAvatarSemaphoreWait(dur time.Duration)

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

func ObserveDB(op string, dur time.Duration, err error)

ObserveDB 是 MySQL 客户端调用的包级入口,签名精确匹配 octo-lib 的 db.DBObserver。 在 main 里用 db.SetDBObserver(metrics.ObserveDB) 注入。op 取值 "connect" / "query"。 未初始化默认实例时为 no-op。

func ObserveObjectStore added in v1.7.0

func ObserveObjectStore(op, backend string, start time.Time, err error)

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

func ObserveRedisCmd(op string, dur time.Duration, err error)

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 ObserveSessionOperation(operation string, started time.Time, err error)

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 SetSessionEffectiveTTL(ttl time.Duration)

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 计数被 singleflight 合并(复用在途渲染)的请求数。
	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 只应调用一次。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址