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:

• Line charts showing merge request trends
• Toggle controls for individual users
• Performance analysis with top/low performer bands
• Responsive design for all screen sizes
• Detailed tooltips with monthly statistics

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.