VictoriaTraces Query
VictoriaTraces 查询
Query VictoriaTraces Jaeger-compatible HTTP API directly via curl. Covers service/operation discovery, trace search, trace retrieval by ID, and dependency mapping.
通过curl直接调用VictoriaTraces兼容Jaeger的HTTP API进行查询。涵盖服务/操作发现、追踪信息搜索、按ID检索追踪信息以及依赖映射功能。
$VM_TRACES_URL - base URL including /select/jaeger prefix
$VM_TRACES_URL - 包含/select/jaeger前缀的基础URL
$VM_AUTH_HEADER - auth header (set for prod, empty for local)
$VM_AUTH_HEADER - 认证请求头（生产环境设置，本地环境留空）
IMPORTANT: The Jaeger API lives under `/select/jaeger/api/...`, NOT root `/api/...`. The `$VM_TRACES_URL` env var already includes the `/select/jaeger` prefix, so all endpoints below use `$VM_TRACES_URL/api/...`.
重要提示：Jaeger API位于`/select/jaeger/api/...`路径下，而非根路径`/api/...`。`$VM_TRACES_URL`环境变量已包含`/select/jaeger`前缀，因此以下所有端点均使用`$VM_TRACES_URL/api/...`格式。
All curl commands use conditional auth:
bash
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"} \
"$VM_TRACES_URL/api/services" | jq .
When
is empty,
flag is omitted automatically.
所有curl命令均使用条件认证：
bash
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"} \
"$VM_TRACES_URL/api/services" | jq .
- Trace search / use Unix MICROSECONDS (16 digits, e.g., )
- Dependencies / use Unix MILLISECONDS (13 digits, e.g., )
- is required for trace search — you must know the service name first
- / are string durations (e.g., , )
- Trace IDs not found return 404 in the array, not an HTTP 404
- Trace search with time ranges outside retention returns plain text error, not JSON — handle gracefully
- Always discover services first, then operations, then search traces
- 追踪搜索的/参数使用Unix微秒（16位数字，例如）
- 依赖查询的/参数使用Unix毫秒（13位数字，例如）
- 追踪搜索必须指定参数——需先知晓服务名称
- /为字符串格式的时长（例如、）
- 未找到的Trace ID会在数组中返回404，而非HTTP 404状态码
- 若追踪搜索的时间范围超出数据保留期，会返回纯文本错误而非JSON——需妥善处理
- 需遵循先发现服务、再发现操作、最后搜索追踪信息的流程
bash
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"} \
"$VM_TRACES_URL/api/services" | jq '.data[]'
No parameters. Returns all traced service names. Always start here to discover what's available.
bash
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"} \
"$VM_TRACES_URL/api/services" | jq '.data[]'
无需参数。返回所有已被追踪的服务名称。建议从该步骤开始，了解可用的服务。
bash
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"} \
"$VM_TRACES_URL/api/services/my-service/operations" | jq '.data[]'
is a PATH parameter. Returns operation names for the given service.
bash
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"} \
"$VM_TRACES_URL/api/services/my-service/operations" | jq '.data[]'
Basic search (last hour, limit 20) — timestamps in microseconds (16 digits)
基础搜索（最近1小时，限制20条）——时间戳为微秒（16位数字）
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_TRACES_URL/api/traces?service=my-service&start=$(($(date +%s%6N) - 3600000000))&end=$(date +%s%6N)&limit=20" | jq .
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_TRACES_URL/api/traces?service=my-service&start=$(($(date +%s%6N) - 3600000000))&end=$(date +%s%6N)&limit=20" | jq .
With operation and duration filter
带操作和时长过滤的搜索
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_TRACES_URL/api/traces?service=my-service&operation=GET+/api/health&start=$(($(date +%s%6N) - 3600000000))&end=$(date +%s%6N)&minDuration=100ms&limit=20" | jq .
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_TRACES_URL/api/traces?service=my-service&operation=GET+/api/health&start=$(($(date +%s%6N) - 3600000000))&end=$(date +%s%6N)&minDuration=100ms&limit=20" | jq .
With tag filter (Jaeger JSON format)
带标签过滤（Jaeger JSON格式）
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_TRACES_URL/api/traces?service=my-service&start=$(($(date +%s%6N) - 3600000000))&end=$(date +%s%6N)&tags=%7B%22http.status_code%22%3A%22500%22%7D&limit=20" | jq .
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_TRACES_URL/api/traces?service=my-service&start=$(($(date +%s%6N) - 3600000000))&end=$(date +%s%6N)&tags=%7B%22http.status_code%22%3A%22500%22%7D&limit=20" | jq .
With tag filter (VictoriaTraces extended format — key=value pairs, space-separated)
带标签过滤（VictoriaTraces扩展格式——键值对，空格分隔）
curl -s -G ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
--data-urlencode 'tags=http.status_code=500 resource_attr:service.namespace=production'
"$VM_TRACES_URL/api/traces?service=my-service&start=$(($(date +%s%6N) - 3600000000))&end=$(date +%s%6N)&limit=20" | jq .
Parameters: `service` (required), `operation`, `start` (Unix µs), `end` (Unix µs), `limit`, `minDuration` (e.g., `1s`), `maxDuration`, `tags` (URL-encoded JSON object or VictoriaTraces key=value format)
curl -s -G ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
--data-urlencode 'tags=http.status_code=500 resource_attr:service.namespace=production'
"$VM_TRACES_URL/api/traces?service=my-service&start=$(($(date +%s%6N) - 3600000000))&end=$(date +%s%6N)&limit=20" | jq .
参数：`service`（必填）、`operation`、`start`（Unix微秒）、`end`（Unix微秒）、`limit`、`minDuration`（例如`1s`）、`maxDuration`、`tags`（URL编码的JSON对象或VictoriaTraces键值对格式）
bash
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"} \
"$VM_TRACES_URL/api/traces/abc123def456789" | jq .
Returns full trace with all spans. If trace not found, response contains
"errors": [{"code": 404, "msg": "trace not found"}]
.
bash
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"} \
"$VM_TRACES_URL/api/traces/abc123def456789" | jq .
返回包含所有Span的完整追踪信息。若未找到追踪信息，响应会包含
"errors": [{"code": 404, "msg": "trace not found"}]
。
Service Dependencies
服务依赖映射
Dependencies for the last hour
查询最近1小时的服务依赖
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_TRACES_URL/api/dependencies?endTs=$(date +%s%3N)&lookback=3600000" | jq '.data[]'
Parameters: `endTs` (Unix ms, required), `lookback` (duration in ms, required). Returns edges between services showing call relationships.
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_TRACES_URL/api/dependencies?endTs=$(date +%s%3N)&lookback=3600000" | jq '.data[]'
参数：`endTs`（Unix毫秒，必填）、`lookback`（毫秒格式的时长，必填）。返回服务间的调用关系边信息。
Trace search and dependencies use DIFFERENT timestamp units:
| Endpoint | Parameter | Unit | Digits | Example |
|---|
| , | Microseconds | 16 | |
| | Milliseconds | 13 | |
| | Milliseconds | 13 | (1 hour) |
追踪搜索和依赖查询使用不同的时间戳单位：
| 端点 | 参数 | 单位 | 位数 | 示例 |
|---|
| , | 微秒 | 16 | |
| | 毫秒 | 13 | |
| | 毫秒 | 13 | （1小时） |
Current time in microseconds (for trace search)
获取当前时间的微秒值（用于追踪搜索）
1 hour ago in microseconds
获取1小时前的微秒值
echo $(($(date +%s%6N) - 3600000000))
echo $(($(date +%s%6N) - 3600000000))
Specific time to microseconds (GNU date)
将指定时间转换为微秒值（GNU date）
date -d "2026-03-07T09:00:00Z" +%s%6N
date -d "2026-03-07T09:00:00Z" +%s%6N
Current time in milliseconds (for dependencies)
获取当前时间的毫秒值（用于依赖查询）
Duration values for minDuration/maxDuration are strings: "1s", "500ms", "100us"
minDuration/maxDuration的时长值为字符串格式："1s", "500ms", "100us"
Duration value for lookback is ms number: 3600000 = 1 hour
lookback的时长值为毫秒数字：3600000 = 1小时
Response Parsing (jq)
响应解析（jq）
Extract trace IDs from search results
从搜索结果中提取Trace ID
... | jq '.data[] | .traceID'
... | jq '.data[] | .traceID'
Get span count per trace
获取每个追踪信息的Span数量
... | jq '.data[] | {traceID: .traceID, spans: (.spans | length)}'
... | jq '.data[] | {traceID: .traceID, spans: (.spans | length)}'
Extract spans with duration > 1s (duration is in microseconds)
提取时长超过1秒的Span（时长单位为微秒）
... | jq '.data[].spans[] | select(.duration > 1000000) | {operation: .operationName, duration_ms: (.duration / 1000)}'
... | jq '.data[].spans[] | select(.duration > 1000000) | {operation: .operationName, duration_ms: (.duration / 1000)}'
Get root span of each trace
获取每个追踪信息的根Span
... | jq '.data[] | .spans[] | select(.references == null or (.references | length) == 0) | {traceID: .traceID, operation: .operationName, service: .processID}'
... | jq '.data[] | .spans[] | select(.references == null or (.references | length) == 0) | {traceID: .traceID, operation: .operationName, service: .processID}'
Extract service-to-service calls from dependencies
从依赖数据中提取服务间调用关系
... | jq '.data[] | "(.parent) -> (.child) ((.callCount) calls)"'
... | jq '.data[] | "(.parent) -> (.child) ((.callCount) calls)"'
Get all tags from a span
提取Span的所有标签
... | jq '.data[].spans[] | {operation: .operationName, tags: [.tags[] | {(.key): .value}] | add}'
... | jq '.data[].spans[] | {operation: .operationName, tags: [.tags[] | {(.key): .value}] | add}'
Find error spans
查找包含错误的Span
... | jq '.data[].spans[] | select(.tags[] | select(.key == "error" and .value == true)) | {traceID: .traceID, operation: .operationName}'
... | jq '.data[].spans[] | select(.tags[] | select(.key == "error" and .value == true)) | {traceID: .traceID, operation: .operationName}'
Full discovery workflow: services -> operations -> traces
完整发现流程：服务 -> 操作 -> 追踪信息
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"} "$VM_TRACES_URL/api/services" | jq '.data[]'
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"} "$VM_TRACES_URL/api/services/my-service/operations" | jq '.data[]'
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"} "$VM_TRACES_URL/api/traces?service=my-service&start=$(($(date +%s%6N) - 3600000000))&end=$(date +%s%6N)&limit=10" | jq '.data[] | .traceID'
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"} "$VM_TRACES_URL/api/services" | jq '.data[]'
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"} "$VM_TRACES_URL/api/services/my-service/operations" | jq '.data[]'
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"} "$VM_TRACES_URL/api/traces?service=my-service&start=$(($(date +%s%6N) - 3600000000))&end=$(date +%s%6N)&limit=10" | jq '.data[] | .traceID'
Find slow traces (> 5 seconds)
查找慢追踪信息（时长超过5秒）
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_TRACES_URL/api/traces?service=my-service&start=$(($(date +%s%6N) - 3600000000))&end=$(date +%s%6N)&minDuration=5s&limit=20" | jq '.data[] | {traceID: .traceID, spans: (.spans | length)}'
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_TRACES_URL/api/traces?service=my-service&start=$(($(date +%s%6N) - 3600000000))&end=$(date +%s%6N)&minDuration=5s&limit=20" | jq '.data[] | {traceID: .traceID, spans: (.spans | length)}'
Look up a trace ID found in logs
查询日志中发现的Trace ID
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_TRACES_URL/api/traces/abc123def456789" | jq '.data[].spans[] | {operation: .operationName, duration_ms: (.duration / 1000), service: .processID}'
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_TRACES_URL/api/traces/abc123def456789" | jq '.data[].spans[] | {operation: .operationName, duration_ms: (.duration / 1000), service: .processID}'
Map service dependencies (last 24 hours) — dependencies use milliseconds
映射服务依赖（最近24小时）——依赖查询使用毫秒单位
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_TRACES_URL/api/dependencies?endTs=$(date +%s%3N)&lookback=86400000" | jq '.data[]'
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_TRACES_URL/api/dependencies?endTs=$(date +%s%3N)&lookback=86400000" | jq '.data[]'
Environment Switching
环境切换
Check current environment
检查当前环境
echo "VM_TRACES_URL: $VM_TRACES_URL"
if [ -n "${VM_AUTH_HEADER-}" ]; then
echo "VM_AUTH_HEADER: (set)"
else
echo "VM_AUTH_HEADER: (unset)"
fi
echo "VM_TRACES_URL: $VM_TRACES_URL"
if [ -n "${VM_AUTH_HEADER-}" ]; then
echo "VM_AUTH_HEADER: (已设置)"
else
echo "VM_AUTH_HEADER: (未设置)"
fi
- The Jaeger API prefix is included in — do NOT add it again
- parameter supports both Jaeger JSON format () and VictoriaTraces extended format (
key=value resource_attr:key=value scope_attr:key=value
- Span durations in responses are in MICROSECONDS (not milliseconds)
- Process info is referenced by in spans, mapped in the trace's object
- GET is sufficient for all endpoints — POST also works for trace search
- For full endpoint details, parameters, and response formats, see
references/api-reference.md
- Jaeger API前缀已包含在中——请勿重复添加
- 参数支持Jaeger JSON格式（）和VictoriaTraces扩展格式（
key=value resource_attr:key=value scope_attr:key=value
- 响应中的Span时长单位为微秒（非毫秒）
- Span中的关联到追踪信息对象中的进程信息
- 所有端点使用GET请求即可——追踪搜索也支持POST请求
- 如需完整的端点详情、参数及响应格式，请查看
references/api-reference.md