Add an option to track_event API to send events to Snowplow

Changelog: changed

doc/api/usage_data.md

@@ -192,3 +192,56 @@ Sample response:
   },
 ...
 ```
+
+## Events Tracking API
+
+Tracks internal events in GitLab. Requires a personal access token with the `api` or `ai_workflows` scope.
+
+To track events to Snowplow, set the `send_to_snowplow` parameter to `true`.
+
+Example request:
+
+```shell
+curl --header "PRIVATE-TOKEN: <your_access_token>" \
+     --header "Content-Type: application/json" \
+     --request POST \
+     --data '{
+       "event": "mr_name_changed",
+       "send_to_snowplow": true,
+       "namespace_id": 1,
+       "project_id": 1,
+       "additional_properties": {
+         "lang": "eng"
+       }
+     }' \
+     "https://gitlab.example.com/api/v4/usage_data/track_event"
+```
+
+If multiple events tracking is required, send an array of events to the `/track_events` endpoint:
+
+```shell
+curl --header "PRIVATE-TOKEN: <your_access_token>" \
+     --header "Content-Type: application/json" \
+     --request POST \
+     --data '{
+       "events": [
+         {
+           "event": "mr_name_changed",
+           "namespace_id": 1,
+           "project_id": 1,
+           "additional_properties": {
+             "lang": "eng"
+           }
+         },
+         {
+           "event": "mr_name_changed",
+           "namespace_id": 2,
+           "project_id": 2,
+           "additional_properties": {
+             "lang": "eng"
+           }
+         }
+       ]
+     }' \
+     "https://gitlab.example.com/api/v4/usage_data/track_events"
+```

doc/development/internal_analytics/internal_event_instrumentation/quick_start.md

@@ -564,6 +564,11 @@ describe('DeleteApplication', () => {
 });
 ```
 
+### Using Internal Events API
+
+You can also use our API to track events from other systems connected to a GitLab instance.
+See the [Usage Data API documentation](../../../api/usage_data.md#events-tracking-api) for more information.
+
 ### Internal Events on other systems
 
 Apart from the GitLab codebase, we are using Internal Events for the systems listed below.

lib/api/usage_data.rb

@@ -20,6 +20,8 @@ class UsageData < ::API::Base
           documentation: { example: 1234 }
         optional :additional_properties, type: Hash, desc: 'Additional properties to be tracked',
           documentation: { example: { label: 'login_button', value: 1 } }
+        optional :send_to_snowplow, type: Boolean, desc: 'Send the tracked event to Snowplow',
+          documentation: { example: true, default: false }
       end
 
       def process_event(params)
@@ -27,12 +29,13 @@ def process_event(params)
         namespace_id = params[:namespace_id]
         project_id = params[:project_id]
         additional_properties = params.fetch(:additional_properties, {}).symbolize_keys
+        send_snowplow_event = !!params[:send_to_snowplow]
 
         Gitlab::Tracking::AiTracking.track_event(event_name, additional_properties.merge(user: current_user))
 
         track_event(
           event_name,
-          send_snowplow_event: false,
+          send_snowplow_event: send_snowplow_event,
           user: current_user,
           namespace_id: namespace_id,
           project_id: project_id,

spec/requests/api/usage_data_spec.rb

@@ -280,6 +280,75 @@
           end
         end
       end
+
+      describe 'send_to_snowplow param' do
+        it 'does not send the event to snowplow when send_to_snowplow is false' do
+          expect(Gitlab::InternalEvents).to receive(:track_event)
+            .with(
+              known_event,
+              send_snowplow_event: false,
+              user: user,
+              namespace: namespace,
+              project: project,
+              additional_properties: additional_properties
+            )
+
+          post api(endpoint, user), params: {
+            event: known_event,
+            namespace_id: namespace.id,
+            project_id: project.id,
+            additional_properties: additional_properties,
+            send_to_snowplow: false
+          }
+
+          expect(response).to have_gitlab_http_status(:ok)
+        end
+
+        it 'sends event to Snowplow when send_to_snowplow is true' do
+          expect(Gitlab::InternalEvents).to receive(:track_event)
+            .with(
+              known_event,
+              send_snowplow_event: true,
+              user: user,
+              namespace: namespace,
+              project: project,
+              additional_properties: additional_properties
+            )
+
+          post api(endpoint, user), params:
+            {
+              event: known_event,
+              namespace_id: namespace.id,
+              project_id: project.id,
+              additional_properties: additional_properties,
+              send_to_snowplow: true
+            }
+
+          expect(response).to have_gitlab_http_status(:ok)
+        end
+
+        it 'does not send event to Snowplow by default' do
+          expect(Gitlab::InternalEvents).to receive(:track_event)
+            .with(
+              known_event,
+              send_snowplow_event: false,
+              user: user,
+              namespace: namespace,
+              project: project,
+              additional_properties: additional_properties
+            )
+
+          post api(endpoint, user), params:
+            {
+              event: known_event,
+              namespace_id: namespace.id,
+              project_id: project.id,
+              additional_properties: additional_properties
+            }
+
+          expect(response).to have_gitlab_http_status(:ok)
+        end
+      end
     end
   end
 
@@ -305,16 +374,12 @@
     end
 
     context 'with the amount events greater than the limit' do
-      let(:params) do
-        {
-          events: Array.new(API::UsageData::MAXIMUM_TRACKED_EVENTS * 2) { { event: event } }
-        }
-      end
+      let(:params) { { events: Array.new(API::UsageData::MAXIMUM_TRACKED_EVENTS * 2) { { event: event } } } }
 
       it 'returns bad request' do
         expect(Gitlab::InternalEvents).not_to receive(:track_event)
 
-        post(api(endpoint, user), params: params)
+        post api(endpoint, user), params: params
 
         expect(response).to have_gitlab_http_status(:bad_request)
       end