菜单
文档面包屑箭头 Grafana Mimir面包屑箭头 查询面包屑箭头 查询指标标签
开源

查询指标标签

Grafana Mimir 支持多个 HTTP API 端点来查询指标标签名称和值。这些 API 端点之间存在差异和权衡。

查询标签名称

以下 API 端点用于查找存储在 Mimir 中的所有（或部分）时间序列的标签名称列表

注意

<prometheus-http-prefix> 是 HTTP API 参考中记录的 Prometheus HTTP 前缀。默认前缀是 /prometheus。

建议和性能权衡

  • 优先使用 获取标签名称 API，而不是 标签名称基数 API，除非您需要知道每个标签名称的唯一标签值数量。
  • 获取标签名称 API 的 start 和 end 参数是可选的。如果省略，Mimir 将查询整个保留期或直到配置的 -store.max-labels-query-length 的标签名称。我们建议始终指定 start 和 end 参数，并且最好将它们设置为适用于您的用例的最短时间段。
  • 对于这两个 API 端点，执行指定时间序列选择器的请求比不带时间序列选择器的相同请求的计算成本更高。但是，当时间序列选择器减少时间序列集时，结果集可能会显著减小。

功能对比

不同的 API 端点具有不同的功能，主要区别如下。

请求中是否可以指定时间范围？

  • 获取标签名称
    可以。但是，实际的时间范围粒度仅限于 TSDB block 范围周期，在默认配置下运行 Mimir 时，最近的指标为 2h，历史指标最长为 24h。实际上，输入的 start 和 end 参数会四舍五入到 TSDB block 边界
    • start 参数会四舍五入到包含时间戳大于或等于输入时间戳的样本的最近 block 的开始时间。
    • end 参数会四舍五入到包含时间戳小于或等于输入时间戳的样本的最近 block 的结束时间。
  • 标签名称基数
    不可以。该 API 仅查询 Ingester 中为租户保存的内存中的时间序列。

请求中是否可以指定时间序列选择器？

  • 获取标签名称 API
    可以。可选的 match[] 参数可以用来选择从中读取标签名称的时间序列。match[] 参数可以多次指定。如果省略，则从所有时间序列中提取标签名称。
  • 标签名称基数 API
    可以。可选的 selector 参数可以用来选择从中读取标签名称的时间序列。selector 参数只能指定一次。如果省略，则从所有时间序列中提取标签名称。

查询标签值

以下 API 端点用于查找给定标签名称的标签值列表

  • 获取标签值
    GET <prometheus-http-prefix>/api/v1/label/{name}/values
  • 标签值基数
    GET,POST <prometheus-http-prefix>/api/v1/cardinality/label_values

注意

<prometheus-http-prefix> 是 HTTP API 参考中记录的 Prometheus HTTP 前缀。默认前缀是 /prometheus。

建议和性能权衡

  • 优先使用 获取标签值 API，而不是 标签值基数 API，除非您需要知道每个标签名称和值的系列数量。
  • 获取标签值 API 可以指定单个标签名称，而标签值基数 API 可以指定多个标签名称。如果您需要获取多个标签名称的标签值，我们建议发出多个获取标签值请求，而不是使用多个标签名称调用单个标签值基数 API。
  • 获取标签值 API 的 start 和 end 参数是可选的。如果省略，Mimir 将查询整个保留期或直到配置的 -store.max-labels-query-length 的标签值。我们建议始终指定 start 和 end 参数，并且最好将它们设置为适用于您的用例的最短时间段。时间范围越长，请求的计算成本越高。
  • 对于这两个 API 端点，执行指定时间序列选择器的请求比不带时间序列选择器的相同请求的计算成本更高。但是，当时间序列选择器减少时间序列集时，结果集可能会显著减小。

功能对比

不同的 API 端点具有不同的功能，主要区别如下。

请求中是否可以指定时间范围？

  • 获取标签值 API
    可以。但是，实际的时间范围粒度仅限于 TSDB block 范围周期，在默认配置下运行 Mimir 时，最近的指标为 2h，历史指标最长为 24h。实际上，输入的 start 和 end 参数会四舍五入到 TSDB block 边界
    • start 参数会四舍五入到包含时间戳大于或等于输入时间戳的样本的最近 block 的开始时间。
    • end 参数会四舍五入到包含时间戳小于或等于输入时间戳的样本的最近 block 的结束时间。
  • 标签值基数 API
    不可以。该 API 仅查询 Ingester 中为租户保存的内存中的时间序列。

请求中是否可以指定时间序列选择器？

  • 获取标签值 API
    可以。可选的 match[] 参数可以用来选择从中读取标签值的时间序列。match[] 参数可以多次指定。如果省略，则从所有时间序列中提取标签值。
  • 标签值基数 API
    可以。可选的 selector 参数可以用来选择从中读取标签名称和值的时间序列。selector 参数只能指定一次。如果省略，则从所有时间序列中提取标签名称和值。

替代方案

以下 API 端点并非专门用于查询指标标签名称和值，但可以从响应中提取标签名称和/或值

注意

<prometheus-http-prefix> 是 HTTP API 参考中记录的 Prometheus HTTP 前缀。默认前缀是 /prometheus。

建议和性能权衡

  • 优先使用 获取标签名称 API 获取标签名称列表。预计 获取标签名称 API 的性能始终优于其他 API。
  • 优先使用 获取标签值 API 获取标签值列表。
    • 如果您在使用 获取标签值 API 查询时响应时间较慢，并且请求包含时间序列选择器且预计时间序列选择器匹配的时间序列集很小（几千个数量级），则可以考虑使用 通过标签匹配器获取时间序列 API，而不是 获取标签值 API。
    • 如果您无法使用 通过标签匹配器获取时间序列 API（例如，您使用的客户端中没有该 API），则回退到 即时查询 API。