observability
/observability
Use when you say `query agent logs`, `find slow tool calls`, `show agent errors`, or `what to log`. Query and analyze agent JSONL event logs for debugging, performance analysis, and decision tracing.
- Author
- rjmurillo ↗
- Repository
- ai-agents ↗
- Licence
- MIT
- Last repository change
- 25.10.2026
Assessment and security
- Files in this package
- 10
- Scripts
- 2
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 2 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/check_event_logging.py, scripts/query_logs.py
What it does and when to use it
Use when you say `query agent logs`, `find slow tool calls`, `show agent errors`, or `what to log`. Query and analyze agent JSONL event logs for debugging, performance analysis, and decision tracing.
Original author description
Use when you say `query agent logs`, `find slow tool calls`, `show agent errors`, or `what to log`. Query and analyze agent JSONL event logs for debugging, performance analysis, and decision tracing.
How it works
- Triggers
- When to Use
- Event Schema
- Log File Location
- Process
- Anti-Patterns
- Scripts
- Quick Start
- Verification
- References
SKILL.md preview
---
name: observability
version: 1.0.0
description: Use when you say `query agent logs`, `find slow tool calls`, `show agent errors`, or `what to log`. Query and analyze agent JSONL event logs for debugging, performance analysis, and decision tracing.
license: MIT
---
# Agent Observability Skill
Query structured JSONL event logs to understand agent behavior, debug failures, and analyze performance.
## Triggers
| 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 |
## When to Use
Use this skill when:
- Debugging why an agent chose a particular tool or approach
- Finding slow tool calls that degrade agent performance
- Analyzing error patterns across agent sessions
- Comparing tool usage across sessions or agents
- Tracing decisions from orchestrator through sub-agents
- Deciding which operational events new code must emit, and which it must leave out (read the event-logging contract below)
Use direct log file inspection instead when:
- Checking a single known event in a small log
- The log file has fewer than 10 events
## Event Schema
Logs use JSONL format (one JSON object per line). See `schema.json` for the full JSON Schema.
### Event Types
| 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 |
### Example Events
```jsonl
{"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}}
```
## Log File Location
Agent event logs are stored at:
```text
.agents/
logs/
{session-id}.jsonl # Per-session event log
```
## Process
1. Identify the log file to query (by session ID or date)
2. Run query_logs.py with appropriate filters
3. Review output for patterns, errors, or performance issues
4. Use summary modes for high-level analysis across many events
## Anti-Patterns
| 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 |
## Scripts
| Script | Platform | Usage |
|--------|----------|-------|
| `scripts/query_logs.py` | Python 3.8+ | Cross-platform |
| `check_event_logging.py` | Python 3.8+ | Check a scenario against the event-logging contract |
| Exit Code | Meaning |
|-----------|---------|
| 0 | Query completed and results output (query) or scenario compliant (check) |
| 1 | File not found or invalid arguments (query) or scenario non-compliant (check) |
| 2 | Invalid JSONL format (query) or malformed scenario (check) |
## Quick Start
```bash
# Show all events in a session log
python .claude/skills/observability/scripts/query_logs.py .project-toolkit/logs/sess-001.jsonl
# Check an emission scenario against the event-logging contract
python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/observability/scripts/check_event_logging.py" scenario.json
# Find errors only
python .claude/skills/observability/scripts/query_logs.py .project-toolkit/logs/sess-001.jsonl --errors-only
# Find tool calls slower than 500ms
python .claude/skills/observability/scripts/query_logs.py .project-toolkit/logs/sess-001.jsonl --slow 500
# Filter by agent
python .claude/skills/observability/scripts/query_logs.py .project-toolkit/logs/sess-001.jsonl --agent implementer
# Session summary as JSON
python .claude/skills/observability/scripts/query_logs.py .project-toolkit/logs/sess-001.jsonl --output summary-sessions
# Tool usage summary
python .claude/skills/observability/scripts/query_logs.py .project-toolkit/logs/sess-001.jsonl --output summary-tools
# Filter by time range
python .claude/skills/observability/scripts/query_logs.py .project-toolkit/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 .project-toolkit/logs/sess-001.jsonl \
--output json --event-type tool_call
```
## Verification
After execution:
- [ ] Script exits with code 0
- [ ] Output format matches requested mode (table, json, summary-sessions, summary-tools)
- [ ] Filters reduce event count as expected
- [ ] Session summaries include all sessions present in the log
## References
Domain knowledge for observability analysis:
| File | Content |
|------|---------|
| [event-logging-contract.md](references/event-logging-contract.md) | Canonical contract for which operational events code emits and omits: decision test, MUST and MUST NOT tables, log vs metric vs trace, worked example |
| [three-pillars-reference.md](references/three-pillars-reference.md) | Logs, metrics, traces definitions, correlation matrix, OpenTelemetry |
| [prometheus-recording-rules.md](references/prometheus-recording-rules.md) | Recording rule patterns, CPU throttling, disk I/O, PSI, TCP metrics |
| [otel-migration-reference.md](references/otel-migration-reference.md) | IFx to OTel migration phases, instrumentation best practices, standard metrics |
## Related Documents
- [Event Schema](schema.json)
- [Agent Metrics Skill](../metrics/SKILL.md)
- [Issue #1301](https://github.com/rjmurillo/ai-agents/issues/1301)
Files in this package (10)
- SKILL.md 7 KB
- schema.json 3 KB
- references/distributed-systems-fallacies.md 4 KB
- references/event-logging-contract.md 7 KB
- references/otel-migration-reference.md 4 KB
- references/otel-semantic-conventions.md 3 KB
- references/prometheus-recording-rules.md 3 KB
- references/three-pillars-reference.md 3 KB
- scripts/check_event_logging.py 7 KB
- scripts/query_logs.py 9 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · rjmurillo/ai-agents | 100 | MIT |
| maragudk/fabrik | 100 | MIT |
| matteocodogno/wellforge | 100 | MIT |
| iuliandita/skills | 100 | MIT |
| ctxpipe-ai/ctxpipe | 100 | MIT |
| rjmurillo/ai-agents | 100 | MIT |
| wrongstack/wrongstack | 100 | MIT |
| nvidia/ai-factory-operations-agent | 100 | Apache-2.0 |
| nimadorostkar/Claude-Skills-collection | 100 | MIT |
Identical content appears in 4 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version bcf61593c4c8 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 1 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100agent-host-logs
Analyze Agent Host debug log exports. Use when given an ah-logs or ahp-logs zip/folder, an Export Agent Host Debug Logs bundle, events.jsonl, AHP JSONL transport logs, Agent Host.log, remote-agenthost.log, or copilot-logs. - 100analyzing-cc-sessions
Use when analyzing Claude Code raw session logs, parsing JSONL transcripts, investigating agent behavior, extracting metrics from session data, debugging subagent dispatches, or building session analysis tools. Triggers on session IDs, JSONL paths, ~/.claude/projects references,… - 90review-agent-observability
Reviews agent projects for tracing, metrics, structured logging and trace propagation. Use for "review agent observability" or "audit agent tracing". - 100troubleshoot
Investigate unexpected chat agent behavior by analyzing direct debug logs in JSONL files. Use when users ask why something happened, why a request was slow, why tools or subagents were used or skipped, or why instructions/skills/agents did not load. - 100troubleshoot
Investigate unexpected chat agent behavior by analyzing direct debug logs in JSONL files. Use when users ask why something happened, why a request was slow, why tools or subagents were used or skipped, or why instructions/skills/agents did not load. - 100analyze-chat-session
Analyze the current conversation's tool calls, responses, errors, and approach to produce a structured feedback report for improving MCP tool usage with ARC-1. Use when the user asks to "analyze this session", "review my chat", "give feedback on tool usage", "how did I do", or…