Project Metrics and Analytics¶

Track project health, team velocity, and identify process bottlenecks with Gira's built-in metrics commands.

Overview¶

Gira provides powerful analytics capabilities that leverage Git history to provide accurate insights into your project's performance. The metrics system includes:

Velocity Tracking: Monitor team productivity across sprints
Trend Analysis: Visualize ticket creation, completion, and backlog growth
Duration Metrics: Identify bottlenecks by analyzing time in each status

Velocity Metrics¶

Track team velocity and sprint performance trends:

# Display velocity trends for last 5 sprints
gira metrics velocity

# Show all sprints including active ones
gira metrics velocity --all

# Export data for external analysis
gira metrics velocity --format json

Understanding Velocity¶

Velocity measures the amount of work completed in each sprint:

Sprint Velocity Trends (Completed)
==================================

Sprint: SPRINT-001
Duration: 14 days (2024-01-01 to 2024-01-15)
Tickets Completed: 12/15 (80%)
────────────────────────────────────────────────────────────
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░ 12

Trend Analysis¶

Monitor ticket flow and backlog health:

# View 30-day trends (default)
gira metrics trends

# Analyze last week
gira metrics trends --days 7

# Filter by priority
gira metrics trends --priority high

# Export for reporting
gira metrics trends --format csv > trends.csv

Reading Trend Charts¶

The trends command displays ASCII charts showing:

Ticket Trends (Last 30 days)
============================

Created vs Completed
        12 ┤     ╭╮
        10 ┤    ╱ ╰╮         Created ───
         8 ┤   ╱   ╰╮        Completed ···
         6 ┤  ╱     ╰────
         4 ┤ ╱
         2 ┤╱
         0 └────────────────────────────────
           1     7    14    21    28  Days

Backlog Size: 45 tickets (trending ↑)

Filtering Options¶

Apply filters to focus on specific areas:

# By ticket type
gira metrics trends --type bug

# By assignee
gira metrics trends --assignee user@example.com

# By epic
gira metrics trends --epic EPIC-001

# Combined filters
gira metrics trends --priority high --type feature --days 14

Duration Analysis¶

Identify process bottlenecks by analyzing time in each status:

# Analyze all tickets
gira metrics duration

# Focus on recent work
gira metrics duration --days 30

# Filter by priority
gira metrics duration --priority high

# Force fresh analysis (bypass cache)
gira metrics duration --no-cache

# Disable progress indicator for scripting
gira metrics duration --no-progress

Understanding Duration Metrics¶

The duration command provides insights into:

Status Durations: Average time tickets spend in each status
Cycle Time: Time from work start to completion
Lead Time: Total time from creation to completion
Status Transitions: How tickets flow between statuses

Example output:

Status Duration Analysis
========================
Git history: 38 tickets, Timestamp fallback: 3 tickets

Average Time in Each Status
┌─────────────────┬────────┬──────────┬────────┬──────┬──────┐
│ Status          │ Count  │ Average  │ Median │ Min  │ Max  │
├─────────────────┼────────┼──────────┼────────┼──────┼──────┤
│ Backlog         │ 15     │ 5.2d     │ 3.1d   │ 2h   │ 15d  │
│ Todo            │ 38     │ 2.3d     │ 1.5d   │ 1h   │ 8d   │
│ In Progress     │ 35     │ 1.8d     │ 1.2d   │ 3h   │ 5d   │
│ Review          │ 32     │ 8.5h     │ 6h     │ 30m  │ 2d   │
│ Done            │ 30     │ -        │ -      │ -    │ -    │
└─────────────────┴────────┴──────────┴────────┴──────┴──────┘

Flow Metrics
Cycle Time    2.5d    1.8d    4h     12d
Lead Time     8.3d    5.2d    1d     45d

Git History Analysis¶

Duration metrics use Git history for accuracy:

Automatic: Git history is analyzed automatically when available
Fallback: Uses timestamps when Git history is unavailable
Cached: Results are cached for performance (invalidated on changes)
Progress: Shows real-time progress with ticket IDs being analyzed
Batch Operations: Automatically uses optimized batch git operations for >10 tickets

Performance Optimizations¶

Duration metrics include several performance features:

# Force batch operations (for testing)
gira metrics duration --force-batch

# Disable progress indicator
gira metrics duration --no-progress

# Bypass cache
gira metrics duration --no-cache

Performance improvements: - Caching: 90%+ performance improvement on subsequent runs - Batch operations: 3-10% improvement for large datasets
- Progress indicators: Real-time feedback during analysis

Working Hours Calculation¶

Calculate durations based on business hours instead of calendar time:

# Use working hours calculation
gira metrics duration --working-hours

# Configure working hours in project
cat >> .gira/config.json << 'EOF'
{
  "working_hours": {
    "timezone": "America/New_York",
    "start_time": "09:00",
    "end_time": "17:00",
    "working_days": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
    "holidays": ["2025-01-01", "2025-07-04", "2025-12-25"]
  }
}
EOF

Working hours features: - Business Hours Only: Excludes weekends and after-hours time - Holiday Support: Configure company holidays to exclude - Timezone Aware: Properly handles different timezones - Dual Display: Shows both calendar time and working hours

Example output with working hours:

Average Time in Each Status (Calendar Time | Working Hours)
┌─────────────────┬────────┬──────────────┬──────────────┬────────┬──────┬──────┐
│ Status          │ Count  │ Avg Calendar │ Avg Working  │ Median │ Min  │ Max  │
├─────────────────┼────────┼──────────────┼──────────────┼────────┼──────┼──────┤
│ Backlog         │ 15     │ 5.2d         │ 3.1d (25h)   │ 3.1d   │ 2h   │ 15d  │
│ Todo            │ 38     │ 2.3d         │ 1.5d (12h)   │ 1.5d   │ 1h   │ 8d   │
│ In Progress     │ 35     │ 1.8d         │ 1.2d (10h)   │ 1.2d   │ 3h   │ 5d   │
│ Review          │ 32     │ 8.5h         │ 6.0h         │ 6h     │ 30m  │ 2d   │
└─────────────────┴────────┴──────────────┴──────────────┴────────┴──────┴──────┘

Working hours: 09:00 - 17:00 (8.0h/day), America/New_York

Performance and Caching¶

Cache System¶

Metrics commands use intelligent caching for performance:

# View cache statistics
gira cache status

# Clear metrics cache
gira cache clear --metrics

# Bypass cache for one command
gira metrics duration --no-cache

When to Clear Cache¶

Clear the cache when: - After bulk ticket updates or migrations - Troubleshooting metrics accuracy - Reclaiming disk space

Performance Tips¶

For large projects: 1. Use date filters to limit scope: --days 30 2. Filter by specific criteria: --type bug --priority high 3. Export and analyze offline: --format json

Export Formats¶

All metrics commands support multiple output formats:

JSON Format¶

gira metrics trends --format json > trends.json

Perfect for: - Custom dashboards - Data pipelines - External analysis tools

CSV Format¶

gira metrics duration --format csv > durations.csv

Ideal for: - Spreadsheet analysis - Reports and presentations - Historical tracking

Human Format (Default)¶

Interactive terminal display with: - ASCII charts - Colored output - Summary statistics

Common Use Cases¶

Sprint Planning¶

# Review velocity trends before planning
gira metrics velocity --limit 10

# Analyze completion patterns
gira metrics trends --days 90

Process Improvement¶

# Find bottlenecks
gira metrics duration --type bug

# Compare priorities
gira metrics duration --priority high
gira metrics duration --priority low

# Analyze with business hours for accurate SLAs
gira metrics duration --working-hours --type bug --priority high

Reporting¶

# Weekly status report
gira metrics trends --days 7 --format json | jq '.summary'

# Monthly velocity report
gira metrics velocity --all --format csv > monthly-velocity.csv

Team Performance¶

# Individual contributor metrics
gira metrics trends --assignee developer@team.com

# Team velocity
gira metrics velocity --all

Best Practices¶

Regular Review: Check metrics weekly to catch trends early
Focus on Trends: Single data points matter less than patterns
Context Matters: Consider external factors affecting metrics
Act on Insights: Use metrics to drive process improvements
Don't Over-optimize: Balance metrics with team happiness

Troubleshooting¶

No Git History Available¶

Some tickets may show "timestamp fallback" - this is normal for: - Tickets created before Git tracking - Imported tickets - Tickets with corrupted history

Slow Performance¶

For large projects:

# Use filters to reduce scope
gira metrics duration --days 30 --type bug

# Clear cache if it's grown too large
gira cache clear --metrics

Inaccurate Metrics¶

If metrics seem wrong:

# Force fresh analysis
gira metrics duration --no-cache

# Check specific ticket history
gira ticket show GCM-123