跳到主要内容

仪表命名

DeepSeek V3 中英对照 Naming Meters

Micrometer 采用了一种命名规范，使用 .（点）字符来分隔小写单词。不同的监控系统对于命名规范有不同的建议，某些命名规范可能在一个系统和另一个系统之间不兼容。每个针对监控系统的 Micrometer 实现都附带了一个命名规范，该规范将小写点符号名称转换为监控系统推荐的命名规范。此外，该命名规范实现还会从指标名称和标签中移除监控系统不允许的特殊字符。你可以通过实现 NamingConvention 并在注册表上设置它来覆盖注册表的默认命名规范：

registry.config().namingConvention(myCustomNamingConvention);
java

有了命名规范后，以下在 Micrometer 中注册的计时器在各种监控系统中看起来都很自然：

registry.timer("http.server.requests");
java
  1. Prometheus - http_server_requests_duration_seconds
  2. Atlas - httpServerRequests
  3. Graphite - http.server.requests
  4. InfluxDB - http_server_requests

通过遵循 Micrometer 的小写点符号约定，你可以确保你的指标名称在监控系统之间具有最大程度的可移植性。

标签命名​

提示

我们建议您在命名标签时遵循与指标名称相同的小写点符号表示法。使用这种一致的命名约定可以使标签更好地转换为相应监控系统的惯用命名方案。

假设我们正在尝试测量 HTTP 请求的数量和数据库调用的数量。

推荐方法

registry.counter("database.calls", "db", "users")
registry.counter("http.requests", "uri", "/api/users")
java

此变体提供了足够的上下文，因此，如果仅选择了名称，可以推断出该值，并且至少具有潜在的意义。例如，如果我们选择 database.calls，我们可以看到所有数据库的调用总数。然后，我们可以通过 db 进行分组或选择，以进一步深入分析或对每个数据库的调用贡献进行比较分析。

错误的方法

registry.counter("calls",
    "class", "database",
    "db", "users");

registry.counter("calls",
    "class", "http",
    "uri", "/api/users");
java

在这种方法中，如果我们选择 calls，我们将得到一个值，该值是数据库调用和 API 端点调用次数的聚合。如果没有进一步的维度下钻，这个时间序列是没有用的。

常用标签​

你可以在注册表级别定义通用标签，并将它们添加到报告给监控系统的每个指标中。这通常用于对操作环境进行维度下钻，例如主机、实例、区域、堆栈等。以下两行代码以两种等效的方式设置相同的标签：

registry.config().commonTags("stack", "prod", "region", "us-east-1");
registry.config().commonTags(Arrays.asList(Tag.of("stack", "prod"), Tag.of("region", "us-east-1"))); // equivalently
java

对 commonTags 的进一步调用会追加额外的公共标签。

important

通常情况下，公共标签必须在任何（可能是自动配置的）计量器绑定器之前添加到注册表中。根据你的环境，有不同的方法来实现这一点。

如果你使用 Spring Boot，你有两个选择：

  • 使用配置属性添加你的公共标签

  • 如果需要更大的灵活性（例如，你必须向共享库中定义的注册表添加公共标签），可以将 MeterRegistryCustomizer 回调接口注册为一个 bean 来添加你的公共标签。更多信息请参阅 Spring Boot 参考文档。

标签值​

标签值必须为非空。

注意

注意来自用户提供的源的标签值可能会导致指标的基数爆炸。你应该始终仔细地对用户提供的输入进行规范化并添加限制。有时，原因很隐蔽。考虑用于记录服务端点上 HTTP 请求的 URI 标签。如果我们不将 404 限制为类似 NOT_FOUND 的值，指标的维度将随着每个找不到的资源而增长。