Prometheus编写导出器

完整译文请访问：http://www.coderdocument.com/docs/prometheus/v2.14/instrumenting/writing_exporters.html。

如果你正为自己的代码添加监控，那么应该遵循使用Prometheus客户端库为代码添加监控的一般规则。当从另一个监控系统获取指标时，事情往往不是那么黑白分明。

此文档包含编写导出器或自定义收集器时应该考虑的事项。涉及的理论对那些添加监控的人应该也有兴趣。

如果你正在写一个导出器并且不清楚本文档中的内空，请联系我们在IRC（#Prometheus on Freenode）或邮件列表。

 

可维护性和纯净

当你编写一个导出器时，你需要做的主要决定是你愿意投入多少工作来获取完美的指标。

如果有问题的系统只有很少更改的几个指标，那么让一切变得完美是一个简单的选择，HAProxy导出器就是一个很好的例子。

另一方面，如果你试图把拥有数百个经常随新版本更改的指标的系统变得完美，那么你将有许多事件要做，MySQL导出器就是一个很好的例子。

节点导出器是这些组件的混合体，其复杂性因模块而异。例如，mdadm收集器手动解析一个文件，并暴露为该收集器专门创建的指标，因此我们也可以获得正确的指标。对于meminfo收集器，不同内核版本的结果各不相同，因此我们最终只做足够的转换来创建有效的指标。

配置

在处理应用程序时，你的目标应该是一个导出器，它不需要用户进行自定义配置，只需告诉用户应用程序的位置即可。你可能还需要提供过滤某些指标的能力，如果在大型设置中它们可能过于细粒度或代价太高，例如HAProxy导出器允许过滤每个服务器的统计数据。类似地，默认情况下可能会禁用一些代价太高的指标。

在使用其他监控系统、框架和协议时，你常常需要提供额外的配置或进行自定义，以生成适配Prometheus的指标。在最理想的情况下，监控系统具有与Prometheus类似的数据模型，你可以自动转换指标，Cloudwatch、SNMP 和 collectd就是如此。我们要做的就是让用户可以选择他们想要抓取的指标。

在其他情况下，来自系统的指标完全是非标准的，这取决于系统和底层应用程序的使用情况。在这种情况下，用户必须告诉我们如何转换指标。JMX导出器就是例子，Graphite 和 StatsD 导出器也需要配置来提取标签。

建议确保导出器在没有配置的情况下开箱即用，并在需要时提供用于转换的示例配置选择。

YAML是标准的Prometheus配置格式，所有配置默认使用YAML。

指标

命名

遵循指标命名的最佳实践。

一般来说，指标名称应该可以让熟悉Prometheus但不熟悉某个特定系统的人对指标的含义做出正确的猜测。一个名为http_requests_total的指标不是特别有用，它们是在刚进入，还是在某个过滤器，还是在到达用户代码时测量的呢？ requests_total更糟，是什么类型的请求？

使用直接添加监控（instrumentation），指定的指标应该存于一个文件中。因此，在导出器和收集器中，一个指标应该只应用于一个子系统，并相应地命名。

除非在编写自定义收集器或导出器时，否则指标名称不应该是程序生成的。

应用程序的指标名称通常应该以导出器名称为前缀，例如：haproxy_up。

指标必须使用基本单位（例如秒、字节），并将它们转换成对绘图工具更具可读性的内容。无论最终使用什么单位，指标名称中的单位必须与使用的单位匹配。类似的，暴露时使用比率（ratio），而不是百分比。更好的是，为比率的两个组件分别指定一个计数器。

指标名称不应该包括用于导出的标签，例如by_type，因为如果标签被聚合掉了，就没有意义了。

唯一的例外是，当你通过多个指标导出具有不同标签的相同数据时，这通常是区分它们的最明智的方法。对于直接添加监控（instrumentation），只有在导出具有所有标签的单一指标时才会出现这种情况，因为它的基数太高。

Prometheus指标和标签名称使用 snake_case格式。将camelCase转换为snake_case是可取的，但是自动地这么做对类似myTCPExample或isNaN的字符串并不是总是有效，所以有时候最好还是让它们保持原样。

暴露的指标不应该包含冒号，这些冒号保留给用户定义的记录规则，以便在聚合时使用。

只有[a-zA-Z0-9:_]在度量名称中有效，任何其他字符都应该被替换为下划线。

摘要图、直方图和计数器使用_sum、_count、_bucket和_total后缀。

_total是计数器的约定，如果使用COUNTER 类型，应该使用_total。

保留process_和scrape_前缀。如果遵循匹配语义，可以在这些前缀上添加自己的前缀。例如，Prometheus使用scrape_duration_seconds来表示抓取的时间，最好也使用一个以导出器为中心的指标，例如jmx_scrape_duration_seconds，表示特定的导出器花了多长时间来完成这件事。对于可以访问PID的进程统计信息，Go和Python都提供了处理这些信息的收集器。HAProxy导出器就是一个很好的例子。

当你有一个成功的请求计数和一个失败的请求计数时，将其暴露的最好方法是，暴露一个总请求数量的指标和一个失败请求数量的指标。这使得计算故障率变得很容易。不要使用带有失败或成功标签的指标。类似地，对于缓存的命中或未命中，最好使用一个总数的指标和一个缓存命中的指标。

考虑这样一种可能性，即使用监控的人将运行代码或web搜索来查找指标名称。如果这些名称非常完善，并且不太可能给领域之外的人（例如SNMP和网络工程师）使用，那么保持它们不变可能是一个好主意。这一逻辑并不适用于所有的导出器，例如，MySQL导出器指标可能被许多人使用，而不仅仅是DBA。使用包含原始名称的HELP字符串与直接使用原始名称效果大致相同。

完整译文请访问：http://www.coderdocument.com/docs/prometheus/v2.14/instrumenting/writing_exporters.html。