https://github.com/lyonsv/gitlab-metrics-collector
https://github.com/lyonsv/gitlab-metrics-collector
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/lyonsv/gitlab-metrics-collector
- Owner: lyonsv
- License: mit
- Created: 2025-02-10T23:21:32.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-12-18T23:33:15.000Z (6 months ago)
- Last Synced: 2025-12-21T17:36:25.009Z (6 months ago)
- Language: JavaScript
- Size: 164 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# GitLab Metrics Collector 📊
> High-performance CLI tool for collecting and analyzing merge request metrics from GitLab instances.
[](https://www.npmjs.com/package/gitlab-metrics-collector)
[](https://opensource.org/licenses/MIT)
## 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](https://github.com/lyonsv/gitlab-metrics-collector/blob/main/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](https://radarz.built.ie) 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):
```bash
# Using homebrew on macOS
brew install node
# Or download from nodejs.org
# https://nodejs.org/
```
2. Install a package manager:
```bash
# Either npm (comes with Node.js)
npm install -g npm@latest
# Or yarn
yarn global add yarn
```
## Installation
```bash
# 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:
```bash
# 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:
```bash
# Add this to your ~/.zshrc or ~/.bashrc
export PATH="$PATH:$(yarn global bin)"
```
After adding the PATH, reload your shell:
```bash
source ~/.zshrc # or source ~/.bashrc
```
## Configuration
First, run the configuration wizard:
```bash
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
```bash
# 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:
```bash
# 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](LICENSE) for details.