Agent skill
loki-troubleshoot
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.
Install this agent skill to your Project
npx add-skill https://github.com/timbuchinger/loadout/tree/main/skills/loki-troubleshoot
SKILL.md
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
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
timbuchinger/loadout
brainstorming
Use when creating or developing, before writing code or implementation plans - refines rough ideas into fully-formed designs through collaborative questioning, alternative exploration, and incremental validation. Don't use during clear 'mechanical' processes
timbuchinger/loadout
add-note
Use this skill whenever important information is learned during a task or when the user explicitly asks to store something. Use when users ask to remember. Triggers on "remember this", "update memory", "share" or any persistent storage request.
timbuchinger/loadout
user-story
Creates well-structured user stories for software development and project management. Use when the user asks to write, create, or format a user story, or needs to document requirements, features, or tasks in user story format.
timbuchinger/loadout
test-driven-development
Use when implementing any feature or bugfix, before writing implementation code - write the test first, watch it fail, write minimal code to pass; ensures tests actually verify behavior by requiring failure first
timbuchinger/loadout
kubernetes-troubleshoot
Troubleshoot and manage Kubernetes clusters, including resource inspection, debugging, pod logs, events, and cluster operations. Use when the user needs to diagnose issues, inspect workloads, analyze pod failures, or perform Kubernetes cluster operations.
timbuchinger/loadout
writing-plans
Use when design is complete and you need detailed implementation tasks - creates comprehensive implementation plans with exact file paths, complete code examples, and verification steps assuming minimal codebase familiarity
Didn't find tool you were looking for?