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

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

Missing events

Ensure hooks are configured for all event types
Check if events are filtered in logging_config.yaml
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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

GSD Logging & Observability System

Documentation

Quick Start

Installation

Configure Claude Code

Verify Installation

Directory Structure

What Gets Logged

Event Categories

Event Schema

Using the Tools

Query Logs

Visualize Workflows

Extract Benchmark Metrics

OpenTelemetry Integration

Debug Mode

Programmatic Usage

Metrics Extracted for Benchmarking

Troubleshooting

Hooks not running

Missing events

High volume of tool events

License

About

Uh oh!

Releases

Packages

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
config		config
docs		docs
examples		examples
hooks		hooks
logs		logs
state		state
tools		tools
.gitattributes		.gitattributes
LICENSE		LICENSE
README.md		README.md
setup_logging.py		setup_logging.py

License

davesienkowski/gsd-logging

Folders and files

Latest commit

History

Repository files navigation

GSD Logging & Observability System

Documentation

Quick Start

Installation

Configure Claude Code

Verify Installation

Directory Structure

What Gets Logged

Event Categories

Event Schema

Using the Tools

Query Logs

Visualize Workflows

Extract Benchmark Metrics

OpenTelemetry Integration

Debug Mode

Programmatic Usage

Metrics Extracted for Benchmarking

Troubleshooting

Hooks not running

Missing events

High volume of tool events

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages