gitlab_internal_events_cli 0.0.1

data/lib/gitlab_internal_events_cli/flows/usage_viewer.rb

@@ -0,0 +1,474 @@
+# frozen_string_literal: true
+
+# Entrypoint for flow to print examples of how to trigger an
+# event in different languages & different methods of testing
+module GitlabInternalEventsCli
+  module Flows
+    class UsageViewer
+      include Helpers
+
+      PROPERTY_EXAMPLES = {
+        'label' => "'string'",
+        'property' => "'string'",
+        'value' => '72'
+      }.freeze
+      DEFAULT_PROPERTY_VALUE = "'custom_value'"
+
+      attr_reader :cli, :event
+
+      def initialize(cli, event_path = nil, event = nil)
+        @cli = cli
+        @event = event
+        @selected_event_path = event_path
+      end
+
+      def run
+        prompt_for_eligible_event
+        prompt_for_usage_location
+      end
+
+      def prompt_for_eligible_event
+        return if event
+
+        event_details = events_by_filepath
+
+        @selected_event_path = cli.select(
+          'Show examples for which event?',
+          get_event_options(event_details),
+          **select_opts,
+          **filter_opts
+        )
+
+        @event = event_details[@selected_event_path]
+      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,
+          **select_opts,
+          **filter_opts,
+          per_page: 10
+        ) do |menu|
+          menu.default default
+        end
+
+        case usage_location
+        when :rails
+          rails_examples
+          prompt_for_usage_location('1. ruby/rails')
+        when :rspec
+          rspec_examples
+          prompt_for_usage_location('2. rspec')
+        when :haml
+          haml_examples
+          prompt_for_usage_location('6. haml')
+        when :js
+          js_examples
+          prompt_for_usage_location('4. javascript (plain)')
+        when :vue
+          vue_examples
+          prompt_for_usage_location('3. javascript (vue)')
+        when :vue_template
+          vue_template_examples
+          prompt_for_usage_location('5. vue template')
+        when :gdk
+          gdk_examples
+          prompt_for_usage_location('7. Manual testing in GDK')
+        when :tableau
+          service_ping_dashboard_examples
+          prompt_for_usage_location('8. Data verification in Tableau')
+        when :other_event
+          self.class.new(cli).run
+        when :exit
+          cli.say(feedback_notice)
+        end
+      end
+
+      def rails_examples
+        identifier_args = identifiers.map do |identifier|
+          "  #{identifier}: #{identifier}"
+        end
+
+        property_args = format_additional_properties do |property, value, description|
+          "    #{property}: #{value}, # #{description}"
+        end
+
+        if property_args.any?
+          property_args.last.sub!(',', '')
+          property_arg = "  additional_properties: {\n#{property_args.join("\n")}\n  }"
+        end
+
+        args = ["'#{action}'", *identifier_args, property_arg].compact.join(",\n")
+        args = "\n  #{args}\n" if args.lines.count > 1
+
+        cli.say format_warning <<~TEXT
+          #{divider}
+          #{format_help('# RAILS')}
+
+          include Gitlab::InternalEventsTracking
+
+          track_internal_event(#{args})
+
+          #{divider}
+        TEXT
+      end
+
+      def rspec_examples
+        cli.say format_warning <<~TEXT
+          #{divider}
+          #{format_help('# RSPEC')}
+
+          #{format_warning(rspec_composable_matchers)}
+
+          #{divider}
+        TEXT
+      end
+
+      def haml_examples
+        property_args = format_additional_properties do |property, value, _|
+          "event_#{property}: #{value}"
+        end
+
+        args = ["event_tracking: '#{action}'", *property_args].join(', ')
+
+        cli.say <<~TEXT
+          #{divider}
+          #{format_help('# HAML -- ON-CLICK')}
+
+          .inline-block{ #{format_warning("data: { #{args} }")} }
+            = _('Important Text')
+
+          #{divider}
+          #{format_help('# HAML -- COMPONENT ON-CLICK')}
+
+          = render Pajamas::ButtonComponent.new(button_options: { #{format_warning("data: { #{args} }")} })
+
+          #{divider}
+          #{format_help('# HAML -- COMPONENT ON-LOAD')}
+
+          = render Pajamas::ButtonComponent.new(button_options: { #{format_warning("data: { event_tracking_load: true, #{args} }")} })
+
+          #{divider}
+        TEXT
+
+        cli.say("Want to see the implementation details? See app/assets/javascripts/tracking/internal_events.js\n\n")
+      end
+
+      def vue_template_examples
+        on_click_args = template_formatted_args('data-event-tracking', indent: 2)
+        on_load_args = template_formatted_args('data-event-tracking-load', indent: 2)
+
+        cli.say <<~TEXT
+          #{divider}
+          #{format_help('// VUE TEMPLATE -- ON-CLICK')}
+
+          <script>
+          import { GlButton } from '@gitlab/ui';
+
+          export default {
+            components: { GlButton }
+          };
+          </script>
+
+          <template>
+            <gl-button#{on_click_args}
+              Click Me
+            </gl-button>
+          </template>
+
+          #{divider}
+          #{format_help('// VUE TEMPLATE -- ON-LOAD')}
+
+          <script>
+          import { GlButton } from '@gitlab/ui';
+
+          export default {
+            components: { GlButton }
+          };
+          </script>
+
+          <template>
+            <gl-button#{on_load_args}
+              Click Me
+            </gl-button>
+          </template>
+
+          #{divider}
+        TEXT
+
+        cli.say("Want to see the implementation details? See app/assets/javascripts/tracking/internal_events.js\n\n")
+      end
+
+      def js_examples
+        args = js_formatted_args(indent: 2)
+
+        cli.say <<~TEXT
+          #{divider}
+          #{format_help('// FRONTEND -- RAW JAVASCRIPT')}
+
+          #{format_warning("import { InternalEvents } from '~/tracking';")}
+
+          export const performAction = () => {
+            #{format_warning("InternalEvents.trackEvent#{args}")}
+
+            return true;
+          };
+
+          #{divider}
+        TEXT
+
+        # https://docs.snowplow.io/docs/understanding-your-pipeline/schemas/
+        cli.say("Want to see the implementation details? See app/assets/javascripts/tracking/internal_events.js\n\n")
+      end
+
+      def vue_examples
+        args = js_formatted_args(indent: 6)
+
+        cli.say <<~TEXT
+          #{divider}
+          #{format_help('// VUE')}
+
+          <script>
+          #{format_warning("import { InternalEvents } from '~/tracking';")}
+          import { GlButton } from '@gitlab/ui';
+
+          #{format_warning('const trackingMixin = InternalEvents.mixin();')}
+
+          export default {
+            components: { GlButton },
+            #{format_warning('mixins: [trackingMixin]')},
+            methods: {
+              performAction() {
+                #{format_warning("this.trackEvent#{args}")}
+              },
+            },
+          };
+          </script>
+
+          <template>
+            <gl-button @click=performAction>Click Me</gl-button>
+          </template>
+
+          #{divider}
+        TEXT
+
+        cli.say("Want to see the implementation details? See app/assets/javascripts/tracking/internal_events.js\n\n")
+      end
+
+      private
+
+      def action
+        event['action']
+      end
+
+      def identifiers
+        Array(event['identifiers']).tap do |ids|
+          # We always auto assign namespace if project is provided
+          ids.delete('namespace') if ids.include?('project')
+        end
+      end
+
+      def additional_properties
+        Array(event['additional_properties'])
+      end
+
+      def format_additional_properties
+        additional_properties.map do |property, details|
+          example_value = PROPERTY_EXAMPLES.fetch(property, DEFAULT_PROPERTY_VALUE)
+          description = details['description'] || 'TODO'
+
+          yield(property, example_value, description)
+        end
+      end
+
+      def rspec_composable_matchers
+        identifier_args = identifiers.map do |identifier|
+          "    #{identifier}: #{identifier}"
+        end
+
+        property_args = format_additional_properties do |property, value|
+          "  #{property}: #{value}"
+        end
+
+        if property_args.any?
+          property_args = format_prefix '    ', <<~TEXT.chomp
+            additional_properties: {
+            #{property_args.join(",\n")}
+            }
+          TEXT
+        end
+
+        args = []
+        args += [*identifier_args] unless identifier_args.empty?
+        args += [*property_args] unless property_args.empty?
+        args = args.join(",\n")
+
+        unless args.empty?
+          args = <<~TEXT.chomp
+            .with(
+            #{args}
+              )
+          TEXT
+        end
+
+        non_sum_metrics_list = []
+        sum_metrics_list = []
+        related_metrics.map do |metric|
+          target_array = metric.operator == 'sum(value)' ? sum_metrics_list : non_sum_metrics_list
+          target_array << "    '#{metric.key_path}'"
+        end
+
+        metrics_list = ''
+        unless non_sum_metrics_list.empty?
+          metrics_list += <<~TEXT.chomp
+            .and increment_usage_metrics(
+            #{non_sum_metrics_list.join(",\n")}
+              )
+          TEXT
+        end
+
+        unless sum_metrics_list.empty?
+          metrics_list += <<~TEXT.chomp
+            .and increment_usage_metrics(
+            #{sum_metrics_list.join(",\n")}
+              ).by(#{PROPERTY_EXAMPLES.fetch('value')})
+          TEXT
+        end
+
+        <<~TEXT.chomp
+          it "triggers an internal event" do
+            expect { subject }.to trigger_internal_events('#{action}')#{args}#{metrics_list}
+          end
+        TEXT
+      end
+
+      def js_formatted_args(indent:)
+        return "('#{action}');" if additional_properties.none?
+
+        property_args = format_additional_properties do |property, value, description|
+          "    #{property}: #{value}, // #{description}"
+        end
+
+        [
+          '(',
+          "  '#{action}',",
+          '  {',
+          *property_args,
+          '  },',
+          ');'
+        ].join("\n#{' ' * indent}")
+      end
+
+      def service_ping_metrics_info
+        product_group = related_metrics.map(&:product_group).uniq
+
+        <<~TEXT
+          #{product_group.map { |group| "#{group}: #{format_info(metric_exploration_group_path(group, find_stage(group)))}" }.join("\n")}
+
+          #{divider}
+          #{format_help("# METRIC TRENDS -- view data for a service ping metric for #{event.action}")}
+
+          #{related_metrics.map { |metric| "#{metric.key_path}: #{format_info(metric_trend_path(metric.key_path))}" }.join("\n")}
+        TEXT
+      end
+
+      def service_ping_no_metric_info
+        <<~TEXT
+          #{format_help("# Warning: There are no metrics for #{event.action} yet.")}
+          #{event.product_group}: #{format_info(metric_exploration_group_path(event.product_group, find_stage(event.product_group)))}
+        TEXT
+      end
+
+      def template_formatted_args(data_attr, indent:)
+        return " #{data_attr}=\"#{action}\">" if additional_properties.none?
+
+        spacer = ' ' * indent
+        property_args = format_additional_properties do |property, value, _|
+          "  data-event-#{property}=#{value.tr("'", '"')}"
+        end
+
+        args = [
+          '',
+          "  #{data_attr}=\"#{action}\"",
+          *property_args
+        ].join("\n#{spacer}")
+
+        "#{format_warning(args)}\n#{spacer}>"
+      end
+
+      def related_metrics
+        cli.global.metrics.select { |metric| metric.actions&.include?(event.action) }
+      end
+
+      def service_ping_dashboard_examples
+        cli.say <<~TEXT
+          #{divider}
+          #{format_help('# GROUP DASHBOARDS -- view all service ping metrics for a specific group')}
+
+          #{related_metrics.any? ? service_ping_metrics_info : service_ping_no_metric_info}
+          #{divider}
+          Note: The metric dashboard links can also be accessed from #{format_info('https://metrics.gitlab.com/')}
+
+          Not what you're looking for? Check this doc:
+            - #{format_info('https://docs.gitlab.com/ee/development/internal_analytics/#data-discovery')}
+
+        TEXT
+      end
+
+      def gdk_examples
+        key_paths = related_metrics.map(&:key_path)
+
+        cli.say <<~TEXT
+          #{divider}
+          #{format_help('# TERMINAL -- monitor events & changes to service ping metrics as they occur')}
+
+          1. From `gitlab/` directory, run the monitor script:
+
+          #{format_warning("bin/rails runner scripts/internal_events/monitor.rb #{event.action}")}
+
+          2. View metric updates within the terminal
+
+          3. [Optional] Configure gdk with snowplow micro to see individual events: https://gitlab-org.gitlab.io/gitlab-development-kit/howto/snowplow_micro/
+
+          #{divider}
+          #{format_help('# RAILS CONSOLE -- generate service ping payload, including most recent usage data')}
+
+          #{format_warning("require_relative 'spec/support/helpers/service_ping_helpers.rb'")}
+
+          #{format_help('# Get current value of a metric')}
+          #{
+            if key_paths.any?
+              key_paths.map { |key_path| format_warning("ServicePingHelpers.get_current_usage_metric_value('#{key_path}')") }.join("\n")
+            else
+              format_help("# Warning: There are no metrics for #{event.action} yet. When there are, replace <key_path> below.\n") +
+              format_warning('ServicePingHelpers.get_current_usage_metric_value(<key_path>)')
+            end
+          }
+
+          #{format_help('# View entire service ping payload')}
+          #{format_warning('ServicePingHelpers.get_current_service_ping_payload')}
+          #{divider}
+          Need to test something else? Check these docs:
+          - https://docs.gitlab.com/ee/development/internal_analytics/internal_event_instrumentation/local_setup_and_debugging.html
+          - https://docs.gitlab.com/ee/development/internal_analytics/service_ping/troubleshooting.html
+          - https://docs.gitlab.com/ee/development/internal_analytics/review_guidelines.html
+
+        TEXT
+      end
+    end
+  end
+end

data/lib/gitlab_internal_events_cli/gitlab_prompt.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module GitlabInternalEventsCli
+  class GitlabPrompt < SimpleDelegator
+    def global
+      @global ||= GlobalState.new
+    end
+  end
+end

data/lib/gitlab_internal_events_cli/global_state.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+# Helpers for shared state across all CLI flows
+module GitlabInternalEventsCli
+  class GlobalState
+    def events
+      @events ||= load_definitions(
+        Event,
+        GitlabInternalEventsCli::NEW_EVENT_FIELDS,
+        all_event_paths
+      )
+    end
+
+    def metrics
+      @metrics ||= begin
+        loaded_files = load_definitions(
+          Metric,
+          GitlabInternalEventsCli::NEW_METRIC_FIELDS,
+          all_metric_paths
+        )
+
+        loaded_files.flat_map do |metric|
+          # copy logic of Gitlab::Usage::MetricDefinition
+          next metric unless metric.time_frame.is_a?(Array)
+
+          metric.time_frame.map do |time_frame|
+            current_metric = metric.dup
+            current_metric.time_frame = time_frame
+            current_metric.key_path = TimeFramedKeyPath.build(current_metric.key_path, time_frame)
+            current_metric
+          end
+        end
+      end
+    end
+
+    def reload_definitions
+      @events = nil
+      @metrics = nil
+    end
+
+    private
+
+    def all_event_paths
+      GitlabInternalEventsCli.configuration.resolve_event_paths
+    end
+
+    def all_metric_paths
+      GitlabInternalEventsCli.configuration.resolve_metric_paths
+    end
+
+    def load_definitions(klass, fields, paths)
+      paths.filter_map do |path|
+        details = YAML.safe_load_file(path)
+        relevant_fields = fields.map(&:to_s)
+
+        relative_path = path.sub("#{GitlabInternalEventsCli.configuration.project_root}/", '')
+        klass.parse(**details.slice(*relevant_fields), file_path: relative_path)
+      rescue StandardError => e
+        puts "\n\n\e[31mEncountered an error while loading #{path}: #{e.message}\e[0m\n\n\n"
+      end
+    end
+  end
+end

data/lib/gitlab_internal_events_cli/helpers/cli_inputs.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+# Helpers related to configuration of TTY::Prompt prompts
+module GitlabInternalEventsCli
+  module Helpers
+    module CliInputs
+      def prompt_for_array_selection(message, choices, default = nil, **opts, &formatter)
+        formatter ||= ->(choice) { choice.sort.join(', ') }
+
+        choices = choices.map do |choice|
+          { name: formatter.call(choice), value: choice }
+        end
+
+        cli.select(message, choices, **select_opts, **opts) do |menu|
+          menu.enum '.'
+          menu.default formatter.call(default) if default
+        end
+      end
+
+      # Prompts the user to input text. Prefer this over calling cli#ask directly (so styling is consistent).
+      #
+      #
+      # @return [String, nil] user-provided text
+      # @param message [String] a single line prompt/question or last line of a prompt
+      # @param value [String, nil] prepopulated as the answer which user can accept/modify
+      # @option multiline [Boolean] indicates that any help text or prompt prefix will be printed on another line
+      #                             before calling #prompt_for_text -->  ex) see MetricDefiner#prompt_for_description
+      # @yield [TTY::Prompt::Question]
+      # @see https://github.com/piotrmurach/tty-prompt?tab=readme-ov-file#21-ask
+      def prompt_for_text(message, value = nil, multiline: false, **opts)
+        prompt = message.dup # mutable for concat in #ask callback
+
+        options = { **input_opts, **opts }
+        value ||= options.delete(:value)
+        options.delete(:prefix) if multiline
+
+        cli.ask(prompt, **options) do |q|
+          q.value(value) if value
+
+          yield q if block_given?
+
+          if multiline
+            # wrap error messages so they render nicely with prompt
+            q.messages.each do |key, error|
+              closing_text = "\n#{format_error('<<|')}" if error.lines.length > 1
+
+              q.messages[key] = [error, closing_text, "\n\n\n"].join
+            end
+          else
+            # append help text only if this line includes the formatted 'prompt' prefix,
+            # otherwise depend on the caller to print the help text if needed
+            prompt.concat(" #{q.required ? input_required_text : input_optional_text(value)}")
+          end
+        end
+      end
+
+      def input_opts
+        { prefix: format_prompt('Input text: ') }
+      end
+
+      def yes_no_opts
+        { prefix: format_prompt('Yes/No: ') }
+      end
+
+      # Provide to cli#select as kwargs for consistent style/ux
+      def select_opts
+        {
+          prefix: format_prompt('Select one: '),
+          cycle: true,
+          show_help: :always,
+          # Strip colors so #format_selection is applied uniformly
+          active_color: ->(choice) { format_selection(clear_format(choice)) }
+        }
+      end
+
+      # Provide to cli#multiselect as kwargs for consistent style/ux
+      def multiselect_opts
+        {
+          **select_opts,
+          prefix: format_prompt('Select multiple: '),
+          min: 1,
+          help: '(Space to select, Enter to submit, ↑/↓/←/→ to move, Ctrl+A|R to select all|none, letters to filter)'
+        }
+      end
+
+      # Accepts a number of lines occupied by text, so remaining
+      # screen real estate can be filled with select options
+      def filter_opts(header_size: nil)
+        {
+          filter: true,
+          per_page: header_size ? [(window_height - header_size), 10].max : 30
+        }
+      end
+
+      # Creates divider to be passed to a select or multiselect
+      # as a menu item. Use with #format_disabled_options_as_dividers
+      # for best formatting.
+      def select_option_divider(text)
+        { name: "-- #{text} --", value: nil, disabled: '' }
+      end
+
+      # Styling all disabled options in a menu without indication
+      # of being a selectable option
+      # @param select_menu [TTY::Prompt]
+      def format_disabled_options_as_dividers(select_menu)
+        select_menu.symbols(cross: '')
+      end
+
+      # For use when menu options are disabled by being grayed out
+      def disabled_format_callback
+        proc { |menu| menu.symbols(cross: format_help('✘')) }
+      end
+
+      # Help text to use with required, multiline cli#ask prompts.
+      # Otherwise, prefer #prompt_for_text.
+      def input_required_text
+        format_help('(leave blank for help)')
+      end
+
+      # Help text to use with optional, multiline cli#ask prompts.
+      # Otherwise, prefer #prompt_for_text.
+      def input_optional_text(value)
+        format_help("(enter to #{value ? 'submit' : 'skip'})")
+      end
+
+      def disableable_option(value:, disabled:, name: nil)
+        should_disable = yield
+        name ||= value
+
+        {
+          value: value,
+          name: (should_disable ? format_help(name) : name),
+          disabled: (disabled if should_disable)
+        }
+      end
+    end
+  end
+end