loki-log-query

name	loki-log-query
description	Query Grafana Loki, fetch raw JSON from the Loki HTTP API, extract trace IDs, follow trace-specific logs, and summarize results. Use when working with Loki, LogQL, query_range, service_namespace log searches, trace_id lookups, or incident/debug log collection. Requires Bash with python3.

Loki Log Query

Use this Skill when the user wants to fetch or inspect logs from Grafana Loki instead of building a separate app.

Default workflow

1. Determine the skill directory:
   • Use the directory that contains this SKILL.md.
   • Common locations:
     • Codex project: .agents/skills/loki-log-query
     • Codex global: ~/.codex/skills/loki-log-query
     • Claude Code project: .claude/skills/loki-log-query
     • Claude Code global: ~/.claude/skills/loki-log-query
     • Shared-harness project installs often use .agents/skills/loki-log-query
2. Read config/loki.env if it exists. If it does not, copy config/loki.env.example to config/loki.env and edit it.
3. Build a valid LogQL query.
   • Prefer stream labels in the selector, for example: {service_namespace="ncc"}
   • If trace_id is an indexed stream label, prefer {service_namespace="ncc", trace_id="..."}
   • If trace_id lives inside the log body, prefer a parser stage such as | json | trace_id="..."
   • For multi-term line searches, prefer regex filters such as |~ "(merchant|timeout|failed)" for broad compatibility.
4. Run the helper script to fetch raw JSON:
   • python3 <SKILL_DIR>/scripts/query_loki.py --query '...' --since 24h --output loki_raw.json --flatten-output loki_flat.jsonl
5. If the user wants trace IDs, run:
   • python3 <SKILL_DIR>/scripts/extract_trace_ids.py loki_raw.json
6. If the user wants per-trace follow-up logs, run:
   • python3 <SKILL_DIR>/scripts/follow_trace_ids.py --input loki_raw.json --selector-template '{service_namespace="ncc", trace_id="{trace_id}"}' --since 24h --output-dir trace_logs --flatten
7. Summarize what was fetched, including time range, selector/query, trace IDs found, and any obvious error patterns.

Notes

• Update config/loki.env when endpoints, auth, tenants, or headers change.
• Edit this SKILL.md only when you want to change the workflow or defaults.
• Keep raw JSON files when the user may want to re-query or audit the exact response.
• For concrete examples and common command patterns, see REFERENCE.md.