log-debug
Skill24 starsChanged yesterdayMITView on GitHub
Investigate a running GoFastr app by querying its log MCP tools. Use when the user asks "why is /path slow", "what's the last error", "check the access logs", "is logging healthy", "what just happened on the server", or any debug-the-running-server question where the app exposes /mcp.
In this repository16 other files it gives its agents.
- AGENTS.mdAGENTS.md
- framework/agents.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- adversarial-testsSkill
- app-introspectSkill
- chaos-testSkill
- component-buildSkill
- eval-reportSkill
- gofastr-docsSkill
- gofastr-hostSkill
- gofastr-mcp-debugSkill
- gofastr-uiSkill
- plain-wordsSkill
- primitives-sweepSkill
- review-gateSkill
- twin-sweepSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 45
Use the Bash tool to curl the MCP endpoint with a JSON-RPC payload.
- Very specific: line 66
Use since_ts with an RFC3339 timestamp:
- Distinctive: line 100
If the agent needs verbose output for an investigation:
- Distinctive: line 125
Before trusting the log queries, check the counters are zero:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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.
Files
Debug a live GoFastr app via the log MCP tools
The battery/log plugin registers JSON-RPC tools on the App's MCP
server: three read-only (log_recent, log_filter, log_metrics)
unconditionally, plus log_set_level only when
log.Config.AllowMCPMutation is true. Use these to investigate a
running app: agent live-debugging, not log greps from the user.
Prerequisites
The user's app must be:
- Running with the
battery/logplugin registered (generated apps andexamples/siteboth do). - In the dev loop (
gofastr devsetsGOFASTR_DEV, which auto-enables the tools + the/mcpmount; opt-outGOFASTR_DEV_MCP=0); OR built withlog.Config{EnableMCP: true}and an/mcpmount (framework.WithMCP()) for non-dev processes.
Quickest way to spin up a known-good target in this repo:
./scripts/dev-watch.sh # examples/site on :8082, auto-rebuilds; tools auto-enable
# or
GOFASTR_DEV=1 go run ./examples/site # :8083; plain go-run without the env has NO log toolsThen curl http://localhost:8082/mcp (or whatever port your app uses).
The tools (three read-only, plus optional log_set_level)
| Tool | Use |
log_recent | Last N entries in chrono order. Optional limit (default 50) + level filter. |
log_filter | Match by msg/path/request_id/since_ts/until_ts/level. historical=true tails the file sink for entries evicted from the ring. |
log_metrics | Counter snapshot: post_stop_drops, sink_write_failures, webhook_dropped, webhook_gave_up. |
log_set_level | Flip the runtime log level (DEBUG/INFO/WARN/ERROR). Returns the previous value. Only registered when log.Config.AllowMCPMutation is true. |
How to invoke
Use the Bash tool to curl the MCP endpoint with a JSON-RPC payload.
The MCP URL is http://localhost:<PORT>/mcp (ask the user if you
don't know the port; common defaults are 8082 (dev-watch) / 8083
(plain go run ./examples/site); prefer the URL the launch output prints).
Last 5 access entries
curl -s http://localhost:8082/mcp \
-X POST -H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"log_recent","arguments":{"limit":5,"level":"INFO"}}}' \
| jq -r '.result.content[0].text' | jq .The double jq is intentional: MCP wraps the tool result in
content[0].text as a JSON-encoded string, so we parse that text
back into structured JSON for readability.
All errors in the last 5 minutes
Use since_ts with an RFC3339 timestamp:
# GNU date (Linux containers): use this form first.
SINCE=$(date -u -d '5 minutes ago' +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
|| date -u -v-5M +%Y-%m-%dT%H:%M:%SZ) # macOS fallback
curl -s http://localhost:8082/mcp \
-X POST -H 'Content-Type: application/json' \
-d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",
\"params\":{\"name\":\"log_filter\",
\"arguments\":{\"level\":\"ERROR\",\"since_ts\":\"$SINCE\",\"limit\":50}}}" \
| jq -r '.result.content[0].text' | jq .Trace a specific request by ID
The framework's middleware.RequestID stamps every request with
X-Request-ID. Pull it from the user's curl response (or browser
network panel), then:
curl -s http://localhost:8082/mcp \
-X POST -H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"log_filter",
"arguments":{"request_id":"<paste-id-here>","historical":true}}}' \
| jq -r '.result.content[0].text' | jq .historical=true extends the search into the file sink so you can
trace IDs older than the ring buffer's window (default 1000 entries).
Temporarily switch to DEBUG
If the agent needs verbose output for an investigation:
# Flip to DEBUG. The response returns {.level:"DEBUG", .previous_level:"<X>"}
# save previous_level so you can restore what was actually there.
RESP=$(curl -s http://localhost:8082/mcp \
-X POST -H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"log_set_level","arguments":{"level":"DEBUG"}}}')
echo "$RESP" | jq -r '.result.content[0].text' | jq .
PREV=$(echo "$RESP" | jq -r '.result.content[0].text' | jq -r '.previous_level')
# ...reproduce the bug, then call log_recent / log_filter...
# Restore the captured level (always restore; leaving DEBUG on in prod is rude;
# the starting level comes from log.Config.Level, NOT guaranteed INFO)
curl -s http://localhost:8082/mcp \
-X POST -H 'Content-Type: application/json' \
-d "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",
\"params\":{\"name\":\"log_set_level\",\"arguments\":{\"level\":\"$PREV\"}}}" \
| jq -r '.result.content[0].text' | jq .Health of the logging system
Before trusting the log queries, check the counters are zero:
curl -s http://localhost:8082/mcp \
-X POST -H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"log_metrics","arguments":{}}}' \
| jq -r '.result.content[0].text' | jq .Non-zero sink_write_failures or post_stop_drops means the
plugin lost entries; anything queried might be incomplete.
Anti-patterns
- Don't reach for the file directly. The ring buffer is faster
and structured; only fall through to file (via
historical=true) when the ring window's been exhausted. - Don't leave DEBUG on after an investigation. Other observers
see the firehose. Restore the
previous_levelthe DEBUG call returned, not a hard-coded INFO (the app may start at WARN/ERROR). - Don't treat
remoteas authoritative. Unless the app setConfig.TrustForwardedFor,remoteis justr.RemoteAddr;forwarded_foris the raw client header, attacker-controlled. - Don't filter for what isn't structured. The plugin's
http.accessentries carrymethod/path/status/bytes/dur_ms/request_id/remote/forwarded_for. Anything else is a substring search viamsgor post-filtering in your head.
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
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.

