Back to Details

victoriatraces-query

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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检索追踪信息以及依赖映射功能。

Environment

环境配置

bash
undefined
bash
undefined

$VM_TRACES_URL - base URL including /select/jaeger prefix

$VM_TRACES_URL - 包含/select/jaeger前缀的基础URL

Example: export VM_TRACES_URL="https://vtselect.example.com/select/jaeger"

示例：export VM_TRACES_URL="https://vtselect.example.com/select/jaeger"

$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/...`格式。

Auth Pattern

认证模式

All curl commands use conditional auth:
bash
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"} \
  "$VM_TRACES_URL/api/services" | jq .
When 
VM_AUTH_HEADER
is empty, 
-H
flag is omitted automatically.
所有curl命令均使用条件认证：
bash
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"} \
  "$VM_TRACES_URL/api/services" | jq .
当
VM_AUTH_HEADER
为空时，会自动省略
-H
参数。

Critical Rules

关键规则

  • Trace search 
    start
    /
    end
    use Unix MICROSECONDS (16 digits, e.g., 
    1709769600000000
    )
  • Dependencies 
    endTs
    /
    lookback
    use Unix MILLISECONDS (13 digits, e.g., 
    1709769600000
    )
  • service
    is required for trace search — you must know the service name first
  • minDuration
    /
    maxDuration
    are string durations (e.g., 
    "1s"
    , 
    "500ms"
    )
  • Trace IDs not found return 404 in the 
    errors
    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
  • 追踪搜索的
    start
    /
    end
    参数使用Unix微秒（16位数字，例如
    1709769600000000
    ）
  • 依赖查询的
    endTs
    /
    lookback
    参数使用Unix毫秒（13位数字，例如
    1709769600000
    ）
  • 追踪搜索必须指定
    service
    参数——需先知晓服务名称
  • minDuration
    /
    maxDuration
    为字符串格式的时长（例如
    "1s"
    、
    "500ms"
    ）
  • 未找到的Trace ID会在
    errors
    数组中返回404，而非HTTP 404状态码
  • 若追踪搜索的时间范围超出数据保留期，会返回纯文本错误而非JSON——需妥善处理
  • 需遵循先发现服务、再发现操作、最后搜索追踪信息的流程

Core Endpoints

核心端点

List Services

列出所有服务

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[]'
无需参数。返回所有已被追踪的服务名称。建议从该步骤开始，了解可用的服务。

Service Operations

服务操作列表

bash
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"} \
  "$VM_TRACES_URL/api/services/my-service/operations" | jq '.data[]'
service
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[]'
service
为路径参数。返回指定服务下的操作名称。

Search Traces

搜索追踪信息

bash
undefined
bash
undefined

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键值对格式）

Get Trace by ID

按ID获取追踪信息

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

服务依赖映射

bash
undefined
bash
undefined

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`（毫秒格式的时长，必填）。返回服务间的调用关系边信息。

Timestamp Format

时间戳格式

Trace search and dependencies use DIFFERENT timestamp units:
EndpointParameterUnitDigitsExample
/api/traces
start
, 
end
Microseconds16
1709769600000000
/api/dependencies
endTs
Milliseconds13
1709769600000
/api/dependencies
lookback
Milliseconds13
3600000
(1 hour)
bash
undefined
追踪搜索和依赖查询使用不同的时间戳单位：
端点参数单位位数示例
/api/traces
start
, 
end
微秒16
1709769600000000
/api/dependencies
endTs
毫秒13
1709769600000
/api/dependencies
lookback
毫秒13
3600000
（1小时）
bash
undefined

Current time in microseconds (for trace search)

获取当前时间的微秒值（用于追踪搜索）

date +%s%6N
date +%s%6N

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)

获取当前时间的毫秒值（用于依赖查询）

date +%s%3N
date +%s%3N

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小时

undefined
undefined

Response Parsing (jq)

响应解析（jq）

bash
undefined
bash
undefined

List service names

列出服务名称

... | jq '.data[]'
... | jq '.data[]'

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}'
undefined
... | jq '.data[].spans[] | select(.tags[] | select(.key == "error" and .value == true)) | {traceID: .traceID, operation: .operationName}'
undefined

Common Patterns

常用操作流程

bash
undefined
bash
undefined

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[]'
undefined
curl -s ${VM_AUTH_HEADER:+-H "$VM_AUTH_HEADER"}
"$VM_TRACES_URL/api/dependencies?endTs=$(date +%s%3N)&lookback=86400000" | jq '.data[]'
undefined

Environment Switching

环境切换

bash
undefined
bash
undefined

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
undefined
echo "VM_TRACES_URL: $VM_TRACES_URL" if [ -n "${VM_AUTH_HEADER-}" ]; then echo "VM_AUTH_HEADER: (已设置)" else echo "VM_AUTH_HEADER: (未设置)" fi
undefined

Important Notes

重要说明

  • The Jaeger API prefix 
    /select/jaeger
    is included in 
    $VM_TRACES_URL
    — do NOT add it again
  • tags
    parameter supports both Jaeger JSON format (
    {"key":"value"}
    ) 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 
    processID
    in spans, mapped in the trace's 
    processes
    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前缀
    /select/jaeger
    已包含在
    $VM_TRACES_URL
    中——请勿重复添加
  • tags
    参数支持Jaeger JSON格式（
    {"key":"value"}
    ）和VictoriaTraces扩展格式（
    key=value resource_attr:key=value scope_attr:key=value
    ）
  • 响应中的Span时长单位为微秒（非毫秒）
  • Span中的
    processID
    关联到追踪信息
    processes
    对象中的进程信息
  • 所有端点使用GET请求即可——追踪搜索也支持POST请求
  • 如需完整的端点详情、参数及响应格式，请查看
    references/api-reference.md