mcpField
V
victoriatraces-query

victoriatraces-query

github.com/victoriametrics云与 DevOps59262 次安装2 周前更新
代码仓库

关于 victoriatraces-query

victoriatraces-query 是一项通过 curl 查询 VictoriaTraces Jaeger 兼容 HTTP API 的技能，面向排查分布式追踪的团队。它支持发现服务、搜索和获取追踪记录，以及检查服务依赖关系。

主要功能

  1. 01发现服务和操作
  2. 02按时间及条件搜索追踪
  3. 03按 ID 获取追踪
  4. 04映射服务依赖关系
  5. 05使用 jq 解析 API 结果

适用场景

  1. 01查找特定服务和操作的追踪
  2. 02在时间范围内排查慢速追踪
  3. 03按 ID 检查追踪及其跨度
  4. 04查看服务间调用关系

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/victoriametrics/skills --skill victoriatraces-query

安装后在 Claude Code 中输入/victoriatraces-query确认已加载。

附带文件references/api-reference.md

详细介绍

VictoriaTraces 查询

通过 curl 直接查询兼容 Jaeger 的 VictoriaTraces HTTP API。涵盖服务和操作发现、追踪搜索、按 ID 获取追踪，以及依赖关系映射。

环境

# $VM_TRACES_URL - base URL including /select/jaeger prefix
#   Example: export VM_TRACES_URL="https://vtselect.example.com/select/jaeger"
# $VM_CURL_CONFIG - curl config file with auth header (set for remote, unset for local)
#   Remote: export VM_CURL_CONFIG="$HOME/.config/victoriametrics/curl.conf"
#   Local:  leave unset (defaults to /dev/null - no auth)

重要：Jaeger API 位于 /select/jaeger/api/... 下，而不是根路径 /api/...。$VM_TRACES_URL 环境变量已包含 /select/jaeger 前缀，因此以下所有端点均使用 $VM_TRACES_URL/api/...。

认证模式

所有 curl 命令都会从 curl 配置文件加载认证信息：

curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$VM_TRACES_URL/api/services" | jq .

未设置 VM_CURL_CONFIG 时，curl 会读取 /dev/null，且不发送认证头。设置后，它必须指向权限模式为 0600、且包含 header = "Authorization: Bearer <token>" 的 curl 配置文件。切勿打印其内容。

关键规则

  • 追踪搜索的 start/end 使用 Unix 微秒（16 位数字，例如 1709769600000000）
  • 依赖关系的 endTs/lookback 使用 Unix 毫秒（13 位数字，例如 1709769600000）
  • 追踪搜索必须提供 service——你必须先知道服务名称
  • minDuration/maxDuration 是字符串形式的时长（例如 "1s"、"500ms"）
  • 未找到追踪 ID 时，404 会出现在 errors 数组中，而不是 HTTP 404 响应中
  • 如果追踪搜索的时间范围超出保留期，API 会返回纯文本错误而非 JSON——请妥善处理
  • 始终先发现服务，再发现操作，然后搜索追踪

核心端点

列出服务
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$VM_TRACES_URL/api/services" | jq '.data[]'

无需参数。返回所有有追踪记录的服务名称。始终从这里开始，以发现可用内容。

服务操作
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$VM_TRACES_URL/api/services/my-service/operations" | jq '.data[]'

service 是路径参数。返回指定服务的操作名称。

搜索追踪
# Basic search (last hour, limit 20) — timestamps in microseconds (16 digits)
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$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 -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$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)
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$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)
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s -G \
  --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 的 key=value 格式）

按 ID 获取追踪
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$VM_TRACES_URL/api/traces/abc123def456789" | jq .

返回包含所有 Span 的完整追踪。如果未找到追踪，响应中会包含 "errors": [{"code": 404, "msg": "trace not found"}]。

服务依赖关系
# Dependencies for the last hour
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$VM_TRACES_URL/api/dependencies?endTs=$(date +%s%3N)&lookback=3600000" | jq '.data[]'

参数：endTs（Unix 毫秒，必填）、lookback（以毫秒为单位的时长，必填）。返回服务之间的边，显示调用关系。

时间戳格式

追踪搜索和依赖关系使用不同的时间戳单位：

端点参数单位位数示例
/api/tracesstart、end微秒161709769600000000
/api/dependenciesendTs毫秒131709769600000
/api/dependencieslookback毫秒133600000（1 小时）
# Current time in microseconds (for trace search)
date +%s%6N

# 1 hour ago in microseconds
echo $(($(date +%s%6N) - 3600000000))

# Specific time to microseconds (GNU date)
date -d "2026-03-07T09:00:00Z" +%s%6N

# Current time in milliseconds (for dependencies)
date +%s%3N

# Duration values for minDuration/maxDuration are strings: "1s", "500ms", "100us"
# Duration value for lookback is ms number: 3600000 = 1 hour

响应解析（jq）

# List service names
... | jq '.data[]'

# Extract trace IDs from search results
... | jq '.data[] | .traceID'

# Get span count per trace
... | jq '.data[] | {traceID: .traceID, spans: (.spans | length)}'

# Extract spans with duration > 1s (duration is in microseconds)
... | jq '.data[].spans[] | select(.duration > 1000000) | {operation: .operationName, duration_ms: (.duration / 1000)}'

# Get root span of each trace
... | 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)"'

# Get all tags from a span
... | jq '.data[].spans[] | {operation: .operationName, tags: [.tags[] | {(.key): .value}] | add}'

# Find error spans
... | jq '.data[].spans[] | select(.tags[] | select(.key == "error" and .value == true)) | {traceID: .traceID, operation: .operationName}'

常见模式

# Full discovery workflow: services -> operations -> traces
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s "$VM_TRACES_URL/api/services" | jq '.data[]'
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s "$VM_TRACES_URL/api/services/my-service/operations" | jq '.data[]'
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s "$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)
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$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
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$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
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$VM_TRACES_URL/api/dependencies?endTs=$(date +%s%3N)&lookback=86400000" | jq '.data[]'

环境切换

# Check current environment
echo "VM_TRACES_URL: $VM_TRACES_URL"
echo "VM_CURL_CONFIG: ${VM_CURL_CONFIG:-(unset - no auth)}"

重要说明

  • 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

评论

支持 Markdown