loki-troubleshoot

"帮助构建高效的Grafana Loki/LogQL查询来调试日志 — 使用基于标签的过滤、窄时间窗口和最佳实践指导,避免昂贵或过于广泛的扫描。"

📖 中文导读:"帮助构建高效的Grafana Loki/LogQL查询来调试日志 — 使用基于标签的过滤、窄时间窗口和最佳实践指导,避免昂贵或过于广泛的扫描。" 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: loki-troubleshoot description: "Help craft efficient Grafana Loki / LogQL queries for debugging logs — with label‑based filtering, narrow time windows, and best‑practice guidance to avoid expensive or overly broad scans."

Loki Troubleshooting & Query‑Builder Skill

What this Skill does

When a user asks you (Claude) for help inspecting logs via Loki — e.g. “find errors in service X”, “search for request_id=abc123”, “show me 500 responses between 2‑3 PM last night” — use this skill to:

  • Ask clarifying questions if needed (e.g. which service / label context, approx time window, any known label names).
  • Build a recommended LogQL query that:
    • uses low‑cardinality labels (service, env, host, etc.) whenever possible
    • confines to a narrow time window (minutes — hours, not days) by default
    • uses fast filters (|= or |!=) rather than regex or heavy parsing
    • performs JSON/structured parsing only after filtering
  • Provide human-readable explanations and warnings for expensive queries
  • Suggest alternative strategies (metrics, recording rules, structured logs)

Best Practices

  • Prefer stable labels (app, env, namespace, cluster, etc.)
  • Avoid high-cardinality labels (user_id, request_id, UUIDs)
  • Always restrict the time window
  • Use |= before regex or parsing
  • Provide warnings for:
    • No label selector
    • Very wide time windows
    • JSON parse without pre-filter
    • Regex-heavy queries

Example Queries

User Request Resulting LogQL
"Show me all 500 errors in the orders service in the last 2 hours." {app="orders", env="prod"}[2h] |= "500"
"Find logs for request_id abc123 in staging for payments service over past 30 minutes." {app="payments", env="staging"}[30m] |= "abc123"

Limitations

  • This skill does not execute queries