Commit 6171c253 authored by Mikolaj Wawrzyniak's avatar Mikolaj Wawrzyniak

Update Usage Ping guide

parent 07ce676b
......@@ -122,6 +122,60 @@ sequenceDiagram
the hostname is `version.gitlab.com`, the protocol is `TCP`, and the port number is `443`,
the required URL is <https://version.gitlab.com/>.
## Usage Ping Metric Life cycle
### 1. New metrics addition
Please follow the [Implementing Usage Ping](#implementing-usage-ping) guide.
### 2. Existing metric change
Because we do not control when customers update their self-managed instances of GitLab,
we **STRONGLY DISCOURAGE** changes to the logic used to calculate any metric.
Any such changes lead to inconsistent reports from multiple GitLab instances.
If there is a problem with an existing metric, it's best to deprecate the existing metric,
and use it, side by side, with the desired new metric.
Example:
Consider following change. Before GitLab 12.6, the `example_metric` was implemented as:
```ruby
{
...
example_metric: distinct_count(Project, :creator_id)
}
```
For GitLab 12.6, the metric was changed to filter out archived projects:
```ruby
{
...
example_metric: distinct_count(Project.non_archived, :creator_id)
}
```
In this scenario all instances running up to GitLab 12.5 continue to report `example_metric`,
including all archived projects, while all instances running GitLab 12.6 and higher filters
out such projects. As Usage Ping data is collected from all reporting instances, the
resulting dataset includes mixed data, which distorts any following business analysis.
The correct approach is to add a new metric for GitLab 12.6 release with updated logic:
```ruby
{
...
example_metric_without_archived: distinct_count(Project.non_archived, :creator_id)
}
```
and update existing business analysis artefacts to use `example_metric_without_archived` instead of `example_metric`
### 3. Metrics deprecation and removal
The process for deprecating and removing metrics is currently under development. For
more information, see the following [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/284637).
## Implementing Usage Ping
Usage Ping consists of two kinds of data, counters and observations. Counters track how often a certain event
......
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