VictoriaTraces / LogsQL 查询操作指导手册

> 适用范围：VictoriaTraces Web UI（`http://<victoria-traces>:10428/select/vmui`）中的 LogsQL 查询，以及基于 Jaeger HTTP API 的 Trace 搜索。
>
> 官方依据：[VictoriaTraces 数据模型](https://docs.victoriametrics.com/victoriatraces/keyconcepts/)、[VictoriaTraces 查询](https://docs.victoriametrics.com/victoriatraces/querying/)、[LogsQL](https://docs.victoriametrics.com/victorialogs/logsql/)。

## 目录

1. [查询前必须理解的字段映射](#1-查询前必须理解的字段映射)
2. [VMUI 的基本操作流程](#2-vmui-的基本操作流程)
3. [发现资源名称、Span 属性名称及对应值](#3-发现资源名称span-属性名称及对应值)
4. [字段值的基础搜索](#4-字段值的基础搜索)
5. [前缀、包含、正则和大小写搜索](#5-前缀包含正则和大小写搜索)
6. [资源属性和 Span 属性搜索](#6-资源属性和-span-属性搜索)
7. [时间、耗时、状态和范围查询](#7-时间耗时状态和范围查询)
8. [多条件及“在原查询基础上再搜索”](#8-多条件及在原查询基础上再搜索)
9. [关联搜索与完整 Trace 调查](#9-关联搜索与完整-trace-调查)
10. [子查询、Join、Union 和上下文关联](#10-子查询joinunion-和上下文关联)
11. [统计、分组、排行和趋势分析](#11-统计分组排行和趋势分析)
12. [字段选择、重命名、解析和格式化](#12-字段选择重命名解析和格式化)
13. [Jaeger API 查询能力](#13-jaeger-api-查询能力)
14. [常用排障剧本](#14-常用排障剧本)
15. [性能和正确性原则](#15-性能和正确性原则)
16. [查询速查表](#16-查询速查表)

## 1. 查询前必须理解的字段映射

VictoriaTraces 接收 OTLP Span 后，会将其转换成可由 LogsQL 查询的结构化字段。

### 1.1 三类属性前缀

| OTLP 数据来源 | VictoriaTraces 字段格式 | 示例 |
|---|---|---|
| Resource attribute | `resource_attr:<属性名>` | `resource_attr:service.name` |
| Span attribute | `span_attr:<属性名>` | `span_attr:http.request.method` |
| Scope attribute | `scope_attr:<属性名>` | `scope_attr:library.name` |

由于映射后的字段名通常包含冒号，LogsQL 查询时应将完整字段名放在引号内：

```logsql
"resource_attr:service.name":="portal-api"
```

不要写成：

```logsql
resource_attr:service.name:="portal-api"
```

后者的多个冒号可能被解释成查询语法，而不是字段名的一部分。

### 1.2 常见内置字段

| 字段 | 含义 | 示例查询 |
|---|---|---|
| `_time` | Span 的查询时间；默认来自 `EndTimeUnixNano` | `_time:15m` |
| `_stream` | 由服务名和 Span 名组成的流信息 | `_stream:*` |
| `_stream_id` | Span 流的唯一标识 | `_stream_id:="<stream-id>"` |
| `trace_id` | Trace ID，同一调用链的 Span 共享此值 | `trace_id:="769d28c4b8633dc9de2cc421d1a1616f"` |
| `span_id` | 当前 Span ID | `span_id:="2a1f3c4bda1d0e43"` |
| `parent_span_id` | 父 Span ID | `parent_span_id:="2a1f3c4bda1d0e43"` |
| `name` | Span/operation 名称 | `name:="HTTP POST"` |
| `duration` | VictoriaTraces 在写入时计算的 Span 时长，通常为纳秒数 | `duration:>100ms` |
| `status_code` | OTLP Span 状态码；实际值应先通过字段值发现确认 | `status_code:="2"` |
| `kind` | OTLP Span kind 的存储值；先发现本环境实际值 | `kind:="2"` |
| `scope_name` | instrumentation scope 名称 | `scope_name:="io.opentelemetry"` |
| `scope_version` | instrumentation scope 版本 | `scope_version:="1.0.0"` |

### 1.3 服务名的实际字段

OTLP 中的：

```text
service.name = portal-api
```

在 LogsQL 中查询：

```logsql
"resource_attr:service.name":="portal-api"
```

查询所有以 `portal` 开头的服务：

```logsql
"resource_attr:service.name":="portal"*
```

## 2. VMUI 的基本操作流程

1. 打开 `http://<victoria-traces>:10428/select/vmui`。
2. 先选择尽可能小的时间范围，例如最近 15 分钟。
3. 在查询框输入最宽的基础查询。
4. 选择显示模式：
   - `Group`：按流字段分组，适合先看服务名和 Span 名。
   - `Table`：逐条查看 Span 字段，适合排查。
   - `JSON`：查看 `/select/logsql/query` 返回的原始字段。
5. 从结果中确认真实字段名、字段值和数据类型。
6. 在原查询后追加 `AND` 条件，逐层缩小范围。
7. 找到目标 Span 后复制 `trace_id`，查询完整调用链。

基础起点示例：

```logsql
_time:15m
```

只保留排查常用字段：

```logsql
_time:15m
| fields _time, trace_id, span_id, parent_span_id, name,
  "resource_attr:service.name", duration, status_code
```

## 3. 发现资源名称、Span 属性名称及对应值

不确定字段名称时，不要猜。先使用 `field_names`、`field_values` 或 `facets`。

### 3.1 列出当前数据中的所有字段名称

```logsql
_time:15m | field_names
```

该查询会返回字段名以及包含该字段的估算 Span 数量。

### 3.2 搜索所有资源属性字段名称

```logsql
_time:15m | field_names filter "resource_attr:"
```

可能发现：

```text
resource_attr:service.name
resource_attr:service.namespace
resource_attr:service.version
resource_attr:host.name
resource_attr:deployment.environment.name
```

### 3.3 搜索所有 Span 属性字段名称

```logsql
_time:15m | field_names filter "span_attr:"
```

可能发现：

```text
span_attr:http.request.method
span_attr:http.response.status_code
span_attr:server.address
span_attr:db.system
span_attr:rpc.method
```

### 3.4 搜索字段名中包含某关键词的资源名称

查找所有包含 `http` 的字段名：

```logsql
_time:1h | field_names filter "http"
```

查找所有包含 `service` 的字段名：

```logsql
_time:1h | field_names filter "service"
```

`field_names filter` 是子字符串过滤，不是 RE2 正则。如果需要更复杂的字段名处理，可先输出字段名，再通过后续管道过滤返回结果。

### 3.5 列出某个资源属性的所有值

列出所有服务名：

```logsql
_time:1h | field_values "resource_attr:service.name"
```

列出所有部署环境：

```logsql
_time:1h | field_values "resource_attr:deployment.environment.name"
```

### 3.6 在字段值中继续搜索

列出服务名中包含 `portal` 的值：

```logsql
_time:1h
| field_values "resource_attr:service.name" filter "portal"
```

只返回至多 20 个值：

```logsql
_time:1h
| field_values "resource_attr:service.name" filter "portal" limit 20
```

### 3.7 一次查看各字段最常见的值

```logsql
_time:15m | facets
```

每个字段最多返回 5 个常见值：

```logsql
_time:15m | facets 5
```

保留在结果中恒定不变的字段：

```logsql
_time:15m | facets 5 keep_const_fields
```

只对 `portal` 服务的 Span 做字段画像：

```logsql
_time:1h AND "resource_attr:service.name":="portal"*
| facets 10
```

## 4. 字段值的基础搜索

### 4.1 精确等于

```logsql
"resource_attr:service.name":="portal-api"
```

适合 ID、服务名、环境名、HTTP 方法等结构化值。

### 4.2 不等于

```logsql
NOT "resource_attr:deployment.environment.name":="test"
```

也可以写：

```logsql
!"resource_attr:deployment.environment.name":="test"
```

### 4.3 包含单词

```logsql
"span_attr:error.message":timeout
```

它搜索完整单词 `timeout`，不会自动等价于任意子字符串。

### 4.4 包含完整短语

```logsql
"span_attr:error.message":"connection refused"
```

### 4.5 字段存在且非空

```logsql
"span_attr:http.response.status_code":*
```

### 4.6 字段不存在或为空

```logsql
"span_attr:http.response.status_code":""
```

VictoriaTraces/LogsQL 将空值按不存在处理；VictoriaTraces 写入阶段还可能把 OTLP 空属性替换为 `-`，因此必要时同时检查：

```logsql
(
  "span_attr:http.response.status_code":""
  OR "span_attr:http.response.status_code":="-"
)
```

### 4.7 多个精确值之一

```logsql
"resource_attr:deployment.environment.name":in("prod", "staging")
```

服务名属于指定集合：

```logsql
"resource_attr:service.name":in("portal-api", "portal-web", "portal-worker")
```

## 5. 前缀、包含、正则和大小写搜索

### 5.1 字段值从某个前缀开始

推荐使用“精确前缀过滤”：

```logsql
"resource_attr:service.name":="portal"*
```

匹配 `portal`、`portal-api`、`portalBackend`，不匹配 `my-portal`。

### 5.2 字段中的某个单词以前缀开始

```logsql
"span_attr:error.message":time*
```

它可匹配 `timeout`、`timed` 等以 `time` 开头的单词，但不要求整个字段值从 `time` 开始。

### 5.3 任意位置包含子字符串

```logsql
"resource_attr:service.name":*portal*
```

它还会匹配 `my-portal-api`。子字符串过滤可能较慢。

### 5.4 RE2 正则

服务名以 `portal` 开头：

```logsql
"resource_attr:service.name":~"^portal"
```

服务名以 `-api` 或 `-web` 结尾：

```logsql
"resource_attr:service.name":~"-(api|web)$"
```

服务名包含数字版本后缀：

```logsql
"resource_attr:service.name":~"^portal-(api|web)-v[0-9]+$"
```

匹配 HTTP 4xx 或 5xx：

```logsql
"span_attr:http.response.status_code":~"^[45][0-9]{2}$"
```

LogsQL 正则使用 RE2；双引号内的反斜杠需要再次转义。例如匹配字面量 `a.b`：

```logsql
"span_attr:example":~"a\\.b"
```

### 5.5 忽略大小写

单词或前缀忽略大小写：

```logsql
"span_attr:error.message":i(timeout*)
```

任意正则忽略大小写：

```logsql
"resource_attr:service.name":~"(?i)^portal"
```

### 5.6 多个候选值

```logsql
"resource_attr:service.name":~"^(portal|gateway|account)-"
```

如果只是有限个精确值，优先使用更快的 `in()`：

```logsql
"resource_attr:service.name":in("portal-api", "gateway-api", "account-api")
```

### 5.7 模式匹配

日志或字段中存在结构固定、变量变化的文本时，可用 `pattern_match`：

```logsql
"span_attr:log.message":pattern_match("user_id=<N>, ip=<IP4>, time=<DATETIME>")
```

常见占位符包括 `<N>`、`<UUID>`、`<IP4>`、`<TIME>`、`<DATE>`、`<DATETIME>` 和 `<W>`。

### 5.8 有序词组搜索

要求 `error` 出现在 `open file` 之前：

```logsql
"span_attr:error.message":seq(error, "open file")
```

## 6. 资源属性和 Span 属性搜索

### 6.1 服务资源属性

服务名前缀：

```logsql
"resource_attr:service.name":="portal"*
```

命名空间：

```logsql
"resource_attr:service.namespace":="customer-platform"
```

服务版本：

```logsql
"resource_attr:service.version":="2.3.1"
```

同一服务的某一版本：

```logsql
"resource_attr:service.name":="portal-api"
AND "resource_attr:service.version":="2.3.1"
```

### 6.2 环境、主机、容器和进程

生产环境：

```logsql
"resource_attr:deployment.environment.name":="production"
```

指定主机：

```logsql
"resource_attr:host.name":="portal-node-01"
```

容器 ID 前缀：

```logsql
"resource_attr:container.id":="5603ff"*
```

指定运行时语言：

```logsql
"resource_attr:telemetry.sdk.language":="go"
```

### 6.3 HTTP Span 属性

GET 请求：

```logsql
"span_attr:http.request.method":="GET"
```

4xx/5xx：

```logsql
"span_attr:http.response.status_code":~"^[45][0-9]{2}$"
```

URL 路径包含 `/portal/`：

```logsql
"span_attr:url.path":*"/portal/"*
```

如果没有 `url.path`，先查字段名：

```logsql
_time:1h | field_names filter "url"
```

### 6.4 RPC 属性

指定 RPC 服务：

```logsql
"span_attr:rpc.service":="PortalService"
```

指定 RPC 方法：

```logsql
"span_attr:rpc.method":="GetPortal"
```

组合查询：

```logsql
"span_attr:rpc.service":="PortalService"
AND "span_attr:rpc.method":="GetPortal"
```

### 6.5 数据库属性

查询数据库系统：

```logsql
"span_attr:db.system":="postgresql"
```

查询语句中包含表名：

```logsql
"span_attr:db.statement":*portal_user*
```

生产环境应谨慎展示 `db.statement`，必要时通过 `hidden_fields_filters` 隐藏敏感字段。

### 6.6 Span 名称和 instrumentation scope

Span 名精确匹配：

```logsql
name:="HTTP POST"
```

Span 名以前缀开始：

```logsql
name:="PortalService/"*
```

Scope 名：

```logsql
scope_name:="go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
```

## 7. 时间、耗时、状态和范围查询

### 7.1 最近时间范围

```logsql
_time:15m
```

```logsql
_time:2h AND "resource_attr:service.name":="portal"*
```

### 7.2 绝对时间范围

```logsql
_time:[2026-07-21T09:00:00+08:00, 2026-07-21T10:00:00+08:00)
```

### 7.3 相对时间偏移

查询一小时前对应的 15 分钟窗口：

```logsql
_time:15m offset 1h
```

### 7.4 Span 时长

超过 500ms：

```logsql
duration:>500ms
```

100ms 到 1s：

```logsql
duration:>=100ms AND duration:<1s
```

Portal 服务中的慢 Span：

```logsql
_time:1h
AND "resource_attr:service.name":="portal"*
AND duration:>1s
```

### 7.5 状态码

先发现环境中的值：

```logsql
_time:1h | field_values status_code
```

如果错误状态值为 `2`：

```logsql
status_code:="2"
```

### 7.6 数字、字符串和 IP 范围

字段值大于某数字：

```logsql
"span_attr:http.response.body.size":>10KiB
```

字符串比较：

```logsql
"resource_attr:service.version":>="2.0.0"
```

IPv4 范围示例：

```logsql
"span_attr:client.address":ipv4_range("10.0.0.0/8")
```

具体版本支持的范围过滤形式应以当前部署版本的 LogsQL 页面为准。

## 8. 多条件及“在原查询基础上再搜索”

### 8.1 推荐的逐层缩小法

第一步，服务名前缀：

```logsql
_time:1h
AND "resource_attr:service.name":="portal"*
```

第二步，追加生产环境：

```logsql
_time:1h
AND "resource_attr:service.name":="portal"*
AND "resource_attr:deployment.environment.name":="production"
```

第三步，追加错误条件：

```logsql
_time:1h
AND "resource_attr:service.name":="portal"*
AND "resource_attr:deployment.environment.name":="production"
AND status_code:="2"
```

第四步，追加慢请求：

```logsql
_time:1h
AND "resource_attr:service.name":="portal"*
AND "resource_attr:deployment.environment.name":="production"
AND status_code:="2"
AND duration:>500ms
```

第五步，只显示调查字段：

```logsql
_time:1h
AND "resource_attr:service.name":="portal"*
AND "resource_attr:deployment.environment.name":="production"
AND status_code:="2"
AND duration:>500ms
| fields _time, trace_id, span_id, parent_span_id, name,
  "resource_attr:service.name", duration, status_code,
  "span_attr:http.request.method", "span_attr:http.response.status_code"
| sort by (duration desc) limit 100
```

### 8.2 AND、OR、NOT

Portal 服务且为错误：

```logsql
"resource_attr:service.name":="portal"* AND status_code:="2"
```

API 或 Web 服务：

```logsql
"resource_attr:service.name":(
  ="portal-api" OR ="portal-web"
)
```

排除健康检查：

```logsql
"resource_attr:service.name":="portal"*
AND NOT name:="GET /health"
```

### 8.3 括号改变优先级

```logsql
"resource_attr:service.name":="portal"*
AND (
  status_code:="2"
  OR "span_attr:http.response.status_code":~"^5"
)
```

不要省略这里的括号，否则 `OR` 可能把其他服务的 5xx Span 也包含进来。

### 8.4 在统计结果上继续过滤

```logsql
_time:1h
AND "resource_attr:service.name":="portal"*
| stats by ("resource_attr:service.name") count() spans
| filter spans:>1000
```

`where` 是 `filter` 的别名：

```logsql
_time:1h
| stats by ("resource_attr:service.name") count() spans
| where spans:>1000
```

## 9. 关联搜索与完整 Trace 调查

### 9.1 根据 Trace ID 查询整条调用链

```logsql
trace_id:="769d28c4b8633dc9de2cc421d1a1616f"
| sort by (_time)
```

推荐显示字段：

```logsql
trace_id:="769d28c4b8633dc9de2cc421d1a1616f"
| fields _time, trace_id, span_id, parent_span_id, name,
  "resource_attr:service.name", duration, status_code
| sort by (_time)
```

### 9.2 从异常 Span 扩展到整条 Trace

先找异常候选：

```logsql
_time:30m
AND "resource_attr:service.name":="portal"*
AND status_code:="2"
| sort by (duration desc) limit 20
```

从结果复制 `trace_id`，再执行：

```logsql
trace_id:="<复制的-trace-id>"
| sort by (_time)
```

### 9.3 使用子查询自动扩展异常 Trace

找出包含 Portal 错误 Span 的所有 Trace，并返回这些 Trace 的全部 Span：

```logsql
_time:1h
AND trace_id:in(
  _time:1h
  AND "resource_attr:service.name":="portal"*
  AND status_code:="2"
  | fields trace_id
)
| sort by (trace_id, _time)
```

子查询必须以只包含一个字段的 `fields` 或 `uniq` 管道结尾。

### 9.4 查找某个 Span 的直接子 Span

```logsql
trace_id:="<trace-id>"
AND parent_span_id:="<目标-span-id>"
| sort by (_time)
```

### 9.5 查找父 Span

已知当前 Span 的 `parent_span_id` 后：

```logsql
trace_id:="<trace-id>"
AND span_id:="<parent-span-id>"
```

### 9.6 查询同一个 Span 流

如果结果中有 `_stream_id`：

```logsql
_stream_id:="<stream-id>"
AND _time:1h
```

这适合观察同一服务名、同一 Span 名的其他实例，但不能替代 `trace_id` 关联。

### 9.7 查找同时经过多个服务的 Trace

查出在一小时内经过 `portal-api` 且也经过 `payment` 的 Trace：

```logsql
_time:1h
AND "resource_attr:service.name":="portal-api"
AND trace_id:in(
  _time:1h
  AND "resource_attr:service.name":="payment"
  | fields trace_id
)
```

若要返回这些 Trace 的全部 Span：

```logsql
_time:1h
AND trace_id:in(
  _time:1h
  AND "resource_attr:service.name":="portal-api"
  AND trace_id:in(
    _time:1h
    AND "resource_attr:service.name":="payment"
    | fields trace_id
  )
  | fields trace_id
)
| sort by (trace_id, _time)
```

## 10. 子查询、Join、Union 和上下文关联

### 10.1 `in(<subquery>)` 关联

返回所有属于“慢 Portal Trace”的 Span：

```logsql
_time:1h
AND trace_id:in(
  _time:1h
  AND "resource_attr:service.name":="portal"*
  AND duration:>1s
  | fields trace_id
)
```

### 10.2 Join 对比两个服务的 Trace 统计

按 `trace_id` 将 Portal Span 和 Payment Span 的统计进行左连接：

```logsql
_time:1h
AND "resource_attr:service.name":="portal-api"
| stats by (trace_id) count() portal_spans, max(duration) portal_max_duration
| join by (trace_id) (
    _time:1h
    AND "resource_attr:service.name":="payment"
    | stats by (trace_id) count() payment_spans, max(duration) payment_max_duration
  )
```

只保留两个服务均存在的 Trace：

```logsql
_time:1h
AND "resource_attr:service.name":="portal-api"
| stats by (trace_id) count() portal_spans
| join by (trace_id) (
    _time:1h
    AND "resource_attr:service.name":="payment"
    | stats by (trace_id) count() payment_spans
  ) inner
```

Join 的右侧结果会保存在内存中，应确保它返回较少的数据。

### 10.3 Union 合并两个查询结果

```logsql
_time:15m AND status_code:="2"
| union (
    _time:1h
    AND "resource_attr:service.name":="portal-api"
    AND duration:>2s
  )
```

`union` 类似 SQL 的 `UNION ALL`，不会自动去重。

### 10.4 同一流的前后上下文

对 Trace Span 通常优先使用 `trace_id` 关联；如果需要查看同一 Span 流中命中记录附近的数据，可以使用：

```logsql
_time:15m AND status_code:="2"
| stream_context before 2 after 5
```

`stream_context` 必须紧跟过滤条件。

## 11. 统计、分组、排行和趋势分析

### 11.1 Span 总数

```logsql
_time:15m | stats count() spans
```

### 11.2 按服务统计

```logsql
_time:1h
| stats by ("resource_attr:service.name") count() spans
| sort by (spans desc)
```

### 11.3 按服务和 Span 名统计

```logsql
_time:1h
| stats by ("resource_attr:service.name", name) count() spans
| sort by (spans desc) limit 100
```

### 11.4 错误数和总数同时统计

```logsql
_time:1h
| stats by ("resource_attr:service.name")
    count() total,
    count() if (status_code:="2") errors
| sort by (errors desc)
```

### 11.5 最大、平均和分位数耗时

```logsql
_time:1h
| stats by ("resource_attr:service.name")
    max(duration) max_duration,
    avg(duration) avg_duration,
    quantile(0.95, duration) p95_duration,
    quantile(0.99, duration) p99_duration
| sort by (p99_duration desc)
```

如果当前版本的 `quantile` 参数次序不同，请通过部署版本的 `stats pipe functions` 页面确认。

### 11.6 每分钟趋势

```logsql
_time:1h
AND "resource_attr:service.name":="portal"*
| stats by (_time:1m) count() spans
| sort by (_time)
```

### 11.7 每分钟错误趋势

```logsql
_time:1h
AND "resource_attr:service.name":="portal"*
| stats by (_time:1m)
    count() total,
    count() if (status_code:="2") errors
| sort by (_time)
```

### 11.8 Top N 慢 Span

```logsql
_time:1h
AND "resource_attr:service.name":="portal"*
| sort by (duration desc) limit 20
```

### 11.9 每个服务分别取最慢 3 条

```logsql
_time:1h
| sort by (duration desc)
  partition by ("resource_attr:service.name") limit 3
```

### 11.10 唯一 Trace 数

```logsql
_time:1h
| stats count_uniq(trace_id) traces
```

## 12. 字段选择、重命名、解析和格式化

### 12.1 只保留需要的字段

```logsql
_time:15m
| fields _time, trace_id, span_id, parent_span_id, name,
  "resource_attr:service.name", duration, status_code
```

保留所有资源属性：

```logsql
_time:15m | fields "resource_attr:"*
```

若字段通配符与特殊字符冲突，可先使用 `field_names` 确认，再显式列出字段。

### 12.2 删除字段

```logsql
_time:15m | delete "resource_attr:process.command_args"
```

### 12.3 重命名字段便于展示

```logsql
_time:15m
| rename "resource_attr:service.name" as service,
         "span_attr:http.response.status_code" as http_status
```

### 12.4 复制字段

```logsql
_time:15m | copy trace_id as correlation_id
```

### 12.5 从文本中提取字段

```logsql
_time:15m
| extract "user_id=<user_id>, ip=<ip>" from "span_attr:log.message"
```

### 12.6 使用正则命名捕获组提取

```logsql
_time:15m
| extract_regexp "user=(?P<user_id>[A-Za-z0-9_-]+)" from "span_attr:log.message"
```

### 12.7 解析 JSON 字段

```logsql
_time:15m
| unpack_json from "span_attr:payload" result_prefix "payload."
```

只解析指定字段：

```logsql
_time:15m
| unpack_json from "span_attr:payload" fields (user_id, tenant_id)
```

### 12.8 格式化输出

字段名含特殊字符时，先用 `rename` 创建简单字段名，再进行格式化：

```logsql
_time:15m
| rename "resource_attr:service.name" as service
| format "service=<service> trace=<trace_id> span=<name>" as summary
```

## 13. Jaeger API 查询能力

VictoriaTraces 还提供 Jaeger Query Service JSON API。

### 13.1 列出所有服务

```bash
curl 'http://<victoria-traces>:10428/select/jaeger/api/services'
```

### 13.2 列出某服务的所有操作名

```bash
curl 'http://<victoria-traces>:10428/select/jaeger/api/services/portal-api/operations'
```

### 13.3 根据 Trace ID 查询

```bash
curl 'http://<victoria-traces>:10428/select/jaeger/api/traces/<trace-id>'
```

### 13.4 按服务、操作、标签、耗时和时间范围查询

```bash
curl -G 'http://<victoria-traces>:10428/select/jaeger/api/traces' \
  --data-urlencode 'service=portal-api' \
  --data-urlencode 'operation=HTTP GET' \
  --data-urlencode 'tags={"http.request.method":"GET"}' \
  --data-urlencode 'minDuration=100ms' \
  --data-urlencode 'maxDuration=5s' \
  --data-urlencode 'limit=20' \
  --data-urlencode 'start=<unix-microseconds>' \
  --data-urlencode 'end=<unix-microseconds>'
```

### 13.5 Jaeger tags 精确匹配

Span 属性：

```text
error=unset
```

多个 Span 属性：

```text
error=unset otel.scope.name=redis-manual
```

资源属性：

```text
resource_attr:telemetry.sdk.language=go
```

资源属性与 Span 属性组合：

```text
span.kind=client resource_attr:os.type=linux
```

### 13.6 Jaeger tags 正则匹配

值以 `~` 开头表示正则：

```text
span.kind=~cli.* http.status_code=~^2
```

### 13.7 服务依赖关系

需要在 VictoriaTraces single-node 或 `vtstorage` 启用 `-servicegraph.enableTask=true`。

```bash
curl 'http://<victoria-traces>:10428/select/jaeger/api/dependencies?endTs=1758213428616&lookback=3600000'
```

返回父服务、子服务和调用次数，例如：

```json
{"parent":"portal-api","child":"payment","callCount":128}
```

### 13.8 隐藏敏感字段

隐藏所有以 `pass` 开头的字段以及 `pin` 字段：

```text
hidden_fields_filters=pass*,pin
```

隐藏资源属性：

```text
hidden_fields_filters=resource_attr%3Atelemetry.sdk.name
```

## 14. 常用排障剧本

### 14.1 Portal 服务错误排查

第一步：确认服务名：

```logsql
_time:1h
| field_values "resource_attr:service.name" filter "portal"
```

第二步：查询错误：

```logsql
_time:1h
AND "resource_attr:service.name":="portal"*
AND status_code:="2"
```

第三步：按服务和操作统计：

```logsql
_time:1h
AND "resource_attr:service.name":="portal"*
AND status_code:="2"
| stats by ("resource_attr:service.name", name) count() errors
| sort by (errors desc)
```

第四步：取最慢异常 Span：

```logsql
_time:1h
AND "resource_attr:service.name":="portal"*
AND status_code:="2"
| sort by (duration desc) limit 20
```

第五步：复制 `trace_id`，查看完整链路：

```logsql
trace_id:="<trace-id>" | sort by (_time)
```

### 14.2 HTTP 5xx 排查

```logsql
_time:30m
AND "span_attr:http.response.status_code":~"^5[0-9]{2}$"
| stats by ("resource_attr:service.name", name,
            "span_attr:http.response.status_code") count() errors
| sort by (errors desc)
```

### 14.3 慢调用排查

```logsql
_time:1h
AND duration:>1s
| stats by ("resource_attr:service.name", name)
    count() slow_spans,
    max(duration) max_duration,
    avg(duration) avg_duration
| sort by (max_duration desc)
```

### 14.4 版本发布后回归排查

新版本：

```logsql
_time:1h
AND "resource_attr:service.name":="portal-api"
AND "resource_attr:service.version":="2.4.0"
| stats count() total, count() if (status_code:="2") errors
```

旧版本：

```logsql
_time:1h offset 1d
AND "resource_attr:service.name":="portal-api"
AND "resource_attr:service.version":="2.3.9"
| stats count() total, count() if (status_code:="2") errors
```

### 14.5 特定用户或请求关联

先发现用户字段：

```logsql
_time:1h | field_names filter "user"
```

查询用户相关 Span：

```logsql
_time:1h AND "span_attr:enduser.id":="user-123"
```

扩展到完整 Trace：

```logsql
_time:1h
AND trace_id:in(
  _time:1h
  AND "span_attr:enduser.id":="user-123"
  | fields trace_id
)
| sort by (trace_id, _time)
```

## 15. 性能和正确性原则

1. **总是尽量限制时间范围。** `_time:15m` 通常远快于 `_time:7d`。
2. **把最具体、最快的条件写在左侧。** 精确匹配、时间和简单词过滤应放在正则之前。
3. **前缀能解决时不要用正则。** `:="portal"*` 通常比 `:~"^portal"` 快。
4. **有限值列表优先使用 `in()`。** 不要为几个精确值写复杂正则。
5. **先发现字段，再写查询。** 使用 `field_names`、`field_values`、`facets`。
6. **资源/Span/Scope 字段名要整体加引号。** 这些字段通常包含冒号和点。
7. **关联完整调用链优先使用 `trace_id`。** `_stream_id` 表示流，不代表一条 Trace。
8. **子查询需要返回单一字段。** 以 `fields trace_id` 或 `uniq by (trace_id)` 结束。
9. **Join 右侧必须小。** 其结果会驻留内存。
10. **排序时限制结果数。** 使用 `sort ... limit N`，避免无界排序。
11. **确认枚举值。** `status_code`、`kind` 等字段的存储值应通过 `field_values` 验证。
12. **敏感字段需隐藏。** 使用 `hidden_fields_filters` 或访问代理策略。

## 16. 查询速查表

| 目标 | 示例 |
|---|---|
| 最近 15 分钟 | `_time:15m` |
| 服务名精确匹配 | `"resource_attr:service.name":="portal-api"` |
| 服务名前缀 | `"resource_attr:service.name":="portal"*` |
| 任意位置包含 | `"resource_attr:service.name":*portal*` |
| 正则 | `"resource_attr:service.name":~"^portal-(api|web)$"` |
| 忽略大小写 | `"resource_attr:service.name":~"(?i)^portal"` |
| 字段存在 | `"span_attr:http.response.status_code":*` |
| 字段为空 | `"span_attr:http.response.status_code":""` |
| 多值之一 | `"resource_attr:service.name":in("portal-api", "portal-web")` |
| 慢 Span | `duration:>1s` |
| Trace 全链路 | `trace_id:="<trace-id>" | sort by (_time)` |
| 直接子 Span | `trace_id:="<trace-id>" AND parent_span_id:="<span-id>"` |
| 所有字段名 | `_time:15m | field_names` |
| 资源字段名 | `_time:15m | field_names filter "resource_attr:"` |
| 某字段所有值 | `_time:15m | field_values "resource_attr:service.name"` |
| 常见字段值 | `_time:15m | facets 10` |
| 按服务统计 | `_time:1h | stats by ("resource_attr:service.name") count() spans` |
| Top 慢 Span | `_time:1h | sort by (duration desc) limit 20` |
| 异常 Trace 的全部 Span | `_time:1h AND trace_id:in(_time:1h AND status_code:="2" | fields trace_id)` |

---

文档以 VictoriaMetrics 官方当前页面为依据。VictoriaTraces 和 LogsQL 仍在持续演进；升级版本后，应使用本手册中的“字段发现”查询确认部署版本的字段映射和枚举值。