victoriatraces-query

VictoriaTraces クエリ

curl を使って VictoriaTraces の Jaeger 互換 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 はルートの /api/... ではなく、/select/jaeger/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 を読み込み、認証ヘッダーを送信しません。設定されている場合は、header = "Authorization: Bearer <token>" を含む mode-0600 の curl 設定ファイルを指定する必要があります。その内容を出力してはいけません。

重要なルール

• トレース検索の start／end は Unix マイクロ秒（16 桁、例：1709769600000000）を使用します
• 依存関係の endTs／lookback は Unix ミリ秒（13 桁、例：1709769600000）を使用します
• トレース検索には service が必須です。最初にサービス名を把握する必要があります
• minDuration／maxDuration は文字列形式の時間です（例："1s"、"500ms"）
• 見つからないトレース ID は HTTP 404 ではなく、errors 配列内で 404 を返します
• 保持期間外の時間範囲でトレースを検索すると、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 は PATH パラメーターです。指定したサービスのオペレーション名を返します。

トレース検索

# 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 µs）、end（Unix µs）、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 .

すべてのスパンを含むトレース全体を返します。トレースが見つからない場合、レスポンスには "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 ms、必須）、lookback（ミリ秒単位の期間、必須）。サービス間の呼び出し関係を示すエッジを返します。

タイムスタンプ形式

トレース検索と依存関係では、異なるタイムスタンプ単位を使用します。

エンドポイント	パラメーター	単位	桁数	例
/api/traces	start、end	マイクロ秒	16	1709769600000000
/api/dependencies	endTs	ミリ秒	13	1709769600000
/api/dependencies	lookback	ミリ秒	13	3600000（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）の両方に対応しています
• レスポンス内のスパン期間はマイクロ秒（ミリ秒ではありません）です
• スパン内の processID はプロセス情報への参照で、トレースの processes オブジェクト内で対応付けられています
• すべてのエンドポイントで GET で十分です。トレース検索では POST も使用できます
• エンドポイント、パラメーター、レスポンス形式の詳細については、references/api-reference.md を参照してください