GitLab Internal Events CLI

An interactive CLI tool for creating event and metric definition files for GitLab's Internal Events tracking.

This gem extracts the Internal Events CLI from the GitLab monorepo, making it an independent, configurable Ruby gem that can be used in GitLab projects.

Features

  • Interactive CLI - Guided flows for creating events and metrics
  • YAML Generation - Creates properly formatted event and metric definition files
  • Code Examples - Generates code snippets for instrumentation in Rails, RSpec, JavaScript, Vue, and HAML
  • Configurable - Adapt paths to work with custom project structures
  • Metadata Fetching - Stages and groups fetched directly from GitLab repository

Installation

Install the gem globally as:

gem install gitlab_internal_events_cli

Usage

Running the CLI

From the root of a project:

gem exec gitlab_internal_events_cli

The CLI provides an interactive menu to:

  • New Event - Define a new event to track specific scenarios
  • New Metric - Define metrics that count events over time, or that are derived from the database
  • View Usage - See code examples for existing events
  • Help/Flow Advisor - Get guidance on which tool to use

Database metrics

Selecting Database at the metric-type prompt scaffolds three files in one go:

  • A YAML metric definition under config/metrics/counts_*/ (or ee/config/metrics/counts_*/ for non-free tiers).
  • A Ruby instrumentation class under lib/gitlab/usage/metrics/instrumentations/ (or ee/lib/...).
  • A matching RSpec file under spec/lib/gitlab/usage/metrics/instrumentations/ (or ee/spec/lib/...) using the a correct instrumented metric value and query shared example.

You will be prompted for the instrumentation class name and the operation (count, distinct_count, estimate_batch_distinct_count, sum, average). After generation, fill in the ActiveRecord relation in the class and the expected_value / expected_query in the spec. See the database metrics documentation for details.

Configuration

The CLI can be configured via a .gitlab_internal_events_cli.yml file in your project root:

# Optional: Customize paths and URLs
project_root: .

# Local file paths (relative to project_root)
event_paths:
  - config/events/*.yml
  - ee/config/events/*.yml
metric_paths:
  - config/metrics/counts_all/*.yml
  - config/metrics/counts_7d/*.yml
  - config/metrics/counts_28d/*.yml
  - ee/config/metrics/counts_all/*.yml
  - ee/config/metrics/counts_7d/*.yml
  - ee/config/metrics/counts_28d/*.yml

Architecture

Metadata Fetching

The gem fetches metadata from GitLab repositories:

  • Stages/Groups: Fetched from gitlab-com/www-gitlab-com master branch for product organization

This ensures the CLI has up-to-date information about product stages and groups without duplicating data.

Milestone Detection

The milestone is automatically detected from the VERSION file in the project root:

  1. VERSION file: Extracts X.Y from content like 17.8.0-pre
  2. Fallback: Defaults to "TODO" if not found

Directory Structure

The CLI expects the following structure (configurable):

project/
├── VERSION                          # Milestone detection (optional)
├── config/
│   ├── events/*.yml                # Event definitions
│   ├── metrics/
│   │   ├── counts_all/*.yml       # Total count metrics
│   │   ├── counts_7d/*.yml        # Weekly metrics
│   │   └── counts_28d/*.yml       # Monthly metrics
│   └── feature_categories.yml     # Feature categories
└── ee/                            # Enterprise Edition
    ├── config/events/*.yml
    └── config/metrics/...

Development

After checking out the repo, run:

bundle install

Run the tests:

bundle exec rspec

Run rubocop:

bundle exec rubocop

Building and running the gem locally

Build the gem:

gem build gitlab_internal_events_cli.gemspec

This produces a .gem file in the current directory (e.g. gitlab_internal_events_cli-0.0.1.gem).

Install it locally:

gem install ./gitlab_internal_events_cli-0.0.1.gem

Then run the CLI from the root of a GitLab project:

gitlab-internal-events-cli

Alternatively, run directly from the repo without installing the gem:

bundle exec exe/gitlab-internal-events-cli

License

The gem is available as open source under the terms of the MIT License.