背景

Grafana Tempo 是一个开源的分布式追踪后端存储系统，支持将 OpenTelemetry、Jaeger、Zipkin等多种协议 Trace 数据存储到对象存储中，并提供大规模分布式追踪数据的高性能查询服务。针对习惯使用 Grafana 分析 Trace 数据的用户，APM 提供了兼容 Tempo 的接口，便于用户使用 Grafana 的 Tempo 数据源插件访问APM进行查询和分析。

兼容原理

APM 所提供的 Grafana HTTP Tempo 兼容接口，其兼容机制是将 TraceQL 查询翻译为日志服务的索引查询，并且按照 Tempo HTTP API 格式规范返回查询分析结果，从而实现 Tempo 查询协议的兼容。

Temop 兼容 API 访问域名

Tempo兼容API的访问域名格式为 https://${endpoint}/trace/tempo， 例如 https://apm.bj.baidubce.com/trace/tempo。 Tempo兼容API当前已支持地域：

地域	地域地址
北京	https://apm.bj.baidubce.com/trace/tempo
广州	https://apm.gz.baidubce.com/trace/tempo
苏州	https://apm.su.baidubce.com/trace/tempo

准备条件

• Tempo 对接支持 Grafana 9.x、10.x、11.x、12.x 版本。本文以 Grafana 12.4.1 为例进行说明。
• 用户已经开通对应 region 的 APM 服务
• 用户已经创建了用于身份鉴权的 AK、SK。

配置数据源

1. 登录Grafana控制台。
2. 在左侧导航栏，选择Connections > Add new connection。
3. 在Add new connection页签，找到并单击Tempo。

4.点击 Tempo 后进入详情页面，然后点击右上角的Add new data source。

5.在 Settings 页签中，完成如下配置（URL 和 HTTP Headers），然后单击 Save&test 测试连通性。

• 添加对应 Region 的域名

• 配置请求时携带的请求头，其中包含accessKey 、 secretKey，填写用于身份鉴权的 AK 和 SK。

• 点击 Save & test，进行验证。

开始使用

配置好数据源后，即可在 Grafana 的Explore页面，进行 Trace 的检索。可使用常见维度搜索 Traces。

单击 Trace ID，使用 Explore Trace 视图快速诊断调用链路中的异常信息等。

同时可以在 Dashboard 页面中，使用 TraceQL 来创建常用的 Panel ，用于快速发现等位问题。

支持的 Tempo API

请求方法	API路径	说明
GET	/api/traces/	查询 Trace 详情。
GET	/api/v2/traces/	查询 Trace 详情（V2 版本接口）。
GET	/api/search	查询 Trace 列表。
GET	/api/search/tags	查询 Tag。
GET	/api/v2/search/tags	查询 Tag（V2 版本接口）。
GET	/api/search/tag/{tags}/values	查询 Tag 值。
GET	/api/v2/search/tag/{tags}/values	查询 Tag 值（V2 版本接口）。
GET	/ready	是否已经准备好对外提供服务。
GET	/api/echo	测试 Tempo 数据源是否正常工作。

支持兼容的 TraceQL 语法

支持兼容的关键字

类别	字段	说明	使用示例
Span	status	状态。枚举值： unset ok* error	status=ok
	statusMessage	状态信息。	statusMessage="404 NOT FOUND"
	duration	Span 耗时。支持带单位，如果没有单位，默认 ns。示例： 500 10ns 500ms 12.88s 10.5min 1h	duration > 500ms
	name	Span 名称，对应 APM 的 spanName。	name="/components/api/v1/mall/product"
	kind	Span 类型。枚举值： unspecified internal server client producer consumer	kind=server
	spanId	Span 标识符。	spanId=”fe81595a906fe2a4“
Trace	traceDuration	Trace 中首 span 耗时（相当于 Trace 耗时）。	traceDuration > 100ms
	traceId	Trace 标识符。	traceId="ea1a0100f617397599186332534d0001"
Attribute	span.开头的字段，示例： span.http.path span.db.statement	Span 属性。	span.http.path="/api/search"
Resource	resource.开头的字段，示例： resource.namespace resource.agentVersion	资源属性。	resource.namespace="arms"
Unscoped Attribute	.开头的字段，示例： .http.path .db.statement	无作用域属性，对应 APM 的 attributes 。	.db.statement="select * from log"

支持兼容的操作符

类别	运算符	说明	示例
Span 选择器	{expression}	表达式需要写在{}内	{status=ok}
比较运算符	=	等于	{name="/components/api/v1/mall/product"}
	!=	不等于	{resource.service.name!="mall-gateway"}
	=~	正则匹配	{span.http.response.status_code=~"3.*
	!~	正则不匹配	{resource.service.name!~"mall-gateway
	>	大于	{duration>500ms}
	>=	大于等于	{duration>=500ms}
	<	小于	{duration<1s}
	<=	小于等于	{duration<=1s}
逻辑运算符	{condA && condB}	与	{duration>=500ms && span.http.response.status_code=~ "5.*" }
	{condA || condB}	或	{name="/components/api/v1/mall/product" || resource.service.name="mall-gateway"}