本文档涵盖了 Prometheus 客户端库应提供的功能和 API，旨在使库之间保持一致性，使简单的用例变得容易，并避免提供可能导致用户走错路的功能。
在撰写本文时，已经支持 10 种语言，因此我们现在对如何编写客户端有了很好的了解。 这些指南旨在帮助新客户端库的作者制作好的库。
MUST/MUST NOT/SHOULD/SHOULD NOT/MAY 的含义在 https://www.ietf.org/rfc/rfc2119.txt 中给出
此外，ENCOURAGED 表示该功能对于库来说是理想的，但即使不存在也可以。换句话说，锦上添花。
要记住的事情
利用每种语言的特性。
常见的用例应该很容易。
做某事的正确方法应该是简单的方法。
更复杂的用例应该是可行的。
常见的用例是（按顺序）
没有标签的计数器在库/应用程序中广泛分布。
在摘要/直方图中定时函数/代码块。
用于跟踪事物当前状态（及其限制）的仪表。
批量作业的监控。
客户端的内部必须基于回调编写。客户端通常应遵循此处描述的结构。
关键类是 Collector。它有一个方法（通常称为“collect”），该方法返回零个或多个指标及其样本。收集器在 CollectorRegistry 中注册。通过将 CollectorRegistry 传递给类/方法/函数“桥”来公开数据，该桥以 Prometheus 支持的格式返回指标。每次抓取 CollectorRegistry 时，都必须回调每个 Collector 的 collect 方法。
大多数用户与之交互的接口是 Counter、Gauge、Summary 和 Histogram 收集器。这些代表一个单一的指标，并且应该涵盖用户检测自己的代码的绝大多数用例。
更高级的用例（例如从另一个监控/检测系统进行代理）需要编写自定义的收集器。有人可能还想编写一个“桥”，该桥获取 CollectorRegistry 并以另一个监控/检测系统理解的格式生成数据，从而允许用户只需要考虑一个检测系统。
CollectorRegistry 应该提供 register()/unregister() 函数，并且应该允许将 Collector 注册到多个 CollectorRegistry。
客户端库必须是线程安全的。
对于 C 等非面向对象的语言，客户端库应尽可能遵循此结构的原则。
客户端库应遵循本文档中提到的函数/方法/类名称，同时牢记它们所使用的语言的命名约定。例如，set_to_current_time() 对于 Python 中的方法名称是好的，但 SetToCurrentTime() 在 Go 中更好，而 setToCurrentTime() 是 Java 中的约定。如果名称因技术原因而异（例如，不允许函数重载），文档/帮助字符串应将用户指向其他名称。
库不得提供与此处给出的名称相同或相似但语义不同的函数/方法/类。
Counter、Gauge、Summary 和 Histogram 指标类型是用户的主要接口。
Counter 和 Gauge 必须是客户端库的一部分。必须至少提供 Summary 和 Histogram 中的一个。
这些主要应该用作文件静态变量，也就是说，在与它们检测的代码相同的文件中定义的全局变量。客户端库应该启用此功能。常见的用例是检测一段代码的整体，而不是一个对象实例上下文中的一段代码。用户不必担心在整个代码中管道传输他们的指标，客户端库应该为他们执行此操作（如果不是这样，用户将编写一个包装器来使库“更容易” - 这很少会顺利进行）。
必须有一个默认的 CollectorRegistry，标准指标必须默认隐式注册到其中，而无需用户进行特殊的工作。必须有一种方法可以使指标不注册到默认的 CollectorRegistry，以便在批量作业和单元测试中使用。自定义收集器也应遵循此方法。
确切应如何创建指标因语言而异。对于某些语言（Java、Go），构建器方法是最好的，而对于其他语言（Python），函数参数足够丰富，可以在一次调用中完成。
例如，在 Java Simpleclient 中，我们有
class YourClass {
static final Counter requests = Counter.build()
.name("requests_total")
.help("Requests.").register();
}
这将向默认的 CollectorRegistry 注册请求。通过调用 build() 而不是 register()，将不会注册指标（方便单元测试），您还可以将 CollectorRegistry 传递给 register()（方便批量作业）。
计数器是一个单调递增的计数器。它不得允许值减少，但可以重置为 0（例如通过服务器重启）。
计数器必须具有以下方法
inc()：将计数器加 1inc(double v)：将计数器增加给定的量。必须检查 v >= 0。鼓励计数器具有
一种统计在给定代码段中抛出/引发的异常的方法，并且可以选择仅统计某些类型的异常。这就是 Python 中的 count_exceptions。
计数器必须从 0 开始。
仪表盘表示可以上下波动的值。
仪表盘必须具有以下方法
inc()：将仪表盘加 1inc(double v)：将仪表盘增加给定的量dec()：将仪表盘减 1dec(double v)：将仪表盘减少给定的量set(double v)：将仪表盘设置为给定值仪表盘必须从 0 开始，您可以提供一种使给定仪表盘以不同的数字开始的方法。
仪表盘应该具有以下方法
set_to_current_time()：将仪表盘设置为当前的 unixtime 秒数。鼓励仪表盘具有
一种跟踪在某些代码/函数中正在进行的请求的方法。这就是 Python 中的 track_inprogress。
一种对一段代码进行计时，并将仪表设置为其持续时间（以秒为单位）的方法。这对于批处理作业很有用。在 Java 中，它是 startTimer/setDuration，在 Python 中是 time() 装饰器/上下文管理器。这应该与 Summary/Histogram 中的模式匹配（尽管是 set() 而不是 observe()）。
摘要会在滑动时间窗口内对观测值（通常是请求持续时间之类的内容）进行采样，并提供对其分布、频率和总和的即时洞察。
摘要绝对不能允许用户将“quantile”设置为标签名称，因为它在内部用于指定摘要的分位数。摘要建议提供分位数作为导出，尽管这些分位数无法聚合并且往往速度较慢。摘要必须允许不包含分位数，因为仅 _count/_sum 就非常有用，并且这必须是默认设置。
摘要必须具有以下方法
observe(double v)：观察给定的量摘要应该具有以下方法
一些以秒为单位对用户代码进行计时的方法。在 Python 中，这是 time() 装饰器/上下文管理器。在 Java 中，这是 startTimer/observeDuration。不允许提供秒以外的单位（如果用户需要其他单位，他们可以手动完成）。这应遵循与 Gauge/Histogram 相同的模式。
摘要的 _count/_sum 必须从 0 开始。
直方图允许聚合事件的分布，例如请求延迟。它的核心是每个桶的计数器。
直方图绝对不允许将 le 作为用户设置的标签，因为 le 在内部用于指定桶。
直方图必须提供一种手动选择桶的方法。应该提供以 linear(start, width, count) 和 exponential(start, factor, count) 方式设置桶的方法。Count 必须包括 +Inf 桶。
直方图应该与其他客户端库具有相同的默认桶。一旦创建指标，桶就不能更改。
直方图必须具有以下方法
observe(double v)：观察给定的量直方图应该具有以下方法
一些以秒为单位对用户代码进行计时的方法。在 Python 中，这是 time() 装饰器/上下文管理器。在 Java 中，这是 startTimer/observeDuration。不允许提供秒以外的单位（如果用户需要其他单位，他们可以手动完成）。这应遵循与 Gauge/Summary 相同的模式。
直方图的 _count/_sum 和桶必须从 0 开始。
其他指标注意事项
建议在指标中提供超出上述文档记录的附加功能，这对于给定的语言来说是有意义的。
如果存在您可以简化操作的常见用例，请执行此操作，只要它不会鼓励不良行为（例如次优的指标/标签布局，或在客户端中进行计算）。
标签是 Prometheus 的最强大的方面之一，但很容易被滥用。因此，客户端库必须非常小心地向用户提供标签的方式。
客户端库绝对不允许用户为 Gauge/Counter/Summary/Histogram 或库提供的任何其他收集器中的同一指标使用不同的标签名称。
来自自定义收集器的指标几乎总是应具有一致的标签名称。由于仍然存在罕见但有效的用例并非如此，因此客户端库不应验证这一点。
虽然标签很强大，但大多数指标都没有标签。因此，API 应允许使用标签，但不要使其占据主导地位。
客户端库必须允许在 Gauge/Counter/Summary/Histogram 创建时可选地指定标签名称列表。客户端库应该支持任意数量的标签名称。客户端库必须验证标签名称是否符合文档要求。
提供对指标的标记维度进行访问的一般方法是通过一个 labels() 方法，该方法接受标签值的列表或从标签名称到标签值的映射，并返回一个“子项”。然后可以在该子项上调用常用的 .inc()/.dec()/.observe() 等方法。
labels() 返回的子项应该可以被用户缓存，以避免必须再次查找它 - 这在延迟关键代码中很重要。
带有标签的指标应该支持一个与 labels() 具有相同签名的 remove() 方法，该方法将从不再导出它的指标中删除一个子项，以及一个从指标中删除所有子项的 clear() 方法。这些操作会使子项的缓存失效。
应该有一种使用默认值初始化给定子项的方法，通常只需调用 labels()。必须始终初始化没有标签的指标，以避免丢失指标的问题。
指标名称必须符合规范。与标签名称一样，对于 Gauge/Counter/Summary/Histogram 的使用以及库提供的任何其他收集器，都必须满足这一点。
许多客户端库提供以三个部分设置名称：namespace_subsystem_name，其中只有 name 是强制性的。
不鼓励使用动态/生成的指标名称或指标名称的子部分，除非自定义收集器正在从其他检测/监控系统中进行代理。生成/动态指标名称表明您应该改用标签。
Gauge/Counter/Summary/Histogram 必须要求提供指标描述/帮助。
客户端库提供的任何自定义收集器都必须在其指标上提供描述/帮助。
建议将其作为强制参数，但不检查其是否具有一定长度，因为如果有人真的不想编写文档，我们将无法说服他们。库提供的收集器（以及我们可以在生态系统中实现的任何地方）应该具有良好的指标描述，以身作则。
客户端必须实现公开格式文档中概述的基于文本的公开格式。
如果可以在没有显著资源成本的情况下实现，则建议以可重复的顺序公开指标（特别是对于人类可读的格式）。
客户端库应该尽可能提供下面记录的标准导出。
这些应该作为自定义收集器实现，并在默认 CollectorRegistry 上默认注册。应该有一种禁用这些的方法，因为在某些非常特殊的用例中，它们会妨碍工作。
这些指标的前缀为 process_。如果使用使用的语言或运行时获取必要值有问题甚至不可能，则客户端库应首选省略相应的指标，而不是导出伪造、不准确或特殊值（如 NaN）。所有内存值以字节为单位，所有时间以 unix 时间戳/秒为单位。
| 指标名称 | 帮助字符串 | 单位 |
|---|---|---|
process_cpu_seconds_total |
总用户和系统 CPU 时间（以秒为单位）。 | 秒 |
process_open_fds |
打开的文件描述符数。 | 文件描述符 |
process_max_fds |
最大打开文件描述符数。 | 文件描述符 |
process_virtual_memory_bytes |
虚拟内存大小（以字节为单位）。 | 字节 |
process_virtual_memory_max_bytes |
可用的最大虚拟内存量（以字节为单位）。 | 字节 |
process_resident_memory_bytes |
驻留内存大小（以字节为单位）。 | 字节 |
process_heap_bytes |
进程堆大小（以字节为单位）。 | 字节 |
process_start_time_seconds |
自 unix 纪元以来进程的开始时间（以秒为单位）。 | 秒 |
process_threads |
进程中操作系统线程的数量。 | 线程 |
此外，建议客户端库还提供其语言运行时方面有意义的指标（例如，垃圾收集统计信息），并使用适当的前缀，例如 go_、hotspot_ 等。
客户端库应该具有涵盖核心检测库和公开的单元测试。
建议客户端库提供一些方法，使使用者可以轻松地对检测代码的使用进行单元测试。例如，Python 中的 CollectorRegistry.get_sample_value。
理想情况下，可以将客户端库包含在任何应用程序中以添加一些检测，而不会破坏应用程序。
因此，在向客户端库添加依赖项时，建议谨慎行事。例如，如果您添加的库使用的 Prometheus 客户端需要库的版本 x.y，但该应用程序在其他地方使用 x.z，这会对应用程序产生不利影响吗？
建议在可能出现这种情况时，将核心检测与给定格式的指标桥接/公开分开。例如，Java simpleclient simpleclient 模块没有依赖项，而 simpleclient_servlet 则具有 HTTP 位。
由于客户端库必须是线程安全的，因此需要某种形式的并发控制，并且必须考虑多核机器和应用程序的性能。
根据我们的经验，性能最差的是互斥锁。
处理器原子指令往往处于中间位置，并且通常可以接受。
避免不同的 CPU 更改同一 RAM 位的方法效果最好，例如 Java simpleclient 中的 DoubleAdder。但是，这会产生内存成本。
如上所述，labels() 的结果应该是可缓存的。倾向于使用标签支持指标的并发映射往往相对较慢。特殊处理没有标签的指标以避免类似 labels() 的查找可以提供很大帮助。
指标在递增/递减/设置等时应该避免阻塞，因为在抓取正在进行时暂停整个应用程序是不可取的。
建议对主要检测操作（包括标签）进行基准测试。
在执行公开时，应牢记资源消耗，特别是 RAM。考虑通过流式传输结果来减少内存占用，并可能限制并发抓取的次数。
此文档是开源的。请通过提交问题或拉取请求来帮助改进它。