Prometheus学习系列（三十二）之编写客户端库

本文档介绍了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和