monitor

README

monitor

metrics client for prometheus

go get code.gopub.tech/monitor@latest

monitor.Record(ctx, "xxx_throughput", "xxx总量")
monitor.RecordN
monitor.Store
monitor.Cost
defer monitor.Timer()()
monitor.Histogram
defer monitor.Observe()()
monitor.Summary
monitor.SummaryObjectives

Documentation

Overview

package monitor provides a simple way to monitor your application.

一个 prometheus 的简易封装, 用于监控打点.

Init 初始化

使用默认的全局客户端, 无需初始化, 如需自定义参数可使用 `NewClient` 初始化. 支持自定义的参数有:

WithNamespace("namespace")	// 默认值为空
WithSubsystem("subsystem")	// 默认值为空
// 指标类型不同, 默认值不同
// Counter 指标, 前缀默认值是 `counter:`
// Gauge 指标, 前缀默认值是 `gauge:`
// Timer 指标, 前缀默认值是 `timer:`, 后缀默认值是 `_seconds`
// Histogram 指标, 前缀默认值是 `histogram:`
// Summary 指标, 前缀默认值是 `summary:`
WithNameAppend(monitor.NameAppends{})
WithRegistry(registry)
WithConstLabels(map[string]string{})
WithLogger(func(context.Context, string, ...any))
// 默认值是 prometheus.DefBuckets
// .005/5ms, .01/10ms, .025/25ms, .05/50ms, .1/100ms,
// .25/250ms, .5/500ms, 1/1s, 2.5/2.5s, 5/5s, 10/10s.
WithBuckets([]float64{})
WithObjectives(map[float64]float64{})

应用程序使用 Record(ctx, "name", "help") 等 API 进行打点, 指标名会自动拼接前缀/后缀, 然后再附加上名称空间/子模块, 最终格式为:

<namespace>:<subsystem>:<prefix><name><suffix>{<labels>}

默认会在 /metrics 端点暴露打点数据. 也可以通过 HTTPHandler() 获取 handler 自行注册到不同的路径.

API 使用

Counter 类型指标用于计数, 只能增加, 不能减少(除非程序重启). 指标名默认会拼接 `counter:` 前缀.

monitor.Record(ctx, name, help)
monitor.RecordN(ctx, name, help, value)

Gauge 类型指标用于存储当前瞬时值, 可以增加, 减少, 重置. 指标名默认会拼接 `gauge:` 前缀.

monitor.Store(ctx, name, help, value)

记录耗时, 使用 Cost, CostBuckets, 或 Timer/Observe 方法. 指标名默认会拼接 `timer:` 前缀, `_seconds` 后缀.

// cost 是 time.Duration 类型
// 会自动通过 Seconds 方法记录为秒值(因此时间类指标默认后缀是 _seconds)
monitor.Cost(ctx, name, help, cost)
// 如需自定义耗时分布, 可以使用 buckets 参数
monitor.CostBuckets(ctx, name, help, cost, buckets)
// 使用 Timer 方法配合 defer 使用, 会自动计时
defer monitor.Timer(buckets...)(ctx, name, help)
// 使用 Observe 方法配合 defer 使用, 会自动记录耗时
// Observe 方法底层使用 Summary 类型
defer monitor.Observe()(ctx, name, help)

记录直方图 指标名默认会拼接 `histogram:` 前缀.

monitor.Histogram(ctx, name, help, value, buckets)

记录摘要 指标名默认会拼接 `summary:` 前缀.

monitor.Summary(ctx, name, help, value)
monitor.SummaryObjectives(ctx, name, help, value, objectives)

标签 Labels

每个 API 都可选传入标签(labels), 一个指标一旦附加了标签, 后续每次打点都需要附加相同的标签名(label name), 标签值(label value)可以不同.

monitor.Record(ctx, "name", "help", "k1", "v1", "k2", "v2")
monitor.Record(ctx, "name", "help", "k1", "v1", "k2", "v22")
// no effect, missing k2 label 缺少标签的打点会被忽略
monitor.Record(ctx, "name", "help", "k1", "v1")
// no effect, mismatch labels 标签对不同的打点会被忽略
monitor.Record(ctx, "name", "help", "k1", "v1", "x", "y")

如果标签对较多, 可以使用 CtxAddLabels 方法往 ctx 上附加, 后续每次打点会自动解析

ctx = monitor.CtxAddLabels(ctx, "k1", "v1", "k2", "v2")
monitor.Record(ctx, "name", "help")

Index

• Constants
• func Cost(ctx context.Context, name, desc string, cost time.Duration, kvs ...string)
• func CostBuckets(ctx context.Context, name, desc string, cost time.Duration, ...)
• func CtxAddLabels(ctx context.Context, kvs ...string) context.Context
• func CtxGetLabels(ctx context.Context) map[string]string
• func Default() *client
• func EscapeName(s string) string
• func HTTPHandler() http.Handler
• func Histogram(ctx context.Context, name, desc string, value nums.AnyNumber, ...)
• func NewClient(opts ...Opt) *client
• func Observe() func(ctx context.Context, name, desc string, kvs ...string) time.Duration
• func Record(ctx context.Context, name, desc string, kvs ...string)
• func RecordN(ctx context.Context, name, desc string, value nums.AnyNumber, kvs ...string)
• func SetDefault(d *client)
• func Store(ctx context.Context, name, desc string, value nums.AnyNumber, kvs ...string)
• func Summary(ctx context.Context, name, desc string, value nums.AnyNumber, kvs ...string)
• func SummaryObjectives(ctx context.Context, name, desc string, value nums.AnyNumber, ...)
• func Timer() func(ctx context.Context, name, desc string, kvs ...string) time.Duration
• type NameAppend
• type NameAppends
• type Opt
  • func WithBuckets(buckets []float64) Opt
  • func WithConstLabels(labels map[string]string) Opt
  • func WithLogger(logger func(context.Context, string, ...any)) Opt
  • func WithNameAppend(nameAppend NameAppends) Opt
  • func WithNamespace(name string) Opt
  • func WithObjectives(objectives map[float64]float64) Opt
  • func WithRegistry(registry *prometheus.Registry) Opt
  • func WithSubsystem(name string) Opt

Constants

const PATTERN_METRICS = "/metrics"

PATTERN_METRICS 默认的 metrics 路径

Functions

func Cost

func Cost(ctx context.Context, name, desc string, cost time.Duration, kvs ...string)

Cost 记录耗时(使用 Timer 指标前缀/后缀)

func CostBuckets

func CostBuckets(ctx context.Context, name, desc string, cost time.Duration, buckets []time.Duration, kvs ...string)

CostBuckets 记录耗时分布(使用 Timer 指标前缀/后缀)

func CtxAddLabels

func CtxAddLabels(ctx context.Context, kvs ...string) context.Context

CtxAddLabels 往 ctx 中添加 labels, 返回新的 ctx

func CtxGetLabels

func CtxGetLabels(ctx context.Context) map[string]string

CtxGetLabels 从 ctx 中获取 labels

func Default

func Default() *client

Default 获取全局默认的 client

func EscapeName

func EscapeName(s string) string

EscapeName 对指标名转义

满足 `^[a-zA-Z_:][a-zA-Z0-9_:]*$` 的直接返回, 否则会进行转义: `U__` 开头, 不在上述范围的字符转义为 `_unicode_` 编码.

func HTTPHandler

func HTTPHandler() http.Handler

HTTPHandler 返回一个 http.Handler 用于暴露 metrics 数据

func Histogram

func Histogram(ctx context.Context, name, desc string, value nums.AnyNumber, buckets []float64, kvs ...string)

Histogram 记录值的分布. 如果无需记录分布, 请使用 Summary

func NewClient

func NewClient(opts ...Opt) *client

NewClient 新建监控打点客户端

func Observe

func Observe() func(ctx context.Context, name, desc string, kvs ...string) time.Duration

Observe 记录耗时摘要(使用 Timer 指标前缀/后缀)

func Record

func Record(ctx context.Context, name, desc string, kvs ...string)

Record 记录打点 累加计数器 +1

func RecordN

func RecordN(ctx context.Context, name, desc string, value nums.AnyNumber, kvs ...string)

RecordN 记录打点 累加计数器 +n

func SetDefault

func SetDefault(d *client)

SetDefault 设置全局默认的 client

func Store

func Store(ctx context.Context, name, desc string, value nums.AnyNumber, kvs ...string)

Store 存储当前瞬时值

func Summary

func Summary(ctx context.Context, name, desc string, value nums.AnyNumber, kvs ...string)

Summary 记录摘要(使用 Summary 指标前缀/后缀)

func SummaryObjectives

func SummaryObjectives(ctx context.Context, name, desc string, value nums.AnyNumber, objectives map[float64]float64, kvs ...string)

SummaryObjectives 记录摘要(自定义分位数)(使用 Summary 指标前缀/后缀)

func Timer

func Timer() func(ctx context.Context, name, desc string, kvs ...string) time.Duration

Timer 记录耗时(使用 Timer 指标前缀/后缀)

Types

type NameAppend

type NameAppend struct {
	Prefix string
	Suffix string
}

NameAppend 自定义指标名称前缀/后缀 只能使用英文字母、数字、下划线、冒号 [a-zA-Z0-9_:]

type NameAppends

type NameAppends struct {
	Counter   NameAppend
	Gauge     NameAppend
	Timer     NameAppend
	Histogram NameAppend
	Summary   NameAppend
}

NameAppends 自定义 Counter/Gauge/Histogram/Summary 指标名称前缀/后缀

type Opt

type Opt func(*client)

func WithBuckets

func WithBuckets(buckets []float64) Opt

WithBuckets 设置 histogram 类型指标值的默认分布 默认值是 prometheus.DefBuckets

func WithConstLabels

func WithConstLabels(labels map[string]string) Opt

WithConstLabels 统一设置指标常量标签 默认值是空的 map

func WithLogger

func WithLogger(logger func(context.Context, string, ...any)) Opt

WithLogger 设置日志输出 默认值是 slog.WarnContext

func WithNameAppend

func WithNameAppend(nameAppend NameAppends) Opt

WithNameAppend 统一设置指标名前缀/后缀 前缀默认值分别是 "counter:" "gauge:" "histogram:" "summary:" 后缀默认值是空字符串

func WithNamespace

func WithNamespace(name string) Opt

WithNamespace 统一设置指标的名称空间 默认值为空字符串

func WithObjectives

func WithObjectives(objectives map[float64]float64) Opt

WithObjectives 设置 summary 类型指标值的默认分位数 默认值是空的 map, 表示不使用 summary 记录分位数. (因为客户端计算分位数性能不高, 且不能用于聚合)

func WithRegistry

func WithRegistry(registry *prometheus.Registry) Opt

WithRegistry 使用指定的 registry 默认值是 nil 会通过 `prometheus.NewRegistry()` 生成一个

func WithSubsystem

func WithSubsystem(name string) Opt

WithSubsystem 统一设置指标名所属子系统 默认值为空字符串