菜单
文档breadcrumb arrow Grafana Tempobreadcrumb arrow 管理breadcrumb arrow 管理高级系统breadcrumb arrow 通过用户可配置的覆盖 API 配置 Tempo 覆盖
开源

用户可配置的覆盖

Tempo 中的用户可配置覆盖允许您使用 API 更改租户的覆盖设置。您（以及依赖 Tempo 的其他服务）可以使用此 API 直接修改覆盖设置，而无需修改文件或 Kubernetes configmap。

架构

用户可配置的覆盖存储在 Tempo 管理的对象存储桶中。

user-configurable-overrides-architecture.png

注意

我们建议为覆盖设置和跟踪存储使用不同的存储桶，但如果需要，它们也可以共享一个存储桶。共享存储桶时，请确保任何生命周期规则的范围设置正确，以免删除用户可配置的覆盖模块数据。

每个租户的覆盖设置存储在 /{tenant name}/overrides.json 中

overrides/
├── 1/
│   └── overrides.json
└── 2/
    └── overrides.json

Tempo 定期轮询此存储桶，并在内存中保留一份限制副本。当请求租户的覆盖设置时，覆盖模块会执行以下操作：

  1. 检查此覆盖设置是否已在用户可配置的覆盖中设置，如果是，则返回该值。
  2. 检查此覆盖设置是否已在运行时配置（configmap）中设置，如果是，则返回该值。
  3. 返回默认值。

支持的字段

用户可配置的覆盖被设计为运行时覆盖的子集。有关所有覆盖设置的信息，请参阅覆盖。当您同时在用户可配置的覆盖和运行时覆盖中设置字段时，用户可配置的覆盖中的值优先。

注意

请注意，processors 是一个例外。Tempo 会将用户可配置的覆盖和运行时覆盖中的值合并到一个列表中。

yaml 
[forwarders: <list of strings>]

metrics_generator:

  [processors: <list of strings>]
  [collection_interval: <duration>]
  [disable_collection: <bool> | default = false]

  processor:

    service_graphs:
      [histogram_buckets: <list of float>]
      [dimensions: <list of string>]
      [peer_attributes: <list of string>]
      [enable_client_server_prefix: <bool>]
      [enable_messaging_system_latency_histogram: <bool>]

    span_metrics:
      [histogram_buckets: <list of float>]
      [dimensions: <list of string>]
      [intrinsic_dimensions: <map string to bool>]
      [filter_policies: [
        [
          include/exclude:
            match_type: <string> # options: strict, regexp
            attributes:
              - key: <string>
                value: <any>
        ]
      ]
      [enable_target_info: <bool>]
      [target_info_excluded_dimensions: <list of string>]

API

所有 API 请求都由 /api/overrides 端点处理。该模块支持 GET、POST、PATCH 和 DELETE 请求。

此端点特定于租户。如果在多租户模式下运行 Tempo，所有请求都应包含相应的 X-Scope-OrgID 头。

如果租户在分布式模式下运行，只有 query-frontend 会接受 API 请求。

操作

GET /api/overrides

返回当前的覆盖设置及其版本。

查询参数

  • scope：是仅返回 API 中的覆盖设置 (api)，还是与运行时覆盖设置合并 (merged)。默认为 api。

示例

shell 
$ curl -X GET -v -H "X-Scope-OrgID: 3" https://:3100/tempo/api/overrides\?scope=merged`

POST /api/overrides

使用给定的 payload 更新覆盖设置。请注意，这会覆盖任何现有的覆盖设置。

示例

shell 
curl -X POST -v -H "X-Scope-OrgID: 3" -H "If-Match: 1697726795401423" https://:3100/api/overrides --data "{}"

PATCH /api/overrides

通过使用 payload 进行修补来更新现有覆盖设置。它遵循 JSON 合并修补协议 (RFC 7386)。

示例

shell 
curl -X PUT -v -H "X-Scope-OrgID: 3" -H "If-Match: 1697726795401423" https://:3100/api/overrides --data "{\"forwarders\":null}"

DELETE /api/overrides

删除现有覆盖设置。

示例

shell 
curl -X DELETE -H "X-Scope-OrgID: 3" -H "If-Match: 1697726795401423" https://:3100/api/overrides

版本控制

为了处理并发读写操作，后端会存储带有版本的覆盖设置。无论何时返回覆盖设置，响应都会带有一个 Etag 头，其中包含当前版本。

shell 
$ curl -v https://:3100/api/overrides
...
< HTTP/1.1 200 OK
< Content-Type: application/json
< Etag: 1697726795401423
< Date: Wed, 07 Feb 2024 17:49:04 GMT
< Content-Length: 118
...

修改或删除覆盖设置的请求需要使用 If-Match 头传递当前版本

shell 
$ curl -X POST -H "If-Match: 1697726795401423" https://:3100/api/overrides --data "..."

此示例使用 overrides.json 文件中的覆盖设置，该文件位于当前工作目录（pwd）中

shell 
$ curl -X POST -H "X-Scope-OrgID: 3" -H "If-Match: 1697726795401423" https://:3100/api/overrides --data @overrides.json

如果版本与后端中的版本不匹配，请求将以 HTTP 错误 412 被拒绝。

运行时覆盖冲突检查

通过用户可配置的覆盖设置的值优先于运行时覆盖。这可能导致误导性的情况，因为在运行时覆盖中设置的值并未被实际使用。

为了警告用户预先存在的运行时覆盖设置，可以选择启用冲突的运行时覆盖检查。如果启用，当出现以下情况时，请求将被拒绝：

  1. 此租户还没有用户可配置的覆盖设置。
  2. 存在包含用户可配置覆盖设置中已有的覆盖设置的运行时覆盖。

可以在配置中启用此检查

yaml 
overrides:
  user_configurable_overrides:
    api:
      check_for_conflicting_runtime_overrides: true

您可以通过设置查询参数 skip-conflicting-overrides-check=true 来绕过此检查

shell 
$ curl -X POST -H "If-Match: 1697726795401423" https://:3100/api/overrides?skip-conflicting-overrides-check=true --data "..."