Jaeger UI Tags 查询指南：语法、转义与实战

目录

• • [0. 概述](#0. 概述)
  • [1. `Tags` 查询本质是什么？](#1. Tags 查询本质是什么？)
  • [2. 基础语法（logfmt）](#2. 基础语法（logfmt）)
  • • [2.1 单条件](#2.1 单条件)
    • [2.2 多条件（AND）](#2.2 多条件（AND）)
  • [3. 什么时候必须加引号？](#3. 什么时候必须加引号？)
  • [4. ES/OpenSearch 场景：为什么要转义？](#4. ES/OpenSearch 场景：为什么要转义？)
  • • [4.1 经典例子：URL 里的 `?`](#4.1 经典例子：URL 里的 ?)
  • [5. 精确匹配示例（可直接用）](#5. 精确匹配示例（可直接用）)
  • [6. 模糊匹配（正则）示例](#6. 模糊匹配（正则）示例)
  • • [6.1 包含 / 前缀 / 后缀](#6.1 包含 / 前缀 / 后缀)
    • [6.2 状态码范围](#6.2 状态码范围)
    • [6.3 SQL 关键词（忽略大小写）](#6.3 SQL 关键词（忽略大小写）)
    • [6.4 多条件组合（AND）](#6.4 多条件组合（AND）)
  • [7. 常见错误与修正](#7. 常见错误与修正)
  • • [错误 1：没加引号](#错误 1：没加引号)
    • [错误 2：ES/OpenSearch 下没转义 `?`](#错误 2：ES/OpenSearch 下没转义 ?)
    • [错误 3：把 OR 当 SQL 写](#错误 3：把 OR 当 SQL 写)
  • [8. 实战排障建议：先粗后细](#8. 实战排障建议：先粗后细)
  • [9. 一页速查（可贴团队 Wiki）](#9. 一页速查（可贴团队 Wiki）)
  • [10. 总结](#10. 总结)

0. 概述

在用 Jaeger 排查问题时，Tags 搜索框是最高频入口之一。

很多"查不到数据"的根因，不是没有数据，而是语法、引号或转义写错了。

这篇文章把 Jaeger UI Tags 的核心规则、Elasticsearch/OpenSearch 下的转义细节、以及 LiteFlow 场景的查询范式一次讲清楚。

---

1. Tags 查询本质是什么？

Jaeger UI 提示里写得很关键：

• Values should be in the logfmt format.
• Use space for AND conjunctions.
• Values containing whitespace or equal-sign = should be enclosed in quotes.
• Elasticsearch/OpenSearch storage supports regex query, reserved characters need escaping for exact match.

换成人话就是：

1. 每个条件是 key=value
2. 多个条件用空格分隔，表示 AND
3. value 里有空格或 =，要加双引号
4. 如果后端是 ES/OpenSearch，value 常按正则语义解析；想精确匹配特殊字符要转义

---

2. 基础语法（logfmt）

2.1 单条件

error=true

2.2 多条件（AND）

error=true http.response.status_code=500

含义：同时满足 error=true 且 http.response.status_code=500。

---

3. 什么时候必须加引号？

当 value 包含这些情况时要加双引号：

• 空格
• 等号 =

例如：

db.statement="select * from User"
http.url="http://svc:8080/api/orders?id=123"

如果不加引号，Jaeger 会把内容错误拆分成多个 token。

---

4. ES/OpenSearch 场景：为什么要转义？

在 ES/OpenSearch 存储下，Tags 的 value 往往支持 regex 语义。

这意味着某些字符（如 ?, ., (, )）不是普通字符，而是"正则元字符"。

4.1 经典例子：URL 里的 ?

要精确匹配这个 URL：

http://0.0.0.0:8081/customer?customer=123

? 在 regex 中是保留字符，需要转义。

在 Jaeger 输入中通常写成：

http.url="http://0.0.0.0:8081/customer\\?customer=123"

记忆法：想匹配字面 ?，写 \\?。

---

5. 精确匹配示例（可直接用）

error=true
http.request.method=GET
http.response.status_code=500
db.system=mysql
db.operation=SELECT
rpc.service=UserService
rpc.method=GetUser

带空格/等号值的示例：

db.statement="select * from user where id = ?"
http.url="http://svc:8080/api/orders\\?id=123"
exception.message="connection reset by peer"

---

6. 模糊匹配（正则）示例

下面示例主要适用于 ES/OpenSearch 后端。

6.1 包含 / 前缀 / 后缀

http.url=".*order.*"             # 包含 order
flow.chain_id="order_.*"         # 前缀 order_
exception.type=".*Timeout.*"     # 包含 Timeout

6.2 状态码范围

http.response.status_code="5.."

6.3 SQL 关键词（忽略大小写）

db.statement="(?i)select .*"
db.statement="(?i).*join.*"

6.4 多条件组合（AND）

http.url=".*order.*" http.response.status_code="5.."
db.statement="(?i)update .*" error=true
flow.chain_id="claim_.*" error=true

---

7. 常见错误与修正

错误 1：没加引号

db.statement=select * from User

修正：

db.statement="select * from User"

错误 2：ES/OpenSearch 下没转义 ?

http.url="http://svc/api?a=1"

修正：

http.url="http://svc/api\\?a=1"

错误 3：把 OR 当 SQL 写

error=true OR http.response.status_code=500

Tags 输入默认不是 SQL/DSL 风格 OR，建议拆分查询或用其他过滤手段。

---

8. 实战排障建议：先粗后细

1. 先用宽条件确认数据存在：error=true
2. 加协议/状态维度：error=true http.response.status_code="5.."
3. 加业务维度：flow.chain_id=xxx
4. 最后再加复杂值（SQL/URL regex）
5. 一旦查不到，优先回看"引号 + 转义"

---

9. 一页速查（可贴团队 Wiki）

# 基本
k=v
k1=v1 k2=v2                # AND

# 需要引号
db.statement="select * from t"
http.url="http://x/api\\?a=1"

# 模糊匹配
k=".*word.*"
k="prefix.*"
k=".*suffix"
status="5.."

---

10. 总结

Jaeger Tags 查询的核心就三件事：

• logfmt 结构 ：key=value，空格是 AND
• 引号规则 ：value 有空格或 = 必须加引号
• ES/OpenSearch 转义 ：正则保留字符要处理，尤其 URL 中的 ?

掌握这三点后，Jaeger 查询成功率会明显提升，排障效率也会更稳定。