From copilot-cli-toolkit
Queries and analyzes JSONL agent event logs to debug behavior, find slow tool calls, trace decisions, and evaluate session performance.
npx claudepluginhub rjmurillo/ai-agentsThis skill uses the workspace's default tool permissions.
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 summarize session performance.
Investigates AI agent sessions and failure patterns using Amplitude Agent Analytics to root-cause issues like tool errors, low quality, or failures from session IDs.
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 |