victorialogs-query

VictoriaLogs のクエリ

curl を介して VictoriaLogs HTTP API に直接クエリを送信します。ログ検索、統計クエリ、フィールド／ストリームの検出、ヒット分析、ファセットを扱います。

環境

# $VM_LOGS_URL - base URL
#   Example: export VM_LOGS_URL="https://vlselect.example.com"
# $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)

認証パターン

すべての curl コマンドは、curl 設定ファイルから認証情報を読み込みます。

curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  "$VM_LOGS_URL/select/logsql/query?query=*&start=2026-03-07T00:00:00Z&limit=10"

VM_CURL_CONFIG が設定されていない場合、curl は /dev/null を読み込み、認証ヘッダーを送信しません。設定されている場合は、header = "Authorization: Bearer <token>" を含むモード 0600 の curl 設定ファイルを指定する必要があります。内容を表示しないでください。

重要なルール

• すべての VictoriaLogs エンドポイントでは、必ず start を指定してください。省略すると、保存されているすべてのデータがスキャンされ、非常に高いコストがかかります。API 上は必須ではありませんが、省略するのが望ましいケースはほとんどありません。
• stats_query では time を使用します（必ず明示的に指定し、デフォルト値に依存しないでください）。stats_query_range では start／end／step を使用します。
• hits エンドポイントでは step が必須です。
• /select/logsql/query は JSON Lines（1 行に JSON オブジェクト 1 つ）を返します。JSON 配列ではありません。
• 特殊文字を含む LogsQL クエリは URL エンコードする必要があります（POST には --data-urlencode を使用してください）。
• stats_query と stats_query_range のクエリには、必ず | stats パイプを含めてください。

主なエンドポイント

ログクエリ

# Basic query (last hour, limit 100)
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  --data-urlencode 'query={namespace="myapp"} error' \
  "$VM_LOGS_URL/select/logsql/query?start=2026-03-07T00:00:00Z&limit=100"

# With time range and field selection
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  --data-urlencode 'query={namespace="myapp"} error' \
  "$VM_LOGS_URL/select/logsql/query?start=2026-03-07T00:00:00Z&end=2026-03-07T12:00:00Z&limit=50&fields=_time,_msg,level"

パラメーター：query（必須）、start（必須、RFC3339）、end、limit、offset、fields（カンマ区切り）、timeout

レスポンス：JSON Lines（1 行に JSON オブジェクト 1 つ）。jq -s . に渡して配列にまとめるか、1 行ずつ処理してください。

統計クエリ（インスタント）

# Count errors by level at a point in time
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  --data-urlencode 'query={namespace="myapp"} | stats by (level) count() as total' \
  "$VM_LOGS_URL/select/logsql/stats_query?time=2026-03-07T09:00:00Z" | jq .

パラメーター：query（必須、| stats パイプを含める必要があります）、time（必須、RFC3339）、start（任意、time の代替）。

レスポンス：Prometheus 互換の JSON 形式。

統計クエリ範囲

# Error count over time with 1h steps
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  --data-urlencode 'query={namespace="myapp"} error | stats count() as total' \
  "$VM_LOGS_URL/select/logsql/stats_query_range?start=2026-03-07T00:00:00Z&end=2026-03-07T12:00:00Z&step=1h" | jq .

パラメーター：query（必須、| stats パイプを含める必要があります）、start（必須）、end、step（例：1h、5m）

レスポンス：Prometheus のマトリックス形式。

ヒット数（ログ量）

# Log volume over time
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  --data-urlencode 'query={namespace="myapp"}' \
  "$VM_LOGS_URL/select/logsql/hits?start=2026-03-07T00:00:00Z&end=2026-03-07T12:00:00Z&step=1h" | jq .

パラメーター：query（必須）、start（必須）、end、step（必須）、field（任意、フィールドでグループ化）

ファセット（最適な検出ツール）

# Discover field value distributions
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  --data-urlencode 'query={namespace="myapp"}' \
  "$VM_LOGS_URL/select/logsql/facets?start=2026-03-07T00:00:00Z&end=2026-03-07T12:00:00Z" | jq .

パラメーター：query（必須）、start（必須）、end。1 回の呼び出しで、すべてのフィールドの最頻値を返します。

検出エンドポイント

フィールド名と値

# Discover non-stream field names
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  --data-urlencode 'query={namespace="myapp"}' \
  "$VM_LOGS_URL/select/logsql/field_names?start=2026-03-07T00:00:00Z" | jq .

# Get values for a specific field
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  --data-urlencode 'query={namespace="myapp"}' \
  "$VM_LOGS_URL/select/logsql/field_values?start=2026-03-07T00:00:00Z&field=level&limit=20" | jq .

ストリームフィールド

# Discover stream field names (e.g., namespace, pod)
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  --data-urlencode 'query=*' \
  "$VM_LOGS_URL/select/logsql/stream_field_names?start=2026-03-07T00:00:00Z" | jq .

# Get values for a stream field
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  --data-urlencode 'query=*' \
  "$VM_LOGS_URL/select/logsql/stream_field_values?start=2026-03-07T00:00:00Z&field=namespace" | jq .

ストリームとストリーム ID

# List log stream identifiers
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  --data-urlencode 'query={namespace="myapp"}' \
  "$VM_LOGS_URL/select/logsql/streams?start=2026-03-07T00:00:00Z&limit=20" | jq .

# List stream IDs
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  --data-urlencode 'query={namespace="myapp"}' \
  "$VM_LOGS_URL/select/logsql/stream_ids?start=2026-03-07T00:00:00Z" | jq .

LogsQL クイックリファレンス

LogsQL はスペース区切りで、デフォルトでは AND 条件です。パイプには | を使います。

# Stream filter (fast, use for namespace/pod selection)
{namespace="myapp"}

# Word filter (matches full words in _msg)
{namespace="myapp"} error

# Multiple words (AND)
{namespace="myapp"} error timeout

# OR filter
{namespace="myapp"} (error OR warning)

# Regex filter on _msg
{namespace="myapp"} ~"err|warn"

# Case-insensitive regex
{namespace="myapp"} ~"(?i)error"

# Field-specific filter
{namespace="myapp"} level:error

# Time filter (alternative to API start/end params)
{namespace="myapp"} _time:1h error

# Negation
{namespace="myapp"} error -"expected error"

# Stats pipe
{namespace="myapp"} _time:1h | stats by (level) count() as total

# Sort pipe
{namespace="myapp"} error | sort by (_time)

# Top pipe
{namespace="myapp"} _time:1h | top 10 (level)

よくある間違い：

• | grep は存在しません。単語フィルターまたは ~"regex" を使用してください。
• | filter は有効なパイプですが、集計結果をフィルタリングする場合に限り、| stats の後で使用できます。
• 時間範囲は API の start／end パラメーターまたは _time: フィルターのどちらかに指定し、両方には指定しないでください。
• ストリームフィールド名は取り込み設定によって異なります。必ず最初に検出してください。
• vmselect をフィルタリングせずに「error」を検索すると、vmselect のログに「error」を含む PromQL テキストがあるため、-"vm_slow_query_stats" を追加して除外してください。

タイムスタンプ形式

時刻はすべて RFC3339 形式（2026-03-07T09:00:00Z）を使用します。VictoriaLogs は Unix タイムスタンプをサポートしていません。

レスポンスの解析（jq）

# Collect JSON Lines into array
... | jq -s .

# Extract message and timestamp from query results
... | jq -s '.[] | {time: ._time, msg: ._msg}'

# Count results from JSON Lines
... | jq -s 'length'

# Extract specific fields
... | jq -s '.[] | {time: ._time, level: .level, msg: ._msg}'

# Stats query — extract metric values
... | jq '.data.result[] | {metric: .metric, value: .value[1]}'

# Stats range query — extract time series
... | jq '.data.result[] | {metric: .metric, values: .values}'

# Facets — list fields and top values
... | jq '.[] | {field: .name, values: [.values[] | .value]}'

よく使うパターン

# Quick error check for a namespace (last hour)
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  --data-urlencode 'query={namespace="myapp"} error' \
  "$VM_LOGS_URL/select/logsql/query?start=$(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)&limit=20"

# Error rate over time
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  --data-urlencode 'query={namespace="myapp"} error | stats count() as errors' \
  "$VM_LOGS_URL/select/logsql/stats_query_range?start=2026-03-07T00:00:00Z&step=1h" | jq .

# Discover all namespaces with logs
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  --data-urlencode 'query=*' \
  "$VM_LOGS_URL/select/logsql/stream_field_values?start=2026-03-07T00:00:00Z&field=namespace" | jq .

# Search by trace ID in logs
curl -q --config "${VM_CURL_CONFIG:-/dev/null}" -s \
  --data-urlencode 'query=trace_id:"abc123def456"' \
  "$VM_LOGS_URL/select/logsql/query?start=2026-03-07T00:00:00Z&limit=50"

環境の切り替え

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

重要な注意事項

• 特殊文字を含むクエリには POST が推奨されます。URL エンコードの問題を避けるため、--data-urlencode を使用してください。
• すべてのエンドポイントは、application/x-www-form-urlencoded を使った GET と POST の両方を受け付けます。
• field_values と stream_field_values エンドポイントでは、field パラメーターが必須です。
• facets は単一呼び出しでの検出に最適なツールで、すべてのフィールドの分布を一度に返します。
• stats_query（インスタント、time を使用）と stats_query_range（範囲、start／end／step を使用）を混同しないでください。
• エンドポイントの詳細、パラメーター、レスポンス形式については、references/api-reference.md を参照してください。