RomanNum3ral
/
claw-code
mirror of https://github.com/instructkr/claw-code.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
claw-code/.guardrails/docs/standards/LOGGING_PATTERNS.md

358 lines
7.8 KiB
Markdown
Raw Blame History

# Logging Patterns for Agents
> Array-based structured logging format.
**Related:** [LOGGING_INTEGRATION.md](./LOGGING_INTEGRATION.md) | [AGENT_GUARDRAILS.md](../AGENT_GUARDRAILS.md)
---
## Overview
This document establishes array-based structured logging patterns for AI agent operations. Consistent logging enables debugging, auditing, and integration with external systems.
---
## Array-Based Logging Pattern
### Core Concept
Logs are stored as an array of structured entries, enabling:
- Easy filtering and searching
- Machine-readable format
- Consistent structure across operations
- Simple export to external systems
```
LOG ARRAY STRUCTURE:
logs = [
{ entry1 },
{ entry2 },
{ entry3 },
...
]
```
### Standard Log Entry Structure
```json
{
"timestamp": "2026-01-14T15:30:00.000Z",
"level": "INFO",
"category": "file_operation",
"action": "read",
"target": "/path/to/file.py",
"result": "success",
"duration_ms": 45,
"metadata": {
"lines_read": 150,
"file_size": 4096
}
}
```
### Required Fields
| Field | Type | Description |
|-------|------|-------------|
| timestamp | ISO8601 string | When the action occurred |
| level | string | Log level (DEBUG, INFO, WARN, ERROR) |
| category | string | Category of operation |
| action | string | What was done |
| target | string | What was acted upon |
| result | string | success, failure, skipped |
### Optional Fields
| Field | Type | Description |
|-------|------|-------------|
| duration_ms | number | How long it took |
| metadata | object | Additional context |
| error | string | Error message if failed |
| stack_trace | string | Stack trace if error |
| agent_id | string | Which agent logged this |
---
## Log Levels
| Level | Code | Use For | Example |
|-------|------|---------|---------|
| DEBUG | 10 | Detailed diagnostics | "Reading line 45-50" |
| INFO | 20 | Normal operations | "File edited successfully" |
| WARN | 30 | Potential issues | "File larger than expected" |
| ERROR | 40 | Failures | "Edit failed: string not found" |
### Level Selection Guide
```
USE DEBUG:
- Internal decision points
- Variable values during processing
- Step-by-step progress
USE INFO:
- Operation start/complete
- Significant milestones
- User-relevant events
USE WARN:
- Unexpected but handled situations
- Deprecation notices
- Performance concerns
USE ERROR:
- Operation failures
- Unhandled exceptions
- Recovery needed
```
---
## Standard Log Categories
### File Operations Log
```json
{
"category": "file_operation",
"action": "read | write | edit | delete",
"target": "/path/to/file",
"metadata": {
"lines_affected": 10,
"old_content": "...",
"new_content": "..."
}
}
```
### Git Operations Log
```json
{
"category": "git_operation",
"action": "commit | push | pull | checkout | status",
"target": "branch_name or file",
"metadata": {
"commit_hash": "abc123",
"message": "commit message",
"files_changed": 3
}
}
```
### Validation Results Log
```json
{
"category": "validation",
"action": "syntax_check | test_run | lint",
"target": "/path/to/file",
"result": "pass | fail",
"metadata": {
"errors": [],
"warnings": [],
"test_count": 15,
"pass_count": 15
}
}
```
### Decision Points Log
```json
{
"category": "decision",
"action": "chose_path | skipped | escalated",
"target": "decision_context",
"metadata": {
"options_considered": ["A", "B", "C"],
"chosen": "A",
"reason": "Best fit for requirements"
}
}
```
---
## Log Array Management
### Initialization
```
At session start:
logs = []
```
### Appending Entries
```
For each operation:
logs.append({
"timestamp": current_time(),
"level": "INFO",
...
})
```
### Log Rotation/Limits
```
RECOMMENDED LIMITS:
- Max entries per session: 1000
- When limit reached: Archive oldest 500, keep recent 500
- On session end: Export full log
```
### Log Export
```json
{
"session_id": "unique-session-id",
"start_time": "2026-01-14T15:00:00Z",
"end_time": "2026-01-14T16:30:00Z",
"agent": "Claude Opus 4.5",
"task_summary": "Implemented feature X",
"log_count": 45,
"logs": [...]
}
```
---
## Log Output Formats
### Human-Readable Format
```
[2026-01-14 15:30:00] INFO [file_operation] read /path/to/file.py → success (45ms)
[2026-01-14 15:30:01] INFO [file_operation] edit /path/to/file.py → success (120ms)
[2026-01-14 15:30:02] INFO [validation] syntax_check /path/to/file.py → pass
[2026-01-14 15:30:03] ERROR [validation] test_run tests/test_file.py → fail
```
### Machine-Readable Format (JSON Lines)
```
{"timestamp":"2026-01-14T15:30:00Z","level":"INFO","category":"file_operation","action":"read","target":"/path/to/file.py","result":"success"}
{"timestamp":"2026-01-14T15:30:01Z","level":"INFO","category":"file_operation","action":"edit","target":"/path/to/file.py","result":"success"}
```
### Summary Format
```
SESSION SUMMARY
===============
Duration: 1h 30m
Operations: 45
- File operations: 20
- Git operations: 10
- Validations: 15
Results:
- Success: 43
- Warnings: 1
- Errors: 1
Files Modified:
- /path/to/file1.py
- /path/to/file2.py
```
---
## Integration with Sprints
### Sprint Execution Logging
```
For each sprint step:
1. Log step start (INFO)
2. Log each sub-operation (DEBUG/INFO)
3. Log validation results (INFO/ERROR)
4. Log step complete (INFO)
```
### Sprint Completion Reports
```json
{
"sprint_id": "SPRINT-2026-01-14",
"status": "COMPLETE",
"steps_completed": 5,
"files_modified": ["file1.py", "file2.py"],
"commits_created": 3,
"validation_results": {
"syntax_checks": "all_pass",
"tests": "15/15 pass"
},
"log_summary": {
"total_entries": 45,
"errors": 0,
"warnings": 1
}
}
```
---
## Anti-Patterns
### What NOT to Do
```
DON'T:
- Log sensitive data (passwords, tokens, PII)
- Log entire file contents (use summaries)
- Skip logging errors
- Use inconsistent formats
- Forget timestamps
- Log at wrong level (DEBUG spam or missing INFO)
DO:
- Sanitize sensitive data before logging
- Log operation summaries
- Always log errors with context
- Use consistent structure
- Always include timestamp
- Choose appropriate level
```
---
## Quick Reference
```
+------------------------------------------------------------------+
| LOGGING PATTERNS QUICK REFERENCE |
+------------------------------------------------------------------+
| ENTRY STRUCTURE: |
| { |
| "timestamp": "ISO8601", |
| "level": "DEBUG|INFO|WARN|ERROR", |
| "category": "file_operation|git_operation|validation|...", |
| "action": "what was done", |
| "target": "what was acted on", |
| "result": "success|failure" |
| } |
+------------------------------------------------------------------+
| LOG LEVELS: |
| DEBUG - Detailed diagnostics |
| INFO - Normal operations |
| WARN - Potential issues |
| ERROR - Failures |
+------------------------------------------------------------------+
| CATEGORIES: |
| file_operation, git_operation, validation, decision |
+------------------------------------------------------------------+
```
---
**Authored by:** TheArchitectit
**Document Owner:** Project Maintainers
**Last Updated:** 2026-01-14
**Line Count:** ~320
Reference in New Issue View Git Blame Copy Permalink