name: victorialogs-analysis description: 使用 LogsQL 进行 VictoriaLogs 日志分析。适用于查询存储在 VictoriaLogs 中的日志。提供统计优先的调查，支持服务器端聚合。 allowed-tools: Bash(python *)

VictoriaLogs 日志分析

查询和分析 VictoriaLogs 中的日志，用于事故调查和调试。

认证

重要：凭证通过代理层自动注入。不要在环境变量中检查 VICTORIALOGS_TOKEN - 它们对您不可见。直接运行脚本即可；认证是透明的。

强制：统计优先调查

切勿转储原始日志。 始终遵循以下模式：

统计 → 字段 → 样本 → 查询

统计优先 — 在查看日志前了解数量、错误率、顶级流
字段发现 — 了解存在哪些字段（帮助构建针对性查询）
策略性采样 — 仅查看代表性错误（最多 20 条）
针对性查询 — 仅在需要时，始终使用 | stats 或 | limit

可用脚本

所有脚本位于 .claude/skills/observability-victorialogs/scripts/

主要调查脚本

get_statistics.py — 始终从这里开始

使用服务器端 LogsQL 聚合的综合统计。

python .claude/skills/observability-victorialogs/scripts/get_statistics.py
python .claude/skills/observability-victorialogs/scripts/get_statistics.py --query '_stream:{app="api"}'
python .claude/skills/observability-victorialogs/scripts/get_statistics.py --time-range 120 --json

输出包括：

总计数、错误计数、错误率百分比
每分钟日志数
按量级前 10 的流
顶级错误模式（标准化和去重）
可操作建议

sample_logs.py — 策略性采样

根据统计选择合适的采样策略。

python .claude/skills/observability-victorialogs/scripts/sample_logs.py --strategy errors_only
python .claude/skills/observability-victorialogs/scripts/sample_logs.py --query '_stream:{app="api"}' --strategy errors_only
python .claude/skills/observability-victorialogs/scripts/sample_logs.py --strategy around_time --timestamp "2026-01-27T05:00:00Z" --window 5
python .claude/skills/observability-victorialogs/scripts/sample_logs.py --strategy all --limit 20

策略：

errors_only — 仅错误/异常/失败日志（默认）
warnings_up — 警告和错误日志
around_time — 围绕特定时间戳的日志
all — 所有日志级别

list_fields.py — 元数据发现

在构建查询前发现可用字段。

python .claude/skills/observability-victorialogs/scripts/list_fields.py
python .claude/skills/observability-victorialogs/scripts/list_fields.py --query '_stream:{app="api"}'
python .claude/skills/observability-victorialogs/scripts/list_fields.py --field level
python .claude/skills/observability-victorialogs/scripts/list_fields.py --field service --limit 20 --json

query_logs.py — 原始 LogsQL（紧急出口）

执行原始 LogsQL 查询。如果缺少安全限制，自动附加。

python .claude/skills/observability-victorialogs/scripts/query_logs.py --query 'error | stats by (service) count() hits | sort by (hits) desc'
python .claude/skills/observability-victorialogs/scripts/query_logs.py --query '_stream:{app="api"} AND timeout' --limit 10
python .claude/skills/observability-victorialogs/scripts/query_logs.py --query 'status:>=500 | stats count() total' --json

LogsQL 快速参考

过滤器（选择哪些日志）

# 单词搜索（默认搜索 _msg 字段）
error
"connection timeout"

# 字段特定匹配
level:error
service:payment
status:500

# 流选择器（高效 — 使用索引流标签）
_stream:{app="api"}
_stream:{app="api", namespace="production"}

# 否定
NOT error
NOT level:debug

# 逻辑运算符
error AND timeout
error OR exception OR fatal

# 数值比较
status:>=500
duration:>1000

# 正则表达式
_msg:~"timeout.*connection"
service:~"payment-.*"

管道（后处理）

# 限制结果（始终使用此或 | stats）
error | limit 20

# 选择特定字段
error | fields _time, _msg, service, level

# 排序
error | sort by (_time) desc

# 去重
error | uniq by (service, _msg)

# 统计（服务器端聚合 — 上下文最有效）
error | stats count() total
error | stats by (service) count() hits | sort by (hits) desc | limit 10
* | stats by (level) count() hits

# 可用统计函数：
#   count(), sum(field), avg(field), min(field), max(field),
#   count_uniq(field), uniq_values(field)

常见模式

# 按服务计数错误
error OR exception | stats by (service) count() errors | sort by (errors) desc

# 查找唯一错误消息
error | stats by (_msg) count() hits | sort by (hits) desc | limit 10

# 在特定时间窗口中的错误（在脚本中使用 --start/--end）
_stream:{app="api"} AND error | limit 20

# HTTP 5xx 错误
status:>=500 | stats by (path) count() hits | sort by (hits) desc

# 慢请求
duration:>1000 | stats by (service) count() slow | sort by (slow) desc

调查工作流

标准事故调查

┌───────────────────────────────────────────────────┐
│ 1. 统计优先（强制）                               │
│    python get_statistics.py                       │
│    → 了解数量、错误率、顶级流                     │
└───────────────────────────────────────────────────┘
                            │
                            ▼
                    高错误率？
           ┌─────────────┴─────────────┐
           │                           │
   YES (>5%)                           NO
           │                           │
           ▼                           ▼
┌───────────────────────┐  ┌────────────────────────┐
│ 2. 快速路径           │  │ 2. 发现字段            │
│    sample_logs.py     │  │    list_fields.py      │
│    --strategy         │  │    → 理解架构          │
│    errors_only        │  │    → 构建针对性        │
│                       │  │      查询              │
└───────────────────────┘  └────────────────────────┘

快速命令参考

目标	命令
开始调查	`get_statistics.py`
发现字段	`list_fields.py --query '_stream:{app="X"}'`
采样错误	`sample_logs.py --strategy errors_only`
调查峰值	`sample_logs.py --strategy around_time --timestamp T`
按服务计数	`query_logs.py --query 'error \| stats by (service) count() hits'`

要避免的反模式

切勿运行不带 | limit 或 | stats 的裸查询 — 脚本作为安全网自动附加限制，但编写高效查询
切勿跳过 get_statistics.py — 这是强制的第一步
切勿获取所有日志 — 使用采样策略和聚合
切勿忽略错误率 — 高错误率意味着调查模式，而非转储日志
切勿查询不带时间边界 — 始终指定 --time-range 或使用默认值