Merge branch '235954-add-helper-for-tracking-redis-hll-events-for-api' into 'master'

Add API helper for tracking Redis HLL events

Closes #235954

See merge request gitlab-org/gitlab!39802

doc/development/telemetry/usage_ping.md

@@ -288,6 +288,29 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd) and [PF
    end
    ```
 
+1. Track event in API using `increment_unique_values(event_name, values)` helper method.
+
+   In order to be able to track the event, Usage Ping must be enabled and the event feature `usage_data_<event_name>` must be enabled.
+
+   Arguments:
+
+   - `event_name`: event name.
+   - `values`: values counted, one value or array of values.
+
+   Example usage:
+
+   ```ruby
+   get ':id/registry/repositories' do
+     repositories = ContainerRepositoriesFinder.new(
+       user: current_user, subject: user_group
+     ).execute
+
+     increment_unique_values('i_list_repositories', current_user.id)
+
+     present paginate(repositories), with: Entities::ContainerRegistry::Repository, tags: params[:tags], tags_count: params[:tags_count]
+   end
+   ```
+
 1. Track event using base module `Gitlab::UsageDataCounters::HLLRedisCounter.track_event(entity_id, event_name)`.
 
    Arguments:

lib/api/helpers.rb

@@ -537,6 +537,20 @@ module API
       )
     end
 
+    # @param event_name [String] the event name
+    # @param values [Array|String] the values counted
+    def increment_unique_values(event_name, values)
+      return unless values.present?
+
+      feature_name = "usage_data_#{event_name}"
+      return unless Feature.enabled?(feature_name)
+      return unless Gitlab::CurrentSettings.usage_ping_enabled?
+
+      Gitlab::UsageDataCounters::HLLRedisCounter.track_event(values, event_name)
+    rescue => error
+      Gitlab::AppLogger.warn("Redis tracking event failed for event: #{event_name}, message: #{error.message}")
+    end
+
     def with_api_params(&block)
       yield({ api: true, request: request })
     end

spec/lib/api/helpers_spec.rb

@@ -189,6 +189,62 @@ RSpec.describe API::Helpers do
     end
   end
 
+  describe '#increment_unique_values' do
+    let(:value) { '9f302fea-f828-4ca9-aef4-e10bd723c0b3' }
+    let(:event_name) { 'my_event' }
+    let(:unknown_event) { 'unknown' }
+    let(:feature) { "usage_data_#{event_name}" }
+
+    context 'with feature enabled' do
+      before do
+        stub_feature_flags(feature => true)
+      end
+
+      it 'tracks redis hll event' do
+        stub_application_setting(usage_ping_enabled: true)
+
+        expect(Gitlab::UsageDataCounters::HLLRedisCounter).to receive(:track_event).with(value, event_name)
+
+        subject.increment_unique_values(event_name, value)
+      end
+
+      it 'does not track event usage ping is not enabled' do
+        stub_application_setting(usage_ping_enabled: false)
+        expect(Gitlab::UsageDataCounters::HLLRedisCounter).not_to receive(:track_event)
+
+        subject.increment_unique_values(event_name, value)
+      end
+
+      it 'logs an exception for unknown event' do
+        stub_application_setting(usage_ping_enabled: true)
+
+        expect(Gitlab::AppLogger).to receive(:warn).with("Redis tracking event failed for event: #{unknown_event}, message: Unknown event #{unknown_event}")
+
+        subject.increment_unique_values(unknown_event, value)
+      end
+
+      it 'does not track event for nil values' do
+        stub_application_setting(usage_ping_enabled: true)
+
+        expect(Gitlab::UsageDataCounters::HLLRedisCounter).not_to receive(:track_event)
+
+        subject.increment_unique_values(unknown_event, nil)
+      end
+    end
+
+    context 'with feature disabled' do
+      before do
+        stub_feature_flags(feature => false)
+      end
+
+      it 'does not track event' do
+        expect(Gitlab::UsageDataCounters::HLLRedisCounter).not_to receive(:track_event)
+
+        subject.increment_unique_values(event_name, value)
+      end
+    end
+  end
+
   describe '#order_options_with_tie_breaker' do
     subject { Class.new.include(described_class).new.order_options_with_tie_breaker }