gitlab_internal_events_cli 0.0.1 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53b38b01e7214b61bb0a8768a926f2a335c7fcdd509c23879aa00627a15b9e6d
-  data.tar.gz: 7a23d46213056876709d6c6c1d77b068c94bf8b54a4887faec103747718d2b0f
+  metadata.gz: 488d06f3e32cbc1e6c1a32bb6cf214181762cda5078069f725892cd9d65a523b
+  data.tar.gz: d05a91f4a982dd1cc3941a0d61f4333054cb8cd6f2d9f5be69bd940926be3a4b
 SHA512:
-  metadata.gz: e869509a120eeb35c09557cdc96c7ce6313338a95ef7dc59b7110202e55719460e01abf1e1f497f0eab3cd2df9a860eb3932f0fdd4307cb350d2cfa8976dc460
-  data.tar.gz: 11afd1175a2873484df7af82f9071610811bcd07e69aa0438eab73dc97bb94ac4008478e78af4b6b50234b0f8a943c6a4a71c9ecd17358816c8c826e3fec9e3e
+  metadata.gz: 123411c52cbd00083d1bef970f4c2361c4c4b8ddebb06f4a736ddf4f11188ebbfbc4cb9cf9141ac17099bfd75911caf29290244f30c31ba62147271ce7fcdcff
+  data.tar.gz: bcf890d1283412da086d3bdee6eb6b91d8b49ed3a2f0c6bbe9a85fa433dcf8e6bf085ebba204831fc85be132f88c264bd979537b496bf90789de89c37af7def4

data/README.md

@@ -14,19 +14,7 @@ This gem extracts the Internal Events CLI from the GitLab monorepo, making it an
 
 ## Installation
 
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'gitlab_internal_events_cli', path: 'path/to/this/repo'
-```
-
-And then execute:
-
-```bash
-bundle install
-```
-
-Or install it yourself as:
+Install the gem globally as:
 
 ```bash
 gem install gitlab_internal_events_cli
@@ -36,18 +24,34 @@ gem install gitlab_internal_events_cli
 
 ### Running the CLI
 
-From the root of a GitLab project (or any project with the expected directory structure):
+From the root of a project:
 
 ```bash
-gitlab-internal-events-cli
+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
+- **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](https://docs.gitlab.com/development/internal_analytics/metrics/metrics_instrumentation/#database-metrics)
+for details.
+
 ### Configuration
 
 The CLI can be configured via a `.gitlab_internal_events_cli.yml` file in your project root:
@@ -90,7 +94,7 @@ The CLI expects the following structure (configurable):
 
 ```
 project/
-├── VERSION                          # Milestone detection
+├── VERSION                          # Milestone detection (optional)
 ├── config/
 │   ├── events/*.yml                # Event definitions
 │   ├── metrics/
@@ -151,14 +155,6 @@ Alternatively, run directly from the repo without installing the gem:
 bundle exec exe/gitlab-internal-events-cli
 ```
 
-## Migration from GitLab Monorepo
-
-This gem was extracted from the original CLI at `gitlab/scripts/internal_events/cli.rb`. Key changes:
-
-1. **Configuration System**: All hardcoded paths are now configurable
-2. **Standalone Gem**: Can be used outside the GitLab monorepo with proper configuration
-3. **Module Renamed**: `InternalEventsCli` → `GitlabInternalEventsCli`
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/lib/gitlab_internal_events_cli/cli.rb

@@ -14,6 +14,7 @@ module GitlabInternalEventsCli
       HttpCache.preload!
 
       cli.say feedback_notice
+      check_for_updates
       cli.say instructions
 
       task = cli.select('What would you like to do?', **select_opts) do |menu|
@@ -39,6 +40,34 @@ module GitlabInternalEventsCli
       end
     end
 
+    private
+
+    def check_for_updates
+      checker = VersionChecker.new
+      return unless checker.update_available?
+
+      cli.say format_warning(
+        "\nUpdate available! Current version: #{VERSION}, Latest version: #{checker.latest_version}\n"
+      )
+
+      return unless cli.yes?(
+        'Would you like to update now?',
+        **yes_no_opts
+      )
+
+      cli.say format_info("\nUpdating #{VersionChecker::GEM_NAME}...\n")
+
+      if checker.self_update!
+        cli.say format_selection("\nUpdate successful! Please restart the CLI to use the new version.\n")
+        exit 0
+      else
+        cli.say format_error("\nUpdate failed. You can update manually with: " \
+                             "gem install #{VersionChecker::GEM_NAME}\n")
+      end
+    rescue StandardError
+      nil
+    end
+
     def instructions
       cli.say <<~TEXT.freeze
         #{format_info('INSTRUCTIONS:')}

data/lib/gitlab_internal_events_cli/configuration.rb

@@ -42,6 +42,12 @@ module GitlabInternalEventsCli
       @event_schema_url = DEFAULT_EVENT_SCHEMA_URL
       @metric_schema_url = DEFAULT_METRIC_SCHEMA_URL
       @stages_url = DEFAULT_STAGES_URL
+      @python_filepaths = [
+        'poetry.lock',
+        'pyproject.toml',
+        '.python-version',
+        'requirements.txt'
+      ]
     end
 
     def milestone
@@ -68,6 +74,10 @@ module GitlabInternalEventsCli
       apply_config(config)
     end
 
+    def python_project?
+      @python_filepaths.any? { |f| File.exist?(absolute_path(f)) }
+    end
+
     private
 
     def apply_config(config)

data/lib/gitlab_internal_events_cli/flows/event_definer.rb

@@ -27,6 +27,8 @@ module GitlabInternalEventsCli
         'Save files'
       ].freeze
 
+      DUO_EVENT_CLASS = 'duo'
+
       IDENTIFIER_FORMATTING_BUFFER = "[#{IDENTIFIER_OPTIONS.keys.map { |k| k.join(', ') }.max_by(&:length)}]".length
 
       attr_reader :cli, :event
@@ -237,7 +239,7 @@ module GitlabInternalEventsCli
           menu.choice 'No - this event is not related to AI/Duo features', :none
         end
 
-        event.classification = 'duo' if classification_choice == :duo
+        event.classification = DUO_EVENT_CLASS if classification_choice == :duo
       end
 
       def create_event_file
@@ -255,6 +257,7 @@ module GitlabInternalEventsCli
 
           #{outcome || '  No files saved.'}
 
+          #{ai_tracking_suggestion}#{python_codebase_advice}
           #{divider}
 
             Do you need to create a metric? Probably!
@@ -301,6 +304,22 @@ module GitlabInternalEventsCli
           cli.say feedback_notice
         end
       end
+
+      def ai_tracking_suggestion
+        return unless duo_event?
+
+        generate_ai_event_suggestion(event.action)
+      end
+
+      def python_codebase_advice
+        return unless GitlabInternalEventsCli.configuration.python_project?
+
+        generate_python_advice
+      end
+
+      def duo_event?
+        event.classification == DUO_EVENT_CLASS
+      end
     end
   end
 end

data/lib/gitlab_internal_events_cli/flows/flow_advisor.rb

@@ -16,9 +16,14 @@ module GitlabInternalEventsCli
 
       def run
         return use_case_error unless goal_is_tracking_usage?
-        return use_case_error unless usage_trackable_with_internal_events?
 
-        event_already_tracked? ? proceed_to_metric_definition : proceed_to_event_definition
+        if usage_trackable_with_internal_events?
+          event_already_tracked? ? proceed_to_metric_definition : proceed_to_event_definition
+        elsif usage_trackable_from_database?
+          proceed_to_database_metric_definition
+        else
+          use_case_error
+        end
       end
 
       private
@@ -44,6 +49,19 @@ module GitlabInternalEventsCli
         )
       end
 
+      def usage_trackable_from_database?
+        new_page!
+
+        cli.say format_info("Got it! Let's check whether a database metric fits.\n")
+        cli.say DATABASE_METRIC_EXAMPLES
+
+        cli.yes?(
+          'Can the data for this metric be derived from a database query (e.g. a count, sum, ' \
+          'distinct count or average over an ActiveRecord relation)?',
+          **yes_no_opts
+        )
+      end
+
       def event_already_tracked?
         new_page!
 
@@ -81,6 +99,20 @@ module GitlabInternalEventsCli
         EventDefiner.new(cli).run
       end
 
+      def proceed_to_database_metric_definition
+        new_page!
+
+        cli.say format_info("Great! The next step is adding a database metric.\n")
+        cli.say(
+          'When prompted for the metric type, choose ' \
+          "#{format_info('Database')} to scaffold the YAML, Ruby class, and spec files.\n"
+        )
+
+        return not_ready_error('New Metric') unless cli.yes?(format_prompt('Ready to start?'))
+
+        MetricDefiner.new(cli).run
+      end
+
       def not_ready_error(description)
         cli.say "\nNo problem! When you're ready, run the CLI & select '#{description}'\n"
         cli.say feedback_notice

data/lib/gitlab_internal_events_cli/flows/metric_definer.rb

@@ -92,13 +92,6 @@ module GitlabInternalEventsCli
       def prompt_for_configuration(type)
         case type
         when :database_metric
-          # CLI doesn't load rails, so perform a simplified string <-> boolean check
-          if [nil, 'false', '0'].include? ENV['ENABLE_DATABASE_METRIC']
-            cli.error DATABASE_METRIC_NOTICE
-            cli.say feedback_notice
-            return
-          end
-
           db_metric_definer = Subflows::DatabaseMetricDefiner.new(cli)
           db_metric_definer.run
           @metric = db_metric_definer.metric
@@ -224,7 +217,31 @@ module GitlabInternalEventsCli
         cli.say format_prompt(format_subheader('SAVING FILE', metric.description))
         cli.say "\n"
 
-        prompt_to_save_file(metric.file_path, metric.formatted_output)
+        yaml_outcome = prompt_to_save_file(metric.file_path, metric.formatted_output)
+
+        return yaml_outcome unless metric.database_metric?
+
+        instrumentation_outcome = save_instrumentation_class_files
+
+        [yaml_outcome, instrumentation_outcome].compact.join("\n")
+      end
+
+      # For database metrics, also scaffold the Ruby instrumentation class
+      # and a matching spec file. These mirror the output of the upstream
+      # `rails generate gitlab:usage_metric` generator.
+      def save_instrumentation_class_files
+        targets = [
+          [metric.instrumentation_class_file_path, metric.instrumentation_class_content],
+          [metric.instrumentation_class_spec_file_path, metric.instrumentation_class_spec_content]
+        ]
+
+        targets.filter_map do |filepath, content|
+          cli.say "\n"
+          cli.say format_prompt(format_subheader('SAVING FILE', filepath))
+          cli.say "\n"
+
+          prompt_to_save_file(filepath, content)
+        end.join("\n")
       end
 
       def show_all_metric_paths(metric)
@@ -248,6 +265,7 @@ module GitlabInternalEventsCli
 
         event_metric_message = "\n  Have you instrumented the application code to trigger the event yet? " \
                                "View usage examples to easily copy/paste implementation!\n"
+        database_metric_message = "\n#{format_prefix('  ', DATABASE_INSTRUMENTATION_FILES_NEXT_STEPS)}"
         cli.say <<~TEXT
           #{divider}
           #{format_info('Done with metric definitions!')}
@@ -255,6 +273,7 @@ module GitlabInternalEventsCli
           #{outcome}
           #{divider}
             #{event_metric_message if metric.event_metric?}
+            #{database_metric_message if metric.database_metric?}
             Want to verify the metrics? Check out the group::#{metric[:product_group]} Metrics Exploration Dashboard in Tableau
               Note: The Metrics Exploration Dashboard data would be available ~1 week after deploy for Gitlab.com, ~1 week after next release for self-managed
               Link: #{format_info(metric_exploration_group_path(metric[:product_group], find_stage(metric.product_group)))}
@@ -339,23 +358,34 @@ module GitlabInternalEventsCli
 
         return unless name_reason
 
-        default_name = metric.key.value
-        display_name = metric.key.value("\e[0m[REPLACE ME]\e[36m")
+        suggested_name = suggested_metric_name
+        default_name = suggested_name || metric.key.value
+        display_name = metric.key.value(suggested_name || "\e[0m[REPLACE ME]\e[36m")
         empty_name = metric.key.value('')
         max_length = MAX_FILENAME_LENGTH - "#{empty_name}.yml".length
-        help_tokens = { name: default_name, count: max_length }
+        help_tokens = {
+          name: default_name,
+          count: max_length,
+          class_name: metric.instrumentation_class.to_s,
+          suggested_name: suggested_name || '(none — please enter a snake_case name)'
+        }
 
         cli.say <<~TEXT
 
-          #{input_opts[:prefix]} #{name_reason[:text]} How should we refererence this metric? #{input_required_text}
+          #{input_opts[:prefix]} #{name_reason[:text]} How should we reference this metric? #{input_required_text}
 
                       ID:  #{format_info(display_name)}
                 Filename:  #{format_info(display_name)}#{format_info('.yml')}
 
+          #{metric_name_format_hint(suggested_name)}
         TEXT
 
         metric.key = prompt_for_text('  Replace with: ', multiline: true) do |q|
           q.required true
+          # Use #default (not #value) so the suggested name is accepted on
+          # blank Enter but does NOT prefill the input buffer — prefilling
+          # would concatenate the user's typing onto the suggestion.
+          q.default suggested_name if suggested_name
           q.messages[:required?] = name_reason[:help] % help_tokens
           q.messages[:valid?] = NAME_ERROR % help_tokens
           q.validate lambda { |input|
@@ -366,6 +396,40 @@ module GitlabInternalEventsCli
         end
       end
 
+      # Inline hint printed alongside the metric name prompt. For database
+      # metrics this is critical context: users have just entered a CamelCase
+      # instrumentation class name (e.g. `CountIssuesMetric`), and without
+      # this hint they typically retype it here and hit the snake_case
+      # validation.
+      def metric_name_format_hint(suggested_name)
+        return '' unless metric.database_metric?
+
+        suggestion_line =
+          if suggested_name
+            "  Suggested: #{format_info(suggested_name)} (press Enter to accept)"
+          else
+            '  Format:    snake_case — lowercase letters, numbers, and underscores only'
+          end
+
+        <<~HINT.chomp
+          #{format_help('Use snake_case here — this is the metric key/filename, not the Ruby class name.')}
+          #{suggestion_line}
+        HINT
+      end
+
+      # For database metrics, propose a snake_case default derived from
+      # the instrumentation class. Returns nil for event metrics and when
+      # the derived value is empty or not unique in the project.
+      def suggested_metric_name
+        return unless metric.database_metric?
+
+        suggestion = metric.default_name_from_instrumentation_class
+        return if suggestion.nil? || suggestion.empty?
+        return if conflicting_key_path?(metric.key.value(suggestion))
+
+        suggestion
+      end
+
       # Helper for #prompt_for_description
       def name_requirement_reason
         if metric.filters.assigned?

data/lib/gitlab_internal_events_cli/flows/usage_viewer.rb

@@ -12,6 +12,22 @@ module GitlabInternalEventsCli
         'property' => "'string'",
         'value' => '72'
       }.freeze
+
+      CHOICES = [
+        { name: '1. ruby/rails', value: :rails },
+        { name: '2. rspec', value: :rspec },
+        { name: '3. python', value: :python },
+        { name: '4. pytest', value: :pytest },
+        { name: '5. javascript (vue)', value: :vue },
+        { name: '6. javascript (plain)', value: :js },
+        { name: '7. vue template', value: :vue_template },
+        { name: '8. haml', value: :haml },
+        { name: '9. Manual testing in GDK', value: :gdk },
+        { name: '10. Data verification in Tableau', value: :tableau },
+        { name: '11. View examples for a different event', value: :other_event },
+        { name: '12. Exit', value: :exit }
+      ].freeze
+
       DEFAULT_PROPERTY_VALUE = "'custom_value'"
 
       attr_reader :cli, :event
@@ -43,25 +59,12 @@ module GitlabInternalEventsCli
       end
 
       def prompt_for_usage_location(default = '1. ruby/rails')
-        choices = [
-          { name: '1. ruby/rails', value: :rails },
-          { name: '2. rspec', value: :rspec },
-          { name: '3. javascript (vue)', value: :vue },
-          { name: '4. javascript (plain)', value: :js },
-          { name: '5. vue template', value: :vue_template },
-          { name: '6. haml', value: :haml },
-          { name: '7. Manual testing in GDK', value: :gdk },
-          { name: '8. Data verification in Tableau', value: :tableau },
-          { name: '9. View examples for a different event', value: :other_event },
-          { name: '10. Exit', value: :exit }
-        ]
-
         usage_location = cli.select(
           'Select a use-case to view examples for:',
-          choices,
+          CHOICES,
           **select_opts,
           **filter_opts,
-          per_page: 10
+          per_page: CHOICES.count
         ) do |menu|
           menu.default default
         end
@@ -73,24 +76,30 @@ module GitlabInternalEventsCli
         when :rspec
           rspec_examples
           prompt_for_usage_location('2. rspec')
+        when :python
+          python_examples
+          prompt_for_usage_location('3. python')
+        when :pytest
+          pytest_examples
+          prompt_for_usage_location('4. pytest')
         when :haml
           haml_examples
-          prompt_for_usage_location('6. haml')
+          prompt_for_usage_location('8. haml')
         when :js
           js_examples
-          prompt_for_usage_location('4. javascript (plain)')
+          prompt_for_usage_location('6. javascript (plain)')
         when :vue
           vue_examples
-          prompt_for_usage_location('3. javascript (vue)')
+          prompt_for_usage_location('5. javascript (vue)')
         when :vue_template
           vue_template_examples
-          prompt_for_usage_location('5. vue template')
+          prompt_for_usage_location('7. vue template')
         when :gdk
           gdk_examples
-          prompt_for_usage_location('7. Manual testing in GDK')
+          prompt_for_usage_location('9. Manual testing in GDK')
         when :tableau
           service_ping_dashboard_examples
-          prompt_for_usage_location('8. Data verification in Tableau')
+          prompt_for_usage_location('10. Data verification in Tableau')
         when :other_event
           self.class.new(cli).run
         when :exit
@@ -269,6 +278,97 @@ module GitlabInternalEventsCli
         cli.say("Want to see the implementation details? See app/assets/javascripts/tracking/internal_events.js\n\n")
       end
 
+      def python_examples
+        identifier_params = identifiers.map do |identifier|
+          "    #{identifier}_id: int,"
+        end
+
+        identifier_args = identifiers.map do |identifier|
+          "        #{identifier}_id=#{identifier}_id,"
+        end
+
+        property_args = format_additional_properties do |property, value, description|
+          "        #{property}=#{value},  # #{description}"
+        end
+
+        additional_properties_arg = if property_args.any?
+                                      "        additional_properties=InternalEventAdditionalProperties(\n" \
+                                        "#{property_args.join("\n")}\n        ),"
+                                    end
+
+        track_args = ["'#{action}',", *identifier_args, additional_properties_arg].compact.join("\n        ")
+
+        function_params = [
+          *identifier_params,
+          '    internal_event_client: InternalEventsClient = Provide[',
+          '        ContainerApplication.internal_event.client',
+          '    ],'
+        ].join("\n")
+
+        imports = if property_args.any?
+                    'from lib.internal_events import InternalEventsClient, InternalEventAdditionalProperties'
+                  else
+                    'from lib.internal_events import InternalEventsClient'
+                  end
+
+        cli.say format_warning <<~TEXT
+          #{divider}
+          #{format_help('# PYTHON')}
+
+          #{imports}
+          from dependency_injector.wiring import Provide, inject
+          from ai_gateway.container import ContainerApplication
+
+          @inject
+          async def my_method(
+          #{function_params}
+          ):
+              internal_event_client.track_event(
+                  #{track_args}
+              )
+
+          #{divider}
+        TEXT
+      end
+
+      def pytest_examples
+        property_args = format_additional_properties do |property, value, description|
+          "        #{property}=#{value},  # #{description}"
+        end
+
+        additional_properties_arg = if property_args.any?
+                                      "    additional_properties = InternalEventAdditionalProperties(\n" \
+                                        "#{property_args.join("\n")}\n    )"
+                                    end
+
+        assert_args = ["event_name='#{action}',"]
+        assert_args << '    additional_properties=additional_properties,' if property_args.any?
+        identifiers.each { |id| assert_args << "    #{id}_id=#{id}_id," }
+        assert_args_str = assert_args.join("\n        ")
+
+        imports = ('from lib.internal_events import InternalEventAdditionalProperties' if property_args.any?)
+
+        cli.say format_warning <<~TEXT
+          #{divider}
+          #{format_help('# PYTEST')}
+
+          from unittest.mock import Mock
+          #{imports}
+
+          def test_#{action}(internal_event_client: Mock):
+          #{"#{additional_properties_arg}\n\n" if additional_properties_arg}    instance = YourClass()
+              instance._internal_event_client = internal_event_client
+
+              instance.trigger_action()
+
+              internal_event_client.track_event.assert_called_once_with(
+                  #{assert_args_str}
+              )
+
+          #{divider}
+        TEXT
+      end
+
       private
 
       def action

data/lib/gitlab_internal_events_cli/helpers/event_options.rb

@@ -32,6 +32,42 @@ module GitlabInternalEventsCli
         events.slice(*event_paths)
       end
 
+      def generate_ai_event_suggestion(action)
+        ai_tracking_url = format_info('https://docs.gitlab.com/development/ai_features/usage_tracking/#adding-new-event-for-tracking')
+        ai_tracking_module = format_info('Gitlab::Tracking::AiTracking')
+
+        <<~TEXT
+          #{divider}
+          #{format_info('AI Tracking')}
+
+            Events with #{format_warning('classification: duo')} are required to be registered in #{ai_tracking_module}, you can do this in the following steps:
+
+            - #{format_info('Add the event name and the unique AI feature ID:')}
+
+              #{format_info('# Tracking without metadata')}
+                events(#{action}: AI_FEATURE_ID)
+
+              or, if your event has additional metadata:
+
+              #{format_info('# Tracking with metadata')}
+                events(#{event.action}: AI_FEATURE_ID) do |context|
+                  { job_id: context['job'].id }
+                end
+
+            Learn more: #{ai_tracking_url}
+        TEXT
+      end
+
+      def generate_python_advice
+        <<~TEXT
+          \n
+          #{divider}
+          #{format_info('Python codebase')}
+
+            It seems like you are using the CLI in a python codebase. Make sure to check the python examples in the usage section.
+        TEXT
+      end
+
       private
 
       def trim_description(description)

data/lib/gitlab_internal_events_cli/helpers/files.rb

@@ -31,13 +31,20 @@ module GitlabInternalEventsCli
       end
 
       def file_saved_message(verb, filepath)
-        attributes = YAML.safe_load_file(absolute_path(filepath))
-
-        format_prefix '    ', [
-          file_saved_success_message(verb, filepath),
-          file_saved_context_message(attributes),
-          file_saved_validations_message(attributes)
-        ].compact.join("\n")
+        # Context/validation messages only apply to YAML definition files.
+        # Other artifacts (e.g. generated Ruby class & spec files for database
+        # metrics) are reported with just the success line.
+        if filepath.end_with?('.yml', '.yaml')
+          attributes = YAML.safe_load_file(absolute_path(filepath))
+
+          format_prefix '    ', [
+            file_saved_success_message(verb, filepath),
+            file_saved_context_message(attributes),
+            file_saved_validations_message(attributes)
+          ].compact.join("\n")
+        else
+          format_prefix '    ', file_saved_success_message(verb, filepath)
+        end
       end
 
       def write_to_file(filepath, content, verb)

data/lib/gitlab_internal_events_cli/metric.rb

@@ -79,7 +79,15 @@ module GitlabInternalEventsCli
     end
   end
 
-  NewMetric = Struct.new(*NEW_METRIC_FIELDS, :identifier, :actions, :key, :filters, :operator, keyword_init: true) do
+  # NOTE: :instrumentation_operation is kept on the struct but intentionally
+  # excluded from NEW_METRIC_FIELDS so it does NOT leak into the YAML output.
+  # It is only used to generate the Ruby instrumentation class file for
+  # database metrics.
+  NewMetric = Struct.new(
+    *NEW_METRIC_FIELDS,
+    :identifier, :actions, :key, :filters, :operator, :instrumentation_operation,
+    keyword_init: true
+  ) do
     def formatted_output
       extra_keys = event_metric? ? { events: events } : {}
 
@@ -107,6 +115,88 @@ module GitlabInternalEventsCli
       )
     end
 
+    # Path to the Ruby instrumentation class file generated for
+    # database metrics. Mirrors the layout used by the upstream
+    # `rails generate gitlab:usage_metric` generator.
+    def instrumentation_class_file_path
+      File.join(
+        *[
+          distribution_path,
+          'lib', 'gitlab', 'usage', 'metrics', 'instrumentations',
+          "#{instrumentation_class_underscored}.rb"
+        ].compact
+      )
+    end
+
+    # Path to the RSpec file for the generated instrumentation class.
+    def instrumentation_class_spec_file_path
+      File.join(
+        *[
+          distribution_path,
+          'spec', 'lib', 'gitlab', 'usage', 'metrics', 'instrumentations',
+          "#{instrumentation_class_underscored}_spec.rb"
+        ].compact
+      )
+    end
+
+    # Renders the body of the database instrumentation class.
+    #
+    # Based on upstream
+    # lib/generators/gitlab/usage_metric/templates/database_instrumentation_class.rb.template
+    # with one intentional deviation: the upstream Rails generator appends
+    # "Metric" to the class name from a separate argument, whereas the CLI
+    # asks the user to provide the full class name (e.g. "CountIssuesMetric")
+    # and interpolates it verbatim.
+    def instrumentation_class_content
+      <<~RUBY
+        # frozen_string_literal: true
+
+        module Gitlab
+          module Usage
+            module Metrics
+              module Instrumentations
+                class #{instrumentation_class} < DatabaseMetric
+                  operation :#{instrumentation_operation}
+
+                  relation do
+                    # Insert ActiveRecord relation here
+                  end
+                end
+              end
+            end
+          end
+        end
+      RUBY
+    end
+
+    # Renders the spec body for the generated instrumentation class.
+    #
+    # Differs from the upstream Rails template in two ways:
+    # 1. Uses the combined `a correct instrumented metric value and query`
+    #    shared example (issue gitlab-org/gitlab#569191), where upstream uses
+    #    `a correct instrumented metric value`.
+    # 2. Adds `data_source: 'database'` to the shared example params, matching
+    #    the convention used by recent database metric specs in
+    #    gitlab-org/gitlab (e.g. `count_admins_metric_spec.rb`).
+    def instrumentation_class_spec_content
+      <<~RUBY
+        # frozen_string_literal: true
+
+        require 'spec_helper'
+
+        RSpec.describe Gitlab::Usage::Metrics::Instrumentations::#{instrumentation_class}, feature_category: :service_ping do
+          let(:expected_value) { 0 }
+          let(:expected_query) { '' }
+
+          it_behaves_like 'a correct instrumented metric value and query', { time_frame: 'all', data_source: 'database' }
+        end
+      RUBY
+    end
+
+    def database_metric?
+      data_source == 'database'
+    end
+
     def distribution_path
       'ee' unless tiers.include?('free')
     end
@@ -235,6 +325,37 @@ module GitlabInternalEventsCli
     def event_metric?
       data_source == 'internal_events'
     end
+
+    # Converts a CamelCase class name like "CountIssuesMetric" to
+    # the snake_case file name stem "count_issues_metric".
+    # Implemented without ActiveSupport to keep the gem dependency-free.
+    def instrumentation_class_underscored
+      return '' unless instrumentation_class
+
+      instrumentation_class
+        .gsub('::', '/')
+        .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+        .downcase
+    end
+
+    # Derives a snake_case metric-name suggestion from the
+    # instrumentation_class so database metrics can show a sensible
+    # default in the "How should we reference this metric?" prompt.
+    #
+    # Trailing `_metric` is stripped because the metric's key_path /
+    # filename should not end in `_metric` (the class name does, but
+    # the key path describes the value, not the Ruby class).
+    #
+    # Examples:
+    #   "CountIssuesMetric"          -> "count_issues"
+    #   "CountStuffINTheDBMetric"    -> "count_stuff_in_the_db"
+    #   nil                          -> nil
+    def default_name_from_instrumentation_class
+      return unless instrumentation_class && !instrumentation_class.empty?
+
+      instrumentation_class_underscored.sub(/_metric\z/, '')
+    end
   end
 
   class Metric

data/lib/gitlab_internal_events_cli/subflows/database_metric_definer.rb

@@ -8,6 +8,20 @@ module GitlabInternalEventsCli
 
       CLASS_NAME_REGEX = /\A[a-zA-Z]+\z/
 
+      # Maps each allowed database operation to its menu description.
+      # Mirrors the operations accepted by upstream
+      # `rails generate gitlab:usage_metric --type database`.
+      DATABASE_OPERATIONS = {
+        'count' => 'count rows in the relation',
+        'distinct_count' => 'count distinct values in a column',
+        'estimate_batch_distinct_count' => 'approximate distinct count using HyperLogLog',
+        'sum' => 'sum a numeric column',
+        'average' => 'average a numeric column'
+      }.freeze
+
+      # Width used to align operation names with their descriptions in the menu.
+      OPERATION_NAME_WIDTH = DATABASE_OPERATIONS.keys.map(&:length).max
+
       attr_reader :metric
 
       def initialize(cli)
@@ -20,6 +34,7 @@ module GitlabInternalEventsCli
         metric.data_source = 'database'
 
         prompt_for_instrumentation_class
+        prompt_for_operation
         prompt_for_time_frame
       end
 
@@ -35,7 +50,10 @@ module GitlabInternalEventsCli
 
         TEXT
 
-        metric.instrumentation_class = prompt_for_text('  Instrumentation class: ') do |q|
+        # multiline: true suppresses the duplicate `Input text:` prefix that
+        # TTY::Prompt would otherwise emit on the input line below — the
+        # question text already includes the prefix via the heredoc above.
+        metric.instrumentation_class = prompt_for_text('  Instrumentation class: ', multiline: true) do |q|
           q.required true
           q.messages[:required?] = INSTRUMENTATION_CLASS_HELP
           q.messages[:valid?] = INSTRUMENTATION_CLASS_ERROR
@@ -43,6 +61,21 @@ module GitlabInternalEventsCli
         end
       end
 
+      def prompt_for_operation
+        cli.say OPERATION_INTRO
+
+        metric.instrumentation_operation = cli.select(
+          'Which operation should the metric perform?',
+          **select_opts
+        ) do |menu|
+          menu.enum '.'
+
+          DATABASE_OPERATIONS.each do |op, description|
+            menu.choice "#{op.ljust(OPERATION_NAME_WIDTH)}  -- #{description}", op
+          end
+        end
+      end
+
       def prompt_for_time_frame
         metric.time_frame = cli.multi_select(
           'For which time frames do you want the metric to be calculated? (Space to select)',

data/lib/gitlab_internal_events_cli/text/flow_advisor.rb

@@ -44,6 +44,19 @@ module GitlabInternalEventsCli
 
       TEXT
 
+      DATABASE_METRIC_EXAMPLES = <<~TEXT
+        Database metrics derive their value from an ActiveRecord relation.
+
+        Common shapes:
+            count           -- ex) total number of merge requests
+            distinct_count  -- ex) count of distinct users who created a project
+            sum             -- ex) total storage used across all projects
+            average         -- ex) average issue weight
+
+        See https://docs.gitlab.com/development/internal_analytics/metrics/metrics_instrumentation/#database-metrics
+
+      TEXT
+
       EVENT_EXISTENCE_CHECK_INSTRUCTIONS = <<~TEXT.freeze
         To determine what to do next, let's figure out if the event is already tracked & usable.
 

data/lib/gitlab_internal_events_cli/text/metric_definer.rb

@@ -5,13 +5,6 @@ module GitlabInternalEventsCli
     module MetricDefiner
       extend Helpers::Formatting
 
-      DATABASE_METRIC_NOTICE = <<~TEXT
-
-        For right now, this script can only define metrics for internal events.
-
-        For more info on instrumenting database-backed metrics, see https://docs.gitlab.com/ee/development/internal_analytics/metrics/metrics_instrumentation.html
-      TEXT
-
       ALL_METRICS_EXIST_NOTICE = <<~TEXT
 
         Looks like the potential metrics for this event either already exist or are unsupported.
@@ -81,9 +74,16 @@ module GitlabInternalEventsCli
       TEXT
 
       DATABASE_METRIC_NAME_HELP = <<~TEXT.freeze
-        #{format_warning('Required. Max %<count>s characters. Only lowercase/numbers/underscores allowed.')}
+        #{format_warning('Required. Max %<count>s characters. Only lowercase letters, numbers, and underscores are allowed.')}
+
+        This value becomes the metric's key path (ID) and YAML filename, so it must be snake_case.
+        It is intentionally different from the instrumentation class name you entered earlier:
 
-        Choose a name considering that it should be clear and discoverable.
+          Instrumentation class (Ruby, CamelCase): %<class_name>s
+          Metric name           (key/filename):    %<suggested_name>s
+
+        Tip: a good metric name describes the value being measured, not the Ruby class.
+        Press Enter to accept the suggested default, or type your own snake_case name.
       TEXT
 
       NAME_REQUIREMENT_REASONS = {
@@ -106,12 +106,13 @@ module GitlabInternalEventsCli
       }.freeze
 
       NAME_ERROR = <<~TEXT.freeze
-        #{format_warning('Input is invalid. Max %<count>s characters. Only lowercase/numbers/underscores allowed. Ensure this key path (ID) is not already in use.')}
+        #{format_warning('Input is invalid. Max %<count>s characters. Only lowercase letters, numbers, and underscores are allowed (snake_case). Ensure this key path (ID) is not already in use.')}
       TEXT
 
       INSTRUMENTATION_CLASS_INTRO = <<~TEXT.freeze
-        #{format_info('METRIC INSTRUMENATION CLASS')}
+        #{format_info('METRIC INSTRUMENTATION CLASS')}
         Choose a name for the Ruby class that will be used to calculate the metric.
+        The CLI will scaffold the class file and a matching spec file for you.
 
         #{format_info('GOOD EXAMPLES:')}
         - CountSnippetsMetric
@@ -133,6 +134,20 @@ module GitlabInternalEventsCli
       INSTRUMENTATION_CLASS_ERROR = <<~TEXT.freeze
         #{format_warning('Input is invalid. Only lowercase/uppercase letters are allowed.')}
       TEXT
+
+      OPERATION_INTRO = <<~TEXT.freeze
+        #{format_info('METRIC OPERATION')}
+        Choose how the metric should derive its value from the database relation.
+
+        See the database metrics documentation for details:
+        https://docs.gitlab.com/development/internal_analytics/metrics/metrics_instrumentation/#database-metrics
+      TEXT
+
+      DATABASE_INSTRUMENTATION_FILES_NEXT_STEPS = <<~TEXT.freeze
+        - Fill in the ActiveRecord relation inside the generated instrumentation class.
+        - Adjust `expected_value` and `expected_query` in the generated spec to match your relation.
+        - Reference: #{format_info('https://docs.gitlab.com/development/internal_analytics/metrics/metrics_instrumentation/#database-metrics')}
+      TEXT
     end
   end
 end

data/lib/gitlab_internal_events_cli/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GitlabInternalEventsCli
-  VERSION = '0.0.1'
+  VERSION = '0.1.1'
 end

data/lib/gitlab_internal_events_cli/version_checker.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module GitlabInternalEventsCli
+  class VersionChecker
+    RUBYGEMS_API_URL = 'https://rubygems.org/api/v1/gems/gitlab_internal_events_cli.json'
+    GEM_NAME = 'gitlab_internal_events_cli'
+
+    def initialize(timeout: 3)
+      @timeout = timeout
+    end
+
+    def latest_version
+      @latest_version ||= fetch_latest_version
+    end
+
+    def update_available?
+      return false unless latest_version
+
+      Gem::Version.new(latest_version) > Gem::Version.new(VERSION)
+    end
+
+    def self_update!
+      system('gem', 'install', GEM_NAME, '--no-document')
+    end
+
+    private
+
+    def fetch_latest_version
+      uri = URI(RUBYGEMS_API_URL)
+      response = Timeout.timeout(@timeout) { Net::HTTP.get(uri) }
+      gem_info = JSON.parse(response)
+
+      return unless gem_info.is_a?(Hash) && gem_info['version']
+
+      gem_info['version']
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/gitlab_internal_events_cli.rb

@@ -20,6 +20,7 @@ require_relative 'gitlab_internal_events_cli/metric'
 require_relative 'gitlab_internal_events_cli/global_state'
 require_relative 'gitlab_internal_events_cli/helpers'
 require_relative 'gitlab_internal_events_cli/gitlab_prompt'
+require_relative 'gitlab_internal_events_cli/version_checker'
 require_relative 'gitlab_internal_events_cli/cli'
 require_relative 'gitlab_internal_events_cli/text/event_definer'
 require_relative 'gitlab_internal_events_cli/text/metric_definer'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gitlab_internal_events_cli
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.1
 platform: ruby
 authors:
 - GitLab
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-09 00:00:00.000000000 Z
+date: 2026-06-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json_schemer
@@ -141,6 +141,7 @@ files:
 - lib/gitlab_internal_events_cli/text/metric_definer.rb
 - lib/gitlab_internal_events_cli/time_framed_key_path.rb
 - lib/gitlab_internal_events_cli/version.rb
+- lib/gitlab_internal_events_cli/version_checker.rb
 homepage: https://gitlab.com/gitlab-org/analytics-section/product-analytics/analytics-cli
 licenses:
 - MIT