GitLab Metrics Collector 📊

High-performance CLI tool for collecting and analyzing merge request metrics from GitLab instances.

Features

• ⚡️ Parallel processing for high-speed data collection
• 🔄 Smart request batching with automatic retries
• 📊 Monthly merge request statistics in CSV format
• 📈 Interactive HTML visualization with charts
• 💬 Interactive prompts for easy configuration
• ⚙️ Configurable performance settings

HTML Demo

You can view a demo of the output by opening the demo.html file.

❗ Important Note on Interpreting Metrics

While this tool provides valuable insights into merge request patterns, it's crucial to interpret these metrics within your team's broader context:

• Some work naturally requires longer development cycles with fewer MRs
• System issues or technical constraints can temporarily affect MR frequency
• Personal circumstances and work-life events may impact individual metrics
• Changes in metrics often signal something worth exploring, but numbers alone don't tell the whole story

For a comprehensive assessment, use this tool in conjunction with other analysis tools such as:

• Radarz for additional team performance insights
• Team retrospectives and feedback sessions
• Project-specific context and complexity measures

Use these metrics as one of many inputs for understanding team dynamics and identifying potential areas for support or improvement, not as absolute performance indicators.

Prerequisites

1. Install Node.js (16.0.0 or higher):

   # Using homebrew on macOS
   brew install node
   
   # Or download from nodejs.org
   # https://nodejs.org/

2. Install a package manager:

   # Either npm (comes with Node.js)
   npm install -g npm@latest
   
   # Or yarn
   yarn global add yarn

Installation

# Install globally using npm
npm install -g gitlab-metrics-collector

# OR using yarn
yarn global add gitlab-metrics-collector

# Verify installation
gitlab-metrics --version

If you get a "command not found" error after installation:

1. For npm users, make sure global npm binaries are in your PATH:

# Add this to your ~/.zshrc or ~/.bashrc
export PATH="$PATH:$(npm config get prefix)/bin"

2. For yarn users, make sure global yarn binaries are in your PATH:

# Add this to your ~/.zshrc or ~/.bashrc
export PATH="$PATH:$(yarn global bin)"

After adding the PATH, reload your shell:

source ~/.zshrc  # or source ~/.bashrc

Configuration

First, run the configuration wizard:

gitlab-metrics configure

You'll be prompted for:

• GitLab instance URL (defaults to gitlab.com)
• Personal Access Token (requires read_api scope)
• Target usernames (comma-separated list)
• Maximum concurrent requests (optional, defaults to 25)

Usage

Collecting Metrics

You can collect metrics either by providing command-line options or through interactive prompts:

Using Command-Line Options

# Full command with all options
gitlab-metrics collect -s 2024-01-01 -e 2024-01-31 -o metrics.csv -f csv

# Minimal command (will prompt for missing options)
gitlab-metrics collect

Command Options

| Option | Description | Default | Required | Interactive Prompt | |--------|-------------|---------|----------|-------------------| | -s, --start-date | Start date (YYYY-MM-DD) | - | Yes | Yes, if not provided | | -e, --end-date | End date (YYYY-MM-DD) | - | Yes | Yes, if not provided | | -o, --output | Output file path | metrics.csv | No | No | | -c, --concurrent | Concurrent request limit | 25 | No | No | | -f, --format | Export format (csv or html) | csv | No | Yes, if not provided |

Export Formats

CSV Format

• User-based rows
• Monthly columns (e.g., "January 2024")
• Merge request count per user per month

HTML Format

The HTML format provides an interactive visualization that includes:

• Individual View: Compare specific team members with optional team average overlay
• Team Average View: See overall team performance (averaged across active developers)
• View All: Display all team members simultaneously
• Line charts showing merge request trends over time
• Toggle controls for selecting individual users
• Team average overlay (purple dashed line) in individual view
• Responsive design for all screen sizes
• Detailed tooltips with monthly statistics

Note on Team Average: The team average only includes developers with at least 1 MR in each month, providing a more accurate baseline by excluding vacation time, sick leave, or periods before/after employment.

Example commands for different formats:

# Export to CSV (default)
gitlab-metrics collect -s 2024-01-01 -e 2024-01-31 -o metrics.csv

# Export to interactive HTML visualization
gitlab-metrics collect -s 2024-01-01 -e 2024-01-31 -o report.html -f html

Performance Tips

• If you encounter rate limiting:
  • Reduce concurrent requests: gitlab-metrics collect -c 15
  • Process data in smaller date ranges
• The tool implements automatic retries with exponential backoff
• For large teams, consider running during off-peak hours

Troubleshooting

1. Command Not Found

   • Verify PATH settings as described in Installation section
   • Try reinstalling the package
   • Make sure Node.js is properly installed: node --version

2. Rate Limiting

   • Reduce concurrent requests using -c 15 or lower
   • Check your GitLab token permissions
   • Verify your token has the read_api scope

3. Connection Issues

   • Verify your GitLab URL is correct
   • Ensure your access token is valid
   • Check your network connection

4. Date Format Errors

   • Ensure dates are in YYYY-MM-DD format
   • Start date must be before end date
   • Dates must be valid calendar dates

License

Released under the MIT License. See LICENSE for details.