菜单
文档breadcrumb arrow Grafana Mimirbreadcrumb arrow 管理breadcrumb arrow 工具breadcrumb arrow Query-tee
开源

Grafana Mimir query-tee

Query-tee 是一个独立工具，您可以在比较两个 Grafana Mimir 集群的查询结果和性能时用于测试。Query-tee 比较的两个 Mimir 集群必须摄取相同的序列和样本。

Query-tee 公开了与 Prometheus 兼容的读取 API 端点，并充当代理。当 query-tee 收到请求时，它会针对两个后端 Grafana Mimir 集群执行相同的请求，并跟踪每个后端的响应时间，然后比较查询结果。

下载 query-tee

  • 使用 Docker
bash 
docker pull "grafana/query-tee:latest"
  • 使用本地二进制文件

下载适用于您的操作系统和架构的相应发布资产并使其可执行。

对于 AMD64 架构的 Linux，执行以下命令

bash 
curl -Lo query-tee https://github.com/grafana/mimir/releases/latest/download/query-tee-linux-amd64
chmod +x query-tee

配置 query-tee

Query-tee 需要后端 Grafana Mimir 集群的端点。您可以通过将 -backend.endpoints 标志设置为逗号分隔的 HTTP 或 HTTPS URL 列表来配置后端端点。

对于每个传入请求，query-tee 会克隆该请求并将其发送到每个配置的后端。

注意

您可以通过 -server.http-service-port 标志配置 query-tee 代理的 HTTP 监听端口，通过 server.grpc-service-port 标志配置 gRPC 监听端口。

query-tee 的工作原理

本节描述了 query-tee 工具的工作原理。

API 端点

Query-tee 接受两种类型的请求

  1. 配置的 -server.http-service-port 标志上的 HTTP 请求（默认端口 80）
  2. 配置的 -server.grpc-service-port 标志上的 HTTP over gRPC 请求（默认端口：9095）

query-tee 支持以下 Prometheus API 端点

  • GET <prefix>/api/v1/query
  • GET <prefix>/api/v1/query_range
  • GET <prefix>/api/v1/query_exemplars
  • GET <prefix>/api/v1/labels
  • GET <prefix>/api/v1/label/{name}/values
  • GET <prefix>/api/v1/series
  • GET <prefix>/api/v1/metadata
  • GET <prefix>/api/v1/alerts
  • GET <prefix>/prometheus/config/v1/rules

您可以通过设置 -server.path-prefix 标志来配置 <prefix>，该标志默认为空字符串。

透传请求

Query-tee 可以选择性地充当透明代理，处理不匹配任何支持的 API 端点的请求。您可以通过设置 -proxy.passthrough-non-registered-routes=true 并使用 -backend.preferred 标志配置首选后端来启用透传支持。启用透传后，对不支持的 API 端点的请求会透明地代理到配置的首选后端。

身份验证

Query-tee 支持 HTTP Basic Authentication（基本身份验证）。Query-tee 可以将接收到的请求中的 HTTP 基本身份验证与后端 URL 中配置的用户名和密码合并。

Query-tee 发送到后端的请求在满足以下任一条件时会包含 HTTP 基本身份验证

  • 如果后端端点 URL 同时配置了用户名和密码，则 query-tee 会使用它。
  • 如果后端端点 URL 只配置了用户名，则 query-tee 会保留配置的用户名，并将传入请求中接收到的密码注入。
  • 如果后端端点 URL 没有配置用户名和密码，则 query-tee 会转发传入请求中的身份验证凭据。

后端选择

您可以使用 query-tee 将请求发送到所有后端，或者将一部分请求发送到所有后端，其余请求仅发送到首选后端。您可以使用 -proxy.secondary-backends-request-proportion CLI 标志进行配置。

例如，如果您将 -proxy.secondary-backends-request-proportion CLI 标志设置为 1.0，则所有请求都会发送到所有后端。或者，如果您将 -proxy.secondary-backends-request-proportion CLI 标志设置为 0.2，则 20% 的请求会发送到所有后端，其余 80% 的请求仅发送到您的首选后端。

后端响应选择

Query-tee 使您能够配置一个首选后端，该后端选择要发送回客户端的响应。Query-tee 会返回首选后端的响应的 Content-Type 头部、HTTP 状态码和正文。可以通过 -backend.preferred=<hostname> 配置首选后端。首选后端配置选项的值必须是其中一个已配置后端的主机名。

配置首选后端后，query-tee 始终返回首选后端的响应。

如果未配置首选后端，query-tee 使用以下算法选择发送回客户端的后端响应

  1. 如果至少有一个后端响应的状态码是 2xx 或 4xx，query-tee 会选择第一个收到的状态码为 2xx 或 4xx 的响应。
  2. 如果没有后端响应的状态码是 2xx 或 4xx，query-tee 会选择第一个收到的响应，无论状态码是什么。

注意

Query-tee 将 4xx 响应视为有效的选择响应，因为 4xx 状态码通常表示无效请求，而不是服务器端问题。

后端结果比较

Query-tee 可以选择性地比较两个后端收到的查询结果。可以通过设置 -proxy.compare-responses=true 标志启用查询结果比较，并要求

  1. 已通过设置 -backend.endpoints 配置了两个后端。
  2. 已通过设置 -backend.preferred 配置了首选后端。

启用查询结果比较后，query-tee 会比较从两个已配置后端收到的响应，并为结果不匹配的每个查询记录一条消息。Query-tee 通过指标 cortex_querytee_responses_compared_total 跟踪成功和失败的比较次数。

默认情况下，即使错误消息不完全相同，query-tee 也认为等效的错误消息是匹配的。这可以确保在已知错误消息不确定性的情况下比较不会失败。设置 -proxy.compare-exact-error-matching=true 以要求错误消息完全匹配。

注意

Query-tee 在比较浮点样本值时使用一个容差，您可以使用 -proxy.value-comparison-tolerance 选项配置该容差。

配置的容差可以防止由于 Prometheus PromQL 引擎内非确定性序列排序导致的浮点值舍入差异造成的误报。

注意

-proxy.compare-skip-recent-samples 的默认值为两分钟。这意味着结果中时间戳在当前时间两分钟内的点不会进行比较。这可以防止由于与摄取竞争以及（如果查询选择记录规则的输出）规则评估导致的误报。

如果任一 Mimir 集群运行的 -ruler.evaluation-delay-duration 值不是默认值，您应该将 -proxy.compare-skip-recent-samples 设置为比 -ruler.evaluation-delay-duration 的值多一分钟。

慢查询日志

您可以通过设置 -proxy.log-slow-query-response-threshold 标志来配置 query-tee 记录比最快后端耗时更长的请求。

默认值是 10s，它会记录比最快后端慢十秒的请求。

要禁用慢查询日志记录，请将 -proxy.log-slow-query-response-threshold 设置为 0。

导出的指标

Query-tee 在 /metrics 端点（监听通过 -server.metrics-port 标志配置的端口）上公开以下 Prometheus 指标

bash 
# HELP cortex_querytee_backend_request_duration_seconds Time (in seconds) spent serving requests.
# TYPE cortex_querytee_backend_request_duration_seconds histogram
cortex_querytee_backend_request_duration_seconds_bucket{backend="<hostname>",method="<method>",route="<route>",status_code="<status>",le="<bucket>"}
cortex_querytee_backend_request_duration_seconds_sum{backend="<hostname>",method="<method>",route="<route>",status_code="<status>"}
cortex_querytee_backend_request_duration_seconds_count{backend="<hostname>",method="<method>",route="<route>",status_code="<status>"}

# HELP cortex_querytee_responses_total Total number of responses sent back to the client by the selected backend.
# TYPE cortex_querytee_responses_total counter
cortex_querytee_responses_total{backend="<hostname>",method="<method>",route="<route>"}

# HELP cortex_querytee_responses_compared_total Total number of responses compared per route name by result.
# TYPE cortex_querytee_responses_compared_total counter
cortex_querytee_responses_compared_total{route="<route>",result="<success|fail>"}

此外，如果配置了后端结果比较，还可以使用两个原生直方图

  • cortex_querytee_backend_response_relative_duration_seconds：次要后端响应时间减去首选后端响应时间（以秒为单位）。
  • cortex_querytee_backend_response_relative_duration_proportional：次要后端响应时间减去首选后端响应时间，与首选后端响应时间的比例。

Ruler 远程操作模式测试

当 ruler 配置为远程评估模式时，您也可以使用 query-tee 比较规则评估。要使用 query-tee 测试 ruler 评估，请将 ruler 的 -ruler.query-frontend.address CLI 标志或其相应的 YAML 配置参数设置为 query-tee 的 gRPC 地址

ruler:
  query_frontend:
    address: "dns://query-tee:9095"

当 ruler 评估规则时，测试流程如下

  1. ruler 向 query-tee 发送 gRPC 请求
  2. query-tee 将请求转发到通过设置 -backend.endpoints CLI 标志配置的 query-frontend 后端
  3. query-tee 接收来自 query-frontend 的响应，并将结果（基于首选后端）转发给 ruler