Allow monitor script to be run without requiring snowplow-micro

doc/development/internal_analytics/internal_event_instrumentation/local_setup_and_debugging.md

@@ -9,75 +9,17 @@ info: Any user with at least the Maintainer role can merge updates to this conte
 NOTE:
 To track user interactions in the browser, Do-Not-Track (“DNT”) needs to be disabled. DNT is disabled by default for most browsers.
 
-Internal events are using a tool called Snowplow under the hood. To develop and test internal events, there are several tools related to Snowplow to test frontend and backend events:
+Internal events are using a tool called Snowplow under the hood. To develop and test internal events, there are several tools to test frontend and backend events:
 
-| Testing Tool                                 | Frontend Tracking  | Backend Tracking    | Local Development Environment | Production Environment | Production Environment |
+| Testing Tool                                 | Frontend Tracking  | Backend Tracking    | Local Development Environment | Production Environment | Shows individual events |
 |----------------------------------------------|--------------------|---------------------|-------------------------------|------------------------|------------------------|
-| Snowplow Analytics Debugger Chrome Extension | Yes | No | Yes            | Yes     | Yes     |
-| Snowplow Micro                               | Yes | Yes  | Yes            | No    | No    |
+| [Internal Events Monitor](#internal-events-monitor) | Yes | Yes | Yes  | Yes     | Yes, if running [Snowplow Micro](#snowplow-micro)    |
+| [Snowplow Micro](#snowplow-micro) | Yes | Yes  | Yes            | No    | Yes    |
+| [Manual check in GDK](#manual-check-in-gdk) | Yes | Yes | Yes            | Yes     | No     |
+| [Snowplow Analytics Debugger Chrome Extension](#snowplow-analytics-debugger-chrome-extension) | Yes | No | Yes            | Yes     | Yes     |
+| [Remote event collector](#remote-event-collector) | Yes | No | Yes   | No     | Yes     |
 
-For local development you will have to either [setup a local event collector](#setup-local-event-collector) or [configure a remote event collector](#configure-a-remote-event-collector).
-We recommend using the local setup together with the [internal events monitor](#internal-events-monitor) when actively developing new events.
-
-## Setup local event collector
-
-By default, self-managed instances do not collect event data via Snowplow. We can use [Snowplow Micro](https://docs.snowplow.io/docs/testing-debugging/snowplow-micro/what-is-micro/), a Docker based Snowplow collector, to test events locally:
-
-1. Ensure [Docker is installed and working](https://www.docker.com/get-started/).
-
-1. Enable Snowplow Micro:
-
-   ```shell
-   gdk config set snowplow_micro.enabled true
-   ```
-
-1. Optional. Snowplow Micro runs on port `9091` by default, you can change to `9092` by running:
-
-   ```shell
-   gdk config set snowplow_micro.port 9092
-   ```
-
-1. Regenerate your Procfile and YAML config by reconfiguring GDK:
-
-   ```shell
-   gdk reconfigure
-   ```
-
-1. Restart the GDK:
-
-   ```shell
-   gdk restart
-   ```
-
-1. You can now see all events being sent by your local instance in the [Snowplow Micro UI](http://localhost:9091/micro/ui) and can filter for specific events.
-
-### Introduction to Snowplow Micro UI and API
-
-<div class="video-fallback">
-  Watch the video about <a href="https://www.youtube.com/watch?v=netZ0TogNcA">Snowplow Micro</a>
-</div>
-<figure class="video-container">
-  <iframe src="https://www.youtube-nocookie.com/embed/netZ0TogNcA" frameborder="0" allowfullscreen> </iframe>
-</figure>
-
-## Configure a remote event collector
-
-On GitLab.com events are sent to a collector configured by GitLab. By default, self-managed instances do not have a collector configured and do not collect data with Snowplow.
-
-You can configure your self-managed GitLab instance to use a custom Snowplow collector.
-
-1. On the left sidebar, at the bottom, select **Admin Area**.
-1. Select **Settings > General**.
-1. Expand **Snowplow**.
-1. Select **Enable Snowplow tracking** and enter your Snowplow configuration information. For example:
-
-   | Name               | Value                         |
-   |--------------------|-------------------------------|
-   | Collector hostname | `your-snowplow-collector.net` |
-   | App ID             | `gitlab`                      |
-   | Cookie domain      | `.your-gitlab-instance.com`   |
-
-1. Select **Save changes**.
+For local development we recommend using the [internal events monitor](#internal-events-monitor) when actively developing new events.
 
 ## Internal Events Monitor
 
@@ -88,7 +30,7 @@ You can configure your self-managed GitLab instance to use a custom Snowplow col
   <iframe src="https://www.youtube-nocookie.com/embed/R7vT-VEzZOI" frameborder="0" allowfullscreen> </iframe>
 </figure>
 
-To understand how events are triggered and metrics are updated while you use the Rails app locally or `rails console`,
+To understand how events are triggered and metrics are updated while you use the GitLab application locally or `rails console`,
 you can use the monitor.
 
 Start the monitor and list one or more events that you would like to monitor. In this example we would like to monitor `i_code_review_user_create_mr`.
@@ -97,11 +39,14 @@ Start the monitor and list one or more events that you would like to monitor. In
 rails runner scripts/internal_events/monitor.rb i_code_review_user_create_mr
 ```
 
-The monitor shows two tables. The top table lists all the metrics that are defined on the `i_code_review_user_create_mr` event.
-The second right-most column shows the value of each metric when the monitor was started and the right most column shows the current value of each metric.
-The bottom table has a list selected properties of all Snowplow events that matches the event name.
+The monitor can show two tables:
+
+- The `RELEVANT METRICS` table lists all the metrics that are defined on the `i_code_review_user_create_mr` event.
+   The second right-most column shows the value of each metric when the monitor was started and the right most column shows the current value of each metric.
 
-If a new `i_code_review_user_create_mr` event is fired, the metrics values will get updated and a new event will appear in the `SNOWPLOW EVENTS` table.
+- The `SNOWPLOW EVENTS` table lists a selection of properties from all Snowplow events that match the event name. This table is only visible if you also set up [Snowplow Micro](#snowplow-micro).
+
+If a new `i_code_review_user_create_mr` event is fired, the metrics values get updated and a new event appears in the `SNOWPLOW EVENTS` table.
 
 The monitor looks like below.
 
@@ -130,7 +75,48 @@ Monitored events: i_code_review_user_create_mr
 +------------------------------+--------------------------+---------+--------------+------------+---------+
 ```
 
-## Manually check the relevant metric values in GDK
+## Snowplow Micro
+
+By default, self-managed instances do not collect event data through Snowplow. We can use [Snowplow Micro](https://docs.snowplow.io/docs/testing-debugging/snowplow-micro/what-is-micro/), a Docker based Snowplow collector, to test events locally:
+
+1. Ensure [Docker is installed and working](https://www.docker.com/get-started/).
+
+1. Enable Snowplow Micro:
+
+   ```shell
+   gdk config set snowplow_micro.enabled true
+   ```
+
+1. Optional. Snowplow Micro runs on port `9091` by default, you can change to `9092` by running:
+
+   ```shell
+   gdk config set snowplow_micro.port 9092
+   ```
+
+1. Regenerate your Procfile and YAML configuration by reconfiguring GDK:
+
+   ```shell
+   gdk reconfigure
+   ```
+
+1. Restart the GDK:
+
+   ```shell
+   gdk restart
+   ```
+
+1. You can now see all events being sent by your local instance in the [Snowplow Micro UI](http://localhost:9091/micro/ui) and can filter for specific events.
+
+### Introduction to Snowplow Micro UI and API
+
+<div class="video-fallback">
+  Watch the video about <a href="https://www.youtube.com/watch?v=netZ0TogNcA">Snowplow Micro</a>
+</div>
+<figure class="video-container">
+  <iframe src="https://www.youtube-nocookie.com/embed/netZ0TogNcA" frameborder="0" allowfullscreen> </iframe>
+</figure>
+
+## Manual check in GDK
 
 As a quick test of whether an event is getting triggered & metric is updated, you can check the latest values in the rails console.
 Make sure to load the helpers below so that the most recent events & records are included in the output.
@@ -157,3 +143,22 @@ It works in production, staging, and local development environments. It is espec
 1. Install the [Snowplow Analytics Debugger](https://chromewebstore.google.com/detail/snowplow-analytics-debugg/jbnlcgeengmijcghameodeaenefieedm) Chrome browser extension.
 1. Open Chrome DevTools to the Snowplow Debugger tab.
 1. Any event triggered on a GitLab page should appear in the Snowplow Debugger tab.
+
+## Remote event collector
+
+On GitLab.com events are sent to a collector configured by GitLab. By default, self-managed instances do not have a collector configured and do not collect data with Snowplow.
+
+You can configure your self-managed GitLab instance to use a custom Snowplow collector.
+
+1. On the left sidebar, at the bottom, select **Admin Area**.
+1. Select **Settings > General**.
+1. Expand **Snowplow**.
+1. Select **Enable Snowplow tracking** and enter your Snowplow configuration information. For example if your custom snowplow collector is available at `your-snowplow-collector.net`:
+
+   | Name               | Value                         |
+   |--------------------|-------------------------------|
+   | Collector hostname | `your-snowplow-collector.net` |
+   | App ID             | `gitlab`                      |
+   | Cookie domain      | `.your-gitlab-instance.com`   |
+
+1. Select **Save changes**.

scripts/internal_events/cli/usage_viewer.rb

@@ -349,14 +349,16 @@ def gdk_examples
 
       cli.say <<~TEXT
         #{divider}
-        #{format_help('# TERMINAL -- monitor events sent to snowplow & changes to service ping metrics as they occur')}
+        #{format_help('# TERMINAL -- monitor events & changes to service ping metrics as they occur')}
 
-        1. Configure gdk with snowplow micro https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/snowplow_micro.md
-        2. From `gitlab/` directory, run the monitor script:
+        1. From `gitlab/` directory, run the monitor script:
 
         #{format_warning("bin/rails runner scripts/internal_events/monitor.rb #{event.action}")}
 
-        3. View all snowplow events in the browser at http://localhost:9091/micro/all (or whichever hostname & port you configured)
+        2. View metric updates within the terminal
+
+        3. [Optional] Configure gdk with snowplow micro to see individual events: https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/snowplow_micro.md
+
         #{divider}
         #{format_help('# RAILS CONSOLE -- generate service ping payload, including most recent usage data')}
 

scripts/internal_events/monitor.rb

@@ -107,6 +107,17 @@ def generate_snowplow_table
   )
 end
 
+def generate_snowplow_placeholder
+  Terminal::Table.new(
+    title: 'SNOWPLOW EVENTS',
+    rows: [
+      ["Could not connect to Snowplow Micro."],
+      ["Please follow these instruction to set up Snowplow Micro:"],
+      ["https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/snowplow_micro.md"]
+    ]
+  )
+end
+
 def relevant_events_from_args(metric_definition)
   metric_definition.events.keys.intersection(ARGV).sort
 end
@@ -143,9 +154,9 @@ def generate_metrics_table
   )
 end
 
-def render_screen(paused)
+def render_screen(paused, snowplow_available)
   metrics_table = generate_metrics_table
-  events_table = generate_snowplow_table
+  events_table = snowplow_available ? generate_snowplow_table : generate_snowplow_placeholder
 
   print TTY::Cursor.clear_screen
   print TTY::Cursor.move_to(0, 0)
@@ -155,7 +166,6 @@ def render_screen(paused)
   puts
 
   puts metrics_table
-
   puts events_table
 
   puts
@@ -163,13 +173,12 @@ def render_screen(paused)
   puts "Press \"q\" to quit"
 end
 
+snowplow_available = true
+
 begin
   snowplow_data
 rescue Errno::ECONNREFUSED
-  puts "Could not connect to Snowplow Micro."
-  puts "Please follow these instruction to set up Snowplow Micro:"
-  puts "https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/snowplow_micro.md"
-  exit 1
+  snowplow_available = false
 end
 
 reader = TTY::Reader.new
@@ -180,12 +189,12 @@ def render_screen(paused)
     case reader.read_keypress(nonblock: true)
     when 'p'
       paused = !paused
-      render_screen(paused)
+      render_screen(paused, snowplow_available)
     when 'q'
       break
     end
 
-    render_screen(paused) unless paused
+    render_screen(paused, snowplow_available) unless paused
 
     sleep 1
   end