本文档介绍了Prometheus客户端库应提供的功能和API,旨在实现库之间的一致性,简化易用用例,避免提供可能导致用户走错路的功能。
在撰写本文时已经支持了10种语言,因此我们现在已经很好地理解了如何编写客户端。 这些指南旨在帮助新客户端库的作者生成良好的库。
一、Conventions约定
MUST/MUST NOT/SHOULD/SHOULD NOT/MAY具有给出的含义在https://www.ietf.org/rfc/rfc2119.txt
此外,ENCOURAGED意味着某个功能对于库来说是理想的,但如果它不存在则可以。 换句话说,一个很好的。
记住下面的几点:
- 利用每种语言的功能。
- 常用用例应该很简单
- 做事情正确方式是简单的方法
- 更复杂的例子应该是可能的
常用用例(有序):
- 没有标签的Counters在库/应用程序之间传播
- Summaries/Histograms的时序功能/代码块
- Gauges跟踪事情的当前状态
- 批量任务监控
二、总体结构
必须将客户端编写为内部回调。客户通常应该遵循这里描述的结构。
关键类是Collector
。有一个方法(通常称为collect
),返回零个或多个指标及其样本。Collector
在CollectorRegistry
注册。通过将CollectorRegistry
传递给class/method/function``bridge
来公开数据,该类以Prometheus支持的格式返回指标。每次抓取CollectorRegistry
时,它都必须回调每个Collector
的collect
方法。
大多数用户与之交互的界面是Counter
,Gauge
,Summary
和Histogram
Collectors。这些代表一个度量标准,应涵盖用户正在使用自己的代码的绝大多数用例。
更高级的用例(例如从另一个监视/检测系统代理)需要编写自定义Collector
。有人可能还想编写一个bridge
,它采用CollectorRegistry
并以不同监控/仪表系统理解的格式生成数据,从而允许用户只需考虑一个仪器系统。
CollectorRegistry
应该提供register()/unregister()
函数,并且应该允许收集器注册到多个CollectorRegistrys
。
客户端库必须是线程安全的。
对于诸如C的非OO语言,客户端库应该尽可能地遵循这种结构的精神。
2.1 命名
客户端库应该遵循本文档中提到的function/method/class
,记住它们所使用的语言的命名约定。例如,set_to_current_time()
适用于方法名称Python,但SetToCurrentTime()
更好 在Go中,setToCurrentTime()
是Java中的约定。 如果名称因技术原因而不同(例如,不允许函数重载),文档/帮助字符串应该将用户指向其他名称。
库不得提供与此处给出的名称相同或相似的函数/方法/类,但具有不同的语义。
三、Metrics
Counter
、Gauge
、Summary
和Histogram
度量指标类型是最主要的接口。
Counter
和Gauge
必须是客户库的一部分。Summary