---

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