summaryrefslogtreecommitdiff
path: root/doc/development/service_ping/implement.md
diff options
context:
space:
mode:
authorGitLab Bot <gitlab-bot@gitlab.com>2021-11-18 13:16:36 +0000
committerGitLab Bot <gitlab-bot@gitlab.com>2021-11-18 13:16:36 +0000
commit311b0269b4eb9839fa63f80c8d7a58f32b8138a0 (patch)
tree07e7870bca8aed6d61fdcc810731c50d2c40af47 /doc/development/service_ping/implement.md
parent27909cef6c4170ed9205afa7426b8d3de47cbb0c (diff)
downloadgitlab-ce-311b0269b4eb9839fa63f80c8d7a58f32b8138a0.tar.gz
Add latest changes from gitlab-org/gitlab@14-5-stable-eev14.5.0-rc42
Diffstat (limited to 'doc/development/service_ping/implement.md')
-rw-r--r--doc/development/service_ping/implement.md49
1 files changed, 25 insertions, 24 deletions
diff --git a/doc/development/service_ping/implement.md b/doc/development/service_ping/implement.md
index 34a845147dc..65a8b4c1cad 100644
--- a/doc/development/service_ping/implement.md
+++ b/doc/development/service_ping/implement.md
@@ -295,19 +295,22 @@ Examples of implementation:
- Using Redis methods [`INCR`](https://redis.io/commands/incr), [`GET`](https://redis.io/commands/get), and [`Gitlab::UsageDataCounters::WikiPageCounter`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/wiki_page_counter.rb)
- Using Redis methods [`HINCRBY`](https://redis.io/commands/hincrby), [`HGETALL`](https://redis.io/commands/hgetall), and [`Gitlab::UsageCounters::PodLogs`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_counters/pod_logs.rb)
-##### UsageData API tracking
+##### `UsageData` API
-<!-- There's nearly identical content in `##### Adding new events`. If you fix errors here, you may need to fix the same errors in the other location. -->
+You can use the `UsageData` API to track events.
+To track events, the `usage_data_api` feature flag must
+be enabled (set to `default_enabled: true`).
+Enabled by default in GitLab 13.7 and later.
-1. Track event using `UsageData` API
+##### UsageData API tracking
- Increment event count using ordinary Redis counter, for given event name.
+1. Track events using the [`UsageData` API](#usagedata-api).
- Tracking events using the `UsageData` API requires the `usage_data_api` feature flag to be enabled, which is enabled by default.
+ Increment event count using an ordinary Redis counter, for a given event name.
API requests are protected by checking for a valid CSRF token.
- To be able to increment the values, the related feature `usage_data_<event_name>` should be enabled.
+ To increment the values, the related feature `usage_data_<event_name>` must be enabled.
```plaintext
POST /usage_data/increment_counter
@@ -315,18 +318,18 @@ Examples of implementation:
| Attribute | Type | Required | Description |
| :-------- | :--- | :------- | :---------- |
- | `event` | string | yes | The event name it should be tracked |
+ | `event` | string | yes | The event name to track. |
Response:
- - `200` if event was tracked
- - `400 Bad request` if event parameter is missing
- - `401 Unauthorized` if user is not authenticated
- - `403 Forbidden` for invalid CSRF token provided
+ - `200` if the event was tracked.
+ - `400 Bad request` if the event parameter is missing.
+ - `401 Unauthorized` if the user is not authenticated.
+ - `403 Forbidden` if an invalid CSRF token is provided.
-1. Track events using JavaScript/Vue API helper which calls the API above
+1. Track events using the JavaScript/Vue API helper which calls the [`UsageData` API](#usagedata-api).
- Note that `usage_data_api` and `usage_data_#{event_name}` should be enabled to be able to track events
+ To track events, `usage_data_api` and `usage_data_#{event_name}` must be enabled.
```javascript
import api from '~/api';
@@ -460,14 +463,10 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd) and [PF
track_usage_event(:incident_management_incident_created, current_user.id)
```
- - Using the `UsageData` API.
- <!-- There's nearly identical content in `##### UsageData API Tracking`. If you find / fix errors here, you may need to fix errors in that section too. -->
+ - Using the [`UsageData` API](#usagedata-api).
Increment unique users count using Redis HLL, for a given event name.
- To track events using the `UsageData` API, ensure the `usage_data_api` feature flag
- is set to `default_enabled: true`. Enabled by default in GitLab 13.7 and later.
-
API requests are protected by checking for a valid CSRF token.
```plaintext
@@ -485,10 +484,7 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd) and [PF
- `401 Unauthorized` if the user is not authenticated.
- `403 Forbidden` if an invalid CSRF token is provided.
- - Using the JavaScript/Vue API helper, which calls the `UsageData` API.
-
- To track events using the `UsageData` API, ensure the `usage_data_api` feature flag
- is set to `default_enabled: true`. Enabled by default in GitLab 13.7 and later.
+ - Using the JavaScript/Vue API helper, which calls the [`UsageData` API](#usagedata-api).
Example for an existing event already defined in [known events](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/):
@@ -559,13 +555,18 @@ We can also disable tracking completely by using the global flag:
##### Known events are added automatically in Service Data payload
-All events added in [`known_events/common.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/common.yml) are automatically added to Service Data generation under the `redis_hll_counters` key. This column is stored in [version-app as a JSON](https://gitlab.com/gitlab-services/version-gitlab-com/-/blob/master/db/schema.rb#L209).
+Service Ping adds all events [`known_events/*.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events) to Service Data generation under the `redis_hll_counters` key. This column is stored in [version-app as a JSON](https://gitlab.com/gitlab-services/version-gitlab-com/-/blob/master/db/schema.rb#L209).
For each event we add metrics for the weekly and monthly time frames, and totals for each where applicable:
- `#{event_name}_weekly`: Data for 7 days for daily [aggregation](#add-new-events) events and data for the last complete week for weekly [aggregation](#add-new-events) events.
- `#{event_name}_monthly`: Data for 28 days for daily [aggregation](#add-new-events) events and data for the last 4 complete weeks for weekly [aggregation](#add-new-events) events.
-Redis HLL implementation calculates automatic total metrics, if there are more than one metric for the same category, aggregation, and Redis slot.
+Redis HLL implementation calculates total metrics when both of these conditions are met:
+
+- The category is manually included in [CATEGORIES_FOR_TOTALS](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/hll_redis_counter.rb#L21).
+- There is more than one metric for the same category, aggregation, and Redis slot.
+
+We add total unique counts for the weekly and monthly time frames where applicable:
- `#{category}_total_unique_counts_weekly`: Total unique counts for events in the same category for the last 7 days or the last complete week, if events are in the same Redis slot and we have more than one metric.
- `#{category}_total_unique_counts_monthly`: Total unique counts for events in same category for the last 28 days or the last 4 complete weeks, if events are in the same Redis slot and we have more than one metric.