7.8 KiB

Raw Blame History

Logging Patterns for Agents

Array-based structured logging format.

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

{
  "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

{
  "category": "file_operation",
  "action": "read | write | edit | delete",
  "target": "/path/to/file",
  "metadata": {
    "lines_affected": 10,
    "old_content": "...",
    "new_content": "..."
  }
}

Git Operations Log

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

7.8 KiB Raw Blame History