文档

Grafana Tempo

管理

Tempo CLI

开源

Tempo CLI

Tempo CLI 是一个单独的可执行文件，包含与 Tempo 软件相关的实用功能。虽然它不是正常安装所必需的，但 Tempo CLI 对深度分析或故障排除可能很有帮助。

Tempo CLI 命令语法

Tempo CLI 中命令的通用语法为

tempo-cli command [subcommand] [options] [arguments...]

--help 或 -h 显示命令或子命令的帮助信息。

示例

tempo-cli -h
tempo-cli command [subcommand] -h

运行 Tempo CLI

Tempo CLI 当前以源代码形式提供。需要一个正常工作的 Go 安装才能构建它。它可以编译成原生二进制文件并正常执行，也可以使用 go run 命令执行。它可以使用 make docker-tempo-cli 打包成 Docker 容器。

示例

./tempo-cli [arguments...]
go run ./cmd/tempo-cli [arguments...]

make docker-tempo-cli
docker run docker.io/grafana/tempo-cli [arguments...]

后端选项

Tempo CLI 在执行某些命令时直接连接到存储后端，这意味着它需要能够从 S3、GCS、Azure 或文件系统存储读取数据。后端可以通过以下几种方式配置

使用 --config-file (-c) 选项加载现有的 Tempo 配置文件。对于频繁使用，推荐此选项。有关更多信息，请参阅配置文档。
指定单个设置
- --backend <value> 存储后端类型，为 s3、gcs、azure 和 local 之一。
- --bucket <value> 存储桶名称。此值的含义取决于后端类型。有关更多信息，请参阅配置文档。
- --s3-endpoint <value> S3 API 端点（例如 s3.dualstack.us-east-2.amazonaws.com）。
- --s3-user <value>, --s3-pass <value> S3 用户名和密码（或访问密钥和 secret key）。可选，因为 Tempo CLI 支持与 Tempo 相同的身份验证机制。有关更多信息，请参阅S3 权限文档。
- --insecure-skip-verify 跳过 TLS 验证，仅适用于 S3 和 GCS。

每个选项仅适用于使用它的命令。例如，--backend <value> 不会永久更改 Tempo 存储数据的位置。它仅更改应用该选项的命令。

Query API 命令

追踪 ID

调用 Tempo API 并按 ID 检索追踪。

tempo-cli query api trace-id <api-endpoint> <trace-id>

参数

api-endpoint Tempo API 的 URL。
trace-id 追踪 ID，十六进制字符串格式。

选项

--org-id <value> 组织 ID（用于多租户设置）。
--v1 使用 v1 API（使用 /api/traces 端点获取追踪，默认为 /api/v2/traces）。

示例

tempo-cli query api trace-id http://tempo:3200 f1cfe82a8eef933b

搜索

调用 Tempo API 并使用 TraceQL 进行搜索。

tempo-cli query api search <host-port> <trace-ql> [<start> <end>]

参数

host-port Tempo 的主机/端口组合。方案将根据提供的选项推断。
trace-ql TraceQL 查询。
start 搜索时间范围的开始：（YYYY-MM-DDThh:mm:ss）
end 搜索时间范围的结束：（YYYY-MM-DDThh:mm:ss）

选项

--org-id <value> 组织 ID（用于多租户设置）。
--use-grpc 使用 GRPC 流
--spss <value> 每个 spanset 返回的 span 数量
--limit <value> 返回结果的数量
--path-prefix <value> 用于作为搜索路径前缀的字符串

注意
通过 HTTP 流式传输需要设置 stream_over_http_enabled 标志。有关更多信息，请参阅Tempo GRPC API 文档。

搜索 Tag

调用 Tempo API 并搜索属性名称。

tempo-cli query api search-tags <host-port> [<start> <end>]

参数

host-port Tempo 的主机/端口组合。方案将根据提供的选项推断。
start 搜索时间范围的开始：（YYYY-MM-DDThh:mm:ss）
end 搜索时间范围的结束：（YYYY-MM-DDThh:mm:ss）

选项

--org-id <value> 组织 ID（用于多租户设置）。
--use-grpc 使用 GRPC 流
--path-prefix <value> 用于作为搜索路径前缀的字符串

注意
通过 HTTP 流式传输需要设置 stream_over_http_enabled 标志。有关更多信息，请参阅Tempo GRPC API 文档。

搜索 Tag 值

调用 Tempo API 并搜索属性值。

tempo-cli query api search-tag-values <tag> <host-port> [<start> <end>]

参数

host-port Tempo 的主机/端口组合。方案将根据提供的选项推断。
tag 要搜索的完全限定 traceql tag。例如 resource.service.name
start 搜索时间范围的开始：（YYYY-MM-DDThh:mm:ss）
end 搜索时间范围的结束：（YYYY-MM-DDThh:mm:ss）

选项

--org-id <value> 组织 ID（用于多租户设置）。
--use-grpc 使用 GRPC 流
--path-prefix <value> 用于作为搜索路径前缀的字符串

注意
通过 HTTP 流式传输需要设置 stream_over_http_enabled 标志。有关更多信息，请参阅Tempo GRPC API 文档。

指标

调用 Tempo API 并使用 TraceQL 从追踪生成指标。

tempo-cli query api metrics <host-port> <trace-ql metrics query> [<start> <end>]

参数

host-port Tempo 的主机/端口组合。方案将根据提供的选项推断。
trace-ql metrics query TraceQL 指标查询。
start 搜索时间范围的开始：（YYYY-MM-DDThh:mm:ss）
end 搜索时间范围的结束：（YYYY-MM-DDThh:mm:ss）

选项

--org-id <value> 组织 ID（用于多租户设置）。
--use-grpc 使用 GRPC 流
--path-prefix <value> 用于作为搜索路径前缀的字符串

注意
通过 HTTP 流式传输需要设置 stream_over_http_enabled 标志。有关更多信息，请参阅Tempo GRPC API 文档。

Query blocks 命令

迭代所有后端块并转储找到的给定追踪 ID 的所有数据。

tempo-cli query blocks <trace-id> <tenant-id>

注意
这可能会占用大量资源，因为它会下载所有布隆过滤器以及一定比例的索引/追踪数据。

参数

trace-id 追踪 ID，十六进制字符串格式。
tenant-id 要搜索的租户。

选项：请参阅上面的后端选项。

示例

tempo-cli query blocks f1cfe82a8eef933b single-tenant

Query trace summary 命令

迭代所有后端块并转储给定追踪 ID 的摘要信息。

摘要包括

追踪所在的块数量
span 数量
追踪大小
追踪持续时间
根服务名称
根 span 信息
最常出现的服务名称

tempo-cli query trace-summary <trace-id> <tenant-id>

注意：这可能会占用大量资源，因为它会下载所有布隆过滤器以及一定比例的索引/追踪数据。

参数

trace-id 追踪 ID，十六进制字符串格式。
tenant-id 要搜索的租户。

选项：请参阅上面的后端选项。

示例

tempo-cli query trace-summary f1cfe82a8eef933b single-tenant

列出块

列出给定租户所有块的信息，并可选地对索引执行完整性检查以查找重复记录。

tempo-cli list blocks <tenant-id>

参数

tenant-id 租户 ID。对于单租户设置，请使用 single-tenant。

选项

--include-compacted 包括已压缩的块。默认行为是仅显示活动块。

输出：输出说明

ID 块 ID。
Lvl 块的压缩级别。
Objects 块中存储的对象数量。
Size 块在任何压缩后的数据大小。
Encoding 块编码（压缩算法）。
Vers 块版本。
Window 用于压缩目的的时间窗口。
Start 块中存储的最早时间戳。
End 块中存储的最新时间戳。
Duration 开始和结束时间之间的持续时间。
Age 块的年龄。
Cmp 块是否已压缩（当指定 –include-compacted 时显示）。

示例

tempo-cli list blocks -c ./tempo.yaml single-tenant

列出块

列出单个块的信息，并可选地扫描其内容。

tempo-cli list block <tenant-id> <block-id>

参数

tenant-id 租户 ID。对于单租户设置，请使用 single-tenant。
block-id 块 ID，UUID 字符串格式。

选项

--scan 同时加载块数据，对重复项执行完整性检查，并收集统计信息。注意：可能会占用大量资源。

示例

tempo-cli list block -c ./tempo.yaml single-tenant ca314fba-efec-4852-ba3f-8d2b0bbf69f1

列出压缩摘要

根据压缩级别汇总给定租户所有块的信息。此命令有助于分析或排除压缩器行为。

tempo-cli list compaction-summary <tenant-id>

参数

tenant-id 租户 ID。对于单租户设置，请使用 single-tenant。

示例

tempo-cli list compaction-summary -c ./tempo.yaml single-tenant

列出缓存摘要

打印关于每个压缩级别每天布隆过滤器分片数量的信息。此命令有助于估算和微调缓存存储。阅读缓存主题了解更多信息。

tempo-cli list cache-summary <tenant-id>

参数

tenant-id 租户 ID。对于单租户设置，请使用 single-tenant。

示例

tempo-cli list cache-summary -c ./tempo.yaml single-tenant

列出索引

列出给定块的基本索引信息。

tempo-cli list index <tenant-id> <block-id>

参数

tenant-id 租户 ID。对于单租户设置，请使用 single-tenant。
block-id 块 ID，UUID 字符串格式。

示例

tempo-cli list index -c ./tempo.yaml single-tenant ca314fba-efec-4852-ba3f-8d2b0bbf69f1

查看索引

查看给定块的索引内容。

tempo-cli view index <tenant-id> <block-id>

参数

tenant-id 租户 ID。对于单租户设置，请使用 single-tenant。
block-id 块 ID，UUID 字符串格式。

示例

tempo-cli view index -c ./tempo.yaml single-tenant ca314fba-efec-4852-ba3f-8d2b0bbf69f1

生成布隆过滤器

如果文件被删除/损坏，为块生成布隆过滤器。

注意：确保块位于本地后端中预期的目录层次结构下，即 path / tenant / blocks。

参数

tenant-id 租户 ID。对于单租户设置，请使用 single-tenant。
block-id 块 ID，UUID 字符串格式。
bloom-fp 用于布隆过滤器的误报率。
bloom-shard-size 用于布隆过滤器的分片大小。

示例

tempo-cli gen bloom --backend=local --bucket=./cmd/tempo-cli/test-data/ single-tenant b18beca6-4d7f-4464-9f72-f343e688a4a0 0.05 100000

布隆过滤器将在块文件夹下所需的位置生成。

生成索引

如果文件被删除/损坏，为块生成索引/布隆。

注意：确保块位于本地后端中预期的目录层次结构下，即 path / tenant / blocks。

参数

tenant-id 租户 ID。对于单租户设置，请使用 single-tenant。
block-id 块 ID，UUID 字符串格式。

示例

tempo-cli gen index --backend=local --bucket=./cmd/tempo-cli/test-data/ single-tenant b18beca6-4d7f-4464-9f72-f343e688a4a0

索引将在块文件夹下所需的位置生成。

Search blocks 命令

在给定时间范围内搜索特定键/值对的块。

tempo-cli search blocks <name> <value> <start> <end> <tenant-id>

注意：这可能会占用大量资源，因为它会下载所有相关块并遍历它们。

参数

name 要搜索的属性名称，例如 http.post
value 要搜索的属性值，例如 GET
start 搜索时间范围的开始：（YYYY-MM-DDThh:mm:ss）
end 搜索时间范围的结束：（YYYY-MM-DDThh:mm:ss）
tenant-id 要搜索的租户。

选项：请参阅上面的后端选项。

示例

tempo-cli search blocks http.post GET 2021-09-21T00:00:00 2021-09-21T00:05:00 single-tenant --backend=gcs --bucket=tempo-trace-data

Parquet convert 命令

将现有的 parquet 文件从其现有模式转换为当前仓库中的模式。此实用命令在尝试确定更改列的压缩或编码的影响时很有用。

tempo-cli parquet convert <in file> <out file>

参数

in file 包含 Tempo 追踪数据的现有 parquet 文件名
out file 要写入的文件。（现有文件将被覆盖。）

示例

tempo-cli parquet convert data.parquet out.parquet

Parquet convert 2 to 3 命令

将 vParquet2 文件（实际 data.parquet）转换为带有可选专用属性列列表的 vParquet3 块。此实用命令在测试不同专用列组合的影响时很有用。目前，所有列出的列都被假定为 span 作用域。

tempo-cli parquet convert-2-to-3 <in file> <out path> <list of dedicated columns>

参数

in file 包含 Tempo 追踪数据的现有 vParquet2 文件名
out path 写入 vParquet3 块的路径。
list of dedicated columns 指示哪些列应设置为专用的额外参数。最多 10 个。专用列应使用带有作用域的 TraceQL 语法命名。例如 span.db.statement 或 resource.namespace。

示例

tempo-cli parquet convert-2-to-3 data.parquet ./out db.statement db.name

Migrate tenant 命令

将块从一个后端和租户复制到另一个。块可以在同一后端内复制，或在两个不同后端之间复制。数据格式不会转换，但 meta.json 中的租户 ID 将被重写。

tempo-cli migrate tenant <source tenant> <dest tenant>

参数

source tenant 复制块的源租户
dest tenant 复制块的目标租户

选项

--source-config-file <value> 源后端配置文件
--config-file <value> 目标后端配置文件

示例

tempo-cli migrate tenant --source-config source.yaml --config-file dest.yaml my-tenant my-other-tenant

Migrate overrides config 命令

将 overrides config 从内联格式（旧版）迁移到缩进 YAML 格式（新版）。

tempo-cli migrate overrides-config <source config file>

参数

source config file 要迁移的配置文件

选项

--config-dest <value> 迁移后配置的目标文件。如果未指定，则配置将打印到 stdout。
--overrides-dest <value> 迁移后 overrides 的目标文件。如果未指定，则 overrides 将打印到 stdout。

示例

tempo-cli migrate overrides-config config.yaml --config-dest config-tmp.yaml --overrides-dest overrides-tmp.yaml

分析块

分析一个块并输出该块通用属性的摘要。这在尝试确定 vParquet3 中专用属性列的候选项时特别有用。

参数

tenant-id 租户 ID。对于单租户设置，请使用 single-tenant。
block-id 块 ID，UUID 字符串格式。

选项

后端选项
--num-attr <value> 输出的属性数量（默认为 10）

示例

tempo-cli analyse block --backend=local --bucket=./cmd/tempo-cli/test-data/ single-tenant b18beca6-4d7f-4464-9f72-f343e688a4a0

分析块（复数）

分析给定时间范围内的所有块，并输出这些块通用属性的摘要。这在尝试确定 vParquet3 和 vParquet4 中专用属性列的候选项时特别有用。

参数

tenant-id 租户 ID。对于单租户设置，请使用 single-tenant。

选项

后端选项
--num-attr <value> 输出的属性数量（默认为 10）
--min-compaction-level <value> 分析中包含的最小压缩级别（默认为 3）
--max-blocks <value> 要分析的最大块数量（默认为 10）
--max-start-time <value> 要处理的块的最早开始时间。RFC3339 格式（默认为禁用）
--min-end-time <value> 要处理的块的最新结束时间。RFC3339 格式（默认为禁用）

示例

tempo-cli analyse blocks --backend=local --bucket=./cmd/tempo-cli/test-data/ single-tenant

按 ID 删除追踪

重写包含特定追踪 ID 的租户的所有块。追踪将从新块中删除，重写后的块将被标记为已压缩以便清理。

参数

tenant-id 租户 ID。对于单租户设置，请使用 single-tenant。
trace-ids 要删除的追踪 ID，以逗号分隔（也支持单个追踪 ID）

选项

后端选项
--drop-traces 默认情况下，此命令以试运行模式运行。提供此参数将使其实际重写删除追踪后的块。

示例

删除单个追踪

tempo-cli rewrite-blocks drop-trace --backend=local --bucket=./cmd/tempo-cli/test-data/ single-tenant 04d5f549746c96e4f3daed6202571db2

删除多个追踪

tempo-cli rewrite-blocks drop-trace --backend=local --bucket=./cmd/tempo-cli/test-data/ single-tenant 04d5f549746c96e4f3daed6202571db2,111fa1850042aea83c17cd7e674210b8