observability

Use when you say `query agent logs`, `find slow tool calls`, or `show agent errors`. Query and analyze agent JSONL event logs for debugging, performance analysis, and decision tracing.

Jump to install

Repository: rjmurillo/ai-agents
Last source activity: July 28, 2026 at 09:45
Detected SKILL.md language: English
Stars: 41
Forks: 13

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

A direct command skips the review prompt. Inspect the source before running it.

npx skills add https://github.com/rjmurillo/ai-agents --skill observability

The command stays on one line. Scroll horizontally to inspect it before copying.

Prefer a local copy? Download the files currently available to SkillsMP.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

File Explorer

9 files

SKILL.md

Source instructions · Read-only preview

Back to search Back to installation

spec

Define what to build. Transform a problem into testable requirements with acceptance criteria.

2026-08-09

session-end

Validate and complete session logs before commit. Auto-populates session end evidence (commit SHA, lint results, memory updates) and runs validation. Use when finishing a session, before committing, or when session validation fails. Do NOT use to create a new session log (use session-init) or to repair a session protocol failure reported by CI (use session-log-fixer).

2026-08-09

session-init

Create protocol-compliant JSON session logs with verification-based enforcement. Autonomous operation with auto-incremented session numbers and objective derivation from git state. Use when starting any new session. Use when you say "start a session", "create the session log". Do NOT use for mid-session protocol checks (use session), or to complete and validate a log at the end of a session (use session-end).

2026-08-09

View all from this repository

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}}

.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

# 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

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

name	observability
version	1.0.0
model	haiku
model-rationale	cost. The 'haiku' rolling alias resolves via the platform model_tiers map to a tier priced below the sonnet-tier harness default; this unit is routing/mechanical work where the cheaper tier suffices (ADR-080 rule 3).
description	Use when you say `query agent logs`, `find slow tool calls`, or `show agent errors`. Query and analyze agent JSONL event logs for debugging, performance analysis, and decision tracing.
license	MIT

Trigger Phrase	Operation
`query agent logs`	Run query_logs.py with filters
`find slow tool calls`	Run with --slow threshold

name	observability
version	1.0.0
model	haiku
model-rationale	cost. The 'haiku' rolling alias resolves via the platform model_tiers map to a tier priced below the sonnet-tier harness default; this unit is routing/mechanical work where the cheaper tier suffices (ADR-080 rule 3).
description	Use when you say `query agent logs`, `find slow tool calls`, or `show agent errors`. Query and analyze agent JSONL event logs for debugging, performance analysis, and decision tracing.
license	MIT

Trigger Phrase	Operation
`query agent logs`	Run query_logs.py with filters
`find slow tool calls`	Run with --slow threshold

Exit Code	Meaning
0	Query completed and results output
1	File not found or invalid arguments
2	Invalid JSONL format

observability

Install options

Review the source files

Agent Observability Skill

Triggers

Agent Observability Skill

Triggers

When to Use

Event Schema

Event Types

Example Events

Log File Location

Process

Anti-Patterns

Scripts

Quick Start

Verification

References

Related Documents

observability

Source facts

Install options

Review the source files

More from this repository

More from this repository

Agent Observability Skill

Triggers

Agent Observability Skill

Triggers

When to Use

Event Schema

Event Types

Example Events

Log File Location

Process

Anti-Patterns

Scripts

Quick Start

Verification

References

Related Documents