Help us improve
Share bugs, ideas, or general feedback.
From project-toolkit
Queries and analyzes JSONL agent event logs to debug behavior, find slow tool calls, trace decisions, and summarize session performance.
npx claudepluginhub rjmurillo/ai-agents --plugin project-toolkitHow this skill is triggered — by the user, by Claude, or both
Slash command
/project-toolkit:observabilityclaude-haiku-4-5The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Query structured JSONL event logs to understand agent behavior, debug failures, and analyze performance.
Queries and analyzes JSONL agent event logs to debug behavior, find slow tool calls, trace decisions, and evaluate session performance.
Investigates AI agent sessions and failure patterns using Amplitude Agent Analytics. Traces root causes of failures, quality issues, and tool errors with session-level data.
Inspects and queries Claude Code hook event logs from .claude/logs JSONL files. Subcommands list sessions, timelines, tool traces, agent lifecycles, team activity, stats, coverage, and daily summaries.
Share bugs, ideas, or general feedback.
Query structured JSONL event logs to understand agent behavior, debug failures, and analyze performance.
| Trigger Phrase | Operation |
|---|---|
query agent logs | Run query_logs.py with filters |
find slow tool calls | Run with --slow threshold |
show agent errors | Run with --errors-only |
summarize session performance | Run with --output summary-sessions |
analyze tool usage | Run with --output summary-tools |
Use this skill when:
Use direct log file inspection instead when:
Logs use JSONL format (one JSON object per line). See schema.json for the full JSON Schema.
| Type | Purpose | Key Fields |
|---|---|---|
| session_start | Agent invocation begins | agent, session_id |
| session_end | Agent invocation completes | agent, session_id |
| tool_call | Tool invocation with timing | tool.name, tool.duration_ms, tool.success |
| decision | Reasoning captured alongside action | decision.action, decision.reasoning |
| metric | Numeric measurement | metric.name, metric.value, metric.unit |
| error | Error occurrence | error.message, error.category, error.recoverable |
{"timestamp":"2026-03-30T10:00:00Z","event_type":"session_start","session_id":"sess-001","agent":"implementer","message":"Session started"}
{"timestamp":"2026-03-30T10:00:01Z","event_type":"tool_call","session_id":"sess-001","agent":"implementer","level":"INFO","tool":{"name":"Read","duration_ms":45,"success":true,"input_summary":"src/main.py"},"message":"Read source file"}
{"timestamp":"2026-03-30T10:00:02Z","event_type":"decision","session_id":"sess-001","agent":"implementer","level":"INFO","decision":{"action":"Edit existing function","reasoning":"Function exists, modifying is safer than rewriting","alternatives_considered":["Rewrite from scratch","Create wrapper"]}}
{"timestamp":"2026-03-30T10:00:10Z","event_type":"error","session_id":"sess-001","agent":"implementer","level":"ERROR","error":{"message":"Test failed: assertion error in test_parse","category":"test_failure","recoverable":true}}
Agent event logs are stored at:
.agents/
logs/
{session-id}.jsonl # Per-session event log
| Avoid | Why | Instead |
|---|---|---|
| Reading raw JSONL manually for large logs | Slow, error-prone | Use query_logs.py with filters |
| Ignoring decision events | Loses the "why" behind agent actions | Filter by --event-type decision |
| Checking only errors | Misses slow degradation patterns | Use --slow to find latency issues |
| Analyzing without session context | Events lack meaning without grouping | Use --output summary-sessions |
| Script | Platform | Usage |
|---|---|---|
scripts/query_logs.py | Python 3.8+ | Cross-platform |
# Show all events in a session log
python .claude/skills/observability/scripts/query_logs.py .agents/logs/sess-001.jsonl
# Find errors only
python .claude/skills/observability/scripts/query_logs.py .agents/logs/sess-001.jsonl --errors-only
# Find tool calls slower than 500ms
python .claude/skills/observability/scripts/query_logs.py .agents/logs/sess-001.jsonl --slow 500
# Filter by agent
python .claude/skills/observability/scripts/query_logs.py .agents/logs/sess-001.jsonl --agent implementer
# Session summary as JSON
python .claude/skills/observability/scripts/query_logs.py .agents/logs/sess-001.jsonl --output summary-sessions
# Tool usage summary
python .claude/skills/observability/scripts/query_logs.py .agents/logs/sess-001.jsonl --output summary-tools
# Filter by time range
python .claude/skills/observability/scripts/query_logs.py .agents/logs/sess-001.jsonl \
--since 2026-03-30T10:00:00Z --until 2026-03-30T11:00:00Z
# JSON output for automation
python .claude/skills/observability/scripts/query_logs.py .agents/logs/sess-001.jsonl \
--output json --event-type tool_call
After execution:
Domain knowledge for observability analysis:
| File | Content |
|---|---|
| three-pillars-reference.md | Logs, metrics, traces definitions, correlation matrix, OpenTelemetry |
| prometheus-recording-rules.md | Recording rule patterns, CPU throttling, disk I/O, PSI, TCP metrics |
| otel-migration-reference.md | IFx to OTel migration phases, instrumentation best practices, standard metrics |