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，不发送身份验证标头。设置后，该变量必须指向权限为 0600、且包含 header = "Authorization: Bearer <token>" 的 curl 配置文件。切勿打印其内容。

关键规则

• 始终为所有 VictoriaLogs 端点传入 start——省略该参数会扫描所有已存储的数据（开销极大）。API 技术上并不要求此参数，但几乎没有理由省略它。
• stats_query 使用 time（始终显式传入；不要依赖默认值），stats_query_range 使用 start／end／step
• hits 端点必须传入 step
• /select/logsql/query 返回 JSON Lines（每行一个 JSON 对象），而不是 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（每行一个 JSON 对象）。通过 jq -s . 汇总为数组，或逐行处理。

统计查询（即时）

# 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。单次调用即可返回所有字段中出现频率最高的值。

发现端点

字段名称和值

# 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: 过滤器指定，不能同时使用两者。
• 流字段名称取决于数据写入配置。务必先发现字段。
• 搜索“error”时若不筛选 vmselect，vmselect 日志会包含 PromQL 文本中的“error”——添加 -"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——使用 --data-urlencode 避免 URL 编码问题
• 所有端点均支持使用 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