GSD Logging & Observability System

Author: David Sienkowski - GitHub

A comprehensive logging infrastructure for the GSD (Get-Shit-Done) meta-prompting framework. Captures every step, decision, agent interaction, and error for debugging, verification, and benchmarking.

Documentation

For the complete implementation guide with architecture details, integration patterns, and advanced configuration, see:

📖 docs/gsd-logging-implementation-guide.md

This guide covers:

• Detailed architecture and event schema design
• Claude Code hooks and OpenTelemetry integration
• Modifying GSD commands for richer logging (optional)
• External observability platform setup (Grafana, Phoenix, LangSmith)
• Connecting logs to the benchmarking framework
• CI/CD integration patterns

Quick Start

Installation

# Option 1: Run setup script
python setup_logging.py

# Option 2: Manual installation
cp -r hooks/ /path/to/your/project/.gsd/hooks/
cp -r tools/ /path/to/your/project/.gsd/tools/
cp -r config/ /path/to/your/project/.gsd/config/
cp -r docs/ /path/to/your/project/.gsd/docs/

Configure Claude Code

Add to your .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [{"matcher": "", "hooks": [{"type": "command", "command": "python3 .gsd/hooks/pre_tool_use.py"}]}],
    "PostToolUse": [{"matcher": "", "hooks": [{"type": "command", "command": "python3 .gsd/hooks/post_tool_use.py"}]}],
    "SubagentStop": [{"hooks": [{"type": "command", "command": "python3 .gsd/hooks/subagent_stop.py"}]}],
    "SessionStart": [{"hooks": [{"type": "command", "command": "python3 .gsd/hooks/session_start.py"}]}],
    "SessionEnd": [{"hooks": [{"type": "command", "command": "python3 .gsd/hooks/session_end.py"}]}]
  }
}

Verify Installation

# Run a quick test
python .gsd/hooks/gsd_logger.py --test --debug

# Check logs
python .gsd/tools/query_logs.py --stats

Directory Structure

.gsd/
├── docs/
│   └── gsd-logging-implementation-guide.md  # Comprehensive guide
├── hooks/                      # Claude Code hook scripts
│   ├── gsd_logger.py          # Core logging module
│   ├── pre_tool_use.py        # Runs before each tool
│   ├── post_tool_use.py       # Runs after each tool
│   ├── subagent_stop.py       # Runs when agents complete
│   ├── session_start.py       # Initializes session
│   └── session_end.py         # Finalizes session
├── tools/                      # Analysis tools
│   ├── query_logs.py          # Query and filter logs
│   ├── visualize_workflow.py  # Generate diagrams
│   └── benchmark_from_logs.py # Extract metrics
├── config/                     # Configuration
│   └── logging_config.yaml    # Logging settings
├── logs/                       # Log storage
│   ├── events.jsonl           # All events (append-only)
│   ├── sessions/              # Per-session logs
│   └── workflows/             # Per-workflow logs
└── state/                      # Runtime state
    └── current_context.json   # Current GSD context

What Gets Logged

Event Categories

Category	Events	Purpose
Session	start, end	Track session lifecycle
Command	invoked, completed, failed	GSD command execution
Agent	spawned, completed, error	Orchestrator → agent delegation
Task	started, completed, failed, verification	Task execution tracking
Plan	generated, verified, revision	Planning quality metrics
Phase	started, completed	Multi-phase workflow tracking
Context	loaded, warning, compacted	Context window management
Error	occurred, recovered	Error tracking and recovery

Event Schema

{
  "timestamp": "2025-01-27T14:32:01.123Z",
  "event_id": "evt_abc123def456",
  "event_type": "gsd.task.completed",
  "session_id": "sess_xyz789",
  "workflow_id": "wf_project123",
  "gsd_context": {
    "command": "/gsd:execute-phase",
    "phase": "2-api-endpoints",
    "agent": "gsd-executor"
  },
  "payload": {
    "task_id": "task_003",
    "task_name": "Create login endpoint",
    "verification_passed": true
  },
  "parent_event_id": "evt_parent456",
  "duration_ms": 45230
}

Using the Tools

Query Logs

# Show statistics
python .gsd/tools/query_logs.py --stats

# Show event timeline
python .gsd/tools/query_logs.py --timeline

# Show errors only
python .gsd/tools/query_logs.py --errors

# Filter by session
python .gsd/tools/query_logs.py --session sess_abc123

# Filter by event type
python .gsd/tools/query_logs.py --type task

# Events from last hour
python .gsd/tools/query_logs.py --since 1h

# List all sessions
python .gsd/tools/query_logs.py --list-sessions

# Export to JSON
python .gsd/tools/query_logs.py --export report.json

Visualize Workflows

# Generate Mermaid flowchart
python .gsd/tools/visualize_workflow.py --session sess_abc123

# Generate sequence diagram
python .gsd/tools/visualize_workflow.py --session sess_abc123 --format sequence

# Generate ASCII tree
python .gsd/tools/visualize_workflow.py --session sess_abc123 --format tree

# Save to file
python .gsd/tools/visualize_workflow.py --session sess_abc123 --output workflow.md --wrap-markdown

Extract Benchmark Metrics

# Extract metrics for one session
python .gsd/tools/benchmark_from_logs.py --session sess_abc123

# Compare GSD vs baseline
python .gsd/tools/benchmark_from_logs.py --compare sess_gsd,sess_baseline

# Export metrics to JSON
python .gsd/tools/benchmark_from_logs.py --session sess_abc123 --output metrics.json

# Extract all sessions
python .gsd/tools/benchmark_from_logs.py --all --output all_metrics.json

OpenTelemetry Integration

Enable native OTEL export to send events to observability platforms:

# Enable telemetry
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# For Grafana Cloud
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp-gateway-prod-us-central-0.grafana.net/otlp"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic <your-token>"

Debug Mode

Enable debug output to see events in real-time:

export GSD_DEBUG=true

Or modify logging_config.yaml:

general:
  debug: true

Programmatic Usage

from gsd_logger import get_logger, EventType

logger = get_logger()

# Log command start
logger.log_command_start('/gsd:plan-phase', {'phase': '2.0'})

# Log agent spawn
logger.log_agent_spawn('gsd-researcher', 'Research authentication patterns')

# Log task completion
logger.log_task_complete('task_001', verification_passed=True, 
                         verification_output='200 OK')

# Log errors
logger.log_error('validation_error', 'Invalid task format', recoverable=True)

# Log custom events
logger.log(EventType.PHASE_STARTED, {
    'phase_number': '2.0',
    'phase_name': 'API Development',
    'goals': ['Create endpoints', 'Add authentication']
})

Metrics Extracted for Benchmarking

Metric	Description
task_completion_rate	Tasks completed / Tasks started
task_success_rate	Verification passed / Tasks completed
command_success_rate	Commands completed / Commands invoked
agent_success_rate	Agents completed / Agents spawned
plan_verification_rate	Plans passed / Plans verified
error_rate	Errors / Total events
efficiency_score	Tasks completed / (Tokens / 1000)
reliability_score	Weighted combination of success rates

Troubleshooting

Hooks not running

1. Check file permissions: chmod +x .gsd/hooks/*.py
2. Verify Python path: which python3
3. Check Claude settings: .claude/settings.json
4. Use absolute paths in settings if needed

Missing events

1. Ensure hooks are configured for all event types
2. Check if events are filtered in logging_config.yaml
3. Verify write permissions to .gsd/logs/

High volume of tool events

Tool events (gsd.tool.pre_use, gsd.tool.post_use) can be verbose. Disable in config:

events:
  tools:
    pre_use: false
    post_use: false

License

MIT License - See LICENSE file for details.

---

Author: David Sienkowski - https://github.com/davesienkowski