agentleFS
letsrevelletsrevel/revel-backend/.claude/skills/loki-logs/SKILL.md

loki-logs

Skill119 starsChanged 3 months agoMITView on GitHub

Use when investigating production behaviour from logs — a 500/error in prod, a failing or stuck Celery task, tracing one request/trace_id/user across services, or confirming a deploy's runtime effect. Pulls real Loki logs from the live stack (web, celery_default, beat, telegram) via Grafana.

  • Reads credentials

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 1 is distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Default window is the last 1h, newest first, 100 lines.

    line 20
  2. Very specific:

    Use the venv interpreter — the script imports python-decouple.

    line 21
  3. Very specific:

    If it errors with "GRAFANA_TOKEN is not set", it isn't configured yet — tell the user.

    line 24
  4. Very specific:

    Start broad: web --level error --since <window> to find the failure.

    line 66
  5. Very specific:

    Use --print-query to inspect/borrow the LogQL.

    line 70
  6. Distinctive:

    Read-only. The token is Viewer-scoped.

    line 81

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Loki Logs

Query the production logs from Loki, the live log store. Loki itself is not publicly reachable; the script asks Grafana (grafana.letsrevel.io) to proxy LogQL to its Loki datasource using a service-account token.

Tool

.venv/bin/python scripts/loki_logs.py [SERVICE] [filters] [--since DUR] [-n LIMIT]

SERVICE is one of web, celery_default, beat, telegram (omit to search all). Default window is the last 1h, newest first, 100 lines. Run --help for the full flag list. Use the venv interpreter — the script imports python-decouple.

Auth: reads GRAFANA_TOKEN via decouple (from the project .env or the environment). If it errors with "GRAFANA_TOKEN is not set", it isn't configured yet — tell the user; do not guess.

What you can filter on

KindFlagsLogQL
Stream labelsSERVICE, --level error (repeatable), --env productionindexed, cheap
Line content--grep TEXT, --exclude TEXT, --regex RE (all repeatable)substring / regex
Request metadata--trace-id, --request-id, --user-id, --method, --path, --status-code, --ip, --user-agentstructlog fields
Raw escape hatch--query '{service_name="web"} | status_code="500"'any LogQL

Logs are structlog JSON; the displayed line is the event message, with a metadata line beneath it (suppress with --no-meta, get raw JSON with --json).

Recipes

# Errors in the API in the last hour
.venv/bin/python scripts/loki_logs.py web --level error

# Follow one request end-to-end across every service
.venv/bin/python scripts/loki_logs.py --request-id <uuid> --since 6h --forward

# Celery failures mentioning a traceback, last day
.venv/bin/python scripts/loki_logs.py celery_default --since 1d --grep Traceback

# All 5xx responses, last 2h
.venv/bin/python scripts/loki_logs.py web --status-code 500 --since 2h

# Everything a user triggered
.venv/bin/python scripts/loki_logs.py --user-id <uuid> --since 12h

# Everything from one client IP (e.g. chasing a scraper/429 burst)
.venv/bin/python scripts/loki_logs.py web --ip <ip> --since 6h

# Discover what labels/values exist
.venv/bin/python scripts/loki_logs.py --labels
.venv/bin/python scripts/loki_logs.py --label-values service_name

Workflow when debugging from a symptom

  1. Start broad: web --level error --since <window> to find the failure.
  2. Grab the trace_id/request_id from the metadata line.
  3. Re-query by that id with --forward to read the full request in order, spanning web → celery_default if work was dispatched.
  4. Use --print-query to inspect/borrow the LogQL; use --json when you need exact timestamps or fields the pretty output omits.

Notes

  • Retention is 30 days; queries older than that return nothing.
  • A query needs at least one matcher — with no SERVICE/--level the script defaults to {service_name=~".+"} (all app streams).
  • Hitting --limit prints a stderr hint; narrow --since or raise -n.
  • --ip/--user-agent only match lines ingested after the Alloy config that promotes ip_address/user_agent; older lines won't match those filters.
  • Read-only. The token is Viewer-scoped; this cannot modify anything.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.