文档 Grafana Mimir 参考 HTTP API

Grafana Mimir HTTP API

Grafana Mimir 暴露了 HTTP API，您可以使用它来写入和查询时序数据，以及操作集群。

本文档按服务对 API 端点进行分组。请注意，当您在微服务模式、单体模式和读写模式下运行 Grafana Mimir 时，API 端点都会暴露。

• 微服务模式：每个服务都暴露其自己的端点。
• 单体模式：Grafana Mimir 实例暴露所有 API 端点。
• 读写模式：组件服务在其包含的端点上暴露。包括 Mimir read、Mimir write 或 Mimir backend。组件分组请参阅部署模式。

端点

路径前缀

下表提供了可配置的占位符路径前缀的使用方法。

身份验证

需要身份验证的端点必须通过指定 X-Scope-OrgID HTTP 请求头为租户 ID 来调用。

如果您禁用多租户，Grafana Mimir 不要求任何请求包含 X-Scope-OrgID 头。

可以通过 -auth.multitenancy-enabled 标志或其相应的 YAML 配置选项启用和禁用多租户。

有关身份验证和授权的更多信息，请参阅身份验证和授权。

所有服务

所有服务都暴露了以下 API 端点。

索引页

复制

GET /

此端点显示一个索引页，其中包含指向 Grafana Mimir 暴露的其他网页的链接。

配置

复制

GET /config

此端点显示当前应用于 Grafana Mimir 的配置，包括默认值和通过 CLI 标志设置的值。此端点以 YAML 格式提供配置并屏蔽敏感数据。

不同模式

复制

GET /config?mode=diff

此端点显示 Grafana Mimir 默认配置与当前配置之间的差异。

复制

GET /config?mode=defaults

此端点显示默认配置值。

状态配置

复制

GET /api/v1/status/config

此端点显示空的配置设置，它的存在仅是为了与 Prometheus 的 /api/v1/status/config API 兼容。

状态标志

复制

GET /api/v1/status/flags

此端点显示空的配置标志，它的存在仅是为了与 Prometheus 的 /api/v1/status/flags API 兼容。

运行时配置

复制

GET /runtime_config

此端点显示当前应用于 Grafana Mimir 的运行时配置（YAML 格式），包括默认值。只有在配置了 -runtime-config.file 选项后，此端点才可用。

不同模式

复制

GET /runtime_config?mode=diff

此端点显示 Grafana Mimir 默认运行时配置与当前运行时配置之间的差异。

服务状态

复制

GET /services

此端点显示一个网页，其中包含 Grafana Mimir 内部服务的状态。

就绪探针

复制

GET /ready

当 Grafana Mimir 准备好提供流量时，此端点返回 200。

指标

复制

GET /metrics

此端点以 Prometheus exposition 格式返回正在运行的 Grafana Mimir 服务的指标。

Pprof

复制

GET /debug/pprof/heap
GET /debug/pprof/block
GET /debug/pprof/profile
GET /debug/pprof/trace
GET /debug/pprof/goroutine
GET /debug/pprof/mutex

这些端点以 pprof 可视化工具预期的格式返回运行时性能分析数据。可以使用此端点分析许多内容，包括堆、追踪、goroutine 等。

有关 pprof 的更多信息，请参阅pprof。

Fgprof

复制

GET /debug/fgprof

此端点返回采样 Go 性能分析数据，可用于分析 On-CPU 和 Off-CPU（例如 I/O）时间。

有关 fgprof 的更多信息，请参阅fgprof。

构建信息

复制

GET /api/v1/status/buildinfo
GET <prometheus-http-prefix>/api/v1/status/buildinfo
GET <alertmanager-http-prefix>/api/v1/status/buildinfo

此端点以 JSON 格式返回有关构建和已启用功能的信息。返回的格式不完全相同，但类似于 Prometheus Build Information 端点。

格式化查询

复制

GET <prometheus-http-prefix>/api/v1/format_query?query={query}
POST <prometheus-http-prefix>/api/v1/format_query

格式化 PromQL 查询。

此端点与 Prometheus format query 端点兼容。

有关格式化查询的更多信息，请参阅 Prometheus 的文档。

Memberlist 集群

复制

GET /memberlist

此管理页面显示有关 Memberlist 集群（节点列表及其健康状况）和 KV 存储（KV 存储中的键和值）的信息。

如果启用了 Memberlist 消息历史记录，此页面还会显示存储在缓冲区中的所有已接收和已发送消息。这对于排除 Memberlist 集群故障很有用。要启用消息历史记录缓冲区，请使用 -memberlist.message-history-buffer-bytes CLI 标志或相应的 YAML 配置参数。

获取租户限制

复制

GET /api/v1/user_limits

以 JSON 格式返回经过身份验证的租户的实时限制。此 API 尚处于实验阶段。

需要身份验证。

只有在配置了 -runtime-config.file 选项后，此端点才可用。

Distributor

以下端点与 Distributor 相关。

远程写入

复制

POST /api/v1/push

Prometheus 远程写入的入口点。

此端点接受一个 HTTP POST 请求，其正文包含使用 Protocol Buffers 编码并使用 Snappy 压缩的请求。您可以在 pkg/mimirpb/mimir.proto 中找到 protobuf 消息的定义。HTTP 请求必须包含 X-Prometheus-Remote-Write-Version 头，并将其设置为 0.1.0。

要跳过标签名称验证，请执行以下操作：

• 启用 API 的标志 -api.skip-label-name-validation-header-enabled=true
• 确保请求带有 X-Mimir-SkipLabelNameValidation: true 头

此功能支持来自非标准下游客户端的写入，这些客户端的指标名称不符合 Prometheus 规范。

有关更多信息，请参阅 Prometheus 远程存储集成。

需要身份验证。

OTLP

复制

POST /otlp/v1/metrics

OTLP HTTP 的入口点。

此端点接受一个 HTTP POST 请求，其正文包含使用 Protocol Buffers 编码并可选地使用 GZIP 压缩的请求。您可以在 metrics.proto 中找到 protobuf 消息的定义。

需要身份验证。

Distributor 环状态

复制

GET /distributor/ring

此端点显示一个网页，其中包含 Distributor 哈希环状态，包括每个 Distributor 的状态、健康状况和上次心跳时间。

租户统计

复制

GET /distributor/all_user_stats

此端点显示一个网页，实时显示每个租户的统计信息，包括所有 Ingesters 中的活跃序列总数以及以每秒样本数显示的当前摄取率。

HA 跟踪器状态

复制

GET /distributor/ha_tracker

此端点显示一个网页，其中包含 HA 跟踪器的当前状态，包括每个 Prometheus HA 集群的当选副本。

Ingester

以下端点与 Ingester 相关。

刷新块 / 数据块

复制

GET,POST /ingester/flush

此端点触发将内存中的序列时序数据刷新到长期存储。当 -blocks-storage.tsdb.flush-blocks-on-shutdown 被禁用时，此端点也会触发刷新。

此端点接受一个 tenant 参数来指定要压缩和发送其数据块的租户。此参数可以多次指定以选择更多租户。如果未指定租户，则刷新所有租户。

flush 端点还接受 wait=true 参数，该参数使调用同步，并且仅在刷新完成后返回状态码。

准备关机

复制

GET,POST,DELETE /ingester/prepare-shutdown

此端点检查或更改内存中的 Ingester 配置，以准备永久停止 Ingester 实例，但实际上并不停止 Ingester 的任何部分。

向 prepare-shutdown 端点发送 POST 请求返回后，当 Ingester 进程接收到 SIGINT / SIGTERM 信号停止时，该 Ingester 将从环中注销，并且内存中的时序数据将刷新到长期存储。即使您禁用 -ingester.ring.unregister-on-shutdown，此端点也会导致 Ingester 在停止时从环中注销。

向 prepare-shutdown 端点发送 GET 请求返回此配置的状态，可以是 set 或 unset。

向 prepare-shutdown 端点发送 DELETE 请求将 Ingester 的配置恢复到其先前的状态（关于关机时注销和内存中时序数据刷新到长期存储）。

此 API 端点通常由 Kubernetes 特定的缩容自动化（例如 rollout-operator）使用。

关机

复制

POST /ingester/shutdown

此端点将内存中的时序数据从 Ingesters 刷新到长期存储，然后关闭 Ingester 服务。在 shutdown 端点返回后，操作员或使用的任何自动化程序会使用 SIGINT / SIGTERM 信号终止进程。在此期间，/ready 不会返回 200。即使您禁用 -ingester.ring.unregister-on-shutdown，此端点也会将 Ingester 从环中注销。

此 API 端点通常由缩容自动化使用。

准备分区缩容

复制

GET,POST,DELETE /ingester/prepare-partition-downscale

此端点通过将其设置为 INACTIVE 状态来准备 Ingester 的分区进行缩容。

对此端点发送 GET 请求返回分区切换到 INACTIVE 状态的时间戳，如果分区未处于 INACTIVE 状态，则返回 0。

对此端点发送 POST 请求将此 Ingester 的分区切换到 INACTIVE 状态（如果尚未处于 INACTIVE 状态），并返回切换到 INACTIVE 状态的时间戳。

对此端点发送 DELETE 请求将分区从 INACTIVE 状态切换回 ACTIVE 状态。

如果 Ingester 未配置使用 ingest-storage，则对此端点的任何调用都会失败。

此 API 端点通常由缩容自动化使用，例如 rollout-operator。

准备实例环缩容

复制

GET,POST,DELETE /ingester/prepare-instance-ring-downscale

此端点通过将其设置为只读模式来准备 Ingester 进行缩容。

对此端点发送 GET 请求返回 Ingester 切换到只读模式的时间戳，如果 Ingester 未处于只读模式，则返回 0。

对此端点发送 POST 请求将此 Ingester 的分区切换到只读模式（如果尚未处于只读状态），并返回切换到只读模式的时间戳。

对此端点发送 DELETE 请求将 Ingester 切换回读写模式。

如果 Ingester 配置使用 ingest-storage，则对此端点的任何调用都会失败。

此 API 端点通常由缩容自动化使用，例如 rollout-operator。

准备注销

复制

GET,PUT,DELETE /ingester/unregister-on-shutdown

此端点控制 Ingester 在下次终止时（即下次收到 SIGINT 或 SIGTERM 信号时）是否应该从环中注销。通过此端点，Mimir 操作员可以动态控制 Ingester 的 -ingester.ring.unregister-on-shutdown 状态，而无需重新启动 Ingester。

PUT 方法设置 Ingester 的注销状态。使用 PUT 方法调用时，端点需要请求体

复制

{"unregister": true}

GET 方法返回 Ingester 当前的注销状态。

DELETE 方法将 Ingester 的注销状态重置为通过 -ingester.ring.unregister-on-shutdown 配置选项传递的值。

无论使用哪种 HTTP 方法，端点始终返回带有 Ingester 当前注销状态的响应体

复制

{"unregister": true}

TSDB 指标

复制

GET /ingester/tsdb_metrics

此端点返回每个租户 TSDB 暴露的底层指标。这对于故障排除很有用。与 /metrics 的区别在于，/metrics 中返回的指标是所有打开的 TSDB 的聚合数据，而此端点仅返回特定租户的 TSDB 指标。

需要身份验证，经过身份验证的租户是返回其 TSDB 指标的租户。

Ingsters 环状态

复制

GET /ingester/ring

此端点显示一个网页，其中包含 Ingesters 哈希环状态，包括每个 Ingester 的状态、健康状况和上次心跳时间。

Ingester 租户

复制

GET /ingester/tenants

显示一个网页，其中包含给定 Ingester 上打开了 TSDB 的租户列表。

Ingester 租户 TSDB

复制

GET /ingester/tsdb/{tenant}

显示一个网页，其中包含给定 Ingester 上租户打开的 TSDB 的详细信息。

Querier / Query-frontend

以下端点由 Querier 和 Query-frontend 共同暴露。

即时查询

复制

GET,POST <prometheus-http-prefix>/api/v1/query

此端点与 Prometheus 即时查询端点兼容。

有关 Prometheus 即时查询的更多信息，请参阅 Prometheus 即时查询。

需要身份验证。

范围查询

复制

GET,POST <prometheus-http-prefix>/api/v1/query_range

此端点与 Prometheus 范围查询端点兼容。当客户端通过 Query-frontend 发送请求时，Query-frontend 使用缓存和并行执行来加速查询。

有关 Prometheus 范围查询的更多信息，请参阅 Prometheus 范围查询。

需要身份验证。

Exemplar 查询

复制

GET,POST <prometheus-http-prefix>/api/v1/query_exemplars

此端点与 Prometheus exemplar query 端点兼容。

有关 Prometheus exemplar 查询的更多信息，请参阅 Prometheus exemplar query。

需要身份验证。

按标签匹配器获取序列

复制

GET,POST <prometheus-http-prefix>/api/v1/series

有关更多信息，请参阅 Prometheus series 端点。

需要身份验证。

按选择器获取活跃序列

复制

GET,POST <prometheus-http-prefix>/api/v1/cardinality/active_series

返回与 PromQL 选择器匹配的所有活跃序列的标签集。

此端点类似于series 端点，但在查询处理时对被视为活跃的序列集进行操作。如果在由 -ingester.active-series-metrics-idle-timeout 指定的时间段内有任何数据写入，则该序列被视为活跃。

此端点默认禁用；您可以通过 -querier.cardinality-analysis-enabled CLI 标志（或其相应的 YAML 配置选项）启用它。

需要身份验证。

查询参数

• selector - 必需 - 用于过滤结果集的 PromQL 选择器。

请求头

• Sharding-Control - 可选 - 指定用于请求执行的分片数量的整数值。

响应格式

响应格式是series 端点格式的子集，仅包含 data 字段。以下显示了此端点的示例请求/响应对。data 数组中的每个项对应于一个匹配的序列。

shell 复制

$ curl 'https://:9090/api/v1/cardinality/active_series' \
    --header 'Sharding-Control: 4' \ # optional
    --data-urlencode 'selector=up'

shell 复制

{
   "data" : [
      {
         "__name__" : "up",
         "job" : "prometheus",
         "instance" : "localhost:9090"
      },
      {
         "__name__" : "up",
         "job" : "node",
         "instance" : "localhost:9091"
      },
      {
         "__name__" : "process_start_time_seconds",
         "job" : "prometheus",
         "instance" : "localhost:9090"
      }
   ]
}

缓存

active series 端点的响应永远不会被缓存。

获取标签名称

复制

GET,POST <prometheus-http-prefix>/api/v1/labels

有关更多信息，请参阅 Prometheus 获取标签名称。

需要身份验证。

缓存

如果启用了 -query-frontend.cache-results 并且 -query-frontend.results-cache-ttl-for-labels-query 设置为大于 0 的值，Query-frontend 可能会返回从查询结果缓存中获取的陈旧响应。

获取标签值

复制

GET <prometheus-http-prefix>/api/v1/label/{name}/values

有关更多信息，请参阅 Prometheus 查询标签值。

需要身份验证。

缓存

如果启用了 -query-frontend.cache-results 并且 -query-frontend.results-cache-ttl-for-labels-query 设置为大于 0 的值，Query-frontend 可能会返回从查询结果缓存中获取的陈旧响应。

获取指标元数据

复制

GET <prometheus-http-prefix>/api/v1/metadata

Prometheus 兼容的指标元数据端点。

有关更多信息，请参阅 Prometheus 指标元数据。

需要身份验证。

远程读取

复制

POST <prometheus-http-prefix>/api/v1/read

Prometheus 兼容的远程读取端点。

有关更多信息，请参阅 Prometheus 远程存储集成。

需要身份验证。

标签名称基数

复制

GET,POST <prometheus-http-prefix>/api/v1/cardinality/label_names

以 JSON 格式返回经过身份验证的租户在所有 Ingesters 中的标签名称基数。它计算每个标签名称的不同标签值数量。

cardinality 字段中的项按 label_values_count 降序排列，按 label_name 升序排列。项的数量受 limit 请求参数限制。

此端点默认禁用，可以通过 -querier.cardinality-analysis-enabled CLI 标志（或其相应的 YAML 配置选项）启用。

需要身份验证。

按 inmemory 或 active 计算序列

提供了两种计数方法：inmemory 和 active。要选择其中一种，请使用 count_method 参数。

inmemory 方法计算 Mimir 的 Ingesters 中当前打开的 TSDB 中的标签数量。如果在两次调用之间某个 Ingester 写入了一个块，则两次后续调用可能会返回完全不同的结果。此计数方法对于理解 Ingester 内存使用情况最有用。

active 方法也计算 Mimir 的 Ingesters 中当前打开的 TSDB 中的标签数量，但会过滤掉在可配置时间段内未接收到样本的值。要配置此持续时间，请使用 -ingester.active-series-metrics-idle-timeout 参数。此计数方法对于理解 Mimir 在最近 -ingester.active-series-metrics-idle-timeout 时间段内摄取的样本中包含哪些标签值最有用。两次后续调用可能会返回相似的结果，因为此时间窗口与 Ingesters 上的块写入无关。值仅会因 Mimir 摄取的数据变化而变化。

缓存

如果启用了 -query-frontend.cache-results 并且 -query-frontend.results-cache-ttl-for-cardinality-query 设置为大于 0 的值，Query-frontend 可能会返回从查询结果缓存中获取的陈旧响应。

请求参数

• selector - 可选 - 指定用于过滤必须分析的序列的 PromQL 选择器。
• count_method - 可选 - 指定将使用哪种序列计数方法。(默认值=“inmemory”，可用选项=[“inmemory”, “active”])
• limit - 可选 - 指定响应中 cardinality 字段的最大项数（默认值=20，最小值=0，最大值=500）

响应模式

json 复制

{
  "label_values_count_total": <number>,
  "label_names_count": <number>,
  "cardinality": [
    {
      "label_name": <string>,
      "label_values_count": <number>
    }
  ]
}

标签值基数

复制

GET,POST <prometheus-http-prefix>/api/v1/cardinality/label_values

以 JSON 格式返回经过身份验证的租户在所有 Ingesters 中与请求参数 label_names[] 相关的标签值基数。它返回与请求参数 label_names[] 相关的每个标签值的序列计数。

labels 字段中的项按 series_count 降序排列，按 label_name 升序排列。cardinality 字段中的项按 series_count 降序排列，按 label_value 升序排列。cardinality 项的数量受请求参数 limit 限制。

此端点默认禁用；您可以通过 -querier.cardinality-analysis-enabled CLI 标志（或其相应的 YAML 配置选项）启用它。

需要身份验证。

按 inmemory 或 active 计算序列

提供了两种计数方法：inmemory 和 active。要选择其中一种，请使用 count_method 参数。

inmemory 方法计算 Mimir 的 Ingesters 中当前打开的 TSDB 中的序列数量。如果在两次调用之间某个 Ingester 写入了一个块，则两次后续调用可能会返回完全不同的结果。此计数方法对于理解 Ingester 内存使用情况最有用。

active 方法也计算 Mimir 的 Ingesters 中当前打开的 TSDB 中的序列数量，但会过滤掉在可配置时间段内未接收到样本的序列。要配置此持续时间，请使用 -ingester.active-series-metrics-idle-timeout 参数。此计数方法对于理解 Mimir 在最近 -ingester.active-series-metrics-idle-timeout 时间段内摄取的样本中包含哪些标签值最有用。两次后续调用可能会返回相似的结果，因为此时间窗口与 Ingesters 上的块写入无关。值仅会因 Mimir 摄取的数据变化而变化。

缓存

如果启用了 -query-frontend.cache-results 并且 -query-frontend.results-cache-ttl-for-cardinality-query 设置为大于 0 的值，Query-frontend 可能会返回从查询结果缓存中获取的陈旧响应。

请求参数

• label_names[] - 必需 - 指定需要提供基数的标签。
• selector - 可选 - 指定用于过滤必须分析的序列的 PromQL 选择器。
• count_method - 可选 - 指定将使用哪种序列计数方法。(默认值=“inmemory”，可用选项=[“inmemory”, “active”])
• limit - 可选 - 指定响应中字段 cardinality 的最大项目数（默认值=20，最小值=0，最大值=500）。

响应模式

json 复制

{
  "series_count_total": <number>,
  "labels": [
    {
      "label_name": <string>,
      "label_values_count": <number>,
      "series_count": <number>,
      "cardinality": [
        {
          "label_value": <string>,
          "series_count": <number>
        }
      ]
    }
  ]
}

• series_count_total - 所有 ingester 中所有已打开的 TSDB 中的序列总数
• labels[].label_name - 通过请求参数 label_names[] 请求的标签名称
• labels[].label_values_count - 标签名称的总标签值数量（请注意，根据 limit 请求参数，并非所有标签值都可能出现在 cardinality 中）
• labels[].series_count - 具有 labels[].label_name 的序列总数
• labels[].cardinality[].label_value - 与 labels[].label_name 关联的标签值
• labels[].cardinality[].series_count - 具有 label_name 的 label_value 的序列总数

Querier

获取租户摄取统计

复制

GET /api/v1/user_stats

以 JSON 格式返回经身份验证的租户的实时摄取速率。

需要身份验证。

Query-scheduler

Query-scheduler 环状态

复制

GET /query-scheduler/ring

显示一个网页，其中包含查询调度器哈希环状态，包括每个查询调度器的状态、健康状况和上次心跳时间。只有当 -query-scheduler.service-discovery-mode 设置为 ring 时，查询调度器环才可用。

Ruler

ruler API 端点需要配置后端对象存储来存储记录规则和警报。ruler API 在创建规则组时使用了“命名空间”的概念。这替代了 Prometheus 中的规则文件名称，并且规则组在命名空间内必须唯一命名。

Ruler 环状态

复制

GET /ruler/ring

显示一个网页，其中包含 ruler 哈希环状态，包括每个 ruler 的状态、健康状况和上次心跳时间。

Ruler 规则

复制

GET /ruler/rule_groups

列出所有租户规则。此端点不是 ruler-API 的一部分，并且无论 ruler-API 是否启用，都始终可用。它不应暴露给最终用户。此端点返回一个 YAML 字典，其中包含每个租户的所有规则组，并在成功时返回 200 状态码。

列出 Prometheus 规则

复制

GET <prometheus-http-prefix>/api/v1/rules?type={alert|record}&file={}&rule_group={}&rule_name={}&exclude_alerts={true|false}

Prometheus 兼容的规则端点，用于列出当前加载的警报和记录规则。

type 参数是可选的。如果设置，则只返回指定类型的规则。

file、rule_group 和 rule_name 参数是可选的，并且可以接受多个值。如果设置，则响应内容会相应地被过滤。这些参数也可以作为 file[]、rule_group[] 和 rule_name[] 提供 - 如果同时提供了例如 file 和 file[]，则 file[] 将优先。

exclude_alerts 参数是可选的。如果设置，它只返回规则并排除活动警报。

group_limit 和 group_next_token 参数是可选的。如果设置了 group_limit，它将限制单个响应中返回的规则组数量。如果规则组总数超过此值，则响应将包含一个 groupNextToken。可以通过 group_next_token 将此令牌传递到后续请求中，以对剩余的组进行分页。最终响应将不包含令牌。有关更多信息，请参阅 Prometheus 规则 文档。

需要身份验证。

列出 Prometheus 警报

复制

GET <prometheus-http-prefix>/api/v1/alerts

Prometheus 兼容的规则端点，用于列出所有活动警报。

有关更多信息，请参阅 Prometheus 警报 文档。

需要身份验证。

列出规则组

复制

GET <prometheus-http-prefix>/config/v1/rules

列出为经身份验证的租户配置的所有规则。此端点返回一个 YAML 字典，其中包含每个命名空间的所有规则组，并在成功时返回 200 状态码。

可以通过 -ruler.enable-api CLI 标志（或其相应的 YAML 配置选项）禁用此端点。

需要身份验证。

响应示例

yaml 复制

---
<namespace1>:
- name: <string>
  interval: <duration;optional>
  source_tenants:
    - <string>
  rules:
  - record: <string>
      expr: <string>
  - alert: <string>
      expr: <string>
      for: <duration>
      annotations:
        <annotation_name>: <string>
      labels:
        <label_name>: <string>
- name: <string>
  interval: <duration;optional>
  source_tenants:
    - <string>
  rules:
  - record: <string>
      expr: <string>
  - alert: <string>
      expr: <string>
      for: <duration>
      annotations:
        <annotation_name>: <string>
      labels:
        <label_name>: <string>
<namespace2>:
- name: <string>
  interval: <duration;optional>
  source_tenants:
    - <string>
  rules:
  - record: <string>
      expr: <string>
  - alert: <string>
      expr: <string>
      for: <duration>
      annotations:
        <annotation_name>: <string>
      labels:
        <label_name>: <string>

按命名空间获取规则组

复制

GET <prometheus-http-prefix>/config/v1/rules/{namespace}

返回为给定命名空间定义的规则组。根据 RFC 3986 中定义的方式，使用百分比编码对 {namespace} 路径段进行转义。例如，将 / 转义为 %2F。

可以通过 -ruler.enable-api CLI 标志（或其相应的 YAML 配置选项）禁用此端点。

需要身份验证。

响应示例

yaml 复制

name: <string>
interval: <duration;optional>
source_tenants:
  - <string>
rules:
  - record: <string>
    expr: <string>
  - alert: <string>
    expr: <string>
    for: <duration>
    annotations:
      <annotation_name>: <string>
    labels:
      <label_name>: <string>

获取规则组

复制

GET <prometheus-http-prefix>/config/v1/rules/{namespace}/{groupName}

返回与请求命名空间和组名称匹配的规则组。根据 RFC 3986 中定义的方式，使用百分比编码对 {namespace} 和 {groupName} 路径段进行转义。例如，将 / 转义为 %2F。

可以通过 -ruler.enable-api CLI 标志（或其相应的 YAML 配置选项）禁用此端点。

需要身份验证。

设置规则组

复制

POST /<prometheus-http-prefix>/config/v1/rules/{namespace}

创建或更新规则组。此端点需要请求包含 Content-Type: application/yaml 头部以及请求体中的规则组 YAML 定义，并在成功时返回 202。请求体必须仅包含一个规则组的定义。根据 RFC 3986 中定义的方式，使用百分比编码对 {namespace} 路径段进行转义。例如，将 / 转义为 %2F。

可以通过 -ruler.enable-api CLI 标志（或其相应的 YAML 配置选项）禁用此端点。

需要身份验证。

请求体示例

yaml 复制

name: MyGroupName
rules:
  - alert: MyAlertName
    expr: up == 0
    labels:
      severity: warning

删除规则组

复制

DELETE /<prometheus-http-prefix>/config/v1/rules/{namespace}/{groupName}

按命名空间和组名称删除规则组。此端点在成功时返回 202。根据 RFC 3986 中定义的方式，使用百分比编码对 {namespace} 和 {groupName} 路径段进行转义。例如，将 / 转义为 %2F。

可以通过 -ruler.enable-api CLI 标志（或其相应的 YAML 配置选项）禁用此端点。

需要身份验证。

删除命名空间

复制

DELETE /<prometheus-http-prefix>/config/v1/rules/{namespace}

删除命名空间中的所有规则组（包括命名空间本身）。此端点在成功时返回 202。根据 RFC 3986 中定义的方式，使用百分比编码对 {namespace} 路径段进行转义。例如，将 / 转义为 %2F。

可以通过 -ruler.enable-api CLI 标志（或其相应的 YAML 配置选项）禁用此端点。

需要身份验证。

删除租户配置

复制

POST /ruler/delete_tenant_config

这将删除租户的所有规则组，并在成功时返回 200。当租户不存在规则组时调用此端点也会返回 200。身份验证仅用于识别租户。

这旨在作为内部 API，不应暴露给用户。无论 -ruler.enable-api 是否启用，此端点都已启用。

需要身份验证。

Alertmanager

Alertmanager 状态

复制

GET /multitenant_alertmanager/status

显示一个网页，其中包含 Alertmanager 的当前状态，包括 Alertmanager 集群成员。

Alertmanager 配置

复制

GET /multitenant_alertmanager/configs

列出所有 Alertmanager 配置。此端点不是 Alertmanager API 的一部分，并且无论 Alertmanager API 是否启用，都始终可用。它不应暴露给最终用户。此端点返回一个 YAML 字典，其中包含所有 Alertmanager 配置，并在成功时返回 200 状态码。

Alertmanager 环状态

复制

GET /multitenant_alertmanager/ring

显示一个网页，其中包含 Alertmanager 哈希环状态，包括每个 Alertmanager 实例的状态、健康状况和上次心跳时间。

Alertmanager UI

复制

GET /<alertmanager-http-prefix>

显示 Alertmanager UI。

需要身份验证。

Alertmanager 删除租户配置

复制

POST /multitenant_alertmanager/delete_tenant_config

此端点删除由 X-Scope-OrgID 头部标识的租户配置。它是内部端点，即使 Alertmanager API 被禁用也可用。如果用户的配置已被删除或从未存在，此端点将返回状态码 200。

需要身份验证。

获取 Alertmanager 配置

复制

GET /api/v1/alerts

获取经身份验证的租户的当前 Alertmanager 配置，该配置从配置的对象存储中读取。

此端点不接受任何 URL 查询参数，并在成功时返回 200。

可以通过 -alertmanager.enable-api CLI 标志（或其相应的 YAML 配置选项）启用或禁用此端点。

需要身份验证。

设置 Alertmanager 配置

复制

POST /api/v1/alerts

存储或更新经身份验证的租户的 Alertmanager 配置。Alertmanager 配置存储在配置的后端对象存储中。

此端点需要在请求体中包含 Alertmanager YAML 配置，并在成功时返回 201。

template_files 中的模板名称必须是有效的文件名，且不能包含任何路径分隔符。例如，/templates/my-template.tpl 和 ./my-template.tpl 都无效，而 my-template.tpl 有效。

可以通过 -alertmanager.enable-api CLI 标志（或其相应的 YAML 配置选项）启用或禁用此端点。

需要身份验证。

请求体示例

yaml 复制

template_files:
  default_template: |
    {{ define "__alertmanager" }}AlertManager{{ end }}
    {{ define "__alertmanagerURL" }}{{ .ExternalURL }}/#/alerts?receiver={{ .Receiver | urlquery }}{{ end }}
alertmanager_config: |
  global:
    smtp_smarthost: 'localhost:25'
    smtp_from: 'youraddress@example.org'
  templates:
    - 'default_template'
  route:
    receiver: example-email
  receivers:
    - name: example-email
      email_configs:
      - to: 'youraddress@example.org'

删除 Alertmanager 配置

复制

DELETE /api/v1/alerts

删除经身份验证的租户的 Alertmanager 配置。

此端点不接受任何 URL 查询参数，并在成功时返回 200。

可以通过 -alertmanager.enable-api CLI 标志（或其相应的 YAML 配置选项）启用或禁用此端点。

需要身份验证。

Store-gateway

Store-gateway 环状态

复制

GET /store-gateway/ring

显示一个网页，其中包含 store-gateway 哈希环状态，包括每个 store-gateway 的状态、健康状况和上次心跳时间。

Store-gateway 租户

复制

GET /store-gateway/tenants

显示一个网页，其中包含在为 store-gateway 配置的存储中拥有块的租户列表。

Store-gateway 租户数据块

复制

GET /store-gateway/tenant/{tenant}/blocks

显示一个网页，列出给定租户的块。

准备关机

复制

GET,POST,DELETE /store-gateway/prepare-shutdown

此端点更改内存中的 store-gateway 配置，以准备永久停止 store-gateway 实例，但实际不停止后者的任何部分。

向 prepare-shutdown 端点发送 POST 请求返回后，当 store-gateway 进程接收到 SIGINT / SIGTERM 信号停止时，store-gateway 将从环中注销。

向 prepare-shutdown 端点发送 GET 请求返回此配置的状态，可以是 set 或 unset。

向 prepare-shutdown 端点发送 DELETE 请求将 store-gateway 的配置恢复到之前（关于注销）的状态。

此 API 端点通常由 Kubernetes 特定的缩容自动化（例如 rollout-operator）使用。

Compactor

Compactor 环状态

复制

GET /compactor/ring

显示一个网页，其中包含 compactor 哈希环状态，包括每个 compactor 的状态、健康状况和上次心跳时间。

开始数据块上传

复制

POST /api/v1/upload/block/{block}/start

开始将具有给定 ID 的 TSDB 块上传到对象存储。客户端应将块的 meta.json 文件作为请求体发送。如果对象存储中已存在完整的块，则返回 409（冲突）状态码。如果提供的 meta.json 文件无效，则返回 400（错误请求）状态码。如果块的最大时间在租户保留期之前，则返回 422（不可处理实体）状态码。

提供的 meta.json 文件必须包含一个 thanos.files 部分，其中列出了块的文件列表，否则请求将被拒绝。

如果 API 请求成功，块的 meta.json 文件的清理版本将以 uploading-meta.json 名称上传到对象存储，并返回 200 状态码。然后您可以开始上传文件，完成后，您可以请求完成块上传。

需要身份验证。

上传数据块文件

复制

POST /api/v1/upload/block/{block}/files?path={path}

为具有给定 ID 的块上传指定路径的文件。文件路径必须是以下之一，否则将返回 400（错误请求）状态码

• 索引
• 块/<6位数字>

客户端必须将文件内容作为请求体发送；如果请求体为空，则返回 400（错误请求）状态码。如果对象存储中已存在完整的块，则返回 409（冲突）状态码。如果对象存储中不存在针对该块的正在上传的元文件（uploading-meta.json），则返回 404（未找到）状态码。

如果 API 请求成功，文件将以给定路径上传到对象存储中的块目录，并返回 200 状态码。

需要身份验证。

完成数据块上传

复制

POST /api/v1/upload/block/{block}/finish

启动将具有给定 ID 的 TSDB 块完成上传到对象存储的过程。如果对象存储中已存在完整的块，则返回 409（冲突）状态码。如果对象存储中不存在针对该块的正在上传的元文件（uploading-meta.json），则返回 404（未找到）状态码。如果 compactor 已达到其并发块上传验证的最大数量限制（通过 -compactor.max-block-upload-validation-concurrency 配置），则返回 429（请求过多）。

如果 API 请求成功，compactor 将在后台开始块验证。如果后台验证通过，通过将块目录中正在上传的元文件重命名为 meta.json 来完成块上传。

此 API 端点在验证开始时返回 200（OK）。要进一步检查块上传的状态，请使用 检查块上传 API 端点。

需要身份验证。

此 API 端点是实验性的，未来可能会更改。

检查数据块上传

复制

GET /api/v1/upload/block/{block}/check

返回块上传的状态。状态以 JSON 对象形式返回，包含 result 字段，可能的值如下：

• complete – 块验证已完成，块上传现已结束。
• uploading – 块仍在上传中，且尚未对该块调用 完成块上传。
• validating – 块正在被验证。验证是由调用 完成块上传 API 启动的。
• failed – 块验证失败。错误消息可在返回的 JSON 对象的 error 字段中获取。

响应示例

json 复制

{ "result": "uploading" }

响应示例

json 复制

{ "result": "failed", "error": "missing index file" }

需要身份验证。

此 API 端点是实验性的，未来可能会更改。

租户删除请求

复制

POST /compactor/delete_tenant

请求删除 X-Scope-OrgID 头部中指定的租户的所有租户数据。如果禁用身份验证，则删除默认的 anonymous 租户（可通过 -auth.no-auth-tenant 配置）。

需要身份验证。

租户删除状态

复制

GET /compactor/delete_tenant_status

返回租户删除的状态。

响应模式

json 复制

{
  "tenant_id": "<id>",
  "blocks_deleted": true
}

如果租户的所有块都被删除，则 blocks_deleted 字段将设置为 true。

需要身份验证。

Compactor 租户

复制

GET /compactor/tenants

显示一个网页，其中包含在为 compactor 配置的存储中拥有块的租户列表。

Compactor 租户计划作业

复制

GET /compactor/tenant/{tenant}/planned_jobs

显示一个网页，列出根据给定租户的存储桶索引计算出的计划压缩作业。

Overrides-exporter

Overrides-exporter 环状态

复制

GET /overrides-exporter/ring

显示一个网页，其中包含 overrides-exporter 哈希环状态，包括每个 overrides-exporter 的状态、健康状况和上次心跳时间。只有当 -overrides-exporter.ring.enabled 设置为 true 时，overrides-exporter 环才可用。