Skip to content

REAL_PERFORMANCE_TRACKING.md

Latest commit

 

History

History
209 lines (151 loc) · 5.43 KB

REAL_PERFORMANCE_TRACKING.md

File metadata and controls

209 lines (151 loc) · 5.43 KB

Real Performance Tracking in Claude Flow

As of v2.0.0-alpha.80, Claude Flow now includes real performance tracking for all analysis commands. All metrics are collected from actual system operations, not simulated data.

Overview

The performance tracking system monitors:

  • Task Execution: Duration, success rates, and types of all executed tasks
  • Agent Performance: Metrics for each agent type including success rates and average durations
  • System Resources: Memory usage, CPU load, and overall system health
  • Neural Events: Tracking of neural network operations and learning events
  • Trends Analysis: Comparison with previous periods to identify improvements or regressions

How It Works

Automatic Tracking

Performance metrics are automatically collected whenever you:

  • Execute any Claude Flow command
  • Spawn agents
  • Run swarm operations
  • Perform analysis tasks

Data Storage

Metrics are stored in .claude-flow/metrics/:

  • performance.json - Overall performance statistics
  • agent-metrics.json - Per-agent type performance data
  • task-metrics.json - Individual task execution history
  • system-metrics.json - System resource usage over time

Using Real Analysis Commands

Performance Reports

Generate comprehensive performance reports showing real metrics:

# Basic performance summary (last 24 hours)
claude-flow analysis performance-report

# Detailed report for the last week
claude-flow analysis performance-report --timeframe 7d --format detailed

# Export as JSON for further analysis
claude-flow analysis performance-report --format json

# Export as HTML for viewing in browser
claude-flow analysis performance-report --format html

What's Tracked:

  • Total tasks executed
  • Success rate percentage
  • Average execution time
  • Number of agents spawned
  • Memory efficiency
  • Neural learning events
  • Trends compared to previous period

Bottleneck Detection

Identify real performance bottlenecks in your system:

# System-wide bottleneck analysis
claude-flow analysis bottleneck-detect

# Agent-specific analysis
claude-flow analysis bottleneck-detect --scope agent --target coordinator

# Memory bottleneck detection
claude-flow analysis bottleneck-detect --scope memory

# Task performance analysis
claude-flow analysis bottleneck-detect --scope task

What's Detected:

  • Slow tasks (>10s execution time)
  • Low agent success rates (<80%)
  • High memory usage (>80%)
  • CPU overload conditions
  • Specific recommendations for each issue

Token Usage (Already Real)

Token usage tracking was already implemented with real data in alpha.80:

# Basic token usage
claude-flow analysis token-usage

# With breakdown by agent type
claude-flow analysis token-usage --breakdown

# With cost analysis
claude-flow analysis token-usage --breakdown --cost-analysis

Metrics Collection Details

Task Metrics

Each task execution records:

  • Task ID and type
  • Success/failure status
  • Execution duration
  • Timestamp
  • Optional metadata

Agent Metrics

For each agent type, we track:

  • Total actions performed
  • Success rate
  • Average duration
  • Recent action history
  • Performance trends

System Metrics

Collected every 30 seconds:

  • Memory usage (total, used, free)
  • Memory efficiency percentage
  • CPU load average
  • Platform information
  • System uptime

Performance Optimization Tips

Based on real metrics, the system provides:

  1. Automatic Recommendations

    • Suggestions for slow task optimization
    • Agent pool recommendations for spawn overhead
    • Memory optimization strategies
    • CPU scaling suggestions

  2. Trend Analysis

    • Compare current performance to previous periods
    • Identify improving or degrading metrics
    • Track the impact of optimizations

  3. Export Capabilities

    • CSV exports for spreadsheet analysis
    • JSON exports for custom tooling
    • HTML reports for easy viewing

Troubleshooting

No Metrics Available

If you see no metrics:

  1. Ensure you've run some commands first
  2. Check .claude-flow/metrics/ directory exists
  3. Verify write permissions

Inaccurate Metrics

Metrics accuracy improves over time:

  • First 24 hours: Limited data
  • After 1 week: Good trend analysis
  • After 1 month: Comprehensive insights

Performance Impact

The tracking system has minimal overhead:

  • <1% CPU usage for monitoring
  • Automatic data rotation (keeps last 1000 tasks)
  • Efficient in-memory caching

API Integration

For programmatic access to metrics:

import { getPerformanceReport, getBottleneckAnalysis } from 'claude-flow/metrics';

// Get performance data
const report = await getPerformanceReport('7d');
console.log(`Success rate: ${report.summary.successRate}%`);

// Detect bottlenecks
const bottlenecks = await getBottleneckAnalysis('system');
bottlenecks.forEach(b => {
  console.log(`${b.severity}: ${b.component} - ${b.metric}`);
});

Future Enhancements

Planned improvements include:

  • Real-time dashboard UI
  • Webhook notifications for critical bottlenecks
  • Machine learning-based anomaly detection
  • Integration with external monitoring tools
  • Custom metric definitions

Privacy and Security

  • All metrics are stored locally in your project
  • No data is sent to external services
  • Sensitive information is never logged
  • Metrics can be cleared with rm -rf .claude-flow/metrics

For more information, see the Claude Flow documentation or run claude-flow help analysis.