# Performance Monitor

> Track execution metrics and performance of skills including execution time, memory usage, and success rates

- Skill: `lodetomasi/performance-monitor` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add lodetomasi/performance-monitor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lodetomasi/performance-monitor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: lodetomasi (https://skillmd.com/u/lodetomasi)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/lodetomasi/performance-monitor

---


# Performance Monitor

## Overview
Tracks and analyzes performance metrics for Claude Code skills and tools, recording execution time, memory usage, success/failure rates, and generating comprehensive performance reports.

## When to Use
- After implementing new skills to establish baselines
- When investigating performance degradation
- For capacity planning and resource optimization
- During performance optimization cycles
- When debugging memory issues

## Capabilities

### 1. Metrics Collection
- Execution time tracking
- Memory usage monitoring (MB)
- Success/failure rate recording
- Timestamp logging
- Error message capture

### 2. Statistical Analysis
- Average/min/max execution times
- Memory usage patterns
- Success rate calculations
- Usage frequency tracking
- Trend analysis

### 3. Performance Reporting
- Summary reports by skill
- Top slowest skills identification
- Memory-intensive skill detection
- Most-used skills ranking
- Failure rate analysis

## Usage

### Generate Performance Report

```bash
python .claude/skills/performance-monitor/performance-monitor.py report
```

### Run Test Execution with Monitoring

```bash
python .claude/skills/performance-monitor/performance-monitor.py test
```

### Custom Metrics File

```bash
python .claude/skills/performance-monitor/performance-monitor.py report custom_metrics.json
```

## Report Output Example

```
================================================================================
PERFORMANCE MONITORING REPORT
================================================================================

Total recorded executions: 147
Tracked skills: 12

Skill                          Executions   Avg Time     Avg Memory   Success Rate
--------------------------------------------------------------------------------
database-optimizer             45           2.341s       124.5MB      100.0%
python-profiler                32           1.892s       89.3MB       96.9%
sast-analyzer                  28           5.123s       256.7MB      100.0%
aws-cost-analyzer              18           3.445s       178.2MB      94.4%
memory-analyzer                12           4.567s       312.1MB      91.7%
code-reviewer                  8            1.234s       67.8MB       100.0%

================================================================================
PERFORMANCE INSIGHTS
================================================================================

🐌 Slowest Skills (Average):
  • sast-analyzer: 5.123s
  • memory-analyzer: 4.567s
  • aws-cost-analyzer: 3.445s

💾 Most Memory Intensive:
  • memory-analyzer: 312.1MB
  • sast-analyzer: 256.7MB
  • aws-cost-analyzer: 178.2MB

⭐ Most Used Skills:
  • database-optimizer: 45 executions
  • python-profiler: 32 executions
  • sast-analyzer: 28 executions

⚠️  Skills with Failures:
  • memory-analyzer: 1 failures (8.3%)
  • aws-cost-analyzer: 1 failures (5.6%)
  • python-profiler: 1 failures (3.1%)
```

## Instrumenting Your Code

### Python Decorator

```python
from .claude.skills.performance-monitor import performance_monitor

@monitor_performance('my-custom-skill')
def my_skill_function():
    # Your code here
    pass
```

### Manual Recording

```python
from .claude.skills.performance-monitor import PerformanceMonitor
import time

monitor = PerformanceMonitor()
start = time.time()

try:
    # Your code
    success = True
    error = None
except Exception as e:
    success = False
    error = str(e)

execution_time = time.time() - start
memory_used = 50  # MB

monitor.record_execution(
    skill_name='my-skill',
    execution_time=execution_time,
    memory_used=memory_used,
    success=success,
    error=error
)
```

## Data Storage

Metrics are stored in JSON format at `performance_metrics.json`:

```json
[
  {
    "timestamp": "2025-01-15T10:30:45.123456",
    "skill": "python-profiler",
    "execution_time": 1.892,
    "memory_used_mb": 89.3,
    "success": true,
    "error": null
  }
]
```

## Performance Optimization Guidelines

### Execution Time
- **Target**: < 5s for most skills
- **Acceptable**: 5-10s for complex analysis
- **Investigate**: > 10s execution time

### Memory Usage
- **Light**: < 100MB
- **Moderate**: 100-300MB
- **Heavy**: > 300MB (review for optimization)

### Success Rate
- **Excellent**: > 98%
- **Good**: 95-98%
- **Needs attention**: < 95%

## Troubleshooting

### High Execution Time
- Profile the skill with cProfile or pyinstrument
- Check for inefficient algorithms (O(n²))
- Look for unnecessary I/O operations
- Review external API calls

### High Memory Usage
- Check for memory leaks
- Review large data structure usage
- Use generators instead of lists
- Implement streaming for large files

### Low Success Rate
- Review error messages in metrics file
- Add error handling
- Validate input data
- Add retry logic for transient failures

## CI/CD Integration

### GitHub Actions
```yaml
name: Performance Monitoring

on: [push]

jobs:
  monitor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run with monitoring
        run: |
          python .claude/skills/performance-monitor/performance-monitor.py test
      - name: Generate report
        run: |
          python .claude/skills/performance-monitor/performance-monitor.py report
```

## Requirements

```bash
pip install psutil  # For memory monitoring
```

## Metrics Retention

- Keep last 1000 executions per skill
- Archive monthly reports
- Clear old metrics: `rm performance_metrics.json`