Skip to content
Skills Library
AI & agents · Analysis

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.

Repository
ai-agents ↗
Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
10
Scripts
2
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 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

  1. Triggers
  2. When to Use
  3. Event Schema
  4. Log File Location
  5. Process
  6. Anti-Patterns
  7. Scripts
  8. Quick Start
  9. Verification
  10. References
Original SKILL.md headings · 153 lines, 750 words
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

RepositoryScoreLicence
This page · rjmurillo/ai-agents100MIT
maragudk/fabrik100MIT
matteocodogno/wellforge100MIT
iuliandita/skills100MIT
ctxpipe-ai/ctxpipe100MIT
rjmurillo/ai-agents100MIT
wrongstack/wrongstack100MIT
nvidia/ai-factory-operations-agent100Apache-2.0
nimadorostkar/Claude-Skills-collection100MIT

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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.