Skip to content

G
gitlab-ce
Commit 9acf8cbe authored by Marcin Sedlak-Jakubowski's avatar Marcin Sedlak-Jakubowski
Browse files
Options

Merge branch 'kpaizee-fix-lists-usage-ping-docs' into 'master' 

Fix list rendering in Usage Ping docs

See merge request gitlab-org/gitlab!64512
parents 8e948357 26abadc0
Hide whitespace changes
Inline Side-by-side
Showing with 75 additions and 74 deletions
doc/development/usage_ping/index.md
View file @ 9acf8cbe
......@@ -712,115 +712,116 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd) and [PF
Aggregation on a `daily` basis does not pull more fine grained data.
- `feature_flag`: optional `default_enabled: :yaml`. If no feature flag is set then the tracking is enabled. One feature flag can be used for multiple events. For details, see our [GitLab internal Feature flags](../feature_flags/index.md) documentation. The feature flags are owned by the group adding the event tracking.
Use one of the following methods to track events:
1. Use one of the following methods to track the event:
1. Track event in controller using `RedisTracking` module with `track_redis_hll_event(*controller_actions, name:, if: nil, &block)`.
- In the controller using the `RedisTracking` module and the following format:
Arguments:
- `controller_actions`: controller actions we want to track.
- `name`: event name.
- `if`: optional custom conditions, using the same format as with Rails callbacks.
- `&block`: optional block that computes and returns the `custom_id` that we want to track. This will override the `visitor_id`.
```ruby
track_redis_hll_event(*controller_actions, name:, if: nil, &block)
```
Example usage:
Arguments:
```ruby
# controller
class ProjectsController < Projects::ApplicationController
include RedisTracking
- `controller_actions`: the controller actions to track.
- `name`: the event name.
- `if`: optional custom conditions. Uses the same format as Rails callbacks.
- `&block`: optional block that computes and returns the `custom_id` that we want to track. This overrides the `visitor_id`.
skip_before_action :authenticate_user!, only: :show
track_redis_hll_event :index, :show, name: 'users_visiting_projects'
Example:
def index
render html: 'index'
end
def new
render html: 'new'
end
```ruby
# controller
class ProjectsController < Projects::ApplicationController
include RedisTracking
def show
render html: 'show'
end
end
```
skip_before_action :authenticate_user!, only: :show
track_redis_hll_event :index, :show, name: 'users_visiting_projects'
1. Track event in API using `increment_unique_values(event_name, values)` helper method.
def index
render html: 'index'
end
Arguments:
def new
render html: 'new'
end
- `event_name`: event name.
- `values`: values counted, one value or array of values.
def show
render html: 'show'
end
end
```
Example usage:
- In the API using the `increment_unique_values(event_name, values)` helper method.
```ruby
get ':id/registry/repositories' do
repositories = ContainerRepositoriesFinder.new(
user: current_user, subject: user_group
).execute
Arguments:
increment_unique_values('users_listing_repositories', current_user.id)
- `event_name`: the event name.
- `values`: the values counted. Can be one value or an array of values.
present paginate(repositories), with: Entities::ContainerRegistry::Repository, tags: params[:tags], tags_count: params[:tags_count]
end
```
Example:
1. Track event using `track_usage_event(event_name, values)` in services and GraphQL
```ruby
get ':id/registry/repositories' do
repositories = ContainerRepositoriesFinder.new(
user: current_user, subject: user_group
).execute
Increment unique values count using Redis HLL, for given event name.
increment_unique_values('users_listing_repositories', current_user.id)
Example:
present paginate(repositories), with: Entities::ContainerRegistry::Repository, tags: params[:tags], tags_count: params[:tags_count]
end
```
[Track usage event for incident created in service](https://gitlab.com/gitlab-org/gitlab/-/blob/v13.8.3-ee/app/services/issues/update_service.rb#L66)
- Using `track_usage_event(event_name, values)` in services and GraphQL.
[Track usage event for incident created in GraphQL](https://gitlab.com/gitlab-org/gitlab/-/blob/v13.8.3-ee/app/graphql/mutations/alert_management/update_alert_status.rb#L16)
Increment unique values count using Redis HLL, for a given event name.
```ruby
track_usage_event(:incident_management_incident_created, current_user.id)
```
Examples:
<!-- 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. -->
- [Track usage event for an incident in a service](https://gitlab.com/gitlab-org/gitlab/-/blob/v13.8.3-ee/app/services/issues/update_service.rb#L66)
- [Track usage event for an incident in GraphQL](https://gitlab.com/gitlab-org/gitlab/-/blob/v13.8.3-ee/app/graphql/mutations/alert_management/update_alert_status.rb#L16)
1. Track event using `UsageData` API
```ruby
track_usage_event(:incident_management_incident_created, current_user.id)
```
Increment unique users count using Redis HLL, for given event name.
- 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. -->
Tracking events using the `UsageData` API requires the `usage_data_api` feature flag to be enabled, which is enabled by default.
Increment unique users count using Redis HLL, for a given event name.
API requests are protected by checking for a valid CSRF token.
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.
```plaintext
POST /usage_data/increment_unique_users
```
API requests are protected by checking for a valid CSRF token.
| Attribute | Type | Required | Description |
| :-------- | :--- | :------- | :---------- |
| `event` | string | yes | The event name it should be tracked |
```plaintext
POST /usage_data/increment_unique_users
```
Response
| Attribute | Type | Required | Description |
| :-------- | :--- | :------- | :---------- |
| `event` | string | yes | The event name to track |
Return 200 if tracking failed for any reason.
Response:
- `200` if event was tracked or any errors
- `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, or if tracking failed for any reason.
- `400 Bad request` if an 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
- Using the JavaScript/Vue API helper, which calls the `UsageData` API.
Example usage for an existing event already defined in [known events](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/):
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.
Usage Data API is behind `usage_data_api` feature flag which, as of GitLab 13.7, is
now set to `default_enabled: true`.
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/):
```javascript
import api from '~/api';
```javascript
import api from '~/api';
api.trackRedisHllUserEvent('my_already_defined_event_name'),
```
api.trackRedisHllUserEvent('my_already_defined_event_name'),
```
1. Get event data using `Gitlab::UsageDataCounters::HLLRedisCounter.unique_events(event_names:, start_date:, end_date:, context: '')`.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7