diff options
Diffstat (limited to 'doc/development')
95 files changed, 4858 insertions, 1067 deletions
diff --git a/doc/development/README.md b/doc/development/README.md index 3b6eb068c13..37d8a8fa570 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -26,7 +26,7 @@ GitLab instance, see the [administration documentation](../administration/index. ## Get started - Set up the GitLab development environment with the - [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/README.md) + [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/README.md) - [GitLab contributing guide](contributing/index.md) - [Issues workflow](contributing/issue_workflow.md) for more information about: - Issue tracker guidelines. @@ -207,6 +207,8 @@ In these cases, use the following workflow: - [Newlines style guide](newlines_styleguide.md) - [Image scaling guide](image_scaling.md) - [Export to CSV](export_csv.md) +- [Cascading Settings](cascading_settings.md) +- [FIPS compliance](fips_compliance.md) ## Performance guides @@ -301,6 +303,6 @@ See [database guidelines](database/index.md). ## Other GitLab Development Kit (GDK) guides -- [Run full Auto DevOps cycle in a GDK instance](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/auto_devops.md) -- [Using GitLab Runner with the GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/runner.md) -- [Using the Web IDE terminal with the GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/web_ide_terminal_gdk_setup.md) +- [Run full Auto DevOps cycle in a GDK instance](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/auto_devops.md) +- [Using GitLab Runner with the GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/runner.md) +- [Using the Web IDE terminal with the GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/web_ide_terminal_gdk_setup.md) diff --git a/doc/development/agent/local.md b/doc/development/agent/local.md index 670315db3a8..50959b5c450 100644 --- a/doc/development/agent/local.md +++ b/doc/development/agent/local.md @@ -116,7 +116,7 @@ Before performing any of these tests, if you have a `k3s` instance running, make stop it manually before running them. Otherwise, the tests might fail with the message `failed to remove k3s cluster`. -You might need to specify the correct Agent image version that matches the `kas` image version. You can use the `GITLAB_AGENTK_VERSION` local env for this. +You might need to specify the correct Agent image version that matches the `kas` image version. You can use the `GITLAB_AGENTK_VERSION` local environment for this. ### Against `staging` @@ -124,7 +124,7 @@ You might need to specify the correct Agent image version that matches the `kas` [this line](https://gitlab.com/gitlab-org/gitlab/-/blob/5b15540ea78298a106150c3a1d6ed26416109b9d/qa/qa/service/cluster_provider/k3s.rb#L8) and [this line](https://gitlab.com/gitlab-org/gitlab/-/blob/5b15540ea78298a106150c3a1d6ed26416109b9d/qa/qa/service/cluster_provider/k3s.rb#L36). We don't allow local connections on `staging` as they require an admin user. -1. Ensure you don't have an `EE_LICENSE` env var set as this would force an admin login. +1. Ensure you don't have an `EE_LICENSE` environment variable set as this would force an admin login. 1. Go to your GDK root folder and `cd gitlab/qa`. 1. Login with your user in staging and create a group to be used as sandbox. Something like: `username-qa-sandbox`. diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index 6256610ae6a..e8b71e0509a 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -79,7 +79,7 @@ Requests time out at 30 seconds. ## Breaking changes The GitLab GraphQL API is [versionless](https://graphql.org/learn/best-practices/#versioning) which means -developers must familiarize themselves with our [deprecation cycle of breaking changes](#breaking-changes). +developers must familiarize themselves with our [Deprecation and Removal process](../api/graphql/index.md#deprecation-and-removal-process). Breaking changes are: @@ -770,6 +770,29 @@ argument :title, GraphQL::STRING_TYPE, description: copy_field_description(Types::MergeRequestType, :title) ``` +### Documentation references + +Sometimes we want to refer to external URLs in our descriptions. To make this +easier, and provide proper markup in the generated reference documentation, we +provide a `see` property on fields. For example: + +```ruby +field :genus, + type: GraphQL::STRING_TYPE, + null: true, + description: 'A taxonomic genus.' + see: { 'Wikipedia page on genera' => 'https://wikipedia.org/wiki/Genus' } +``` + +This will render in our documentation as: + +```markdown +A taxonomic genus. See: [Wikipedia page on genera](https://wikipedia.org/wiki/Genus) +``` + +Multiple documentation references can be provided. The syntax for this property +is a `HashMap` where the keys are textual descriptions, and the values are URLs. + ## Authorization See: [GraphQL Authorization](graphql_guide/authorization.md) @@ -867,7 +890,7 @@ The main use case for this is one resolver to find all items, and another to find one specific one. For this, we supply convenience methods: - `BaseResolver.single`, which constructs a new resolver that selects the first item. -- `BaseResolver.last`, with constructs a resolver that selects the last item. +- `BaseResolver.last`, which constructs a resolver that selects the last item. The correct singular type is inferred from the collection type, so we don't have to define the `type` here. @@ -973,7 +996,7 @@ end For this reason, whenever you call a resolver (mainly in tests - as framework abstractions Resolvers should not be considered re-usable, finders are to be preferred), remember to call the `ready?` method and check the boolean flag -before calling `resolve`! An example can be seen in our [`GraphQLHelpers`](https://gitlab.com/gitlab-org/gitlab/-/blob/2d395f32d2efbb713f7bc861f96147a2a67e92f2/spec/support/helpers/graphql_helpers.rb#L20-27). +before calling `resolve`! An example can be seen in our [`GraphqlHelpers`](https://gitlab.com/gitlab-org/gitlab/-/blob/2d395f32d2efbb713f7bc861f96147a2a67e92f2/spec/support/helpers/graphql_helpers.rb#L20-27). ### Look-Ahead @@ -1161,8 +1184,8 @@ are returned as the result of the mutation. The service-oriented architecture in GitLab means that most mutations call a Create, Delete, or Update service, for example `UpdateMergeRequestService`. -For Update mutations, a you might want to only update one aspect of an object, and thus only need a -_fine-grained_ mutation, for example `MergeRequest::SetWip`. +For Update mutations, you might want to only update one aspect of an object, and thus only need a +_fine-grained_ mutation, for example `MergeRequest::SetDraft`. It's acceptable to have both fine-grained mutations and coarse-grained mutations, but be aware that too many fine-grained mutations can lead to organizational challenges in maintainability, code @@ -1258,7 +1281,7 @@ end [input type](https://graphql.org/learn/schema/#input-types). For example, the -[`mergeRequestSetWip` mutation](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/mutations/merge_requests/set_wip.rb) +[`mergeRequestSetDraft` mutation](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/mutations/merge_requests/set_draft.rb) defines these arguments (some [through inheritance](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/mutations/merge_requests/base.rb)): @@ -1271,17 +1294,16 @@ argument :iid, GraphQL::STRING_TYPE, required: true, description: "The IID of the merge request to mutate." -argument :wip, +argument :draft, GraphQL::BOOLEAN_TYPE, required: false, description: <<~DESC - Whether or not to set the merge request as a WIP. - If not passed, the value will be toggled. - DESC + Whether or not to set the merge request as a draft. + DESC ``` These arguments automatically generate an input type called -`MergeRequestSetWipInput` with the 3 arguments we specified and the +`MergeRequestSetDraftInput` with the 3 arguments we specified and the `clientMutationId`. ### Object identifier arguments @@ -1318,7 +1340,7 @@ From here, we can call the service that modifies the resource. The `resolve` method should then return a hash with the same field names as defined on the mutation including an `errors` array. For example, -the `Mutations::MergeRequests::SetWip` defines a `merge_request` +the `Mutations::MergeRequests::SetDraft` defines a `merge_request` field: ```ruby @@ -1356,13 +1378,13 @@ module Types graphql_name "Mutation" - mount_mutation Mutations::MergeRequests::SetWip + mount_mutation Mutations::MergeRequests::SetDraft end end ``` -Generates a field called `mergeRequestSetWip` that -`Mutations::MergeRequests::SetWip` to be resolved. +Generates a field called `mergeRequestSetDraft` that +`Mutations::MergeRequests::SetDraft` to be resolved. ### Authorizing resources @@ -1372,8 +1394,8 @@ To authorize resources inside a mutation, we first provide the required ```ruby module Mutations module MergeRequests - class SetWip < Base - graphql_name 'MergeRequestSetWip' + class SetDraft < Base + graphql_name 'MergeRequestSetDraft' authorize :update_merge_request end diff --git a/doc/development/approval_rules.md b/doc/development/approval_rules.md index 368987eb85f..922a0cd46a2 100644 --- a/doc/development/approval_rules.md +++ b/doc/development/approval_rules.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Approval Rules development guide **(FREE)** This document explains the backend design and flow of all related functionality -about [merge request approval rules](../user/project/merge_requests/merge_request_approvals.md). +about [merge request approval rules](../user/project/merge_requests/approvals/index.md). This should help contributors to understand the code design easier and to also help see if there are parts to improve as the feature and its implementation @@ -87,7 +87,7 @@ The `ApprovalState` model get these records when approval rules are not overwritten. The `protected_branches` attribute is set and used when a rule is scoped to -protected branches. See [Scoped to Protected Branch doc](../user/project/merge_requests/merge_request_approvals.md#scoped-to-protected-branch) +protected branches. See [Approvals for protected branches](../user/project/merge_requests/approvals/rules.md#approvals-for-protected-branches) for more information about the feature. ### `ApprovalMergeRequestRule` diff --git a/doc/development/architecture.md b/doc/development/architecture.md index 5564d0722b0..fdcaa91a639 100644 --- a/doc/development/architecture.md +++ b/doc/development/architecture.md @@ -302,7 +302,7 @@ GitLab can be considered to have two layers from a process perspective: - [Omnibus](https://docs.gitlab.com/omnibus/settings/ssl.html) - [Charts](https://docs.gitlab.com/charts/installation/tls.html) - [Source](../install/installation.md#using-https) - - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/https.md) + - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/https.md) - Layer: Core Service (Processor) - GitLab.com: [Secrets Management](https://about.gitlab.com/handbook/engineering/infrastructure/production/architecture/#secrets-management) @@ -332,7 +332,7 @@ Consul is a tool for service discovery and configuration. Consul is distributed, - [Omnibus](../integration/elasticsearch.md) - [Charts](../integration/elasticsearch.md) - [Source](../integration/elasticsearch.md) - - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/elasticsearch.md) + - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/elasticsearch.md) - Layer: Core Service (Data) - GitLab.com: [Get Advanced Search working on GitLab.com (Closed)](https://gitlab.com/groups/gitlab-org/-/epics/153) epic. @@ -369,9 +369,11 @@ repository updates to secondary nodes. - Configuration: - [Omnibus](../administration/geo/setup/index.md) - [Charts](https://docs.gitlab.com/charts/advanced/geo/) - - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/geo.md) + - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/geo.md) - Layer: Core Service (Processor) +Geo is a premium feature built to help speed up the development of distributed teams by providing one or more read-only mirrors of a primary GitLab instance. This mirror (a Geo secondary site) reduces the time to clone or fetch large repositories and projects, or can be part of a Disaster Recovery solution. + #### GitLab Exporter - [Project page](https://gitlab.com/gitlab-org/gitlab-exporter) @@ -403,7 +405,7 @@ You can use it to sync deployments onto your Kubernetes cluster. - [Omnibus](../administration/pages/index.md) - [Charts](https://gitlab.com/gitlab-org/charts/gitlab/-/issues/37) - [Source](../install/installation.md#install-gitlab-pages) - - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/pages.md) + - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/pages.md) - Layer: Core Service (Processor) - GitLab.com: [GitLab Pages](../user/gitlab_com/index.md#gitlab-pages) @@ -418,7 +420,7 @@ You can use it either for personal or business websites, such as portfolios, doc - [Omnibus](https://docs.gitlab.com/runner/) - [Charts](https://docs.gitlab.com/runner/install/kubernetes.html) - [Source](https://docs.gitlab.com/runner/) - - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/runner.md) + - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/runner.md) - Layer: Core Service (Processor) - GitLab.com: [Runner](../user/gitlab_com/index.md#shared-runners) @@ -507,7 +509,7 @@ Mattermost is an open source, private cloud, Slack-alternative from <https://mat - Configuration: - [Omnibus](https://min.io/download) - [Charts](https://docs.gitlab.com/charts/charts/minio/) - - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/object_storage.md) + - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/object_storage.md) - Layer: Core Service (Data) - GitLab.com: [Storage Architecture](https://about.gitlab.com/handbook/engineering/infrastructure/production/architecture/#storage-architecture) @@ -625,6 +627,8 @@ Redis is packaged to provide a place to store: - temporary cache information - background job queues +See our [Redis guidelines](redis.md) for more information about how GitLab uses Redis. + #### Redis Exporter - [Project page](https://github.com/oliver006/redis_exporter/blob/master/README.md) @@ -644,7 +648,7 @@ Redis is packaged to provide a place to store: - [Omnibus](../update/upgrading_from_source.md#10-install-libraries-migrations-etc) - [Charts](https://docs.gitlab.com/charts/charts/registry/) - [Source](../administration/packages/container_registry.md#enable-the-container-registry) - - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/registry.md) + - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/registry.md) - Layer: Core Service (Processor) - GitLab.com: [GitLab Container Registry](../user/packages/container_registry/index.md#build-and-push-by-using-gitlab-cicd) @@ -729,7 +733,7 @@ disabled by default. - [Omnibus](../administration/auth/ldap/index.md) - [Charts](https://docs.gitlab.com/charts/charts/globals.html#ldap) - [Source](https://gitlab.com/gitlab-org/gitlab/blob/master/config/gitlab.yml.example) - - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/ldap.md) + - [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/ldap.md) - Layer: Core Service (Processor) - GitLab.com: [Product Tiers](https://about.gitlab.com/pricing/#gitlab-com) diff --git a/doc/development/audit_event_guide/index.md b/doc/development/audit_event_guide/index.md new file mode 100644 index 00000000000..0bff297f2a0 --- /dev/null +++ b/doc/development/audit_event_guide/index.md @@ -0,0 +1,181 @@ +--- +stage: Manage +group: Compliance +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Audit Event Guide + +This guide provides an overview of how Audit Events work, and how to instrument +new audit events. + +## What are Audit Events? + +Audit Events are a tool for GitLab owners and administrators to view records of important +actions performed across the application. + +## Audit Event Schemas + +To instrument an audit event, the following attributes should be provided: + +| Attribute | Type | Required? | Description | +|:-------------|:---------------------|:----------|:----------------------------------------------------| +| `name` | string | false | Action name to be audited. Used for error tracking | +| `author` | User | true | User who authors the change | +| `scope` | User, Project, Group | true | Scope which the audit event belongs to | +| `target` | Object | true | Target object being audited | +| `ip_address` | IPAddr | false | Request IP address | +| `message` | string | true | Message describing the action | + +## How to instrument new Audit Events + +There are three ways of instrumenting audit events: + +- Create a new class in `ee/lib/ee/audit/` and extend `AuditEventService` +- Call `AuditEventService` after a successful action +- Call `Gitlab::Audit::Auditor.audit` passing an action block + +This inconsistency leads to unexpected bugs, increases maintainer effort, and worsens the +developer experience. Therefore, we suggest you use `Gitlab::Audit::Auditor` to +instrument new audit events. + +With new service, we can instrument audit events in two ways: + +- Using block for multiple events. +- Using standard method call for single events. + +### Using block to record multiple events + +This method is useful when events are emitted deep in the call stack. + +For example, we can record multiple audit events when the user updates a merge +request approval rule. As part of this user flow, we would like to audit changes +to both approvers and approval groups. In the initiating service +(for example, `MergeRequestRuleUpdateService`), we can wrap the `execute` call as follows: + +```ruby +# in the initiating service +audit_context = { + name: 'merge_approval_rule_updated', + author: current_user, + scope: project_alpha, + target: merge_approval_rule, + ip_address: request.remote_ip, + message: 'Attempted to update an approval rule' +} + +Gitlab::Audit::Auditor.audit(audit_context) do + service.execute +end +``` + +In the model (for example, `ApprovalProjectRule`), we can push audit events on model +callbacks (for example, `after_save` or `after_add`). + +```ruby +# in the model +include Auditable + +def audit_add(model) + push_audit_event('Added an approver on Security rule') +end + +def audit_remove(model) + push_audit_event('Removed an approver on Security rule') +end +``` + +Please note that this method does not support actions that are asynchronous, or +span across multiple processes (for example, background jobs). + +### Using standard method call to record single event + +This method allows recording single audit event and involves fewer moving parts. + +```ruby +if merge_approval_rule.save + audit_context = { + name: 'merge_approval_rule_created', + author: current_user, + scope: project_alpha, + target: merge_approval_rule, + ip_address: request.remote_ip, + message: 'Created a new approval rule' + } + + Gitlab::Audit::Auditor.audit(audit_context) +end +``` + +## Audit Event instrumentation flows + +The two ways we can instrument audit events have different flows. + +### Using block to record multiple events + +We wrap the operation block in a `Gitlab::Audit::Auditor` which captures the +initial audit context (that is, `author`, `scope`, `target`, `ip_address`) object that are +available at the time the operation is initiated. + +Extra instrumentation is required in the interacted classes in the chain with +`Auditable` mixin to add audit events to the Audit Event queue via `Gitlab::Audit::EventQueue`. + +The `EventQueue` is stored in a local thread via `SafeRequestStore` and then later +extracted when we record an audit event in `Gitlab::Audit::Auditor`. + +```plantuml +skinparam shadowing false +skinparam BoxPadding 10 +skinparam ParticipantPadding 20 + +participant "Instrumented Class" as A +participant "Audit::Auditor" as A1 #LightBlue +participant "Audit::EventQueue" as B #LightBlue +participant "Interacted Class" as C +participant "AuditEvent" as D + +A->A1: audit <b>{ block } +activate A1 +A1->B: begin! +A1->C: <b>block.call +activate A1 #FFBBBB +activate C +C-->B: push [ message ] +C-->A1: true +deactivate A1 +deactivate C +A1->B: read +activate A1 #FFBBBB +activate B +B-->A1: [ messages ] +deactivate B +A1->D: bulk_insert! +deactivate A1 +A1->B: end! +A1-->A: +deactivate A1 +``` + +### Using standard method call to record single event + +This method has a more straight-forward flow, and does not rely on `EventQueue` +and local thread. + +```plantuml +skinparam shadowing false +skinparam BoxPadding 10 +skinparam ParticipantPadding 20 + +participant "Instrumented Class" as A +participant "Audit::Auditor" as B #LightBlue +participant "AuditEvent" as C + +A->B: audit +activate B +B->C: bulk_insert! +B-->A: +deactivate B +``` + +In addition to recording to the database, we also write these events to +[a log file](../../administration/logs.md#audit_jsonlog). diff --git a/doc/development/avoiding_downtime_in_migrations.md b/doc/development/avoiding_downtime_in_migrations.md index d8981ce0999..6b6c47cfece 100644 --- a/doc/development/avoiding_downtime_in_migrations.md +++ b/doc/development/avoiding_downtime_in_migrations.md @@ -365,6 +365,12 @@ if the application no longer uses the table. Renaming tables requires downtime as an application may continue using the old table name during/after a database migration. +If the table and the ActiveRecord model is not in use yet, removing the old +table and creating a new one is the preferred way to "rename" the table. + +Renaming a table is possible without downtime by following our multi-release +[rename table process](database/rename_database_tables.md#rename-table-without-downtime). + ## Adding Foreign Keys Adding foreign keys usually works in 3 steps: diff --git a/doc/development/cascading_settings.md b/doc/development/cascading_settings.md new file mode 100644 index 00000000000..631de544238 --- /dev/null +++ b/doc/development/cascading_settings.md @@ -0,0 +1,241 @@ +--- +stage: Manage +group: Access +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Cascading Settings + +> Introduced in [GitLab 13.11](https://gitlab.com/gitlab-org/gitlab/-/issues/321724). + +The cascading settings framework allows groups to essentially inherit settings +values from ancestors (parent group on up the group hierarchy) and from +instance-level application settings. The framework also allows settings values +to be enforced on groups lower in the hierarchy. + +Cascading settings can currently only be defined within `NamespaceSetting`, though +the framework may be extended to other objects in the future. + +## Add a new cascading setting + +Settings are not cascading by default. To define a cascading setting, take the following steps: + +1. In the `NamespaceSetting` model, define the new attribute using the `cascading_attr` + helper method. You can use an array to define multiple attributes on a single line. + + ```ruby + class NamespaceSetting + include CascadingNamespaceSettingAttribute + + cascading_attr :delayed_project_removal + end + ``` + +1. Create the database columns. + + You can use the following database migration helper for a completely new setting. + The helper creates four columns, two each in `namespace_settings` and + `application_settings`. + + ```ruby + class AddDelayedProjectRemovalCascadingSetting < ActiveRecord::Migration[6.0] + include Gitlab::Database::MigrationHelpers::CascadingNamespaceSettings + + def up + add_cascading_namespace_setting :delayed_project_removal, :boolean, default: false, null: false + end + + def down + remove_cascading_namespace_setting :delayed_project_removal + end + end + ``` + + Existing settings being converted to a cascading setting will require individual + migrations to add columns and change existing columns. Use the specifications + below to create migrations as required: + + 1. Columns in `namespace_settings` table: + - `delayed_project_removal`: No default value. Null values allowed. Use any column type. + - `lock_delayed_project_removal`: Boolean column. Default value is false. Null values not allowed. + 1. Columns in `application_settings` table: + - `delayed_project_removal`: Type matching for the column created in `namespace_settings`. + Set default value as desired. Null values not allowed. + - `lock_delayed_project_removal`: Boolean column. Default value is false. Null values not allowed. + +## Convenience methods + +By defining an attribute using the `cascading_attr` method, a number of convenience +methods are automatically defined. + +**Definition:** + +```ruby +cascading_attr :delayed_project_removal +``` + +**Convenience Methods Available:** + +- `delayed_project_removal` +- `delayed_project_removal=` +- `delayed_project_removal_locked?` +- `delayed_project_removal_locked_by_ancestor?` +- `delayed_project_removal_locked_by_application_setting?` +- `delayed_project_removal?` (Boolean attributes only) +- `delayed_project_removal_locked_ancestor` (Returns locked namespace settings object [namespace_id]) + +### Attribute reader method (`delayed_project_removal`) + +The attribute reader method (`delayed_project_removal`) returns the correct +cascaded value using the following criteria: + +1. Returns the dirty value, if the attribute has changed. This allows standard + Rails validators to be used on the attribute, though `nil` values *must* be allowed. +1. Return locked ancestor value. +1. Return locked instance-level application settings value. +1. Return this namespace's attribute, if not nil. +1. Return value from nearest ancestor where value is not nil. +1. Return instance-level application setting. + +### `_locked?` method + +By default, the `_locked?` method (`delayed_project_removal_locked?`) returns +`true` if an ancestor of the group or application setting locks the attribute. +It returns `false` when called from the group that locked the attribute. + +When `include_self: true` is specified, it returns `true` when called from the group that locked the attribute. +This would be relevant, for example, when checking if an attribute is locked from a project. + +## Display cascading settings on the frontend + +There are a few Rails view helpers, HAML partials, and JavaScript functions that can be used to display a cascading setting on the frontend. + +### Rails view helpers + +[`cascading_namespace_setting_locked?`](https://gitlab.com/gitlab-org/gitlab/-/blob/c2736823b8e922e26fd35df4f0cd77019243c858/app/helpers/namespaces_helper.rb#L86) + +Calls through to the [`_locked?` method](#_locked-method) to check if the setting is locked. + +| Argument | Description | Type | Required (default value) | +|:------------|:---------------------------------------------------------------------------------|:----------------------------------------------------------------------------------|:-------------------------| +| `attribute` | Name of the setting. For example, `:delayed_project_removal`. | `String` or `Symbol` | `true` | +| `group` | Current group. | [`Group`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/models/group.rb) | `true` | +| `**args` | Additional arguments to pass through to the [`_locked?` method](#_locked-method) | | `false` | + +### HAML partials + +[`_enforcement_checkbox.html.haml`](https://gitlab.com/gitlab-org/gitlab/-/blob/c2736823b8e922e26fd35df4f0cd77019243c858/app/views/shared/namespaces/cascading_settings/_enforcement_checkbox.html.haml) + +Renders the enforcement checkbox. + +| Local | Description | Type | Required (default value) | +|:-----------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------|:------------------------------------------------| +| `attribute` | Name of the setting. For example, `:delayed_project_removal`. | `String` or `Symbol` | `true` | +| `form` | [Rails FormBuilder object](https://apidock.com/rails/ActionView/Helpers/FormBuilder). | [`ActionView::Helpers::FormBuilder`](https://apidock.com/rails/ActionView/Helpers/FormBuilder) | `true` | +| `setting_locked` | If the setting is locked by an ancestor group or admin setting. Can be calculated with [`cascading_namespace_setting_locked?`](https://gitlab.com/gitlab-org/gitlab/-/blob/c2736823b8e922e26fd35df4f0cd77019243c858/app/helpers/namespaces_helper.rb#L86). | `Boolean` | `true` | +| `help_text` | Text shown below the checkbox. | `String` | `false` (Subgroups cannot change this setting.) | + +[`_setting_label_checkbox.html.haml`](https://gitlab.com/gitlab-org/gitlab/-/blob/c2736823b8e922e26fd35df4f0cd77019243c858/app/views/shared/namespaces/cascading_settings/_setting_label_checkbox.html.haml) + +Renders the label for a checkbox setting. + +| Local | Description | Type | Required (default value) | +|:-----------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------|:-------------------------| +| `attribute` | Name of the setting. For example, `:delayed_project_removal`. | `String` or `Symbol` | `true` | +| `form` | [Rails FormBuilder object](https://apidock.com/rails/ActionView/Helpers/FormBuilder). | [`ActionView::Helpers::FormBuilder`](https://apidock.com/rails/ActionView/Helpers/FormBuilder) | `true` | +| `setting_locked` | If the setting is locked by an ancestor group or admin setting. Can be calculated with [`cascading_namespace_setting_locked?`](https://gitlab.com/gitlab-org/gitlab/-/blob/c2736823b8e922e26fd35df4f0cd77019243c858/app/helpers/namespaces_helper.rb#L86). | `Boolean` | `true` | +| `settings_path_helper` | Lambda function that generates a path to the ancestor setting. For example, `settings_path_helper: -> (locked_ancestor) { edit_group_path(locked_ancestor, anchor: 'js-permissions-settings') }` | `Lambda` | `true` | +| `help_text` | Text shown below the checkbox. | `String` | `false` (`nil`) | + +[`_setting_label_fieldset.html.haml`](https://gitlab.com/gitlab-org/gitlab/-/blob/c2736823b8e922e26fd35df4f0cd77019243c858/app/views/shared/namespaces/cascading_settings/_setting_label_fieldset.html.haml) + +Renders the label for a fieldset setting. + +| Local | Description | Type | Required (default value) | +|:-----------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------|:-------------------------| +| `attribute` | Name of the setting. For example, `:delayed_project_removal`. | `String` or `Symbol` | `true` | +| `setting_locked` | If the setting is locked. Can be calculated with [`cascading_namespace_setting_locked?`](https://gitlab.com/gitlab-org/gitlab/-/blob/c2736823b8e922e26fd35df4f0cd77019243c858/app/helpers/namespaces_helper.rb#L86). | `Boolean` | `true` | +| `settings_path_helper` | Lambda function that generates a path to the ancestor setting. For example, `-> (locked_ancestor) { edit_group_path(locked_ancestor, anchor: 'js-permissions-settings') }` | `Lambda` | `true` | +| `help_text` | Text shown below the checkbox. | `String` | `false` (`nil`) | + +[`_lock_popovers.html.haml`](https://gitlab.com/gitlab-org/gitlab/-/blob/b73353e47e283a7d9c9eda5bdedb345dcfb685b6/app/views/shared/namespaces/cascading_settings/_lock_popovers.html.haml) + +Renders the mount element needed to initialize the JavaScript used to display the popover when hovering over the lock icon. This partial is only needed once per page. + +### JavaScript + +[`initCascadingSettingsLockPopovers`](https://gitlab.com/gitlab-org/gitlab/-/blob/b73353e47e283a7d9c9eda5bdedb345dcfb685b6/app/assets/javascripts/namespaces/cascading_settings/index.js#L4) + +Initializes the JavaScript needed to display the popover when hovering over the lock icon (**{lock}**). +This function should be imported and called in the [page-specific JavaScript](fe_guide/performance.md#page-specific-javascript). + +### Put it all together + +```haml +-# app/views/groups/edit.html.haml + += render 'shared/namespaces/cascading_settings/lock_popovers' + +- delayed_project_removal_locked = cascading_namespace_setting_locked?(:delayed_project_removal, @group) +- merge_method_locked = cascading_namespace_setting_locked?(:merge_method, @group) + += form_for @group do |f| + .form-group{ data: { testid: 'delayed-project-removal-form-group' } } + .gl-form-checkbox.custom-control.custom-checkbox + = f.check_box :delayed_project_removal, checked: @group.namespace_settings.delayed_project_removal?, disabled: delayed_project_removal_locked, class: 'custom-control-input' + = render 'shared/namespaces/cascading_settings/setting_label_checkbox', attribute: :delayed_project_removal, + group: @group, + form: f, + setting_locked: delayed_project_removal_locked, + settings_path_helper: -> (locked_ancestor) { edit_group_path(locked_ancestor, anchor: 'js-permissions-settings') }, + help_text: s_('Settings|Projects will be permanently deleted after a 7-day delay. Inherited by subgroups.') do + = s_('Settings|Enable delayed project removal') + = render 'shared/namespaces/cascading_settings/enforcement_checkbox', + attribute: :delayed_project_removal, + group: @group, + form: f, + setting_locked: delayed_project_removal_locked + + %fieldset.form-group + = render 'shared/namespaces/cascading_settings/setting_label_fieldset', attribute: :merge_method, + group: @group, + setting_locked: merge_method_locked, + settings_path_helper: -> (locked_ancestor) { edit_group_path(locked_ancestor, anchor: 'js-permissions-settings') }, + help_text: s_('Settings|Determine what happens to the commit history when you merge a merge request.') do + = s_('Settings|Merge method') + + .gl-form-radio.custom-control.custom-radio + = f.radio_button :merge_method, :merge, class: "custom-control-input", disabled: merge_method_locked + = f.label :merge_method_merge, class: 'custom-control-label' do + = s_('Settings|Merge commit') + %p.help-text + = s_('Settings|Every merge creates a merge commit.') + + .gl-form-radio.custom-control.custom-radio + = f.radio_button :merge_method, :rebase_merge, class: "custom-control-input", disabled: merge_method_locked + = f.label :merge_method_rebase_merge, class: 'custom-control-label' do + = s_('Settings|Merge commit with semi-linear history') + %p.help-text + = s_('Settings|Every merge creates a merge commit.') + + .gl-form-radio.custom-control.custom-radio + = f.radio_button :merge_method, :ff, class: "custom-control-input", disabled: merge_method_locked + = f.label :merge_method_ff, class: 'custom-control-label' do + = s_('Settings|Fast-forward merge') + %p.help-text + = s_('Settings|No merge commits are created.') + + = render 'shared/namespaces/cascading_settings/enforcement_checkbox', + attribute: :merge_method, + group: @group, + form: f, + setting_locked: merge_method_locked +``` + +```javascript +// app/assets/javascripts/pages/groups/edit/index.js + +import { initCascadingSettingsLockPopovers } from '~/namespaces/cascading_settings'; + +initCascadingSettingsLockPopovers(); +``` diff --git a/doc/development/changelog.md b/doc/development/changelog.md index ee80d998c14..6412c303735 100644 --- a/doc/development/changelog.md +++ b/doc/development/changelog.md @@ -48,16 +48,13 @@ the `author` field. GitLab team members **should not**. - Any client-facing change to our REST and GraphQL APIs **must** have a changelog entry. See the [complete list what comprises a GraphQL breaking change](api_graphql_styleguide.md#breaking-changes). - Any change that introduces an [Advanced Search migration](elasticsearch.md#creating-a-new-advanced-search-migration) **must** have a changelog entry. - Performance improvements **should** have a changelog entry. - also require a changelog entry. - _Any_ contribution from a community member, no matter how small, **may** have a changelog entry regardless of these guidelines if the contributor wants one. Example: "Fixed a typo on the search results page." - Any docs-only changes **should not** have a changelog entry. -- Any change behind a feature flag **disabled** by default **should not** have a changelog entry. -- Any change behind a feature flag that is **enabled** by default **should** have a changelog entry. -- Any change that adds new Usage Data metrics and changes that needs to be documented in Product Intelligence [Metrics Dictionary](usage_ping/dictionary.md) **should** have a changelog entry. +- For changes related to feature flags, use [feature flag guide](feature_flags/index.md#changelog) to determine the changelog entry. +- Any change that adds new Usage Data metrics, sets the status of existing ones to `removed`, and changes that need to be documented in Product Intelligence [Metrics Dictionary](usage_ping/dictionary.md) **should** have a changelog entry. - A change that adds snowplow events **should** have a changelog entry - -- A change that [removes a feature flag, or removes a feature and its feature flag](feature_flags/index.md) **must** have a changelog entry. - A fix for a regression introduced and then fixed in the same release (i.e., fixing a bug introduced during a monthly release candidate) **should not** have a changelog entry. diff --git a/doc/development/cicd/cicd_reference_documentation_guide.md b/doc/development/cicd/cicd_reference_documentation_guide.md new file mode 100644 index 00000000000..a05916178a9 --- /dev/null +++ b/doc/development/cicd/cicd_reference_documentation_guide.md @@ -0,0 +1,154 @@ +--- +stage: Verify +group: Continuous Integration +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# CI/CD YAML reference style guide + +The CI/CD YAML reference uses a standard style to make it easier to use and update. + +The reference information should be kept as simple as possible, and expanded details +and examples documented in a separate page. + +## YAML reference structure + +Every YAML keyword must have its own section in the reference. The sections should +be nested so that the keywords follow a logical tree structure. For example: + +```plaintext +### `artifacts` +#### `artifacts:name` +#### `artifacts:paths` +#### `artifacts:reports` +##### `artifacts:reports:dast` +##### `artifacts:reports:sast` +``` + +## YAML reference style + +Each keyword entry in the reference should use the following style: + +````markdown +### `keyword-name` + +> Version information + +Keyword description and main details. + +**Keyword type**: + +**Possible inputs**: + +**Example of `keyword-name`**: + +(optional) In this example... + +(optional) **Additional details**: + +- List of extra details. + +(optional) **Related topics**: + +- List of links to topics related to the keyword. +```` + +- ``### `keyword-name` ``: The keyword name must always be in backticks. + If it is a subkey of another keyword, write out all the keywords, with each separated + by `:`, for example: `artifacts:reports:dast`. + +- ``> Version information``: The [version history details](../documentation/styleguide/index.md#version-text-in-the-version-history). + If the keyword is feature flagged, see the [feature flag documentation guide](../documentation/feature_flags.md) + as well. + +- `Keyword description and main details.`: A simple description of the keyword, and + how to use it. Additional use cases and benefits should be added to a page outside + the reference document. Link to that document in this section. + +- `**Keyword type**:`: Most keywords are defined at the job level, like `script`, + or at the pipeline level, like `stages`. Add the appropriate line: + + - `**Keyword type**: Job keyword. You can use it only as part of a job.` + - `**Keyword type**: Pipeline keyword. You cannot use it as part of a job.` + + If a keyword can be used at both the job and pipeline level, like `variables`, + explain it in detail instead of using the pre-written lines above. + +- `**Possible inputs**:`: Explain in detail which inputs the keyword can accept. + You can add the details in a sentence, paragraph, or list. + +- ``**Example of `keyword-name`**:``: An example configuration that uses the keyword. + Do not add extra keywords that are not required to understand the behavior. + +- (optional) `In this example...`: If the example needs extra details, + add the clarification text below the example. + +- (optional) `**Additional details**:` If there are any caveats or extra details you + want to document along with the keyword, add each one as a list item here. + +- (optional) `**Related topics**:` If there are any other keywords or pages that + relate to this keyword, add these links as list items here. + +### YAML reference style example + +See the [`only:changes` / `except:changes`](../../ci/yaml/README.md#onlychanges--exceptchanges) +documentation for an example of the YAML reference style. The following example is a +shortened version of that documentation's Markdown: + +````markdown +#### `only:changes` / `except:changes` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/19232) in GitLab 11.4. + +Use the `changes` keyword with `only` to run a job, or with `except` to skip a job, +when a Git push event modifies a file. + +Use `changes` in pipelines with the following refs: + +- `branches` +- `external_pull_requests` +- `merge_requests` (see additional details about [using `only:changes` with pipelines for merge requests](../jobs/job_control.md#use-onlychanges-with-pipelines-for-merge-requests)) + +**Keyword type**: Job keyword. You can use it only as part of a job. + +**Possible inputs**: An array including any number of: + +- Paths to files. +- Wildcard paths for single directories, for example `path/to/directory/*`, or a directory + and all its subdirectories, for example `path/to/directory/**/*`. + +**Example of `only:changes`**: + +```yaml +docker build: + script: docker build -t my-image:$CI_COMMIT_REF_SLUG . + only: + refs: + - branches + changes: + - Dockerfile + - docker/scripts/* + - dockerfiles/**/* +``` + +In this example, `docker build` only runs in branch pipelines, and only if at least one of +these files changed: + +- `Dockerfile`. +- Any file in `docker/scripts` +- Any file in `dockerfiles/` or any of its subdirectories. + +**Additional details**: + +- If you use refs other than `branches`, `external_pull_requests`, or `merge_requests`, + `changes` can't determine if a given file is new or old and always returns `true`. +- If you use `only: changes` with other refs, jobs ignore the changes and always run. +- If you use `except: changes` with other refs, jobs ignore the changes and never run. + +**Related topics**: + +- [`only: changes` and `except: changes` examples](../jobs/job_control.md#onlychanges--exceptchanges-examples). +- If you use `changes` with [only allow merge requests to be merged if the pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md#only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds), + you should [also use `only:merge_requests`](../jobs/job_control.md#use-onlychanges-with-pipelines-for-merge-requests). +- Use `changes` with [scheduled pipelines](../jobs/job_control.md#use-onlychanges-with-scheduled-pipelines). +```` diff --git a/doc/development/cicd/index.md b/doc/development/cicd/index.md index 35c4cc0694e..965ab3610dd 100644 --- a/doc/development/cicd/index.md +++ b/doc/development/cicd/index.md @@ -11,6 +11,9 @@ Development guides that are specific to CI/CD are listed here. If you are creating new CI/CD templates, please read [the development guide for GitLab CI/CD templates](templates.md). +See the [CI/CD YAML reference documentation guide](cicd_reference_documentation_guide.md) +to learn how to update the [reference page](../../ci/yaml/README.md). + ## CI Architecture overview The following is a simplified diagram of the CI architecture. Some details are left out in order to focus on diff --git a/doc/development/cicd/templates.md b/doc/development/cicd/templates.md index fd1456a1676..fc342794919 100644 --- a/doc/development/cicd/templates.md +++ b/doc/development/cicd/templates.md @@ -127,7 +127,7 @@ job2: #### Use `rules` instead of `only` or `except` -Avoid using [`only` or `except`](../../ci/yaml/README.md#onlyexcept-basic) if possible. +Avoid using [`only` or `except`](../../ci/yaml/README.md#only--except) if possible. Only and except is not being developed any more, and [`rules`](../../ci/yaml/README.md#rules) is now the preferred syntax: diff --git a/doc/development/code_review.md b/doc/development/code_review.md index 731fec98933..b91e27b7051 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -39,7 +39,7 @@ or more [maintainers](https://about.gitlab.com/handbook/engineering/workflow/cod For approvals, we use the approval functionality found in the merge request widget. For reviewers, we use the [reviewer functionality](../user/project/merge_requests/getting_started.md#reviewer) in the sidebar. -Reviewers can add their approval by [approving additionally](../user/project/merge_requests/merge_request_approvals.md#adding-or-removing-an-approval). +Reviewers can add their approval by [approving additionally](../user/project/merge_requests/approvals/index.md#approve-a-merge-request). Getting your merge request **merged** also requires a maintainer. If it requires more than one approval, the last maintainer to review and approve merges it. @@ -101,7 +101,7 @@ with [domain expertise](#domain-experts). 1. If your merge request includes frontend changes (*1*), it must be **approved by a [frontend maintainer](https://about.gitlab.com/handbook/engineering/projects/#gitlab_maintainers_frontend)**. 1. If your merge request includes user-facing changes (*3*), it must be - **approved by a [Product Designer](https://about.gitlab.com/handbook/engineering/ux/product-design/)**, + **approved by a [Product Designer](https://about.gitlab.com/handbook/engineering/projects/#gitlab_reviewers_UX)**, based on assignments in the appropriate [DevOps stage group](https://about.gitlab.com/handbook/product/categories/#devops-stages). 1. If your merge request includes adding a new JavaScript library (*1*)... - If the library significantly increases the @@ -114,8 +114,8 @@ with [domain expertise](#domain-experts). 1. If your merge request includes a new dependency or a file system change, it must be **approved by a [Distribution team member](https://about.gitlab.com/company/team/)**. See how to work with the [Distribution team](https://about.gitlab.com/handbook/engineering/development/enablement/distribution/#how-to-work-with-distribution) for more details. 1. If your merge request includes documentation changes, it must be **approved - by a [Technical writer](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments)**, based on - the appropriate [product category](https://about.gitlab.com/handbook/product/categories/). + by a [Technical writer](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments)**, + based on assignments in the appropriate [DevOps stage group](https://about.gitlab.com/handbook/product/categories/#devops-stages). 1. If your merge request includes end-to-end **and** non-end-to-end changes (*4*), it must be **approved by a [Software Engineer in Test](https://about.gitlab.com/handbook/engineering/quality/#individual-contributors)**. 1. If your merge request only includes end-to-end changes (*4*) **or** if the MR author is a [Software Engineer in Test](https://about.gitlab.com/handbook/engineering/quality/#individual-contributors), it must be **approved by a [Quality maintainer](https://about.gitlab.com/handbook/engineering/projects/#gitlab_maintainers_qa)** @@ -299,8 +299,10 @@ first time. of your shiny new branch, read through the entire diff. Does it make sense? Did you include something unrelated to the overall purpose of the changes? Did you forget to remove any debugging code? -- Consider providing instructions on how to test the merge request. This can be - helpful for reviewers not familiar with the product feature or area of the codebase. +- Write a detailed description as outlined in the [merge request guidelines](contributing/merge_request_workflow.md#merge-request-guidelines). + Some reviewers may not be familiar with the product feature or area of the + codebase. Thorough descriptions help all reviewers understand your request + and test effectively. - If you know your change depends on another being merged first, note it in the description and set an [merge request dependency](../user/project/merge_requests/merge_request_dependencies.md). - Be grateful for the reviewer's suggestions. (`Good call. I'll make that change.`) @@ -371,6 +373,9 @@ if necessary. If blocked by one or more open MRs, set an [MR dependency](../user "Looks good to me", or "Just a couple things to address." - Let the author know if changes are required following your review. +WARNING: +**If the merge request is from a fork, also check the [additional guidelines for community contributions](#community-contributions).** + ### Merging a merge request Before taking the decision to merge: @@ -385,7 +390,7 @@ If a merge request is fundamentally ready, but needs only trivial fixes (such as typos), consider demonstrating a [bias for action](https://about.gitlab.com/handbook/values/#bias-for-action) by making those changes directly without going back to the author. You can do this by -using the [suggest changes](../user/discussions/index.md#suggest-changes) feature to apply +using the [suggest changes](../user/project/merge_requests/reviews/suggestions.md) feature to apply your own suggestions to the merge request. Note that: - If the changes are not straightforward, please prefer allowing the author to make the change. @@ -399,6 +404,9 @@ your own suggestions to the merge request. Note that: When ready to merge: +WARNING: +**If the merge request is from a fork, also check the [additional guidelines for community contributions](#community-contributions).** + - Consider using the [Squash and merge](../user/project/merge_requests/squash_and_merge.md#squash-and-merge) feature when the merge request has a lot of commits. @@ -407,17 +415,6 @@ When ready to merge: messy commit history, it will be more efficient to squash commits instead of circling back with the author about that. Otherwise, if the MR only has a few commits, we'll be respecting the author's setting by not squashing them. - -WARNING: -**If the merge request is from a fork, review all changes thoroughly for malicious code before -starting a [Pipeline for Merged Results](../ci/merge_request_pipelines/index.md#run-pipelines-in-the-parent-project-for-merge-requests-from-a-forked-project).** -Pay particular attention to new dependencies and dependency updates, such as Ruby gems and Node packages. -While changes to files like `Gemfile.lock` or `yarn.lock` might appear trivial, they could lead to the -fetching of malicious packages. -If the MR source branch is more than 100 commits behind the target branch, ask the author to rebase it. -Review links and images, especially in documentation MRs. -When in doubt, ask someone from `@gitlab-com/gl-security/appsec` to review the merge request **before starting any merge request pipeline**. - - Start a new merge request pipeline with the `Run pipeline` button in the merge request's "Pipelines" tab, and enable "Merge When Pipeline Succeeds" (MWPS). Note that: @@ -430,6 +427,10 @@ When in doubt, ask someone from `@gitlab-com/gl-security/appsec` to review the m enough to `master`. - When you set the MR to "Merge When Pipeline Succeeds", you should take over subsequent revisions for anything that would be spotted after that. +- For merge requests that have had [Squash and + merge](../user/project/merge_requests/squash_and_merge.md#squash-and-merge) set, + the squashed commit’s default commit message is taken from the merge request title. + You're encouraged to [select a commit with a more informative commit message](../user/project/merge_requests/squash_and_merge.md#overview) before merging. Thanks to **Pipeline for Merged Results**, authors no longer have to rebase their branch as frequently anymore (only when there are conflicts) because the Merge @@ -439,6 +440,45 @@ for a final rebase: instead, they only have to start a MR pipeline and set MWPS. This step brings us very close to the actual Merge Trains feature by testing the Merge Results against the latest `master` at the time of the pipeline creation. +### Community contributions + +WARNING: +**Review all changes thoroughly for malicious code before starting a +[Pipeline for Merged Results](../ci/merge_request_pipelines/index.md#run-pipelines-in-the-parent-project-for-merge-requests-from-a-forked-project).** + +When reviewing merge requests added by wider community contributors: + +- Pay particular attention to new dependencies and dependency updates, such as Ruby gems and Node packages. + While changes to files like `Gemfile.lock` or `yarn.lock` might appear trivial, they could lead to the + fetching of malicious packages. +- Review links and images, especially in documentation MRs. +- When in doubt, ask someone from `@gitlab-com/gl-security/appsec` to review the merge request **before manually starting any merge request pipeline**. + +If the MR source branch is more than 1,000 commits behind the target branch: + +- Ask the author to rebase it, or consider taking a bias-for-action and rebasing it yourself + if the MR has "Allows commits from members who can merge to the target branch" enabled. +- Reviewing MRs in the context of recent changes can help prevent hidden runtime conflicts and + promote consistency. Depending on the nature of the change, you might also want to rebase if the + MR is less than 1,000 commits behind. +- A forced push could throw off the contributor, so it's a good idea to communicate that you've performed a rebase, + or check with the contributor first when they're actively working on the MR. +- The rebase can usually be done inside GitLab with the `/rebase` [quick action](../user/project/quick_actions.md). + +When an MR needs further changes but the author is not responding for a long period of time, +or unable to finish the MR, we can take it over in accordance with our +[Closing policy for issues and merge requests](contributing/#closing-policy-for-issues-and-merge-requests): + +1. Add a comment to their MR saying you'll take it over to be able to get it merged. +1. Add the label `~"coach will finish"` to their MR. +1. Create a new feature branch from the main branch. +1. Merge their branch into your new feature branch. +1. Open a new merge request to merge your feature branch into the main branch. +1. Link the community MR from your MR and label it as `~"Community contribution"`. +1. Make any necessary final adjustments and ping the contributor to give them the chance to review your changes, and to make them aware that their content is being merged into the main branch. +1. Make sure the content complies with all the merge request guidelines. +1. Follow the regular review process as we do for any merge request. + ### The right balance One of the most difficult things during code review is finding the right @@ -519,8 +559,9 @@ Enterprise Edition instance. This has some implications: 1. Try to avoid that, and add to `ApplicationSetting` instead. 1. Ensure that it is also [added to Omnibus](https://docs.gitlab.com/omnibus/settings/gitlab.yml.html#adding-a-new-setting-to-gitlab-yml). -1. **File system access** can be slow, so try to avoid - [shared files](shared_files.md) when an alternative solution is available. +1. **File system access** is not possible in a [cloud-native architecture](architecture.md#adapting-existing-and-introducing-new-components). + Ensure that we support object storage for any file storage we need to perform. For more + information, see the [uploads documentation](uploads.md). ### Review turnaround time diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md index 227923b324e..26a32464041 100644 --- a/doc/development/contributing/index.md +++ b/doc/development/contributing/index.md @@ -123,7 +123,7 @@ The general flow of contributing to GitLab is: 1. [Create a fork](../../user/project/repository/forking_workflow.md#creating-a-fork) of GitLab. In some cases, you will want to set up the [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit) to - [develop against your fork](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/index.md#develop-in-your-own-gitlab-fork). + [develop against your fork](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/index.md#develop-in-your-own-gitlab-fork). 1. Make your changes in your fork. 1. When you're ready, [create a new merge request](../../user/project/merge_requests/creating_merge_requests.md). 1. In the merge request's description: @@ -152,7 +152,7 @@ Keep the following in mind when submitting merge requests: reviewer will have reservations about the code's overall quality. When there is a reservation, the reviewer will inform the author and provide some guidance. - Though GitLab generally allows anyone to indicate - [approval](../../user/project/merge_requests/merge_request_approvals.md) of merge requests, the + [approval](../../user/project/merge_requests/approvals/index.md) of merge requests, the maintainer may require [approvals from certain reviewers](../code_review.md#approval-guidelines) before merging a merge request. - After review, the author may be asked to update the merge request. Once the merge request has been diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index c505b8cf467..dfabeca34ce 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -358,7 +358,7 @@ code snippet right after your description in a new line: `~feature`. Please keep feature proposals as small and simple as possible, complex ones might be edited to make them small and simple. -Please submit Feature Proposals using the ['Feature Proposal' issue template](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/issue_templates/Feature%20proposal.md) provided on the issue tracker. +Please submit Feature Proposals using the ['Feature Proposal' issue template](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/issue_templates/Feature%20proposal%20-%20detailed.md) provided on the issue tracker. For changes in the interface, it is helpful to include a mockup. Issues that add to, or change, the interface should be given the ~"UX" label. This will allow the UX team to provide input and guidance. You may diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index 32b0ff45847..922bc52773b 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -78,8 +78,7 @@ request is as follows: 1. If your MR touches code that executes shell commands, reads or opens files, or handles paths to files on disk, make sure it adheres to the [shell command guidelines](../shell_commands.md) -1. If your code creates new files on disk please read the - [shared files guidelines](../shared_files.md). +1. If your code needs to handle file storage, see the [uploads documentation](../uploads.md). 1. If your merge request adds one or more migrations, make sure to execute all migrations on a fresh database before the MR is reviewed. If the review leads to large changes in the MR, execute the migrations again once the review is complete. @@ -251,6 +250,8 @@ requirements. with any questions. 1. The new feature does not degrade the user experience of the product. +Contributions do not require approval from the [Product team](https://about.gitlab.com/handbook/product/product-processes/#gitlab-pms-arent-the-arbiters-of-community-contributions). + ## Dependencies If you add a dependency in GitLab (such as an operating system package) please diff --git a/doc/development/contributing/style_guides.md b/doc/development/contributing/style_guides.md index 444a067a780..20e47b501e6 100644 --- a/doc/development/contributing/style_guides.md +++ b/doc/development/contributing/style_guides.md @@ -100,6 +100,9 @@ Our codebase style is defined and enforced by [RuboCop](https://github.com/ruboc You can check for any offenses locally with `bundle exec rubocop --parallel`. On the CI, this is automatically checked by the `static-analysis` jobs. +In addition, you can [integrate RuboCop](../developing_with_solargraph.md) into +supported IDEs using the [Solargraph](https://github.com/castwide/solargraph) gem. + For RuboCop rules that we have not taken a decision on yet, we follow the [Ruby Style Guide](https://github.com/rubocop-hq/ruby-style-guide), [Rails Style Guide](https://github.com/rubocop-hq/rails-style-guide), and diff --git a/doc/development/creating_enums.md b/doc/development/creating_enums.md index 1a72d99112f..301c6031d28 100644 --- a/doc/development/creating_enums.md +++ b/doc/development/creating_enums.md @@ -53,7 +53,7 @@ module Enums end end -Enums::Pipeline.prepend_if_ee('EE::Enums::Pipeline') +Enums::Pipeline.prepend_mod_with('Enums::Pipeline') ``` ```ruby diff --git a/doc/development/database/index.md b/doc/development/database/index.md index 01f6753e7a0..b61a71ffb8e 100644 --- a/doc/development/database/index.md +++ b/doc/development/database/index.md @@ -60,6 +60,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w - [Updating multiple values](setting_multiple_values.md) - [Constraints naming conventions](constraint_naming_convention.md) - [Query performance guidelines](../query_performance.md) +- [Pagination guidelines](pagination_guidelines.md) + - [Pagination performance guidelines](pagination_performance_guidelines.md) ## Case studies diff --git a/doc/development/database/pagination_guidelines.md b/doc/development/database/pagination_guidelines.md new file mode 100644 index 00000000000..aa3915cd4b6 --- /dev/null +++ b/doc/development/database/pagination_guidelines.md @@ -0,0 +1,315 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Pagination guidelines + +This document gives an overview of the current capabilities and provides best practices for paginating over data in GitLab, and in particular for PostgreSQL. + +## Why do we need pagination? + +Pagination is a popular technique to avoid loading too much data in one web request. This usually happens when we render a list of records. A common scenario is visualizing parent-children relations (has many) on the UI. + +Example: listing issues within a project + +As the number of issues grows within the project, the list gets longer. To render the list, the backend does the following: + +1. Loads the records from the database, usually in a particular order. +1. Serializes the records in Ruby. Build Ruby (ActiveRecord) objects and then build a JSON or HTML string. +1. Sends the response back to the browser. +1. The browser renders the content. + +We have two options for rendering the content: + +- HTML: backend deals with the rendering (HAML template). +- JSON: the client (client-side JavaScript) transforms the payload into HTML. + +Rendering long lists can significantly affect both the frontend and backend performance: + +- The database will need to read a lot of data from the disk. +- The result of the query (records) will eventually be transformed to Ruby objects which increases memory allocation. +- Large responses will take more time to send over the wire, to the user's browser. +- Rendering long lists might freeze the browser (bad user experience). + +With pagination, the data is split into equal pieces (pages). On the first visit, the user receives only a limited number of items (page size). The user can see more items by paginating forward which results in a new HTTP request and a new database query. + + + +## General guidelines for paginating + +### Pick the right approach + +Let the database handle the pagination, filtering, and data retrieval. Implementing in-memory pagination on the backend (`paginate_array` from kaminari) or on the frontend (JavaScript) might work for a few hundreds of records. If application limits are not defined, things can get out of control quickly. + +### Reduce complexity + +When we list records on the page we often provide additional filters and different sort options. This can complicate things on the backend side significantly. + +For the MVC version, consider the following: + +- Reduce the number of sort options to the minimum. +- Reduce the number of filters (dropdown, search bar) to the minimum. + +To make sorting and pagination efficient, for each sort option we need at least two database indexes (ascending, descending order). If we add filter options (by state or by author), we might need more indexes to maintain good performance. Note that indexes are not free, they can significantly affect the `UPDATE` query timings. + +It's not possible to make all filter and sort combinations performant, so we should try optimizing the performance by usage patterns. + +### Prepare for scaling + +Offset-based pagination is the easiest way to paginate over records, however, it does not scale well for large tables. As a long-term solution, keyset pagination is preferred. The tooling around keyset pagination is not as mature as for offset pagination so currently, it's easier to start with offset pagination and then switch to keyset pagination. + +To avoid losing functionality and maintaining backward compatibility when switching pagination methods, it's advised to consider the following approach in the design phase: + +- Avoid presenting total counts, prefer limit counts. + - Example: count maximum 1001 records, and then on the UI show 1000+ if the count is 1001, show the actual number otherwise. + - See the [badge counters approach](../merge_request_performance_guidelines.md#badge-counters) for more information. +- Avoid using page numbers, use next and previous page buttons. + - Keyset pagination doesn't support page numbers. +- For APIs, advise against building URLs for the next page by "hand". + - Promote the usage of the [`Link` header](../../api/README.md#pagination-link-header) where the URLs for the next and previous page are provided by the backend. + - This way changing the URL structure is possible without breaking backward compatibility. + +NOTE: +Infinite scroll can use keyset pagination without affecting the user experience since there are no exposed page numbers. + +## Options for pagination + +### Offset pagination + +The most common way to paginate lists is using offset-based pagination (UI and REST API). It's backed by the popular [kaminari](https://github.com/kaminari/kaminari) Ruby gem, which provides convenient helper methods to implement pagination on ActiveRecord queries. + +Offset-based pagination is leveraging the `LIMIT` and `OFFSET` SQL clauses to take out a specific slice from the table. + +Example database query when looking for the 2nd page of the issues within our project: + +```sql +SELECT issues.* FROM issues WHERE project_id = 1 ORDER BY id LIMIT 20 OFFSET 20 +``` + +1. Move an imaginary pointer over the table rows and skip 20 rows. +1. Take the next 20 rows. + +Notice that the query also orders the rows by the primary key (`id`). When paginating data, specifying the order is very important. Without it, the returned rows are non-deterministic and can confuse the end-user. + +#### Page numbers + +Example pagination bar: + + + +The kaminari gem renders a nice pagination bar on the UI with page numbers and optionally quick shortcuts the next, previous, first, and last page buttons. To render these buttons, kaminari needs to know the number of rows, and for that, a count query is executed. + +```sql +SELECT COUNT(*) FROM issues WHERE project_id = 1 +``` + +#### Performance + +##### Index coverage + +To achieve the good performance, the `ORDER BY` clause needs to be covered by an index. + +Assuming that we have the following index: + +```sql +CREATE INDEX index_on_issues_project_id ON issues (project_id); +``` + +Let's try to request the first page: + +```sql +SELECT issues.* FROM issues WHERE project_id = 1 ORDER BY id LIMIT 20; +``` + +We can produce the same query in Rails: + +```ruby +Issue.where(project_id: 1).page(1).per(20) +``` + +The SQL query will return a maximum of 20 rows from the database. However, it doesn't mean that the database will only read 20 rows from the disk to produce the result. + +This is what will happen: + +1. The database will try to plan the execution in the most efficient way possible based on the table statistics and the available indexes. +1. The planner knows that we have an index covering the `project_id` column. +1. The database will read all rows using the index on `project_id`. +1. The rows at this point are not sorted, so the database will need to sort the rows. +1. The database returns the first 20 rows. + +In case the project has 10_000 rows, the database will read 10_000 rows and sort them in memory (or on disk). This is not going to scale well in the long term. + +To fix this we need the following index: + +```sql +CREATE INDEX index_on_issues_project_id ON issues (project_id, id); +``` + +By making the `id` column part of the index, the previous query will read maximum 20 rows. The query will perform well regardless of the number of issues within a project. So with this change, we've also improved the initial page load (when the user loads the issue page). + +NOTE: +Here we're leveraging the ordered property of the b-tree database index. Values in the index are sorted so reading 20 rows will not require further sorting. + +#### Limitations + +##### `COUNT(*)` on a large dataset + +Kaminari by default executes a count query to determine the number of pages for rendering the page links. Count queries can be quite expensive for a large table, in an unfortunate scenario the queries will simply time out. + +To work around this, we can run kaminari without invoking the count SQL query. + +```ruby +Issue.where(project_id: 1).page(1).per(20).without_count +``` + +In this case, the count query will not be executed and the pagination will no longer render the page numbers. We'll see only the next and previous links. + +##### `OFFSET` on a large dataset + +When we paginate over a large dataset, we might notice that the response time will get slower and slower. This is due to the `OFFSET` clause that seeks through the rows and skips N rows. + +From the user point of view, this might not be always noticeable. As the user paginates forward, the previous rows might be still in the buffer cache of the database. If the user shares the link with someone else and it's opened after a few minutes or hours, the response time might be significantly higher or it would even time out. + +When requesting a large page number, the database needs to read `PAGE * PAGE_SIZE` rows. This makes offset pagination **unsuitable for large database tables**. + +Example: listing users on the Admin page + +Listing users with a very simple SQL query: + +```sql +SELECT "users".* FROM "users" ORDER BY "users"."id" DESC LIMIT 20 OFFSET 0 +``` + +The query execution plan shows that this query is efficient, the database only read 20 rows from the database (`rows=20`): + +```plaintext + Limit (cost=0.43..3.19 rows=20 width=1309) (actual time=0.098..2.093 rows=20 loops=1) + Buffers: shared hit=103 + -> Index Scan Backward using users_pkey on users (cost=0.43..X rows=X width=1309) (actual time=0.097..2.087 rows=20 loops=1) + Buffers: shared hit=103 + Planning Time: 0.333 ms + Execution Time: 2.145 ms +(6 rows) +``` + +See the [Understanding EXPLAIN plans](../understanding_explain_plans.md) to find more information about reading execution plans. + +Let's visit the 50_000th page: + +```sql +SELECT "users".* FROM "users" ORDER BY "users"."id" DESC LIMIT 20 OFFSET 999980; +``` + +The plan shows that the database reads 1_000_000 rows to return 20 rows, with a very high execution time (5.5 seconds): + +```plaintext +Limit (cost=137878.89..137881.65 rows=20 width=1309) (actual time=5523.588..5523.667 rows=20 loops=1) + Buffers: shared hit=1007901 read=14774 written=609 + I/O Timings: read=420.591 write=57.344 + -> Index Scan Backward using users_pkey on users (cost=0.43..X rows=X width=1309) (actual time=0.060..5459.353 rows=1000000 loops=1) + Buffers: shared hit=1007901 read=14774 written=609 + I/O Timings: read=420.591 write=57.344 + Planning Time: 0.821 ms + Execution Time: 5523.745 ms +(8 rows) +``` + +We can argue that a normal user will not be going to visit these pages, however, API users could easily navigate to very high page numbers (scraping, collecting data). + +### Keyset pagination + +Keyset pagination addresses the performance concerns of "skipping" previous rows when requesting a large page, however, it's not a drop-in replacement for offset-based pagination. Keyset pagination is used only in the [GraphQL API](../graphql_guide/pagination.md) + +Consider the following `issues` table: + +|`id`|`project_id`| +|-|-| +|1|1| +|2|1| +|3|2| +|4|1| +|5|1| +|6|2| +|7|2| +|8|1| +|9|1| +|10|2| + +Let's paginate over the whole table ordered by the primary key (`id`). The query for the first page is the same as the offset pagination query, for simplicity, we use 5 as the page size: + +```sql +SELECT "issues".* FROM "issues" ORDER BY "issues"."id" ASC LIMIT 5 +``` + +Notice that we didn't add the `OFFSET` clause. + +To get to the next page, we need to extract values that are part of the `ORDER BY` clause from the last row. In this case, we just need the `id`, which is 5. Now we construct the query for the next page: + +```sql +SELECT "issues".* FROM "issues" WHERE "issues"."id" > 5 ORDER BY "issues"."id" ASC LIMIT 5 +``` + +Looking at the query execution plan, we can see that this query read only 5 rows (offset-based pagination would read 10 rows): + +```plaintext + Limit (cost=0.56..2.08 rows=5 width=1301) (actual time=0.093..0.137 rows=5 loops=1) + -> Index Scan using issues_pkey on issues (cost=0.56..X rows=X width=1301) (actual time=0.092..0.136 rows=5 loops=1) + Index Cond: (id > 5) + Planning Time: 7.710 ms + Execution Time: 0.224 ms +(5 rows) +``` + +#### Limitations + +##### No page numbers + +Offset pagination provides an easy way to request a specific page. We can simply edit the URL and modify the `page=` URL parameter. Keyset pagination cannot provide page numbers because the paging logic might depend on different columns. + +In the previous example, the column is the `id`, so we might see something like this in the `URL`: + +```plaintext +id_after=5 +``` + +In GraphQL, the parameters are serialized to JSON and then encoded: + +```plaintext +eyJpZCI6Ijk0NzMzNTk0IiwidXBkYXRlZF9hdCI6IjIwMjEtMDQtMDkgMDg6NTA6MDUuODA1ODg0MDAwIFVUQyJ9 +``` + +NOTE: +Pagination parameters will be visible to the user, so we need to be careful about which columns we order by. + +Keyset pagination can only provide the next, previous, first, and last pages. + +##### Complexity + +Building queries when we order by a single column is very easy, however, things get more complex if tie-breaker or multi-column ordering is used. The complexity increases if the columns are nullable. + +Example: ordering by `id` and `created_at` where `created_at` is nullable, query for getting the second page: + +```sql +SELECT "issues".* +FROM "issues" +WHERE (("issues"."id" > 99 + AND "issues"."created_at" = '2021-02-16 11:26:17.408466') + OR ("issues"."created_at" > '2021-02-16 11:26:17.408466') + OR ("issues"."created_at" IS NULL)) +ORDER BY "issues"."created_at" DESC NULLS LAST, "issues"."id" DESC +LIMIT 20 +``` + +##### Tooling + +Using keyset pagination outside of GraphQL is not straightforward. We have the low-level blocks for building keyset pagination database queries, however, the usage in application code is still not streamlined yet. + +#### Performance + +Keyset pagination provides stable performance regardless of the number of pages we moved forward. To achieve this performance, the paginated query needs an index that covers all the columns in the `ORDER BY` clause, similarly to the offset pagination. + +### General performance guidelines + +See the [pagination general performance guidelines page](pagination_performance_guidelines.md). diff --git a/doc/development/database/pagination_performance_guidelines.md b/doc/development/database/pagination_performance_guidelines.md new file mode 100644 index 00000000000..ade1e853027 --- /dev/null +++ b/doc/development/database/pagination_performance_guidelines.md @@ -0,0 +1,325 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Pagination performance guidelines + +The following document gives a few ideas for improving the pagination (sorting) performance. These apply both on [offset](pagination_guidelines.md#offset-pagination) and [keyset](pagination_guidelines.md#keyset-pagination) paginations. + +## Tie-breaker column + +When ordering the columns it's advised to order by distinct columns only. Consider the following example: + +|`id`|`created_at`| +|-|-| +|1|2021-01-04 14:13:43| +|2|2021-01-05 19:03:12| +|3|2021-01-05 19:03:12| + +If we order by `created_at`, the result would likely depend on how the records are located on the disk. + +Using the tie-breaker column is advised when the data is exposed via a well defined interface and its consumed +by an automated process, such as an API. Without the tie-breaker column, the order of the rows could change +(data is re-imported) which could cause problems that are hard to debug, such as: + +- An integration comparing the rows to determine changes breaks. +- E-tag cache values change, which requires a complete re-download. + +```sql +SELECT issues.* FROM issues ORDER BY created_at; +``` + +We can fix this by adding a second column to `ORDER BY`: + +```sql +SELECT issues.* FROM issues ORDER BY created_at, id; +``` + +This change makes the order distinct so we have "stable" sorting. + +NOTE: +To make the query efficient, we need an index covering both columns: `(created_at, id)`. The order of the columns **should match** the columns in the `ORDER BY` clause. + +## Ordering by joined table column + +Oftentimes, we want to order the data by a column on a joined database table. The following example orders `issues` records by the `first_mentioned_in_commit_at` metric column: + +```sql +SELECT issues.* FROM issues +INNER JOIN issue_metrics on issue_metrics.issue_id=issues.id +WHERE issues.project_id = 2 +ORDER BY issue_metrics.first_mentioned_in_commit_at DESC, issues.id DESC +LIMIT 20 +OFFSET 0 +``` + +With PostgreSQL version 11, the planner will first look up all issues matching the `project_id` filter and then join all `issue_metrics` rows. The ordering of rows will happen in memory. In case the joined relation is always present (1:1 relationship), the database will read `N * 2` rows where N is the number of rows matching the `project_id` filter. + +For performance reasons, we should avoid mixing columns from different tables when specifying the `ORDER BY` clause. + +In this particular case there is no simple way (like index creation) to improve the query. We might think that changing the `issues.id` column to `issue_metrics.issue_id` will help, however, this will likely make the query perform worse because it might force the database to process all rows in the `issue_metrics` table. + +One idea to address this problem is denormalization. Adding the `project_id` column to the `issue_metrics` table will make the filtering and sorting efficient: + +```sql +SELECT issues.* FROM issues +INNER JOIN issue_metrics on issue_metrics.issue_id=issues.id +WHERE issue_metrics.project_id = 2 +ORDER BY issue_metrics.first_mentioned_in_commit_at DESC, issue_metrics.issue_id DESC +LIMIT 20 +OFFSET 0 +``` + +NOTE: +The query will require an index on `issue_metrics` table with the following column configuration: `(project_id, first_mentioned_in_commit_at DESC, issue_id DESC)`. + +## Filtering + +### By project + +Filtering by a project is a very common use case since we have many features on the project level. Examples: merge requests, issues, boards, iterations. + +These features will have a filter on `project_id` in their base query. Loading issues for a project: + +```ruby +project = Project.find(5) + +# order by internal id +issues = project.issues.order(:iid).page(1).per(20) +``` + +To make the base query efficient, there is usually a database index covering the `project_id` column. This significantly reduces the number of rows the database needs to scan. Without the index, the whole `issues` table would be read (full table scan) by the database. + +Since `project_id` is a foreign key, we might have the following index available: + +```sql +"index_issues_on_project_id" btree (project_id) +``` + +GitLab 13.11 has the following index definition on the `issues` table: + +```sql +"index_issues_on_project_id_and_iid" UNIQUE, btree (project_id, iid) +``` + +This index fully covers the database query and the pagination. + +### By group + +Unfortunately, there is no efficient way to sort and paginate on the group level. The database query execution time will increase based on the number of records in the group. + +Things get worse when group level actually means group and its subgroups. To load the first page, the database needs to look up the group hierarchy, find all projects and then look up all issues. + +The main reason behind the inefficient queries on the group level is the way our database schema is designed; our core domain models are associated with a project, and projects are associated with groups. This doesn't mean that the database structure is bad, it's just in a well-normalized form that is not optimized for efficient group level queries. We might need to look into denormalization in the long term. + +Example: List issues in a group + +```ruby +group = Group.find(9970) + +Issue.where(project_id: group.projects).order(:iid).page(1).per(20) +``` + +The generated SQL query: + +```sql +SELECT "issues".* +FROM "issues" +WHERE "issues"."project_id" IN + (SELECT "projects"."id" + FROM "projects" + WHERE "projects"."namespace_id" = 5) +ORDER BY "issues"."iid" ASC +LIMIT 20 +OFFSET 0 +``` + +The execution plan shows that we read significantly more rows than requested (20), and the rows are sorted in memory: + +```plaintext + Limit (cost=10716.87..10716.92 rows=20 width=1300) (actual time=1472.305..1472.308 rows=20 loops=1) + -> Sort (cost=10716.87..10717.03 rows=61 width=1300) (actual time=1472.303..1472.305 rows=20 loops=1) + Sort Key: issues.iid + Sort Method: top-N heapsort Memory: 41kB + -> Nested Loop (cost=1.00..10715.25 rows=61 width=1300) (actual time=0.215..1331.647 rows=177267 loops=1) + -> Index Only Scan using index_projects_on_namespace_id_and_id on projects (cost=0.44..3.77 rows=19 width=4) (actual time=0.077..1.057 rows=270 loops=1) + Index Cond: (namespace_id = 9970) + Heap Fetches: 25 + -> Index Scan using index_issues_on_project_id_and_iid on issues (cost=0.56..559.28 rows=448 width=1300) (actual time=0.101..4.781 rows=657 loops=270) + Index Cond: (project_id = projects.id) + Planning Time: 12.281 ms + Execution Time: 1472.391 ms +(12 rows) +``` + +#### Columns in the same database table + +Filtering by columns located in the same database table can be improved with an index. In case we want to support filtering by the `state_id` column, we can add the following index: + +```sql +"index_issues_on_project_id_and_state_id_and_iid" UNIQUE, btree (project_id, state_id, iid) +``` + +Example query in Rails: + +```ruby +project = Project.find(5) + +# order by internal id +issues = project.issues.opened.order(:iid).page(1).per(20) +``` + +SQL query: + +```sql +SELECT "issues".* +FROM "issues" +WHERE + "issues"."project_id" = 5 + AND ("issues"."state_id" IN (1)) +ORDER BY "issues"."iid" ASC +LIMIT 20 +OFFSET 0 +``` + +Keep in mind that the index above will not support the following project level query: + +```sql +SELECT "issues".* +FROM "issues" +WHERE "issues"."project_id" = 5 +ORDER BY "issues"."iid" ASC +LIMIT 20 +OFFSET 0 +``` + +#### Special case: confidential flag + +In the `issues` table, we have a boolean field (`confidential`) that marks an issue confidential. This makes the issue invisible (filtered out) for non-member users. + +Example SQL query: + +```sql +SELECT "issues".* +FROM "issues" +WHERE "issues"."project_id" = 5 +AND "issues"."confidential" = FALSE +ORDER BY "issues"."iid" ASC +LIMIT 20 +OFFSET 0 +``` + +We might be tempted to add an index on `project_id`, `confidential`, and `iid` to improve the database query, however, in this case it's probably unnecessary. Based on the data distribution in the table, confidential issues are rare. Filtering them out does not make the database query significantly slower. The database might read a few extra rows, the performance difference might not even be visible to the end-user. + +On the other hand, if we would implement a special filter where we only show confidential issues, we will surely need the index. Finding 20 confidential issues might require the database to scan hundreds of rows or in the worst case, all issues in the project. + +NOTE: +Be aware of the data distribution and the table access patterns (how features work) when introducing a new database index. Sampling production data might be necessary to make the right decision. + +#### Columns in a different database table + +Example: filtering issues in a project by an assignee + +```ruby +project = Project.find(5) + +project + .issues + .joins(:issue_assignees) + .where(issue_assignees: { user_id: 10 }) + .order(:iid) + .page(1) + .per(20) +``` + +```sql +SELECT "issues".* +FROM "issues" +INNER JOIN "issue_assignees" ON "issue_assignees"."issue_id" = "issues"."id" +WHERE "issues"."project_id" = 5 + AND "issue_assignees"."user_id" = 10 +ORDER BY "issues"."iid" ASC +LIMIT 20 +OFFSET 0 +``` + +Example database (oversimplified) execution plan: + +1. The database parses the SQL query and detects the `JOIN`. +1. The database splits the query into two subqueries. + - `SELECT "issue_assignees".* FROM "issue_assignees" WHERE "issue_assignees"."user_id" = 10` + - `SELECT "issues".* FROM "issues" WHERE "issues"."project_id" = 5` +1. The database estimates the number of rows and the costs to run these queries. +1. The database executes the cheapest query first. +1. Using the query result, load the rows from the other table (from the other query) using the JOIN column and filter the rows further. + +In this particular example, the `issue_assignees` query would likely be executed first. + +Running the query in production for the GitLab project produces the following execution plan: + +```plaintext + Limit (cost=411.20..411.21 rows=1 width=1300) (actual time=24.071..24.077 rows=20 loops=1) + -> Sort (cost=411.20..411.21 rows=1 width=1300) (actual time=24.070..24.073 rows=20 loops=1) + Sort Key: issues.iid + Sort Method: top-N heapsort Memory: 91kB + -> Nested Loop (cost=1.00..411.19 rows=1 width=1300) (actual time=0.826..23.705 rows=190 loops=1) + -> Index Scan using index_issue_assignees_on_user_id on issue_assignees (cost=0.44..81.37 rows=92 width=4) (actual time=0.741..13.202 rows=215 loops=1) + Index Cond: (user_id = 4156052) + -> Index Scan using issues_pkey on issues (cost=0.56..3.58 rows=1 width=1300) (actual time=0.048..0.048 rows=1 loops=215) + Index Cond: (id = issue_assignees.issue_id) + Filter: (project_id = 278964) + Rows Removed by Filter: 0 + Planning Time: 1.141 ms + Execution Time: 24.170 ms +(13 rows) +``` + +The query looks up the `assignees` first, filtered by the `user_id` (`user_id = 4156052`) and it finds 215 rows. Using that 215 rows, the database will look up the 215 associated issue rows by the primary key. Notice that the filter on the `project_id` column is not backed by an index. + +In most cases, we are lucky that the joined relation will not be going to return too many rows, therefore, we will end up with a relatively efficient database query that accesses low number of rows. As the database grows, these queries might start to behave differently. Let's say the number `issue_assignees` records for a particular user is very high (millions), then this join query will not perform well, and it will likely time out. + +A similar problem could be a double join, where the filter exists in the 2nd JOIN query. Example: `Issue -> LabelLink -> Label(name=bug)`. + +There is no easy way to fix these problems. Denormalization of data could help significantly, however, it has also negative effects (data duplication and keeping the data up to date). + +Ideas for improving the `issue_assignees` filter: + +- Add `project_id` column to the `issue_assignees` table so when JOIN-ing, the extra `project_id` filter will further filter the rows. The sorting will likely happen in memory: + + ```sql + SELECT "issues".* + FROM "issues" + INNER JOIN "issue_assignees" ON "issue_assignees"."issue_id" = "issues"."id" + WHERE "issues"."project_id" = 5 + AND "issue_assignees"."user_id" = 10 + AND "issue_assignees"."project_id" = 5 + ORDER BY "issues"."iid" ASC + LIMIT 20 + OFFSET 0 + ``` + +- Add the `iid` column to the `issue_assignees` table. Notice that the `ORDER BY` column is different and the `project_id` filter is gone from the `issues` table: + + ```sql + SELECT "issues".* + FROM "issues" + INNER JOIN "issue_assignees" ON "issue_assignees"."issue_id" = "issues"."id" + WHERE "issue_assignees"."user_id" = 10 + AND "issue_assignees"."project_id" = 5 + ORDER BY "issue_assignees"."iid" ASC + LIMIT 20 + OFFSET 0 + ``` + +The query now performs well for any number of `issue_assignees` records, however, we pay a very high price for it: + +- Two columns are duplicated which increases the database size. +- We need to keep the two columns in sync. +- We need more indexes on the `issue_assignees` table to support the query. +- The new database query is very specific to the assignee search and needs complex backend code to build it. + - If the assignee is filtered by the user, then order by a different column, remove the `project_id` filter, etc. + +NOTE: +Currently we're not doing these kinds of denormalization at GitLab. diff --git a/doc/development/database/rename_database_tables.md b/doc/development/database/rename_database_tables.md new file mode 100644 index 00000000000..743558fae19 --- /dev/null +++ b/doc/development/database/rename_database_tables.md @@ -0,0 +1,140 @@ +--- +stage: Enablement +group: Database +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Rename table without downtime + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/54354) in GitLab 13.12. + +With our database helper methods built into GitLab, it's possible to rename a database table without downtime. + +The technique builds on top of database views, using the following steps: + +1. Rename the database table. +1. Create a database view using the old table name by pointing to the new table name. +1. Add workaround for ActiveRecord's schema cache. + +For example, consider that we are renaming the `issues` table name to `tickets`. Run: + +```sql +BEGIN; + ALTER TABLE issues RENAME TO tickets; + CREATE VIEW issues AS SELECT * FROM tickets; +COMMIT; +``` + +As database views do not expose the underlying table schema (default values, not null +constraints, and indexes), we need further steps to update the application to use the new +table name. ActiveRecord heavily relies on this data, for example, to initialize new +models. + +To work around this limitation, we need to tell ActiveRecord to acquire this information +from a different table using the new table name. + +## Migration strategy breakdown + +### Release N.M: Mark the ActiveRecord model's table + +Consider the current release as "Release N.M". + +In this release, register the database table so that it instructs ActiveRecord to fetch the +database table information (for `SchemaCache`) using the new table name (if it's present). Otherwise, fall back +to the old table name. This is necessary to avoid errors during a zero-downtime deployment. + +1. Edit the `TABLES_TO_BE_RENAMED` constant in: `lib/gitlab/database.rb` + + ```ruby + TABLES_TO_BE_RENAMED = { + 'issues' => 'tickets' + }.freeze + ``` + +Note that, in this release (N.M), the `tickets` database table does not exist yet. This step is preparing for the actual table rename in release N.M+1. + +### Release N.M+1: Rename the database table + +Consider the next release as "Release N.M". + +Execute a standard migration (not a post-migration): + +```ruby + include Gitlab::Database::MigrationHelpers + + def up + rename_table_safely(:issues, :tickets) + end + + def down + undo_rename_table_safely(:issues, :tickets) + end +``` + +**Important notes:** + +- Let other developers know that the table is going to be renamed. + - Ping the `@gl-database` group in your merge request. + - Add a note in the Engineering Week-in-Review document: `table_name` is going to be renamed in N.M. Modifications to this table are not allowed in release N.M and N.M+1. +- The helper method uses the standard `rename_table` helper from Rails for renaming the table. +- The helper renames the sequence and the indexes. Sometimes it diverges from the standard Rails convention +when naming indexes, so there is a possibility that not all indexes are properly renamed. After running +the migration locally, check if there are inconsistently named indexes (`db/structure.sql`). Those can be +renamed manually in a separate migration, which can be also part of the release M.N+1. +- Foreign key columns might still contain the old table name. For smaller tables, follow our [standard column +rename process](../avoiding_downtime_in_migrations.md#renaming-columns) +- Avoid renaming database tables which are using with triggers. +- Table modifications (add or remove columns) are not allowed during the rename process, please make sure that all changes to the table happen before the rename migration is started (or in the next release). +- As the index names might change, verify that the model does not use bulk insert +(for example, `insert_all` and `upsert_all`) with the `unique_by: index_name` option. +Renaming an index while using these methods may break functionality. +- Modify the model code to point to the new database table. Do this by +renaming the model directly or setting the `self.table_name` variable. + +At this point, we don't have applications using the old database table name in their queries. + +1. Remove the database view through a post-migration: + + ```ruby + include Gitlab::Database::MigrationHelpers + + def up + finalize_table_rename(:issues, :tickets) + end + + def down + undo_finalize_table_rename(:issues, :tickets) + end + ``` + +1. Additionally the table definition from `TABLES_TO_BE_RENAMED` **must** be removed. + +To do so, edit the `TABLES_TO_BE_RENAMED` constant in `lib/gitlab/database.rb`: + + From: + + ```ruby + TABLES_TO_BE_RENAMED = { + 'issues' => 'tickets' + }.freeze + ``` + + To: + + ```ruby + TABLES_TO_BE_RENAMED = {}.freeze + ``` + +#### Zero-downtime deployments + +When the application is upgraded without downtime, there can be application instances +running the old code. The old code still references the old database table. The queries +still function without any problems, because the backward-compatible database view is +in place. + +In case the old version of the application needs to be restarted or reconnected to the +database, ActiveRecord fetches the column information again. At this time, our previously +marked table (`TABLES_TO_BE_RENAMED`) instructs ActiveRecord to use the new database table name +when fetching the database table information. + +The new version of the application will use the new database table. diff --git a/doc/development/developing_with_solargraph.md b/doc/development/developing_with_solargraph.md new file mode 100644 index 00000000000..877fbad8ab2 --- /dev/null +++ b/doc/development/developing_with_solargraph.md @@ -0,0 +1,28 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Using Solargraph + +Gemfile packages [Solargraph](https://github.com/castwide/solargraph) language server for additional IntelliSense and code formatting capabilities with editors that support it. + +Example configuration for Solargraph can be found in [.solargraph.yml.example](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.solargraph.yml.example) file. Copy the contents of this file to `.solargraph.yml` file for language server to pick this configuration up. Since `.solargraph.yml` configuration file is ignored by Git, it's possible to adjust configuration according to your needs. + +Refer to particular IDE plugin documentation on how to integrate it with Solargraph language server: + +- **Visual Studio Code** + - GitHub: [`vscode-solargraph`](https://github.com/castwide/vscode-solargraph) + +- **Atom** + - GitHub: [`atom-solargraph`](https://github.com/castwide/atom-solargraph) + +- **Vim** + - GitHub: [`LanguageClient-neovim`](https://github.com/autozimu/LanguageClient-neovim) + +- **Emacs** + - GitHub: [`emacs-solargraph`](https://github.com/guskovd/emacs-solargraph) + +- **Eclipse** + - GitHub: [`eclipse-solargraph`](https://github.com/PyvesB/eclipse-solargraph) diff --git a/doc/development/distributed_tracing.md b/doc/development/distributed_tracing.md index e5293c0804c..8bd8599a0b0 100644 --- a/doc/development/distributed_tracing.md +++ b/doc/development/distributed_tracing.md @@ -89,8 +89,6 @@ The easiest way to access tracing from a GDK environment is through the [performance-bar](../administration/monitoring/performance/performance_bar.md). This can be shown by typing `p` `b` in the browser window. - - Once the performance bar is enabled, click on the **Trace** link in the performance bar to go to the Jaeger UI. diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index 7dd02c44afa..7fa80e2d0f5 100644 --- a/doc/development/documentation/feature_flags.md +++ b/doc/development/documentation/feature_flags.md @@ -52,7 +52,7 @@ Include details of the feature flag in the documentation: [by-project information](#features-enabled-by-project). Otherwise, do not say anything about it. - Say whether it's recommended for production use. -- Document how to enable and disable it. +- Document how to enable and disable it, preferably at the end of the file. - Add a warning to the user saying that the feature might be disabled. For example, for a feature disabled by default, disabled on GitLab.com, cannot @@ -110,7 +110,7 @@ default: [by-project information](#features-enabled-by-project). Otherwise, do not say anything about it. - Say whether it's recommended for production use. -- Document how to disable and enable it. +- Document how to disable and enable it, preferably at the end of the file. - Add a warning to the user saying that the feature might be disabled. For example, for a feature initially deployed disabled by default, that became @@ -169,7 +169,7 @@ For features enabled by default: [by-project information](#features-enabled-by-project). Otherwise, do not say anything about it. - Say whether it's recommended for production use. -- Document how to disable and enable it. +- Document how to disable and enable it, preferably at the end of the file. - Add a warning to the user saying that the feature might be disabled. For example, for a feature enabled by default, enabled on GitLab.com, that diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index f10396570a2..05aa003d89e 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -411,7 +411,7 @@ on how the left-side navigation menu is built and updated. NOTE: To preview your changes to documentation locally, follow this -[development guide](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/README.md#development-when-contributing-to-gitlab-documentation) or [these instructions for GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/gitlab_docs.md). +[development guide](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/README.md#development-when-contributing-to-gitlab-documentation) or [these instructions for GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/gitlab_docs.md). The live preview is currently enabled for the following projects: @@ -502,7 +502,7 @@ help of a configuration file known as **screenshot generator**. To run the tool on an existing screenshot generator, take the following steps: -1. Set up the [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/gitlab_docs.md). +1. Set up the [GitLab Development Kit (GDK)](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/gitlab_docs.md). 1. Navigate to the subdirectory with your cloned GitLab repository, typically `gdk/gitlab`. 1. Make sure that your GDK database is fully migrated: `bin/rake db:migrate RAILS_ENV=development`. 1. Install `pngquant`, see the tool website for more information: [`pngquant`](https://pngquant.org/) diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md index 33bfc040bb6..67bdbffa2a1 100644 --- a/doc/development/documentation/structure.md +++ b/doc/development/documentation/structure.md @@ -58,6 +58,9 @@ Don't tell them **how** to do this thing. Tell them **what it is**. If you start describing another topic, start a new concept and link to it. +Also, do not use "Overview" or "Introduction" for the topic title. Instead, +use a noun or phrase that someone would search for. + Concept topics should be in this format: ```markdown @@ -111,13 +114,16 @@ Prerequisites: To create an issue: 1. Go to **Issues > List**. -1. In the top right, click **New issue**. +1. In the top right, select **New issue**. 1. Complete the fields. (If you have a reference topic that lists each field, link to it here.) -1. Click **Create issue**. +1. Select **Create issue**. The issue is created. You can view it by going to **Issues > List**. ``` +If you have several tasks on a page that share prerequisites, you can make a +reference topic with the title **Prerequisites**, and link to it. + ## Reference A reference topic provides information in an easily-scannable format, @@ -133,6 +139,9 @@ Introductory sentence. | **Name** | Descriptive sentence about the setting. | ``` +If a feature or concept has its own prerequisites, you can use the reference +topic type to create a **Prerequisites** header for the information. + ## Troubleshooting Troubleshooting topics can be one of two categories: diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index 25cdbaf75ba..0ac393a8509 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -164,13 +164,12 @@ standard for GitLab documentation). A rule that could cause confusion is `MD044/proper-names`, as it might not be immediately clear what caused markdownlint to fail, or how to correct the -failure. This rule checks a list of known words, listed in the `.markdownlint.json` +failure. This rule checks a list of known words, listed in the `.markdownlint.yml` file in each project, to verify proper use of capitalization and backticks. Words in backticks are ignored by markdownlint. In general, product names should follow the exact capitalization of the official -names of the products, protocols, and so on. See [`.markdownlint.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.markdownlint.json) -for the words tested for proper capitalization in GitLab documentation. +names of the products, protocols, and so on. Some examples fail if incorrect capitalization is used: @@ -370,7 +369,7 @@ Capitalize names of: - Third-party organizations, software, and products. For example, Prometheus, Kubernetes, Git, and The Linux Foundation. - Methods or methodologies. For example, Continuous Integration, - Continuous Deployment, Scrum, and Agile. (Tested in [`.markdownlint.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.markdownlint.json).) + Continuous Deployment, Scrum, and Agile. Follow the capitalization style listed at the [authoritative source](#links-to-external-documentation) for the entity, which may use non-standard case styles. For example: GitLab and @@ -1112,13 +1111,9 @@ document to ensure it links to the most recent version of the file. When documenting navigation through the user interface: - Use the exact wording as shown in the UI, including any capital letters as-is. -- Use bold text for navigation items and the char "greater than" (`>`) as a - separator. For example: `From your project, go to **Settings > CI/CD**`. -- If there are any expandable menus, make sure to mention that the user needs to - expand the tab to find the settings you're referring to. For example: - `From your group, go to **Settings > CI/CD** and expand **General pipelines**`. +- Use bold text for navigation items. -### Navigational elements +### What to call the menus Use these terms when referring to the main GitLab user interface elements: @@ -1130,6 +1125,19 @@ elements: - **Right sidebar**: This is the navigation sidebar on the right of the user interface, specific to the open issue, merge request, or epic. +### How to document the left sidebar + +To be consistent, use this format when you refer to the left sidebar. + +- Go to your project and select **Settings > CI/CD**. +- Go to your group and select **Settings > CI/CD**. +- Go to the Admin Area (**{admin}**) and select **Overview > Projects**. + +For expandable menus, use this format: + +1. Go to your group and select **Settings > CI/CD**. +1. Expand **General pipelines**. + ## Images Images, including screenshots, can help a reader better understand a concept. diff --git a/doc/development/documentation/testing.md b/doc/development/documentation/testing.md index aee3144e6de..af95f3b9023 100644 --- a/doc/development/documentation/testing.md +++ b/doc/development/documentation/testing.md @@ -150,11 +150,11 @@ from those guidelines. markdownlint configuration is found in the following projects: -- [`gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/.markdownlint.json) -- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner/blob/master/.markdownlint.json) -- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/.markdownlint.json) -- [`charts`](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/.markdownlint.json) -- [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/.markdownlint.json) +- [`gitlab`](https://gitlab.com/gitlab-org/gitlab) +- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner) +- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab) +- [`charts`](https://gitlab.com/gitlab-org/charts/gitlab) +- [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit) This configuration is also used in build pipelines. diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index 35e7824721a..452b957c705 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.md @@ -20,7 +20,7 @@ Since the implementation of [GitLab CE features to work with unlicensed EE instance](https://gitlab.com/gitlab-org/gitlab/-/issues/2500) GitLab Enterprise Edition should work like GitLab Community Edition when no license is active. So EE features always should be guarded by -`project.feature_available?` or `group.feature_available?` (or +`project.feature_available?` or `group.licensed_feature_available?` (or `License.feature_available?` if it is a system-wide feature). Frontend features should be guarded by pushing a flag from the backend by [using `push_licensed_feature`](licensed_feature_availability.md#restricting-frontend-features), and checked using `this.glFeatures.someFeature` in the frontend. @@ -94,11 +94,11 @@ class User < ActiveRecord::Base # ... lots of code here ... end -User.prepend_ee_mod +User.prepend_mod ``` Do not use methods such as `prepend`, `extend`, and `include`. Instead, use -`prepend_ee_mod`, `extend_ee_mod`, or `include_ee_mod`. These methods will try to +`prepend_mod`, `extend_mod`, or `include_mod`. These methods will try to find the relevant EE module by the name of the receiver module, for example; ```ruby @@ -108,13 +108,13 @@ module Vulnerabilities end end -Vulnerabilities::Finding.prepend_ee_mod +Vulnerabilities::Finding.prepend_mod ``` will prepend the module named `::EE::Vulnerabilities::Finding`. If the extending module does not follow this naming convention, you can also provide the module name -by using `prepend_if_ee`, `extend_if_ee`, or `include_if_ee`. These methods take a +by using `prepend_mod_with`, `extend_mod_with`, or `include_mod_with`. These methods take a _String_ containing the full module name as the argument, not the module itself, like so; ```ruby @@ -122,7 +122,7 @@ class User #... end -User.prepend_if_ee('::EE::UserExtension') +User.prepend_mod_with('UserExtension') ``` Since the module would require an `EE` namespace, the file should also be @@ -254,7 +254,7 @@ class ApplicationController < ActionController::Base # ... end -ApplicationController.prepend_if_ee('EE::ApplicationController') +ApplicationController.prepend_mod_with('ApplicationController') ``` And create a new file in the `ee/` sub-directory with the altered @@ -429,7 +429,7 @@ module Gitlab end end -Gitlab::BackgroundMigration::PruneOrphanedGeoEvents.prepend_if_ee('EE::Gitlab::BackgroundMigration::PruneOrphanedGeoEvents') +Gitlab::BackgroundMigration::PruneOrphanedGeoEvents.prepend_mod_with('Gitlab::BackgroundMigration::PruneOrphanedGeoEvents') ``` GitLab EE: @@ -563,7 +563,7 @@ EE-specific LDAP classes in `ee/lib/ee/gitlab/ldap`. ### Code in `lib/api/` -It can be very tricky to extend EE features by a single line of `prepend_if_ee`, +It can be very tricky to extend EE features by a single line of `prepend_mod_with`, and for each different [Grape](https://github.com/ruby-grape/grape) feature, we might need different strategies to extend it. To apply different strategies easily, we would use `extend ActiveSupport::Concern` in the EE module. @@ -602,7 +602,7 @@ constants. We can define `params` and use `use` in another `params` definition to include parameters defined in EE. However, we need to define the "interface" first in CE in order for EE to override it. We don't have to do this in other places -due to `prepend_if_ee`, but Grape is complex internally and we couldn't easily +due to `prepend_mod_with`, but Grape is complex internally and we couldn't easily do that, so we follow regular object-oriented practices that we define the interface first here. @@ -642,7 +642,7 @@ module API end end -API::Helpers::ProjectsHelpers.prepend_if_ee('EE::API::Helpers::ProjectsHelpers') +API::Helpers::ProjectsHelpers.prepend_mod_with('API::Helpers::ProjectsHelpers') ``` We could override it in EE module: @@ -683,7 +683,7 @@ module API end end -API::JobArtifacts.prepend_if_ee('EE::API::JobArtifacts') +API::JobArtifacts.prepend_mod_with('API::JobArtifacts') ``` And then we can follow regular object-oriented practices to override it: @@ -736,7 +736,7 @@ module API end end -API::MergeRequests.prepend_if_ee('EE::API::MergeRequests') +API::MergeRequests.prepend_mod_with('API::MergeRequests') ``` Note that `update_merge_request_ee` doesn't do anything in CE, but @@ -777,7 +777,7 @@ can't easily extend it with an EE module because Grape has different context in different blocks. In order to overcome this, we need to move the data to a class method that resides in a separate module or class. This allows us to extend that module or class before its data is used, without having to place a -`prepend_if_ee` in the middle of CE code. +`prepend_mod_with` in the middle of CE code. For example, in one place we need to pass an extra argument to `at_least_one_of` so that the API could consider an EE-only argument as the @@ -798,7 +798,7 @@ module API end end -API::MergeRequests::Parameters.prepend_if_ee('EE::API::MergeRequests::Parameters') +API::MergeRequests::Parameters.prepend_mod_with('API::MergeRequests::Parameters') # api/merge_requests.rb module API @@ -848,7 +848,7 @@ class Identity < ActiveRecord::Base [:provider] end - prepend_if_ee('EE::Identity') + prepend_mod_with('Identity') validates :extern_uid, allow_blank: true, @@ -900,7 +900,7 @@ class Identity < ActiveRecord::Base end end -Identity::UniquenessScopes.prepend_if_ee('EE::Identity::UniquenessScopes') +Identity::UniquenessScopes.prepend_mod_with('Identity::UniquenessScopes') # app/models/identity.rb class Identity < ActiveRecord::Base diff --git a/doc/development/elasticsearch.md b/doc/development/elasticsearch.md index 705a69765f7..6b829faf74d 100644 --- a/doc/development/elasticsearch.md +++ b/doc/development/elasticsearch.md @@ -25,7 +25,7 @@ Developers making significant changes to Elasticsearch queries should test their ## Setting up development environment -See the [Elasticsearch GDK setup instructions](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/elasticsearch.md) +See the [Elasticsearch GDK setup instructions](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/elasticsearch.md) ## Helpful Rake tasks @@ -241,8 +241,8 @@ cron worker runs. Default value is 5 minutes. - `pause_indexing!` - Pause indexing while the migration runs. This setting will record the indexing setting before the migration runs and set it back to that value when the migration is completed. -- `space_requirements!` - Verify that enough free space is available in the cluster when the migration runs. This setting - will halt the migration if the storage required is not available when the migration runs. The migration must provide +- `space_requirements!` - Verify that enough free space is available in the cluster when the migration runs. This setting + will halt the migration if the storage required is not available when the migration runs. The migration must provide the space required in bytes by defining a `space_required_bytes` method. ```ruby @@ -285,7 +285,7 @@ defer it to another release if there is risk of important data loss. Follow these best practices for best results: - When working in batches, keep the batch size under 9,000 documents - and `throttle_delay` over 3 minutes. The bulk indexer is set to run + and `throttle_delay` for at least 3 minutes. The bulk indexer is set to run every 1 minute and process a batch of 10,000 documents. These limits allow the bulk indexer time to process records before another migration batch is attempted. @@ -316,11 +316,11 @@ choose to remove the migration code and tests so that: anymore. To be extra safe, we will not delete migrations that were created in the last -minor version before the major upgrade. So, if the we are upgrading to `%14.0`, -we should not delete migrations that were only added in `%13.11`. This is an +minor version before the major upgrade. So, if we are upgrading to `%14.0`, +we should not delete migrations that were only added in `%13.12`. This is an extra safety net as we expect there are migrations that get merged that may take multiple weeks to finish on GitLab.com. It would be bad if we upgraded -GitLab.com to `%14.0` before the migrations in `%13.11` were finished. Since +GitLab.com to `%14.0` before the migrations in `%13.12` were finished. Since our deployments to GitLab.com are automated and we currently don't have automated checks to prevent this, the extra precaution is warranted. Additionally, even if we did have automated checks to prevent it, we wouldn't @@ -340,7 +340,7 @@ being upgraded to, we do the following: def migrate log_raise "Migration has been deleted in the last major version upgrade." \ "Migrations are supposed to be finished before upgrading major version https://docs.gitlab.com/ee/update/#upgrading-to-a-new-major-version ." \ - "In order to correct this issue you will need to reacreate your index from scratch https://docs.gitlab.com/ee/integration/elasticsearch.html#last-resort-to-recreate-an-index ." + "To correct this issue, recreate your index from scratch: https://docs.gitlab.com/ee/integration/elasticsearch.html#last-resort-to-recreate-an-index." end def completed? diff --git a/doc/development/experiment_guide/gitlab_experiment.md b/doc/development/experiment_guide/gitlab_experiment.md index 4b93105ea50..db9bc521cfd 100644 --- a/doc/development/experiment_guide/gitlab_experiment.md +++ b/doc/development/experiment_guide/gitlab_experiment.md @@ -503,7 +503,7 @@ so you can use it when resolving some concepts around experimentation in the cli ### Use experiments in Vue -With the `experiment` component, you can define slots that match the name of the +With the `gitlab-experiment` component, you can define slots that match the name of the variants pushed to `window.gon.experiment`. For example, if we alter the `pill_color` experiment to just use the default variants of `control` and `candidate` like so: @@ -520,15 +520,15 @@ We can make use of the named slots `control` and `candidate` in the Vue componen ```vue <script> -import Experiment from '~/experimentation/components/experiment.vue'; +import GitlabExperiment from '~/experimentation/components/gitlab_experiment.vue'; export default { - components: { Experiment } + components: { GitlabExperiment } } </script> <template> - <experiment name="pill_color"> + <gitlab-experiment name="pill_color"> <template #control> <button class="bg-default">Click default button</button> </template> @@ -536,7 +536,7 @@ export default { <template #candidate> <button class="bg-red">Click red button</button> </template> - </experiment> + </gitlab-experiment> </template> ``` @@ -545,7 +545,7 @@ For example, the Vue component for the previously-defined `pill_color` experimen ```vue <template> - <experiment name="pill_color"> + <gitlab-experiment name="pill_color"> <template #control> <button class="bg-default">Click default button</button> </template> @@ -557,7 +557,7 @@ For example, the Vue component for the previously-defined `pill_color` experimen <template #blue> <button class="bg-blue">Click blue button</button> </template> - </experiment> + </gitlab-experiment> </template> ``` diff --git a/doc/development/experiment_guide/index.md b/doc/development/experiment_guide/index.md index 15430831f4a..0d534a974a1 100644 --- a/doc/development/experiment_guide/index.md +++ b/doc/development/experiment_guide/index.md @@ -59,4 +59,4 @@ feature flags, and there is currently no strong suggestion to use one over the o Historical Context: `Experimentation Module` was built iteratively with the needs that appeared while implementing Growth sub-department experiments, while GLEX was built -with the learnings of the team and an easier to use API. +with the findings of the team and an easier to use API. diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md index e87b4197269..49c511c2b85 100644 --- a/doc/development/fe_guide/graphql.md +++ b/doc/development/fe_guide/graphql.md @@ -118,6 +118,8 @@ To distinguish queries from mutations and fragments, the following naming conven - `add_user.mutation.graphql` for mutations; - `basic_user.fragment.graphql` for fragments. +If you are using queries for the [CustomersDot GraphQL endpoint](https://gitlab.com/gitlab-org/gitlab/-/blob/be78ccd832fd40315c5e63bb48ee1596ae146f56/app/controllers/customers_dot/proxy_controller.rb), end the filename with `.customer.query.graphql`, `.customer.mutation.graphql`, or `.customer.fragment.graphql`. + ### Fragments [Fragments](https://graphql.org/learn/queries/#fragments) are a way to make your complex GraphQL queries more readable and re-usable. Here is an example of GraphQL fragment: @@ -780,7 +782,7 @@ While the Apollo client has support for simple polling, for performance reasons, Once the backend is set up, there are a few changes to make on the frontend. -First, get your resource Etag path from the backend. In the example of the pipelines graph, this is called the `graphql_resource_etag`. This will be used to create new headers to add to the Apollo context: +First, get your resource ETag path from the backend. In the example of the pipelines graph, this is called the `graphql_resource_etag`. This will be used to create new headers to add to the Apollo context: ```javascript /* pipelines/components/graph/utils.js */ @@ -815,7 +817,7 @@ apollo: { }, ``` -Then, because Etags depend on the request being a `GET` instead of GraphQL's usual `POST`, but our default link library does not support `GET` we need to let our defaut Apollo client know to use a different library. +Then, because ETags depend on the request being a `GET` instead of GraphQL's usual `POST`, but our default link library does not support `GET` we need to let our default Apollo client know to use a different library. ```javascript /* componentMountIndex.js */ diff --git a/doc/development/fe_guide/icons.md b/doc/development/fe_guide/icons.md index ad344c00efd..3f7490b0221 100644 --- a/doc/development/fe_guide/icons.md +++ b/doc/development/fe_guide/icons.md @@ -198,3 +198,10 @@ export default { <img :src="svgIllustrationPath" /> </template> ``` + +### Minimize SVGs + +When you develop or export a new SVG illustration, minimize it with an [SVGO](https://github.com/svg/svgo) powered tool, like +[SVGOMG](https://jakearchibald.github.io/svgomg/), to save space. Illustrations +added to [GitLab SVG](https://gitlab.com/gitlab-org/gitlab-svgs) are automatically +minimized, so no manual action is needed. diff --git a/doc/development/fe_guide/performance.md b/doc/development/fe_guide/performance.md index b6130335654..dd3945ae324 100644 --- a/doc/development/fe_guide/performance.md +++ b/doc/development/fe_guide/performance.md @@ -246,6 +246,55 @@ Layout to be recalculated, which is much more expensive. For details on this, se If you _do_ need to change layout (for example, a sidebar that pushes main content over), prefer [FLIP](https://aerotwist.com/blog/flip-your-animations/). FLIP allows you to change expensive properties once, and handle the actual animation with transforms. +### Prefetching assets + +In addition to prefetching data from the [API](graphql.md#making-initial-queries-early-with-graphql-startup-calls) +we allow prefetching the named JavaScript "chunks" as +[defined in the Webpack configuration](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/webpack.config.js#L298-359). +We support two types of prefetching for the chunks: + +- The [`prefetch` link type](https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types/prefetch) + is used to prefetch a chunk for the future navigation +- The [`preload` link type](https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types/preloadh) + is used to prefetch a chunk that is crucial for the current navigation but is not + discovered until later in the rendering process + +Both `prefetch` and `preload` links bring the loading performance benefit to the pages. Both are +fetched asynchronously, but contrary to [deferring the loading](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-defer) +of the assets which is used for other JavaScript resources in the product by default, `prefetch` and +`preload` neither parse nor execute the fetched script unless explicitly imported in any JavaScript +module. This allows to cache the fetched resources without blocking the execution of the +remaining page resources. + +To prefetch a JavaScript chunk in a HAML view, `:prefetch_asset_tags` with the combination of +the `webpack_preload_asset_tag` helper is provided: + +```javascript +- content_for :prefetch_asset_tags do + - webpack_preload_asset_tag('monaco') +``` + +This snippet will add a new `<link rel="preload">` element into the resulting HTML page: + +```HTML +<link rel="preload" href="/assets/webpack/monaco.chunk.js" as="script" type="text/javascript"> +``` + +By default, `webpack_preload_asset_tag` will `preload` the chunk. You don't need to worry about +`as` and `type` attributes for preloading the JavaScript chunks. However, when a chunk is not +critical, for the current navigation, one has to explicitly request `prefetch`: + +```javascript +- content_for :prefetch_asset_tags do + - webpack_preload_asset_tag('monaco', prefetch: true) +``` + +This snippet will add a new `<link rel="prefetch">` element into the resulting HTML page: + +```HTML +<link rel="prefetch" href="/assets/webpack/monaco.chunk.js"> +``` + ## Reducing Asset Footprint ### Universal code diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md index 574faa0898f..1cce699218c 100644 --- a/doc/development/fe_guide/vue.md +++ b/doc/development/fe_guide/vue.md @@ -102,9 +102,9 @@ across the codebase. #### Providing Rails form fields to Vue applications When composing a form with Rails, the `name`, `id`, and `value` attributes of form inputs are generated -to match the backend. It can be helpful to have access to these generated attributes when converting +to match the backend. It can be helpful to have access to these generated attributes when converting a Rails form to Vue, or when [integrating components (datepicker, project selector, etc)](https://gitlab.com/gitlab-org/gitlab/-/blob/8956ad767d522f37a96e03840595c767de030968/app/assets/javascripts/access_tokens/index.js#L15) into it. -The [`parseRailsFormFields`](https://gitlab.com/gitlab-org/gitlab/-/blob/fe88797f682c7ff0b13f2c2223a3ff45ada751c1/app/assets/javascripts/lib/utils/forms.js#L107) utility can be used to parse the generated form input attributes so they can be passed to the Vue application. +The [`parseRailsFormFields`](https://gitlab.com/gitlab-org/gitlab/-/blob/fe88797f682c7ff0b13f2c2223a3ff45ada751c1/app/assets/javascripts/lib/utils/forms.js#L107) utility can be used to parse the generated form input attributes so they can be passed to the Vue application. This allows us to easily integrate Vue components without changing how the form submits. ```haml @@ -116,7 +116,7 @@ This allows us to easily integrate Vue components without changing how the form ``` > The `js_name` data attribute is used as the key in the resulting JavaScript object. -For example `= form.text_field :email, data: { js_name: 'fooBarBaz' }` would be translated +For example `= form.text_field :email, data: { js_name: 'fooBarBaz' }` would be translated to `{ fooBarBaz: { name: 'user[email]', id: 'user_email', value: '' } }` ```javascript diff --git a/doc/development/feature_flags/controls.md b/doc/development/feature_flags/controls.md index c9538c38850..08a4401181b 100644 --- a/doc/development/feature_flags/controls.md +++ b/doc/development/feature_flags/controls.md @@ -266,7 +266,7 @@ Changes to the issue format can be submitted in the Any feature flag change that affects any GitLab instance is automatically logged in [features_json.log](../../administration/logs.md#features_jsonlog). You can search the change history in [Kibana](https://about.gitlab.com/handbook/support/workflows/kibana.html). -You can access the feature flag change history for GitLab.com [here](https://log.gprd.gitlab.net/goto/d060337c017723084c6d97e09e591fc6). +You can also access the feature flag change history for GitLab.com [in Kibana](https://log.gprd.gitlab.net/goto/d060337c017723084c6d97e09e591fc6). ## Cleaning up diff --git a/doc/development/feature_flags/index.md b/doc/development/feature_flags/index.md index 560e4f8cb90..e18bcaa1f4e 100644 --- a/doc/development/feature_flags/index.md +++ b/doc/development/feature_flags/index.md @@ -15,12 +15,6 @@ This document provides guidelines on how to use feature flags in the GitLab codebase to conditionally enable features and test them. -Features that are developed and merged behind a feature flag -should not include a changelog entry. A changelog entry with `type: added` should be included in the merge -request removing the feature flag or the merge request where the default value of -the feature flag is set to enabled. If the feature contains any database migrations, it -*should* include a changelog entry for the database changes. - WARNING: All newly-introduced feature flags should be [disabled by default](https://about.gitlab.com/handbook/product-development-flow/feature-flag-lifecycle/#feature-flags-in-gitlab-development). @@ -55,7 +49,7 @@ should be leveraged: a specific project and ensure that there are no issues with the implementation. 1. When the feature is ready to be announced, create a merge request that adds documentation about the feature, including [documentation for the feature flag itself](../documentation/feature_flags.md), - and a changelog entry. In the same merge request either flip the feature flag to + and a [changelog entry](#changelog). In the same merge request either flip the feature flag to be **on by default** or remove it entirely in order to enable the new behavior. One might be tempted to think that feature flags will delay the release of a @@ -461,6 +455,24 @@ as follows: Feature.remove(:feature_flag_name) ``` +## Changelog + +- Any change behind a feature flag **disabled** by default **should not** have a changelog entry. + - **Exception:** database migrations **should** have a changelog entry. +- Any change related to a feature flag itself (flag removal, default-on setting) **should** have a changelog entry. + Use the flowchart to determine the changelog entry type. + + ```mermaid + graph LR + A[flag: default off] -->|'added' / 'changed'| B(flag: default on) + B -->|'other'| C(remove flag, keep new code) + B -->|'removed' / 'changed'| D(remove flag, keep old code) + A -->|'added' / 'changed'| C + A -->|no changelog| D + ``` + +- Any change behind a feature flag that is **enabled** by default **should** have a changelog entry. + ## Feature flags in tests Introducing a feature flag into the codebase creates an additional code path that should be tested. diff --git a/doc/development/fips_compliance.md b/doc/development/fips_compliance.md new file mode 100644 index 00000000000..0b6d1751668 --- /dev/null +++ b/doc/development/fips_compliance.md @@ -0,0 +1,144 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# FIPS compliance + +FIPS is short for "Federal Information Processing Standard", a document which +defines certain security practices for a "cryptographic module" (CM). It aims +to ensure a certain security floor is met by vendors selling products to U.S. +Federal institutions. + +WARNING: +GitLab is not FIPS compliant, even when built and run on a FIPS-enforcing +system. Large parts of the build are broken, and many features use forbidden +cryptographic primitives. Running GitLab on a FIPS-enforcing system is not +supported and may result in data loss. This document is intended to help +engineers looking to develop FIPS-related fixes. It is not intended to be used +to run a production GitLab instance. + +There are two current FIPS standards: [140-2](https://en.wikipedia.org/wiki/FIPS_140-2) +and [140-3](https://en.wikipedia.org/wiki/FIPS_140-3). At GitLab we usually +mean FIPS 140-2. + +## Current status + +GitLab Inc has not committed to making GitLab FIPS-compliant at this time. We are +performing initial investigations to see how much work such an effort would be. + +Read [Epic &5104](https://gitlab.com/groups/gitlab-org/-/epics/5104) for more +information on the status of the investigation. + +## FIPS compliance at GitLab + +In a FIPS context, compliance is a form of self-certification - if we say we are +"FIPS compliant", we mean that we *believe* we are. There are no external +certifications to acquire, but if we are aware of non-compliant areas +in GitLab, we cannot self-certify in good faith. + +The known areas of non-compliance are tracked in [Epic &5104](https://gitlab.com/groups/gitlab-org/-/epics/5104). + +To be compliant, all components (GitLab itself, Gitaly, etc) must be compliant, +along with the communication between those components, and any storage used by +them. Where functionality cannot be brought into compliance, it must be disabled +when FIPS mode is enabled. + +## FIPS validation at GitLab + +Unlike FIPS compliance, FIPS validation is a formal declaration of compliance by +an accredited auditor. The requirements needed to pass the audit are the same as +for FIPS compliance. + +A list of FIPS-validated modules can be found at the +NIST (National Institute of Standards and Technology) +[cryptographic module validation program](https://csrc.nist.gov/projects/cryptographic-module-validation-program/validated-modules). + +## Setting up a FIPS-enabled development environment + +The simplest approach is to set up a virtual machine running +[Red Hat Enterprise Linux 8](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/using-the-system-wide-cryptographic-policies_security-hardening#switching-the-system-to-fips-mode_using-the-system-wide-cryptographic-policies). + +Red Hat provide free licenses to developers, and permit the CD image to be +downloaded from the [Red Hat developer's portal](https://developers.redhat.com). +Registration is required. + +After the virtual machine is set up, you can follow the [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit) +installation instructions, including the [advanced instructions for RHEL](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/advanced.md#red-hat-enterprise-linux). +Note that `asdf` is not used for dependency management because it's essential to +use the RedHat-provided Go compiler and other system dependencies. + +### Working around broken frontend asset compilation + +A known bug affects asset compilation with FIPS mode enabled: [issue #322883](https://gitlab.com/gitlab-org/gitlab/-/issues/322883). +Until this is resolved, working on frontend issues is not feasible. We can still +work on backend issues by compiling the assets while FIPS is disabled, and +placing GDK into [static asset mode](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/configuration.md#webpack-settings): + +1. Modify your `gdk.yml` to contain the following: + + ```yaml + webpack: + host: 127.0.0.1 + port: 3808 + static: true + ``` + +1. In the GitLab repository, apply this patch to prevent the assets from being + automatically deleted whenever GDK is restarted: + + ```diff + diff --git a/scripts/frontend/webpack_dev_server.js b/scripts/frontend/webpack_dev_server.js + index fbb80c9617d..114720d457c 100755 + --- a/scripts/frontend/webpack_dev_server.js + +++ b/scripts/frontend/webpack_dev_server.js + @@ -15,7 +15,7 @@ const baseConfig = { + // run webpack in compile-once mode and watch for changes + if (STATIC_MODE) { + nodemon({ + - exec: `rm -rf public/assets/webpack ; yarn run webpack && exec ruby -run -e httpd public/ -p ${DEV_SERVER_PORT}`, + + exec: `ruby -run -e httpd public/ -p ${DEV_SERVER_PORT}`, + watch: [ + 'config/webpack.config.js', + 'app/assets/javascripts', + ``` + +1. Run this command in the GitLab repository to generate the asset files + to be served: + + ```shell + bin/rails gitlab:assets:compile + ``` + +Every time you change a frontend asset, you must re-run this command +(with FIPS mode disabled) before seeing the changes. + +### Enable FIPS mode + +After the assets are generated, run this command (as root) and restart the +virtual machine: + +```shell +fips-mode-setup --enable +``` + +You can check whether it's taken effect by running: + +```shell +fips-mode-setup --check +``` + +In this environment, OpenSSL refuses to perform cryptographic operations +forbidden by the FIPS standards. This enables you to reproduce FIPS-related bugs, +and validate fixes. + +You should be able to open a web browser inside the virtual machine and log in +to the GitLab instance. + +You can disable FIPS mode again by running this command, then restarting the +virtual machine: + +```shell +fips-mode-setup --disable +``` diff --git a/doc/development/gemfile.md b/doc/development/gemfile.md index f50e19bc383..e071aa4ffd9 100644 --- a/doc/development/gemfile.md +++ b/doc/development/gemfile.md @@ -19,6 +19,63 @@ dependencies and build times. Refer to [licensing guidelines](licensing.md) for ensuring license compliance. +## GitLab-created gems + +Sometimes we create libraries within our codebase that we want to +extract, either because we want to use them in other applications +ourselves, or because we think it would benefit the wider community. +Extracting code to a gem also means that we can be sure that the gem +does not contain any hidden dependencies on our application code. + +In general, we want to think carefully before doing this as there are +also disadvantages: + +1. Gems - even those maintained by GitLab - do not necessarily go + through the same [code review process](code_review.md) as the main + Rails application. +1. Extracting the code into a separate project means that we need a + minimum of two merge requests to change functionality: one in the gem + to make the functional change, and one in the Rails app to bump the + version. +1. Our needs for our own usage of the gem may not align with the wider + community's needs. In general, if we are not using the latest version + of our own gem, that might be a warning sign. + +In the case where we do want to extract some library code we've written +to a gem, go through these steps: + +1. Start with the code in the Rails application. Here it's fine to have + the code in `lib/` and loaded automatically. We can skip this step if + the step below makes more sense initially. +1. Before extracting to its own project, move the gem to `vendor/gems` and + load it in the `Gemfile` using the `path` option. This gives us a gem + that can be published to RubyGems.org, with its own test suite and + isolated set of dependencies, that is still in our main code tree and + goes through the standard code review process. + - For an example, see the [merge request !57805](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57805). +1. Once the gem is stable - we have been using it in production for a + while with few, if any, changes - extract to its own project under + the `gitlab-org` namespace. + 1. When creating the project, follow the [instructions for new projects](https://about.gitlab.com/handbook/engineering/#creating-a-new-project). + 1. Follow the instructions for setting up a [CI/CD configuration](https://about.gitlab.com/handbook/engineering/#cicd-configuration). + 1. Follow the instructions for [publishing a project](https://about.gitlab.com/handbook/engineering/#publishing-a-project). + - See [issue + #325463](https://gitlab.com/gitlab-org/gitlab/-/issues/325463) + for an example. + - In some cases we may want to move a gem to its own namespace. Some + examples might be that it will naturally have more than one project + (say, something that has plugins as separate libraries), or that we + expect non-GitLab-team-members to be maintainers on this project as + well as GitLab team members. + + The latter situation (maintainers from outside GitLab) could also + apply if someone who currently works at GitLab wants to maintain + the gem beyond their time working at GitLab. + +When publishing a gem to RubyGems.org, also note the section on [gem +owners](https://about.gitlab.com/handbook/developer-onboarding/#ruby-gems) +in the handbook. + ## Upgrade Rails When upgrading the Rails gem and its dependencies, you also should update the following: @@ -58,7 +115,7 @@ operator](https://thoughtbot.com/blog/rubys-pessimistic-operator)) making it possible to upgrade `license_finder` or any other gem to a version that depends on `thor 1.2`. -Simlarly, if `license_finder` had a vulnerability fixed in 6.0.1, we +Similarly, if `license_finder` had a vulnerability fixed in 6.0.1, we should add: ```ruby @@ -70,7 +127,7 @@ still depend on a newer version of `thor`, such as `6.0.2`, but would not be able to depend on the vulnerable version `6.0.0`. A downgrade like that could happen if we introduced a new dependency -that also relied on thor but had its version pinned to a vulnerable +that also relied on `thor` but had its version pinned to a vulnerable one. These changes are easy to miss in the `Gemfile.lock`. Pinning the version would result in a conflict that would need to be solved. diff --git a/doc/development/geo/framework.md b/doc/development/geo/framework.md index 2b3e4826de5..4460e6f66a8 100644 --- a/doc/development/geo/framework.md +++ b/doc/development/geo/framework.md @@ -164,7 +164,9 @@ Models that use [CarrierWave's](https://github.com/carrierwaveuploader/carrierwa Each file is expected to have its own primary ID and model. Geo strongly recommends treating *every single file* as a first-class citizen, because in our experience this greatly simplifies tracking replication and verification state. -To implement Geo replication of a new blob-type Model, [open an issue with the provided issue template](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Geo%3A%20Replicate%20a%20new%20blob%20type). +To implement Geo replication of a new blob-type Model, [open an issue with the provided issue template](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Geo%20Replicate%20a%20new%20blob%20type). + +To view the implementation steps without opening an issue, [view the issue template file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Geo%20Replicate%20a%20new%20blob%20type.md). ### Repository Replicator Strategy @@ -172,4 +174,6 @@ Models that refer to any Git repository on disk are supported by Geo with the `G Each Git repository is expected to have its own primary ID and model. -To implement Geo replication of a new Git repository-type Model, [open an issue with the provided issue template](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Geo%3A%20Replicate%20a%20new%20Git%20repository%20type). +To implement Geo replication of a new Git repository-type Model, [open an issue with the provided issue template](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Geo%20Replicate%20a%20new%20Git%20repository%20type). + +To view the implementation steps without opening an issue, [view the issue template file](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Geo%20Replicate%20a%20new%20Git%20repository%20type.md). diff --git a/doc/development/git_object_deduplication.md b/doc/development/git_object_deduplication.md index d9ff88aef60..1607f3e7a12 100644 --- a/doc/development/git_object_deduplication.md +++ b/doc/development/git_object_deduplication.md @@ -35,9 +35,9 @@ to work, it is of course critical that **no objects ever get deleted from B** because A might need them. WARNING: -Do not run `git prune` or `git gc` in pool repositories! This can -cause data loss in "real" repositories that depend on the pool in -question. +Do not run `git prune` or `git gc` in object pool repositories, which are +stored in the `@pools` directory. This can cause data loss in the regular +repositories that depend on the object pool. The danger lies in `git prune`, and `git gc` calls `git prune`. The problem is that `git prune`, when running in a pool repository, cannot @@ -45,8 +45,8 @@ reliable decide if an object is no longer needed. ### Git alternates in GitLab: pool repositories -GitLab organizes this object borrowing by creating special **pool -repositories** which are hidden from the user. We then use Git +GitLab organizes this object borrowing by [creating special **pool +repositories**](../administration/repository_storage_types.md) which are hidden from the user. We then use Git alternates to let a collection of project repositories borrow from a single pool repository. We call such a collection of project repositories a pool. Pools form star-shaped networks of repositories diff --git a/doc/development/go_guide/index.md b/doc/development/go_guide/index.md index e8c0c751af9..1513b65d19f 100644 --- a/doc/development/go_guide/index.md +++ b/doc/development/go_guide/index.md @@ -449,12 +449,12 @@ Once you've picked a new Go version to use, the steps to update Omnibus and CNG are: - [Create a merge request in the CNG project](https://gitlab.com/gitlab-org/build/CNG/-/edit/master/ci_files/variables.yml?branch_name=update-go-version), - updating the `GO_VERSION` in `ci_files/variables.yml`. + update the `GO_VERSION` in `ci_files/variables.yml`. - [Create a merge request in the `gitlab-omnibus-builder` project](https://gitlab.com/gitlab-org/gitlab-omnibus-builder/-/edit/master/docker/VERSIONS?branch_name=update-go-version), - updating the `GO_VERSION` in `docker/VERSIONS`. + update the `GO_VERSION` in `docker/VERSIONS`. - Tag a new release of `gitlab-omnibus-builder` containing the change. - [Create a merge request in the `omnibus-gitlab` project](https://gitlab.com/gitlab-org/omnibus-gitlab/edit/master/.gitlab-ci.yml?branch_name=update-gitlab-omnibus-builder-version), - updating the `BUILDER_IMAGE_REVISION` to match the newly-created tag. + update the `BUILDER_IMAGE_REVISION` to match the newly-created tag. To reduce unnecessary differences between two distribution methods, Omnibus and CNG **should always use the same Go version**. @@ -501,7 +501,7 @@ up to run `goimports -local gitlab.com/gitlab-org` so that it's applied to every ### Analyzer Tests -The conventional Secure [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/) has a [`convert` function](https://gitlab.com/gitlab-org/security-products/analyzers/command/-/blob/main/convert.go#L15-17) that converts SAST/DAST scanner reports into [GitLab Security Reports](https://gitlab.com/gitlab-org/security-products/security-report-schemas). When writing tests for the `convert` function, we should make use of [test fixtures](https://dave.cheney.net/2016/05/10/test-fixtures-in-go) using a `testdata` directory at the root of the analyzer's repo. The `testdata` directory should contain two subdirectories: `expect` and `reports`. The `reports` directory should contain sample SAST/DAST scanner reports which are passed into the `convert` function during the test setup. The `expect` directory should contain the expected GitLab Security Report that the `convert` returns. See Secret Detection for an [example](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/blob/160424589ef1eed7b91b59484e019095bc7233bd/convert_test.go#L13-66). +The conventional Secure [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/) has a [`convert` function](https://gitlab.com/gitlab-org/security-products/analyzers/command/-/blob/main/convert.go#L15-17) that converts SAST/DAST scanner reports into [GitLab Security Reports](https://gitlab.com/gitlab-org/security-products/security-report-schemas). When writing tests for the `convert` function, we should make use of [test fixtures](https://dave.cheney.net/2016/05/10/test-fixtures-in-go) using a `testdata` directory at the root of the analyzer's repository. The `testdata` directory should contain two subdirectories: `expect` and `reports`. The `reports` directory should contain sample SAST/DAST scanner reports which are passed into the `convert` function during the test setup. The `expect` directory should contain the expected GitLab Security Report that the `convert` returns. See Secret Detection for an [example](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/blob/160424589ef1eed7b91b59484e019095bc7233bd/convert_test.go#L13-66). If the scanner report is small, less than 35 lines, then feel free to [inline the report](https://gitlab.com/gitlab-org/security-products/analyzers/sobelow/-/blob/8bd2428a/convert/convert_test.go#L13-77) rather than use a `testdata` directory. diff --git a/doc/development/graphql_guide/authorization.md b/doc/development/graphql_guide/authorization.md index ee5713f6fda..8f17a8b6c93 100644 --- a/doc/development/graphql_guide/authorization.md +++ b/doc/development/graphql_guide/authorization.md @@ -148,7 +148,7 @@ end ``` In this example, we use field authorization (such as -`Ability.allowed?(current_user, :read_transactions, bank_account)`) to avoid +`Ability.allowed?(current_user, :read_transactions, bank_account)`) to avoid a more expensive query: ```ruby diff --git a/doc/development/graphql_guide/pagination.md b/doc/development/graphql_guide/pagination.md index 55ff7942418..5db9238faed 100644 --- a/doc/development/graphql_guide/pagination.md +++ b/doc/development/graphql_guide/pagination.md @@ -12,6 +12,10 @@ GitLab uses two primary types of pagination: **offset** and **keyset** (sometimes called cursor-based) pagination. The GraphQL API mainly uses keyset pagination, falling back to offset pagination when needed. +### Performance considerations + +See the [general pagination guidelines section](../database/pagination_guidelines.md) for more information. + ### Offset pagination This is the traditional, page-by-page pagination, that is most common, diff --git a/doc/development/i18n/externalization.md b/doc/development/i18n/externalization.md index 0f7b8078933..b177a7e0138 100644 --- a/doc/development/i18n/externalization.md +++ b/doc/development/i18n/externalization.md @@ -19,7 +19,7 @@ All `rake` commands described on this page must be run on a GitLab instance, usu ## Setting up GitLab Development Kit (GDK) In order to be able to work on the [GitLab Community Edition](https://gitlab.com/gitlab-org/gitlab-foss) -project you must download and configure it through [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/set-up-gdk.md). +project you must download and configure it through [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/set-up-gdk.md). After you have the GitLab project ready, you can start working on the translation. @@ -491,6 +491,48 @@ To avoid this error, use the applicable HTML entity code (`<` or `>`) inst // => 'In < 1 hour' ``` +### Numbers + +Different locales may use different number formats. To support localization of numbers, we use `formatNumber`, +which leverages [`toLocaleString()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toLocaleString). + +`formatNumber` formats numbers as strings using the current user locale by default. + +- In JavaScript + +```javascript +import { formatNumber } from '~/locale'; + +// Assuming "User Preferences > Language" is set to "English": + +const tenThousand = formatNumber(10000); // "10,000" (uses comma as decimal symbol in English locale) +const fiftyPercent = formatNumber(0.5, { style: 'percent' }) // "50%" (other options are passed to toLocaleString) +``` + +- In Vue templates + +```html +<script> +import { formatNumber } from '~/locale'; + +export default { + //... + methods: { + // ... + formatNumber, + }, +} +</script> +<template> +<div class="my-number"> + {{ formatNumber(10000) }} <!-- 10,000 --> +</div> +<div class="my-percent"> + {{ formatNumber(0.5, { style: 'percent' }) }} <!-- 50% --> +</div> +</template> +``` + ### Dates / times - In JavaScript: @@ -753,6 +795,10 @@ aren't in the message with ID `1 pipeline`. ## Adding a new language +A new language should only be added as an option in User Preferences once at least 10% of the +strings have been translated and approved. Even though a larger number of strings may have been +translated, only the approved translations display in the GitLab UI. + NOTE: [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/221012) in GitLab 13.3: Languages with less than 2% of translations are not available in the UI. diff --git a/doc/development/i18n/merging_translations.md b/doc/development/i18n/merging_translations.md index 553820733e7..48474a68d16 100644 --- a/doc/development/i18n/merging_translations.md +++ b/doc/development/i18n/merging_translations.md @@ -78,3 +78,10 @@ recreate it with the following steps: 1. Select the `gitlab-org/gitlab` repository. 1. In `Select Branches for Translation`, select `master`. 1. Ensure the `Service Branch Name` is `master-i18n`. + +## Manually update the translation levels + +There's no automated way to pull the translation levels from CrowdIn, to display +this information in the language selection dropdown. Therefore, the translation +levels are hard-coded in the `TRANSLATION_LEVELS` constant in [`i18n.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/i18n.rb), +and must be regularly updated. diff --git a/doc/development/img/distributed_tracing_performance_bar.png b/doc/development/img/distributed_tracing_performance_bar.png Binary files differdeleted file mode 100644 index 8c819045104..00000000000 --- a/doc/development/img/distributed_tracing_performance_bar.png +++ /dev/null diff --git a/doc/development/img/offset_pagination_ui_v13_11.jpg b/doc/development/img/offset_pagination_ui_v13_11.jpg Binary files differnew file mode 100644 index 00000000000..d17acc20dcb --- /dev/null +++ b/doc/development/img/offset_pagination_ui_v13_11.jpg diff --git a/doc/development/img/project_issues_pagination_v13_11.jpg b/doc/development/img/project_issues_pagination_v13_11.jpg Binary files differnew file mode 100644 index 00000000000..3f3c268cd16 --- /dev/null +++ b/doc/development/img/project_issues_pagination_v13_11.jpg diff --git a/doc/development/img/speedscope_v13_12.png b/doc/development/img/speedscope_v13_12.png Binary files differnew file mode 100644 index 00000000000..03ff46f4e0b --- /dev/null +++ b/doc/development/img/speedscope_v13_12.png diff --git a/doc/development/import_export.md b/doc/development/import_export.md index fd795880d2d..bc1927fffde 100644 --- a/doc/development/import_export.md +++ b/doc/development/import_export.md @@ -284,6 +284,27 @@ methods: - :type ``` +Customize the export order of the model relationships: + +```yaml +# Specify a custom export reordering for a given relationship +# For example for issues we use a custom export reordering by relative_position, so that on import, we can reset the +# relative position value, but still keep the issues order to the order in which issues were in the exported project. +# By default the ordering of relations is done by PK. +# column - specify the column by which to reorder, by default it is relation's PK +# direction - specify the ordering direction :asc or :desc, default :asc +# nulls_position - specify where would null values be positioned. Because custom ordering column can contain nulls we +# need to also specify where would the nulls be placed. It can be :nulls_last or :nulls_first, defaults +# to :nulls_last + +export_reorders: + project: + issues: + column: :relative_position + direction: :asc + nulls_position: :nulls_last +``` + ### Import The import job status moves from `none` to `finished` or `failed` into different states: diff --git a/doc/development/import_project.md b/doc/development/import_project.md index a4917cc0c3d..0c8406e2ebc 100644 --- a/doc/development/import_project.md +++ b/doc/development/import_project.md @@ -216,6 +216,6 @@ This is due to a [n+1 calls limit being set for development setups](gitaly.md#to Many of the tests also require a GitLab Personal Access Token. This is due to numerous endpoints themselves requiring authentication. -[The official GitLab docs detail how to create this token](../user/profile/personal_access_tokens.md#creating-a-personal-access-token). The tests require that the token is generated by an admin user and that it has the `API` and `read_repository` permissions. +[The official GitLab docs detail how to create this token](../user/profile/personal_access_tokens.md#create-a-personal-access-token). The tests require that the token is generated by an admin user and that it has the `API` and `read_repository` permissions. Details on how to use the Access Token with each type of test are found in their respective documentation. diff --git a/doc/development/integrations/codesandbox.md b/doc/development/integrations/codesandbox.md index 62acdda6d0d..234f8c7fe0b 100644 --- a/doc/development/integrations/codesandbox.md +++ b/doc/development/integrations/codesandbox.md @@ -15,7 +15,7 @@ creating upstream contributions like [this one](https://github.com/codesandbox/c Before using CodeSandbox with your local GitLab instance, you must: 1. Enable HTTPS on your GDK. CodeSandbox uses Service Workers that require `https`. - Follow the GDK [NGINX configuration instructions](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/nginx.md) to enable HTTPS for GDK. + Follow the GDK [NGINX configuration instructions](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/nginx.md) to enable HTTPS for GDK. 1. Clone the [`codesandbox-client` project](https://github.com/codesandbox/codesandbox-client) locally. If you plan on contributing upstream, you might want to fork and clone first. 1. (Optional) Use correct `python` and `nodejs` versions. Otherwise, `yarn` may fail to diff --git a/doc/development/integrations/jira_connect.md b/doc/development/integrations/jira_connect.md index 860fd88612f..98a48007238 100644 --- a/doc/development/integrations/jira_connect.md +++ b/doc/development/integrations/jira_connect.md @@ -16,7 +16,7 @@ The following are required to install and test the app: - [GDK in Gitpod](https://www.loom.com/share/9c9711d4876a40869b9294eecb24c54d) video. - - [GDK with Gitpod](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/gitpod.md) + - [GDK with Gitpod](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/gitpod.md) documentation. You **must not** use tunneling tools such as @@ -61,7 +61,7 @@ To install the app in Jira: If the app install failed, you might need to delete `jira_connect_installations` from your database. -1. Open the [database console](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/postgresql.md#access-postgresql). +1. Open the [database console](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/postgresql.md#access-postgresql). 1. Run `TRUNCATE TABLE jira_connect_installations CASCADE;`. ## Add a namespace diff --git a/doc/development/integrations/secure.md b/doc/development/integrations/secure.md index ae4e952d063..fe3135b72b6 100644 --- a/doc/development/integrations/secure.md +++ b/doc/development/integrations/secure.md @@ -69,7 +69,7 @@ so the [`allow_failure`](../../ci/yaml/README.md#allow_failure) parameter should Scanning jobs must declare a report that corresponds to the type of scanning they perform, using the [`artifacts:reports`](../../ci/yaml/README.md#artifactsreports) keyword. -Valid reports are: `dependency_scanning`, `container_scanning`, `dast`, and `sast`. +Valid reports are: `dependency_scanning`, `container_scanning`, `dast`, `api_fuzzing`, `coverage_fuzzing`, and `sast`. For example, here is the definition of a SAST job that generates a file named `gl-sast-report.json`, and uploads it as a SAST report: @@ -290,6 +290,8 @@ You can find the schemas for these scanners here: - [DAST](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/dast-report-format.json) - [Dependency Scanning](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/dependency-scanning-report-format.json) - [Container Scanning](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/container-scanning-report-format.json) +- [Coverage Fuzzing](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/coverage-fuzzing-report-format.json) +- [Secret Detection](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/secret-detection-report-format.json) ### Version @@ -384,7 +386,7 @@ It is recommended to reuse the identifiers the GitLab scanners already define: | [ELSA](https://linux.oracle.com/security/) | `elsa` | ELSA-2020-0085 | The generic identifiers listed above are defined in the [common library](https://gitlab.com/gitlab-org/security-products/analyzers/common), -which is shared by the analyzers that GitLab maintains. You can [contribute](https://gitlab.com/gitlab-org/security-products/analyzers/common/blob/master/issue/identifier.go) +which is shared by some of the analyzers that GitLab maintains. You can [contribute](https://gitlab.com/gitlab-org/security-products/analyzers/common/blob/master/issue/identifier.go) new generic identifiers to if needed. Analyzers may also produce vendor-specific or product-specific identifiers, which don't belong in the [common library](https://gitlab.com/gitlab-org/security-products/analyzers/common). @@ -548,7 +550,7 @@ of the available SAST Analyzers and what data is currently available. The `remediations` field of the report is an array of remediation objects. Each remediation describes a patch that can be applied to -[automatically fix](../../user/application_security/#apply-an-automatic-remediation-for-a-vulnerability) +[automatically fix](../../user/application_security/vulnerabilities/index.md#remediate-a-vulnerability-automatically) a set of vulnerabilities. Here is an example of a report that contains remediations. diff --git a/doc/development/integrations/secure_partner_integration.md b/doc/development/integrations/secure_partner_integration.md index 3154dc83ea4..fedd424309d 100644 --- a/doc/development/integrations/secure_partner_integration.md +++ b/doc/development/integrations/secure_partner_integration.md @@ -47,7 +47,7 @@ best place to integrate your own product and its results into GitLab. displays the results of the pipeline's security checks and the developer can review them. The developer can review both a summary and a detailed version of the results. -- If certain policies (such as [merge request approvals](../../user/project/merge_requests/merge_request_approvals.md)) +- If certain policies (such as [merge request approvals](../../user/project/merge_requests/approvals/index.md)) are in place for a project, developers must resolve specific findings or get an approval from a specific list of people. - The [security dashboard](../../user/application_security/security_dashboard/index.md) @@ -101,7 +101,7 @@ and complete an integration with the Secure stage. - Users can interact with the findings from your artifact within their workflow. They can dismiss the findings or accept them and create a backlog issue. - To automatically create issues without user interaction, use the [issue API](../../api/issues.md). 1. Optional: Provide auto-remediation steps: - - If you specified `remediations` in your artifact, it is proposed through our [automatic remediation](../../user/application_security/index.md#apply-an-automatic-remediation-for-a-vulnerability) + - If you specified `remediations` in your artifact, it is proposed through our [automatic remediation](../../user/application_security/vulnerabilities/index.md#remediate-a-vulnerability-automatically) interface. 1. Demo the integration to GitLab: - After you have tested and are ready to demo your integration please diff --git a/doc/development/interacting_components.md b/doc/development/interacting_components.md index 4c2d0580428..f6fec0cde8c 100644 --- a/doc/development/interacting_components.md +++ b/doc/development/interacting_components.md @@ -20,7 +20,7 @@ change that affects uploads should also be tested against [object storage](https which is _not_ enabled by default in [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit). When working on a related feature, make sure to enable and test it -against [MinIO](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/object_storage.md). +against [MinIO](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/object_storage.md). See also [File Storage in GitLab](file_storage.md). diff --git a/doc/development/internal_api.md b/doc/development/internal_api.md index 7c4f869d1a7..57dd1c0a65b 100644 --- a/doc/development/internal_api.md +++ b/doc/development/internal_api.md @@ -14,6 +14,22 @@ working on the GitLab codebase. This documentation does not yet include the internal API used by GitLab Pages. +## Adding new endpoints + +API endpoints should be externally accessible by default, with proper authentication and authorization. +Before adding a new internal endpoint, consider if the API would potentially be +useful to the wider GitLab community and can be made externally accessible. + +One reason we might favor internal API endpoints sometimes is when using such an endpoint requires +internal data that external actors can not have. For example, in the internal Pages API we might use +a secret token that identifies a request as internal or sign a request with a public key that is +not available to a wider community. + +Another reason to separate something into an internal API is when request to such API endpoint +should never go through an edge (public) load balancer. This way we can configure different rate +limiting rules and policies around how the endpoint is being accessed, because we know that only +internal requests can be made to that endpoint going through an internal load balancer. + ## Authentication These methods are all authenticated using a shared secret. This secret @@ -437,7 +453,8 @@ metric counters. | Attribute | Type | Required | Description | |:----------|:-------|:---------|:------------| -| `gitops_sync_count` | integer| yes | The number to increase the `gitops_sync_count` counter by | +| `gitops_sync_count` | integer| no | The number to increase the `gitops_sync_count` counter by | +| `k8s_api_proxy_request_count` | integer| no | The number to increase the `k8s_api_proxy_request_count` counter by | ```plaintext POST /internal/kubernetes/usage_metrics diff --git a/doc/development/jh_features_review.md b/doc/development/jh_features_review.md new file mode 100644 index 00000000000..260da2d7ef2 --- /dev/null +++ b/doc/development/jh_features_review.md @@ -0,0 +1,80 @@ +--- +stage: none +group: unassigned +info: https://gitlab.com/gitlab-jh/gitlab +--- + +# Guidelines for reviewing JiHu (JH) Edition related merge requests + +We have two kinds of changes related to JH: + +- Inside `jh/` + - This is beyond EE repository and not the intention for this documentation. +- Outside `jh/` + - These will have to sit in EE repository, so reviewers and maintainers for + EE repository will have to review and maintain. This includes codes like + `Gitlab.jh?`, and how it attempts to load codes under `jh/` just like we + have codes which will load codes under `ee/`. + - This documentation intended to guide how those codes should look like, so + we'll have better understanding what are the changes needed for looking up + codes under `jh/`. + - We will generalize this so both EE and JH can share the same mechanism, + then we wouldn't have to treat them differently. + +If needed, review the corresponding JH merge request located at [JH repository](https://gitlab.com/gitlab-jh/gitlab) + +## Act as EE when `jh/` does not exist + +- In the case of EE repository, `jh/` does not exist so it should just act like EE (or CE when the license is absent) +- In the case of JH repository, `jh/` does exist but `EE_ONLY` environment variable can be set to force it run under EE mode. +- In the case of JH repository, `jh/` does exist but `FOSS_ONLY` environment variable can be set to force it run under CE mode. + +## CI pipelines in a JH context + +EE repository does not have `jh/` directory therefore there is no way to run +JH pipelines in the EE repository. All JH tests should go to [JH repository](https://gitlab.com/gitlab-jh/gitlab). + +The top-level JH CI configuration is located at `jh/.gitlab-ci.yml` (which +does not exist in EE repository) and it'll include EE CI configurations +accordingly. Sometimes it's needed to update the EE CI configurations for JH +to customize more easily. + +### JH features based on CE or EE features + +For features that build on existing CE/EE features, a module in the `JH` +namespace injected in the CE/EE class/module is needed. This aligns with +what we're doing with EE features. + +See [EE features based on CE features](ee_features.md#ee-features-based-on-ce-features) for more details. + +For example, to prepend a module into the `User` class you would use +the following approach: + +```ruby +class User < ActiveRecord::Base + # ... lots of code here ... +end + +User.prepend_mod +``` + +Under EE, `User.prepend_mod` will attempt to: + +- Load EE module + +Under JH, `User.prepend_mod` will attempt to: + +- Load EE module, and: +- Load JH module + +Do not use methods such as `prepend`, `extend`, and `include`. Instead, use +`prepend_mod`, `extend_mod`, or `include_mod`. These methods will try to find +the relevant EE and JH modules by the name of the receiver module. + +If reviewing the corresponding JH file is needed, it should be found at +[JH repository](https://gitlab.com/gitlab-jh/gitlab). + +### General guidance for writing JH extensions + +See [Guidelines for implementing Enterprise Edition features](ee_features.md) +for general guidance. diff --git a/doc/development/licensing.md b/doc/development/licensing.md index 1ab56e60a0b..5f03013a780 100644 --- a/doc/development/licensing.md +++ b/doc/development/licensing.md @@ -48,6 +48,12 @@ For all of the above, please include `--why "Reason"` and `--who "My Name"` so t More detailed information on how the gem and its commands work is available in the [License Finder README](https://github.com/pivotal/LicenseFinder). +## Encryption keys + +If your license was created in your local development or staging environment for Customers Portal or License App, an environment variable called `GITLAB_LICENSE_MODE` with the value `test` needs to be set to use the correct decryption key. + +Those projects are set to use a test license encryption key by default. + ## Additional information Please see the [Open Source](https://about.gitlab.com/handbook/engineering/open-source/#using-open-source-libraries) page for more information on licensing. diff --git a/doc/development/merge_request_performance_guidelines.md b/doc/development/merge_request_performance_guidelines.md index 0f696d39092..543ca809f45 100644 --- a/doc/development/merge_request_performance_guidelines.md +++ b/doc/development/merge_request_performance_guidelines.md @@ -162,7 +162,22 @@ query. This in turn makes it much harder for this code to overload a database. In a DB cluster we have many read replicas and one primary. A classic use of scaling the DB is to have read-only actions be performed by the replicas. We use [load balancing](../administration/database_load_balancing.md) to distribute this load. This allows for the replicas to grow as the pressure on the DB grows. -By default, queries use read-only replicas, but due to [primary sticking](../administration/database_load_balancing.md#primary-sticking), GitLab sticks to using the primary for a certain period of time and reverts back to secondaries after they have either caught up or after 30 seconds, which can lead to a considerable amount of unnecessary load on the primary. In this [merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56849) we introduced the `without_sticky_writes` block to prevent switching to the primary. This [merge request example](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57328) provides a good use case for when queries can stick to the primary and how to prevent this by using `without_sticky_writes`. +By default, queries use read-only replicas, but due to +[primary sticking](../administration/database_load_balancing.md#primary-sticking), GitLab uses the +primary for some time and reverts to secondaries after they have either caught up or after 30 seconds. +Doing this can lead to a considerable amount of unnecessary load on the primary. +To prevent switching to the primary [merge request 56849](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56849) introduced the +`without_sticky_writes` block. Typically, this method can be applied to prevent primary stickiness +after a trivial or insignificant write which doesn't affect the following queries in the same session. + +To learn when a usage timestamp update can lead the session to stick to the primary and how to +prevent it by using `without_sticky_writes`, see [merge request 57328](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57328) + +As a counterpart of the `without_sticky_writes` utility, +[merge request 59167](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/59167) introduced +`use_replicas_for_read_queries`. This method forces all read-only queries inside its block to read +replicas regardless of the current primary stickiness. +This utility is reserved for cases where queries can tolerate replication lag. Internally, our database load balancer classifies the queries based on their main statement (`select`, `update`, `delete`, etc.). When in doubt, it redirects the queries to the primary database. Hence, there are some common cases the load balancer sends the queries to the primary unnecessarily: @@ -171,7 +186,12 @@ Internally, our database load balancer classifies the queries based on their mai - In-flight connection configuration set - Sidekiq background jobs -Worse, after the above queries are executed, GitLab [sticks to the primary](../administration/database_load_balancing.md#primary-sticking). In [this merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/56476), we introduced `use_replica_if_possible` to make the inside queries prefer to use the replicas. That MR is also an example how we redirected a costly, time-consuming query to the replicas. +After the above queries are executed, GitLab +[sticks to the primary](../administration/database_load_balancing.md#primary-sticking). +To make the inside queries prefer using the replicas, +[merge request 59086](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/59086) introduced +`fallback_to_replicas_for_ambiguous_queries`. This MR is also an example of how we redirected a +costly, time-consuming query to the replicas. ## Use CTEs wisely @@ -406,6 +426,8 @@ Take into consideration the following when choosing a pagination strategy: The database has to sort and iterate all previous items, and this operation usually can result in substantial load put on database. +You can find useful tips related to pagination in the [pagination guidelines](database/pagination_guidelines.md). + ## Badge counters Counters should always be truncated. It means that we don't want to present diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index 40457dbb533..e1444f1a726 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -33,7 +33,7 @@ compatible. For GitLab.com, please take into consideration that regular migrations (under `db/migrate`) are run before [Canary is deployed](https://gitlab.com/gitlab-com/gl-infra/readiness/-/tree/master/library/canary/#configuration-and-deployment), -and post-deployment migrations (`db/post_migrate`) are run after the deployment to production has finished. +and [post-deployment migrations](post_deployment_migrations.md) (`db/post_migrate`) are run after the deployment to production has finished. ## Schema Changes @@ -114,6 +114,30 @@ rails schema statement: [`add_index`](https://api.rubyonrails.org/v5.2/classes/A This is a blocking operation, but it doesn't cause problems because the table is not yet used, and therefore it does not have any records yet. +## Naming conventions + +We keep column names consistent with [ActiveRecord's schema conventions](https://guides.rubyonrails.org/active_record_basics.html#schema-conventions). + +Custom index names should follow the pattern `index_#{table_name}_on_#{column_1}_and_#{column_2}_#{condition}`. + +Examples: + +- `index_services_on_type_and_id_and_template_when_active` +- `index_projects_on_id_service_desk_enabled` +- `index_clusters_on_enabled_cluster_type_id_and_created_at` + +### Truncate long index names + +PostgreSQL [limits the length of identifiers](https://www.postgresql.org/docs/current/limits.html), +like column or index names. Column names are not usually a problem, but index names tend +to be longer. Some methods for shortening a name that's too long: + +- Prefix it with `i_` instead of `index_`. +- Skip redundant prefixes. For example, + `index_vulnerability_findings_remediations_on_vulnerability_remediation_id` becomes + `index_vulnerability_findings_remediations_on_remediation_id`. +- Instead of columns, specify the purpose of the index, such as `index_users_for_unconfirmation_notification`. + ## Heavy operations in a single transaction When using a single-transaction migration, a transaction holds a database connection diff --git a/doc/development/multi_version_compatibility.md b/doc/development/multi_version_compatibility.md index ff831bfa348..44e93bfb8a8 100644 --- a/doc/development/multi_version_compatibility.md +++ b/doc/development/multi_version_compatibility.md @@ -65,7 +65,7 @@ Let's see how we can handle them safely. ### Route changes When changing routing we should pay attention to make sure a route generated from the new version can be served by the old one and vice versa. -As you can see in [an example later on this page](#some-links-to-issues-and-mrs-were-broken), not doing it can lead to an outage. +[As you can see](#some-links-to-issues-and-mrs-were-broken), not doing it can lead to an outage. This type of change may look like an immediate switch between the two implementations. However, especially with the canary stage, there is an extended period of time where both version of the code coexists in production. diff --git a/doc/development/packages.md b/doc/development/packages.md index d4982473d67..3727376d957 100644 --- a/doc/development/packages.md +++ b/doc/development/packages.md @@ -219,12 +219,12 @@ demonstrates adding an instance-level endpoint for Conan to workhorse. You can a implemented in the same file. Once the route has been added, you must add an additional `/authorize` version of the upload endpoint to your API file. -[Here is an example](https://gitlab.com/gitlab-org/gitlab/blob/398fef1ca26ae2b2c3dc89750f6b20455a1e5507/ee/lib/api/maven_packages.rb#L164) -of the additional endpoint added for Maven. The `/authorize` endpoint verifies and authorizes the request from workhorse, +[This example](https://gitlab.com/gitlab-org/gitlab/blob/398fef1ca26ae2b2c3dc89750f6b20455a1e5507/ee/lib/api/maven_packages.rb#L164) +shows the additional endpoint added for Maven. The `/authorize` endpoint verifies and authorizes the request from workhorse, then the normal upload endpoint is implemented below, consuming the metadata that workhorse provides in order to create the package record. Workhorse provides a variety of file metadata such as type, size, and different checksum formats. -For testing purposes, you may want to [enable object storage](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/object_storage.md) +For testing purposes, you may want to [enable object storage](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/main/doc/howto/object_storage.md) in your local development environment. #### File size limits @@ -256,6 +256,30 @@ These route prefixes guarantee a higher rate limit: /api/v4/groups/:group_id/-/packages/ ``` +### MVC Checklist + +When adding support to GitLab for a new package manager, the first iteration must contain the +following features. You can add the features through many merge requests as needed, but all the +features must be implemented when the feature flag is removed. + +- Project-level API +- Push event tracking +- Pull event tracking +- Authentication with Personal Access Tokens +- Authentication with Job Tokens +- Authentication with Deploy Tokens (group and project) +- File size [limit](#file-size-limits) +- File format guards (only accept valid file formats for the package type) +- Name regex with validation +- Version regex with validation +- Workhorse route for [accelerated](uploads.md#how-to-add-a-new-upload-route) uploads +- Background workers for extracting package metadata (if applicable) +- Documentation (how to use the feature) +- API Documentation (individual endpoints with curl examples) +- Seeding in [`db/fixtures/development/26_packages.rb`](https://gitlab.com/gitlab-org/gitlab/blob/master/db/fixtures/development/26_packages.rb) +- Update the [runbook](https://gitlab.com/gitlab-com/runbooks/-/blob/31fb4959e89db25fddf865bc81734c222daf32dd/dashboards/stage-groups/package.dashboard.jsonnet#L74) for the Grafana charts +- End-to-end feature tests for (at the minimum) publishing and installing a package + ### Future Work While working on the MVC, contributors might find features that are not mandatory for the MVC but can provide a better user experience. It's generally a good idea to keep an eye on those and open issues. diff --git a/doc/development/performance.md b/doc/development/performance.md index e93dc26e4fc..c6fe9f29b53 100644 --- a/doc/development/performance.md +++ b/doc/development/performance.md @@ -257,8 +257,8 @@ The following configuration options can be configured: Defaults to `cpu`. - `STACKPROF_INTERVAL`: Sampling interval. Unit semantics depend on `STACKPROF_MODE`. For `object` mode this is a per-event interval (every `nth` event is sampled) - and defaults to `1000`. - For other modes such as `cpu` this is a frequency and defaults to `10000` μs (100hz). + and defaults to `100`. + For other modes such as `cpu` this is a frequency interval and defaults to `10100` μs (99hz). - `STACKPROF_FILE_PREFIX`: File path prefix where profiles are stored. Defaults to `$TMPDIR` (often corresponds to `/tmp`). - `STACKPROF_TIMEOUT_S`: Profiling timeout in seconds. Profiling will @@ -363,16 +363,18 @@ This patch is available by default for [CNG](https://gitlab.com/gitlab-org/build/CNG/-/merge_requests/591), [GitLab CI](https://gitlab.com/gitlab-org/gitlab-build-images/-/merge_requests/355), [GCK](https://gitlab.com/gitlab-org/gitlab-compose-kit/-/merge_requests/149) -and can additionally be enabled for [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/advanced.md#apply-custom-patches-for-ruby). +and can additionally be enabled for [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/advanced.md#apply-custom-patches-for-ruby). -This patch provides a set of 3 metrics that makes it easier to understand efficiency of memory usage for a given codepath: +This patch provides the following metrics that make it easier to understand efficiency of memory use for a given codepath: +- `mem_total_bytes`: the number of bytes consumed both due to new objects being allocated into existing object slots + plus additional memory allocated for large objects (that is, `mem_bytes + slot_size * mem_objects`). +- `mem_bytes`: the number of bytes allocated by `malloc` for objects that did not fit into an existing object slot. - `mem_objects`: the number of objects allocated. -- `mem_bytes`: the number of bytes allocated by malloc. -- `mem_mallocs`: the number of malloc allocations. +- `mem_mallocs`: the number of `malloc` calls. The number of objects and bytes allocated impact how often GC cycles happen. -Fewer objects allocations result in a significantly more responsive application. +Fewer object allocations result in a significantly more responsive application. It is advised that web server requests do not allocate more than `100k mem_objects` and `100M mem_bytes`. You can view the current usage on [GitLab.com](https://log.gprd.gitlab.net/goto/3a9678bb595e3f89a0c7b5c61bcc47b9). diff --git a/doc/development/permissions.md b/doc/development/permissions.md index 2af451840d6..6ff0c6d5167 100644 --- a/doc/development/permissions.md +++ b/doc/development/permissions.md @@ -39,11 +39,16 @@ Additionally, the following project features can have different visibility level - Issues - Repository - Merge Request + - Forks - Pipelines - - Container Registry - - Git Large File Storage +- Analytics +- Requirements +- Security & Compliance - Wiki - Snippets +- Pages +- Operations +- Metrics Dashboard These features can be set to "Everyone with Access" or "Only Project Members". They make sense only for public or internal projects because private projects diff --git a/doc/development/pipelines.md b/doc/development/pipelines.md index 8a93a46247e..24f35bdab57 100644 --- a/doc/development/pipelines.md +++ b/doc/development/pipelines.md @@ -424,31 +424,85 @@ This experiment is only enabled when the CI/CD variable `RSPEC_FAIL_FAST_ENABLED The test files related to the Merge Request are determined using the [`test_file_finder`](https://gitlab.com/gitlab-org/ci-cd/test_file_finder) gem. We are using a custom mapping between source file to test files, maintained in the `tests.yml` file. +### RSpec minimal job experiment + +As part of the objective to improve overall pipeline duration, we are experimenting with a minimal set of RSpec tests. +The purpose of this experiment is to verify if we are able to run a minimal set of RSpec tests in a Merge Request pipeline, +without resulting in increased number of broken master. + +To identify the minimal set of tests needed, we use [Crystalball gem](https://github.com/toptal/crystalball) to create a test mapping. +The test mapping contains a map of each source files to a list of test files which is dependent of the source file. +This mapping is currently generated using a combination of test coverage tracing and a static mapping. +In the `detect-tests` job, we use this mapping to identify the minimal tests needed for the current Merge Request. + +In this experiment, each `rspec` job is accompanied with a `minimal` version. +For example, `rspec unit` job has a corresponding `rspec unit minimal` job. +During the experiment, each Merge Request pipeline will contain both versions of the job, running in parallel. + +To illustrate this: + +```mermaid +graph LR + A --"artifact: list of test files"--> C1 & D1 & E1 & F1 + + subgraph "prepare stage"; + A["detect-tests"]; + end + + subgraph "test stage"; + C["rspec migration"]; + C1["rspec migration minimal"]; + D["rspec unit"]; + D1["rspec unit minimal"]; + E["rspec integration"]; + E1["rspec integration minimal"]; + F["rspec system"]; + F1["rspec system minimal"]; + end +``` + +The result of both set of jobs in the pipeline is then compared to identify any false positive. +A list of such pipeline can be found in [Sisense](https://app.periscopedata.com/app/gitlab/496118/Engineering-Productivity-Sandbox?widget=10492739&udv=833427). + +A false positive is defined as a pipeline where the `minimal` jobs passed, but the non-`minimal` jobs failed. +This indicates that the changeset resulted in a test failure, which was not detected by the `minimal` jobs. +Consequently, this signifies a gap in the test mapping used, which would need to be rectified. + +#### Findings + +After a round of the experiment done in December 2020, +we discovered that it was challenging to achieve a mapping that gives high confidence at the moment, +because of 2 reasons: + +- Each identified gap in the test mapping is unique, each needing its own investigation and improvement to the creation of the test mapping. +- There is a large number of flaky tests which added a lot of noise in the data, slowing down the investigation process. + ### PostgreSQL versions testing -Even though [Omnibus defaults to PG12 for new installs and upgrades](https://docs.gitlab.com/omnibus/package-information/postgresql_versions.html), -our test suite is currently running against PG11, since GitLab.com still runs on PG11. +Our test suite runs against PG12 as GitLab.com runs on PG12 and +[Omnibus defaults to PG12 for new installs and upgrades](https://docs.gitlab.com/omnibus/package-information/postgresql_versions.html), +Our test suite is currently running against PG11, since GitLab.com still runs on PG11. -We do run our test suite against PG12 on nightly scheduled pipelines as well as upon specific -database library changes in MRs and `master` pipelines (with the `rspec db-library-code pg12` job). +We do run our test suite against PG11 on nightly scheduled pipelines as well as upon specific +database library changes in MRs and `master` pipelines (with the `rspec db-library-code pg11` job). #### Current versions testing | Where? | PostgreSQL version | | ------ | ------------------ | -| MRs | 11, 12 for DB library changes | -| `master` (non-scheduled pipelines) | 11, 12 for DB library changes | -| 2-hourly scheduled pipelines | 11, 12 for DB library changes | -| `nightly` scheduled pipelines | 11, 12 | +| MRs | 12, 11 for DB library changes | +| `master` (non-scheduled pipelines) | 12, 11 for DB library changes | +| 2-hourly scheduled pipelines | 12, 11 for DB library changes | +| `nightly` scheduled pipelines | 12, 11 | #### Long-term plan We follow the [PostgreSQL versions shipped with Omnibus GitLab](https://docs.gitlab.com/omnibus/package-information/postgresql_versions.html): -| PostgreSQL version | 13.7 (December 2020) | 13.8 (January 2021) | 13.9 (February 2021) | 13.10 (March 2021) | 13.11 (April 2021) | 14.0 (May 2021?) | -| -------------------| -------------------- | ------------------- | -------------------- | ------------------ | ------------------ | ---------------- | -| PG11 | MRs/`2-hour`/`nightly` | MRs/`2-hour`/`nightly` | MRs/`2-hour`/`nightly` | MRs/`2-hour`/`nightly` | MRs/`2-hour`/`nightly` | MRs/`2-hour`/`nightly` | -| PG12 | `nightly` | `nightly` | `nightly` | `nightly` | `nightly` | `nightly` | +| PostgreSQL version | 13.11 (April 2021) | 13.12 (May 2021) | 14.0 (June 2021?) | +| -------------------| ---------------------- | ---------------------- | ---------------------- | +| PG12 | `nightly` | MRs/`2-hour`/`nightly` | MRs/`2-hour`/`nightly` | +| PG11 | MRs/`2-hour`/`nightly` | `nightly` | `nightly` | ### Test jobs @@ -494,7 +548,7 @@ request, be sure to start the `dont-interrupt-me` job before pushing. 1. All jobs must only pull caches by default. 1. All jobs must be able to pass with an empty cache. In other words, caches are only there to speed up jobs. -1. We currently have several different caches defined in +1. We currently have several different cache definitions defined in [`.gitlab/ci/global.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/global.gitlab-ci.yml), with fixed keys: - `.setup-test-env-cache` @@ -505,17 +559,15 @@ request, be sure to start the `dont-interrupt-me` job before pushing. - `.qa-cache` - `.yarn-cache` - `.assets-compile-cache` (the key includes `${NODE_ENV}` so it's actually two different caches). +1. These cache definitions are composed of [multiple atomic caches](../ci/yaml/README.md#multiple-caches). 1. Only 6 specific jobs, running in 2-hourly scheduled pipelines, are pushing (i.e. updating) to the caches: - `update-setup-test-env-cache`, defined in [`.gitlab/ci/rails.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/rails.gitlab-ci.yml). - - `update-rails-cache`, defined in [`.gitlab/ci/rails.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/rails.gitlab-ci.yml). - `update-static-analysis-cache`, defined in [`.gitlab/ci/rails.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/rails.gitlab-ci.yml). - - `update-coverage-cache`, defined in [`.gitlab/ci/rails.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/rails.gitlab-ci.yml). - - `update-danger-review-cache`, defined in [`.gitlab/ci/review.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/review.gitlab-ci.yml). - `update-qa-cache`, defined in [`.gitlab/ci/qa.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/qa.gitlab-ci.yml). - `update-assets-compile-production-cache`, defined in [`.gitlab/ci/frontend.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/frontend.gitlab-ci.yml). - `update-assets-compile-test-cache`, defined in [`.gitlab/ci/frontend.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/frontend.gitlab-ci.yml). - `update-yarn-cache`, defined in [`.gitlab/ci/frontend.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/frontend.gitlab-ci.yml). -1. These jobs run in merge requests whose title include `UPDATE CACHE`. +1. These jobs can also be forced to run in merge requests whose title include `UPDATE CACHE` (this can be useful to warm the caches in a MR that updates the cache keys). ### Artifacts strategy @@ -539,12 +591,12 @@ The `CI_PRE_CLONE_SCRIPT` is currently defined as a project CI/CD variable: ( echo "Downloading archived master..." wget -O /tmp/gitlab.tar.gz https://storage.googleapis.com/gitlab-ci-git-repo-cache/project-278964/gitlab-master-shallow.tar.gz - + if [ ! -f /tmp/gitlab.tar.gz ]; then echo "Repository cache not available, cloning a new directory..." exit fi - + rm -rf $CI_PROJECT_DIR echo "Extracting tarball into $CI_PROJECT_DIR..." mkdir -p $CI_PROJECT_DIR diff --git a/doc/development/policies.md b/doc/development/policies.md index c1a87990bc9..315878e19d9 100644 --- a/doc/development/policies.md +++ b/doc/development/policies.md @@ -68,7 +68,7 @@ Within the rule DSL, you can use: - `can?(:other_ability)` delegates to the rules that apply to `:other_ability`. Note that this is distinct from the instance method `can?`, which can check dynamically - this only configures a delegation to another ability. `~`, `&` and `|` operators are overridden methods in -[`DeclarativePolicy::Rule::Base`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/declarative_policy/rule.rb). +[`DeclarativePolicy::Rule::Base`](https://gitlab.com/gitlab-org/declarative-policy/-/blob/main/lib/declarative_policy/rule.rb). Do not use boolean operators such as `&&` and `||` within the rule DSL, as conditions within rule blocks are objects, not booleans. The same diff --git a/doc/development/product_analytics/snowplow.md b/doc/development/product_analytics/snowplow.md deleted file mode 100644 index 4e2f6530126..00000000000 --- a/doc/development/product_analytics/snowplow.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../snowplow/index.md' ---- - -This document was moved to [another location](../snowplow/index.md). - -<!-- This redirect file can be deleted after April 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/product_analytics/usage_ping.md b/doc/development/product_analytics/usage_ping.md deleted file mode 100644 index 43acf5b7e3f..00000000000 --- a/doc/development/product_analytics/usage_ping.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../usage_ping/index.md' ---- - -This document was moved to [another location](../usage_ping/index.md). - -<!-- This redirect file can be deleted after April 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/development/profiling.md b/doc/development/profiling.md index 5c5ad5f9c39..81881a4d490 100644 --- a/doc/development/profiling.md +++ b/doc/development/profiling.md @@ -96,6 +96,16 @@ that builds on this to add some additional niceties, such as allowing configuration with a single YAML file for multiple URLs, and uploading of the profile and log output to S3. +## Speedscope flamegraphs + +You can generate a flamegraph for a particular URL by adding the `performance_bar=flamegraph` parameter to the request. + + + +More information about the views can be found in the [Speedscope docs](https://github.com/jlfwong/speedscope#views) + +This is enabled for all users that can access the performance bar. + ## Sherlock Sherlock is a custom profiling tool built into GitLab. Sherlock is _only_ @@ -106,7 +116,7 @@ environment variable `ENABLE_SHERLOCK` to a non empty value. For example: ENABLE_SHERLOCK=1 bundle exec rails s ``` -Sherlock is also [available though the GitLab GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/sherlock.md). +Sherlock is also [available though the GitLab GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/sherlock.md). Recorded transactions can be found by navigating to `/sherlock/transactions`. @@ -195,7 +205,7 @@ This endpoint is only available for Rails web workers. Sidekiq workers can not b To disable those features for profiling/benchmarking set the `RAILS_PROFILE` environment variable to `true` before starting GitLab. For example when using GDK: -- create a file [`env.runit`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/runit.md#modifying-environment-configuration-for-services) in the root GDK directory +- create a file [`env.runit`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/runit.md#modifying-environment-configuration-for-services) in the root GDK directory - add `export RAILS_PROFILE=true` to your `env.runit` file - restart GDK with `gdk restart` diff --git a/doc/development/rake_tasks.md b/doc/development/rake_tasks.md index f88424287b1..c6c3d39c57f 100644 --- a/doc/development/rake_tasks.md +++ b/doc/development/rake_tasks.md @@ -362,3 +362,7 @@ This uses GraphQL Ruby's built-in Rake tasks to generate files in both [IDL](htt ### Update documentation and schema definitions The following command combines the intent of [Update GraphQL documentation and schema definitions](#update-graphql-documentation-and-schema-definitions) and [Update machine-readable schema files](#update-machine-readable-schema-files): + +```shell +bundle exec rake gitlab:graphql:update_all +``` diff --git a/doc/development/service_measurement.md b/doc/development/service_measurement.md index 895ac540838..82fb9731bcb 100644 --- a/doc/development/service_measurement.md +++ b/doc/development/service_measurement.md @@ -52,7 +52,7 @@ class DummyService end end -DummyService.prepend_if_ee('EE::DummyService') +DummyService.prepend_mod_with('DummyService') DummyService.prepend(Measurable) ``` diff --git a/doc/development/shared_files.md b/doc/development/shared_files.md index 6c273f2899d..e26464a5d80 100644 --- a/doc/development/shared_files.md +++ b/doc/development/shared_files.md @@ -6,34 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Shared files -Historically, GitLab has been storing shared files in many different -directories: `public/uploads`, `builds`, `tmp/repositories`, `tmp/rebase` (EE), -etc. Having so many shared directories makes it difficult to deploy GitLab on -shared storage (e.g. NFS). Working towards GitLab 9.0 we are consolidating -these different directories under the `shared` directory. +Historically, GitLab supported storing files that could be accessed from multiple application +servers in `shared/`, using a shared storage solution like NFS. Although this is still an option for +some GitLab installations, it must not be the only file storage option for a given feature. This is +because [cloud-native GitLab installations do not support it](architecture.md#adapting-existing-and-introducing-new-components). -This means that if GitLab begins storing puppies in some future version -then we should put them in `shared/puppies`. Temporary puppy files should be -stored in `shared/tmp`. - -In the GitLab application code you can get the full path to the `shared` -directory with `Gitlab.config.shared.path`. - -## What is not a 'shared file' - -Files that belong to only one process, or on only one server, should not go in -`shared`. Examples include PID files and sockets. - -## Temporary files and shared storage - -Sometimes you create a temporary file on disk with the intention of it becoming -'official'. For example you might be first streaming an upload from a user to -disk in a temporary file so you can perform some checks on it. When the checks -pass, you make the file official. In scenarios like this please follow these -rules: - -- Store the temporary file under `shared/tmp`, i.e. on the same file system you - want the official file to be on. -- Use move/rename operations when operating on the file instead of copy - operations where possible, because renaming a file is much faster than - copying it. +Our [uploads documentation](uploads.md) describes how to handle file storage in +such a way that it supports both options: direct disk access and object storage. diff --git a/doc/development/sidekiq_style_guide.md b/doc/development/sidekiq_style_guide.md index 4bcd5e50fae..82b6a54540f 100644 --- a/doc/development/sidekiq_style_guide.md +++ b/doc/development/sidekiq_style_guide.md @@ -15,6 +15,36 @@ All workers should include `ApplicationWorker` instead of `Sidekiq::Worker`, which adds some convenience methods and automatically sets the queue based on the worker's name. +## Retries + +Sidekiq defaults to using [25 +retries](https://github.com/mperham/sidekiq/wiki/Error-Handling#automatic-job-retry), +with back-off between each retry. 25 retries means that the last retry +would happen around three weeks after the first attempt (assuming all 24 +prior retries failed). + +For most workers - especially [idempotent workers](#idempotent-jobs) - +the default of 25 retries is more than sufficient. Many of our older +workers declare 3 retries, which used to be the default within the +GitLab application. 3 retries happen over the course of a couple of +minutes, so the jobs are prone to failing completely. + +A lower retry count may be applicable if any of the below apply: + +1. The worker contacts an external service and we do not provide + guarantees on delivery. For example, webhooks. +1. The worker is not idempotent and running it multiple times could + leave the system in an inconsistent state. For example, a worker that + posts a system note and then performs an action: if the second step + fails and the worker retries, the system note will be posted again. +1. The worker is a cronjob that runs frequently. For example, if a cron + job runs every hour, then we don't need to retry beyond an hour + because we don't need two of the same job running at once. + +Each retry for a worker is counted as a failure in our metrics. A worker +which always fails 9 times and succeeds on the 10th would have a 90% +error rate. + ## Dedicated Queues All workers should use their own queue, which is automatically set based on the @@ -719,6 +749,23 @@ possible situations: 1. A job is queued by a node running the newer version of the application, but executed on a node running an older version of the application. +### Adding new workers + +On GitLab.com, we [do not currently have a Sidekiq deployment in the +canary stage](https://gitlab.com/gitlab-org/gitlab/-/issues/19239). This +means that a new worker than can be scheduled from an HTTP endpoint may +be scheduled from canary but not run on Sidekiq until the full +production deployment is complete. This can be several hours later than +scheduling the job. For some workers, this will not be a problem. For +others - particularly [latency-sensitive +jobs](#latency-sensitive-jobs) - this will result in a poor user +experience. + +This only applies to new worker classes when they are first introduced. +As we recommend [using feature flags](feature_flags/) as a general +development process, it's best to control the entire change (including +scheduling of the new Sidekiq worker) with a feature flag. + ### Changing the arguments for a worker Jobs need to be backward and forward compatible between consecutive versions diff --git a/doc/development/snowplow/dictionary.md b/doc/development/snowplow/dictionary.md new file mode 100644 index 00000000000..f20ec41d558 --- /dev/null +++ b/doc/development/snowplow/dictionary.md @@ -0,0 +1,44 @@ +--- +stage: Growth +group: Product Intelligence +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +<!--- + This documentation is auto generated by a script. + + Please do not edit this file directly, check generate_metrics_dictionary task on lib/tasks/gitlab/usage_data.rake. +---> + +<!-- vale gitlab.Spelling = NO --> + +# Event Dictionary + +This file is autogenerated, please do not edit it directly. + +To generate these files from the GitLab repository, run: + +```shell +bundle exec rake gitlab:snowplow:generate_event_dictionary +``` + +The Event Dictionary is based on the following event definition YAML files: + +- [`config/events`](https://gitlab.com/gitlab-org/gitlab/-/tree/f9a404301ca22d038e7b9a9eb08d9c1bbd6c4d84/config/events) +- [`ee/config/events`](https://gitlab.com/gitlab-org/gitlab/-/tree/f9a404301ca22d038e7b9a9eb08d9c1bbd6c4d84/ee/config/events) + +## Event definitions + +### `epics promote` + +| category | action | label | property | value | +|---|---|---|---|---| +| `epics` | `promote` | `` | `The string "issue_id"` | `ID of the issue` | + +Issue promoted to epic + +YAML definition: `/ee/config/events/epics_promote.yml` + +Owner: `group::product planning` + +Tiers: `premium`, `ultimate` diff --git a/doc/development/snowplow/event_dictionary_guide.md b/doc/development/snowplow/event_dictionary_guide.md new file mode 100644 index 00000000000..5ae81c3426d --- /dev/null +++ b/doc/development/snowplow/event_dictionary_guide.md @@ -0,0 +1,94 @@ +--- +stage: Growth +group: Product Intelligence +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Event dictionary guide + +NOTE: +The event dictionary is a work in progress, and this process is subject to change. + +This guide describes the event dictionary and how it's implemented. + +## Event definition and validation + +This process is meant to document all Snowplow events and ensure consistency. Event definitions must comply with the [JSON Schema](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/events/schema.json). + +All event definitions are stored in the following directories: + +- [`config/events`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/config/events) +- [`ee/config/events`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/ee/config/events) + +Each event is defined in a separate YAML file consisting of the following fields: + +| Field | Required | Additional information | +|------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `description` | yes | A description of the event. | +| `category` | yes | The event category (see [Structured event taxonomy](index.md#structured-event-taxonomy)). | +| `action` | yes | The event action (see [Structured event taxonomy](index.md#structured-event-taxonomy)). | +| `label_description` | no | A description of the event label (see [Structured event taxonomy](index.md#structured-event-taxonomy)). | +| `property_description` | no | A description of the event property (see [Structured event taxonomy](index.md#structured-event-taxonomy)). | +| `value_description` | no | A description of the event value (see [Structured event taxonomy](index.md#structured-event-taxonomy)). | +| `extra_properties` | no | The type and description of each extra property sent with the event. | +| `identifiers` | no | A list of identifiers sent with the event. Can be set to one or more of `project`, `user`, or `namespace`. | +| `iglu_schema_url` | no | The URL to the custom schema sent with the event, for example, `iglu:com.gitlab/gitlab_experiment/jsonschema/1-0-0`. | +| `product_section` | yes | The [section](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/data/sections.yml). | +| `product_stage` | no | The [stage](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/stages.yml) for the event. | +| `product_group` | yes | The [group](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/stages.yml) that owns the event. | +| `product_category` | no | The [product category](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/categories.yml) for the event. | +| `milestone` | no | The milestone when the event is introduced. | +| `introduced_by_url` | no | The URL to the merge request that introduced the event. | +| `distributions` | yes | The [distributions](https://about.gitlab.com/handbook/marketing/strategic-marketing/tiers/#definitions) where the tracked feature is available. Can be set to one or more of `ce` or `ee`. | +| `tiers` | yes | The [tiers]( https://about.gitlab.com/handbook/marketing/strategic-marketing/tiers/) where the tracked feature is available. Can be set to one or more of `free`, `premium`, or `ultimate`. | + +### Example event definition + +The linked [`uuid`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/events/epics_promote.yml) +YAML file includes an example event definition. + +```yaml +description: Issue promoted to epic +category: epics +action: promote +property_description: The string "issue_id" +value_description: ID of the issue +extra_properties: + weight: + type: integer + description: Weight of the issue +identifiers: +- project +- user +- namespace +product_section: dev +product_stage: plan +product_group: group::product planning +product_category: epics +milestone: "11.10" +introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/10537 +distributions: +- ee +tiers: +- premium +- ultimate +``` + +## Create a new event definition + +Use the dedicated [event definition generator](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/generators/gitlab/snowplow_event_definition_generator.rb) +to create new event definitions. + +The `category` and `action` of each event are included in the filename to enforce uniqueness. + +The generator takes three options: + +- `--ee`: Indicates if the event is for EE. +- `--category=CATEGORY`: Indicates the `category` of the event. +- `--action=ACTION`: Indicates the `action` of the event. +- `--force`: Overwrites the existing event definition, if one already exists. + +```shell +bundle exec rails generate gitlab:snowplow_event_definition --category Groups::EmailCampaignsController --action click +create create config/events/groups__email_campaigns_controller_click.yml +``` diff --git a/doc/development/snowplow/index.md b/doc/development/snowplow/index.md index c07291d61f2..ece72dbbf03 100644 --- a/doc/development/snowplow/index.md +++ b/doc/development/snowplow/index.md @@ -114,13 +114,13 @@ The current method provides several attributes that are sent on each click event | category* | label | action | property** | value | |-------------|------------------|-----------------------|----------|:-----:| -| [root:index] | main_navigation | click_navigation_link | `[link_label]` | - | -| [groups:boards:show] | toggle_swimlanes | click_toggle_button | - | `[is_active]` | -| [projects:registry:index] | registry_delete | click_button | - | - | -| [projects:registry:index] | registry_delete | confirm_deletion | - | - | -| [projects:blob:show] | congratulate_first_pipeline | click_button | `[human_access]` | - | -| [projects:clusters:new] | chart_options | generate_link | `[chart_link]` | - | -| [projects:clusters:new] | chart_options | click_add_label_button | `[label_id]` | - | +| `[root:index]` | `main_navigation` | `click_navigation_link` | `[link_label]` | - | +| `[groups:boards:show]` | `toggle_swimlanes` | `click_toggle_button` | - | `[is_active]` | +| `[projects:registry:index]` | `registry_delete` | `click_button` | - | - | +| `[projects:registry:index]` | `registry_delete` | `confirm_deletion` | - | - | +| `[projects:blob:show]` | `congratulate_first_pipeline` | `click_button` | `[human_access]` | - | +| `[projects:clusters:new]` | `chart_options` | `generate_link` | `[chart_link]` | - | +| `[projects:clusters:new]` | `chart_options` | `click_add_label_button` | `[label_id]` | - | _* It's ok to omit the category, and use the default._<br> _** Property is usually the best place for variable strings._ @@ -131,8 +131,8 @@ _** Property is usually the best place for variable strings._ ```sql SELECT + session_id, event_id, - v_tracker, event_label, event_action, event_property, @@ -427,7 +427,7 @@ https://docs.gitlab.com/ee/development/testing_guide/best_practices.html#test-sn ### Performance -We use the [AsyncEmitter](https://github.com/snowplow/snowplow/wiki/Ruby-Tracker#52-the-asyncemitter-class) when tracking events, which allows for instrumentation calls to be run in a background thread. This is still an active area of development. +We use the [AsyncEmitter](https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/ruby-tracker/emitters/#the-asyncemitter-class) when tracking events, which allows for instrumentation calls to be run in a background thread. This is still an active area of development. ## Developing and testing Snowplow @@ -579,6 +579,7 @@ The [`StandardContext`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/g | `namespace_id` | **{dotted-circle}** | integer | | | `environment` | **{check-circle}** | string (max 32 chars) | Name of the source environment, such as `production` or `staging` | | `source` | **{check-circle}** | string (max 32 chars) | Name of the source application, such as `gitlab-rails` or `gitlab-javascript` | +| `plan` | **{dotted-circle}** | string (max 32 chars) | Name of the plan for the namespace, such as `free`, `premium`, or `ultimate`. Automatically picked from the `namespace`. | | `extra` | **{dotted-circle}** | JSON | Any additional data associated with the event, in the form of key-value pairs | ### Default Schema diff --git a/doc/development/stage_group_dashboards.md b/doc/development/stage_group_dashboards.md index 58e998e46a8..44c738092ac 100644 --- a/doc/development/stage_group_dashboards.md +++ b/doc/development/stage_group_dashboards.md @@ -25,7 +25,7 @@ The dashboards for stage groups are at a very early stage. All contributions are Read more about how we are using error budgets overall in our [handbook](https://about.gitlab.com/handbook/engineering/error-budgets/). -By default, the first row of panels on the dashbhoard will show the [error +By default, the first row of panels on the dashboard will show the [error budget for the stage group](https://about.gitlab.com/handbook/engineering/error-budgets/#budget-spend-by-stage-group). This row shows how the features owned by @@ -57,7 +57,7 @@ component has 2 indicators: The calculation to a ratio then happens as follows: ```math -\frac {operations\_meeting\_apdex + (total\_operations - operations\_with_\errors)} {total\_apdex\_measurements + total\_operations} +\frac {operations\_meeting\_apdex + (total\_operations - operations\_with\_errors)} {total\_apdex\_measurements + total\_operations} ``` *Caveat:* Not all components are included, causing the diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md index 828e9925d46..c3125f52cf2 100644 --- a/doc/development/testing_guide/best_practices.md +++ b/doc/development/testing_guide/best_practices.md @@ -168,7 +168,7 @@ can be used: ```ruby RSpec.describe API::Search, factory_default: :keep do - let_it_be(:namespace) { create_default(:namespace).freeze } + let_it_be(:namespace) { create_default(:namespace) } ``` Then every project we create uses this `namespace`, without us having to pass @@ -176,9 +176,9 @@ it as `namespace: namespace`. In order to make it work along with `let_it_be`, ` must be explicitly specified. That keeps the default factory for every example in a suite instead of recreating it for each example. -Objects created inside a `factory_default: :keep`, and using -`create_default` inside a `let_it_be` should be frozen to prevent accidental reliance -between test examples. +To prevent accidental reliance between test examples, objects created +with `create_default` are +[frozen](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/support/factory_default.rb). Maybe we don't need to create 208 different projects - we can create one and reuse it. In addition, we can see that only about 1/3 of the @@ -186,7 +186,7 @@ projects we create are ones we ask for (76/208). There is benefit in setting a default value for projects as well: ```ruby - let_it_be(:project) { create_default(:project).freeze } + let_it_be(:project) { create_default(:project) } ``` In this case, the `total time` and `top-level time` numbers match more closely: @@ -451,7 +451,7 @@ expect(page).to have_current_path 'gitlab/gitlab-test/-/issues' expect(page).to have_title 'Not Found' -# acceptable when a more specific matcher above is not possible +# acceptable when a more specific matcher above is not possible expect(page).to have_css 'h2', text: 'Issue title' expect(page).to have_css 'p', text: 'Issue description', exact: true expect(page).to have_css '[data-testid="weight"]', text: 2 @@ -895,6 +895,27 @@ When you want to ensure that no event got called, you can use `expect_no_snowplo end ``` +#### Test Snowplow context against the schema + +The [Snowplow schema matcher](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60480) +helps to reduce validation errors by testing Snowplow context against the JSON schema. +The schema matcher accepts the following parameters: + +- `schema path` +- `context` + +To add a schema matcher spec: + +1. Add a new schema to the [Iglu repository](https://gitlab.com/gitlab-org/iglu), + then copy the same schema to the `spec/fixtures/product_intelligence/` directory. +1. In the copied schema, remove the `"$schema"` key and value. We do not need it for specs + and the spec fails if we keep the key, as it tries to look for the schema in the URL. +1. Use the following snippet to call the schema matcher: + + ```ruby + match_snowplow_context_schema(schema_path: '<filename from step 1>', context: <Context Hash> ) + ``` + ### Table-based / Parameterized tests This style of testing is used to exercise one piece of code with a comprehensive diff --git a/doc/development/testing_guide/end_to_end/beginners_guide.md b/doc/development/testing_guide/end_to_end/beginners_guide.md index 29f6c93d65a..7cde2cad300 100644 --- a/doc/development/testing_guide/end_to_end/beginners_guide.md +++ b/doc/development/testing_guide/end_to_end/beginners_guide.md @@ -210,7 +210,7 @@ end Behind the scenes, `be_signed_in` is a [predicate matcher](https://relishapp.com/rspec/rspec-expectations/v/3-8/docs/built-in-matchers/predicate-matchers) -that [implements checking the user avatar](https://gitlab.com/gitlab-org/gitlab/-/blob/master/qa/qa/page/main/menu.rb#L74). +that [implements checking the user avatar](https://gitlab.com/gitlab-org/gitlab/-/blob/master/qa/qa/page/main/menu.rb#L92). ## De-duplicate your code @@ -339,11 +339,12 @@ Before running the spec, make sure that: - No additional [RSpec metadata tags](rspec_metadata_tests.md) have been applied. - Your working directory is `qa/` within your GDK GitLab installation. - Your GitLab instance-level settings are default. If you changed the default settings, some tests might have unexpected results. +- Because the GDK requires a password change on first login, you must include the GDK password for `root` user To run the spec, run the following command: ```ruby -bundle exec bin/qa Test::Instance::All http://localhost:3000 -- <test_file> +GITLAB_PASSWORD=<GDK root password> bundle exec bin/qa Test::Instance::All http://localhost:3000 -- <test_file> ``` Where `<test_file>` is: diff --git a/doc/development/testing_guide/end_to_end/capybara_to_chemlab_migration_guide.md b/doc/development/testing_guide/end_to_end/capybara_to_chemlab_migration_guide.md new file mode 100644 index 00000000000..9c7e0ef73a8 --- /dev/null +++ b/doc/development/testing_guide/end_to_end/capybara_to_chemlab_migration_guide.md @@ -0,0 +1,148 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Migration Guide Capybara → Chemlab + +Given the view: + +*_form.html* + +```html +<form id="my-form"> + <label for="first-name">First name</label> + <input type="text" name="first-name" data-qa-selector="first_name" /> + + <label for="last-name">Last name</label> + <input type="text" name="last-name" data-qa-selector="last_name" /> + + <label for="company-name">Company name</label> + <input type="text" name="company-name" data-qa-selector="company_name" /> + + <label for="user-name">User name</label> + <input type="text" name="user-name" data-qa-selector="user_name" /> + + <label for="password">Password</label> + <input type="password" name="password" data-qa-selector="password" /> + + <input type="submit" value="Continue" data-qa-selector="continue"/> +</form> +``` + +| Capybara | Chemlab | +| ------ | ----- | +|  |  | + +<!-- +```ruby +# frozen_string_literal: true + +module QA + module Page + class Form < Page::Base + view '_form.html' do + element :first_name + element :last_name + element :company_name + element :user_name + element :password + element :continue + end + end + end +end +``` +```ruby +# frozen_string_literal: true + +module QA + module Page + class Form < Chemlab::Page + text_field :first_name + text_field :last_name + text_field :company_name + text_field :user_name + text_field :password + + button :continue + end + end +end +``` +--> + +## Key Differences + +### Page Library Design vs Page Object Design + +Page Objects as implemented in the existing framework require you to define methods to perform actions on elements. (Usually one-liners) + +```ruby +def set_first_name(first_name) + fill_element(:first_name, first_name) +end + +def click_continue + click_element(:continue) +end + +it 'sets first name and clicks continue' do + Page::Form.perform do |form| + form.set_first_name('First Name') + form.click_continue + end +end +``` + +Page Libraries make this more efficient by providing methods based on the page's elements, making extra methods unnecessary. + +```ruby +it 'sets first name and clicks continue' do + Page::Form.perform do |form| + form.first_name = 'First Name' # sets the first_name + form.continue # clicks Continue + end +end +``` + +Consider if we needed to validate the text of the `First name` field using Capybara. We'd need to add a one-liner to fetch the text: + +```ruby +def get_first_name + find_element(:first_name).text +end + +Page::Form.perform do |form| + form.set_first_name('First Name') + expect(form.get_first_name).to eq('First Name') + form.click_continue +end +``` + +Instead, because the page library automatically creates methods from page elements, we can fetch the text by calling `first_name` without writing code to define the method ourselves: + +```ruby +Page::Form.perform do |form| + form.first_name = 'First Name' + expect(form.first_name).to eq('First Name') + form.continue +end +``` + +### Element Naming Convention + +Since the element type is preserved within the Page Library, there is no need to specify a `_field` or `_button` suffix to the data-qa-selector. + +```html +<!-- Before --> +<input type="text" name="first-name" data-qa-selector="first_name_field" /> +<input type="submit" name="continue" value="Continue" data-qa-selector="continue_button" /> + +<!-- After --> +<input type="text" name="first-name" data-qa-selector="first_name" /> +<input type="submit" name="continue" value="Continue" data-qa-selector="continue" /> +``` + +This makes it much easier for Developers to write tests and contributes to testability since we can write the Page Library while we look at the UI. diff --git a/doc/development/testing_guide/end_to_end/img/gl-capybara_V13_12.png b/doc/development/testing_guide/end_to_end/img/gl-capybara_V13_12.png Binary files differnew file mode 100644 index 00000000000..9ceccd39025 --- /dev/null +++ b/doc/development/testing_guide/end_to_end/img/gl-capybara_V13_12.png diff --git a/doc/development/testing_guide/end_to_end/img/gl-chemlab_V13_12.png b/doc/development/testing_guide/end_to_end/img/gl-chemlab_V13_12.png Binary files differnew file mode 100644 index 00000000000..489a043f52e --- /dev/null +++ b/doc/development/testing_guide/end_to_end/img/gl-chemlab_V13_12.png diff --git a/doc/development/testing_guide/end_to_end/page_objects.md b/doc/development/testing_guide/end_to_end/page_objects.md index b124ac430f6..9ffa7ea4f77 100644 --- a/doc/development/testing_guide/end_to_end/page_objects.md +++ b/doc/development/testing_guide/end_to_end/page_objects.md @@ -260,7 +260,7 @@ These modules must: These steps ensure the sanity selectors check detect problems properly. For example, `qa/qa/ee/page/merge_request/show.rb` adds EE-specific methods to `qa/qa/page/merge_request/show.rb` (with -`QA::Page::MergeRequest::Show.prepend_if_ee('QA::EE::Page::MergeRequest::Show')`) and following is how it's implemented +`QA::Page::MergeRequest::Show.prepend_mod_with('Page::MergeRequest::Show', namespace: QA)`) and following is how it's implemented (only showing the relevant part and referring to the 4 steps described above with inline comments): ```ruby diff --git a/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md b/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md index ea48a3aa8b8..549ab95a5d1 100644 --- a/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md +++ b/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md @@ -147,10 +147,10 @@ docker rm gitlab-gitaly-cluster praefect postgres gitaly3 gitaly2 gitaly1 To run the Monitor tests locally, against the GDK, please follow the preparation steps below: -1. Complete the [Prerequisites](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/auto_devops/index.md#prerequisites-for-gitlab-team-members-only), at least through step 5. Note that the monitor tests do not require permissions to work with GKE because they use [k3s as a Kubernetes cluster provider](https://github.com/rancher/k3s). +1. Complete the [Prerequisites](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/auto_devops/index.md#prerequisites-for-gitlab-team-members-only), at least through step 5. Note that the monitor tests do not require permissions to work with GKE because they use [k3s as a Kubernetes cluster provider](https://github.com/rancher/k3s). 1. The test setup deploys the app in a Kubernetes cluster, using the Auto DevOps deployment strategy. -To enable Auto DevOps in GDK, follow the [associated setup](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/auto_devops/index.md#setup) instructions. If you have problems, review the [troubleshooting guide](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/auto_devops/tips_and_troubleshooting.md) or reach out to the `#gdk` channel in the internal GitLab Slack. -1. Do [secure your GitLab instance](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/auto_devops/index.md#secure-your-gitlab-instance) since it is now publicly accessible on `https://[YOUR-PORT].qa-tunnel.gitlab.info`. +To enable Auto DevOps in GDK, follow the [associated setup](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/auto_devops/index.md#setup) instructions. If you have problems, review the [troubleshooting guide](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/auto_devops/tips_and_troubleshooting.md) or reach out to the `#gdk` channel in the internal GitLab Slack. +1. Do [secure your GitLab instance](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/auto_devops/index.md#secure-your-gitlab-instance) since it is now publicly accessible on `https://[YOUR-PORT].qa-tunnel.gitlab.info`. 1. Install the Kubernetes command line tool known as `kubectl`. Use the [official installation instructions](https://kubernetes.io/docs/tasks/tools/). You might see NGINX issues when you run `gdk start` or `gdk restart`. In that case, run `sft login` to revalidate your credentials and regain access the QA Tunnel. @@ -272,7 +272,7 @@ You can free some memory with either of the following commands: `docker prune sy ## Geo tests -Geo end-to-end tests can run locally against a [Geo GDK setup](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/geo.md) or on Geo spun up in Docker containers. +Geo end-to-end tests can run locally against a [Geo GDK setup](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/geo.md) or on Geo spun up in Docker containers. ### Using Geo GDK diff --git a/doc/development/testing_guide/flaky_tests.md b/doc/development/testing_guide/flaky_tests.md index a9af8f03d63..6b1c7a7eb58 100644 --- a/doc/development/testing_guide/flaky_tests.md +++ b/doc/development/testing_guide/flaky_tests.md @@ -76,6 +76,33 @@ For instance `RETRIES=1 bin/rspec ...` would retry the failing examples once. - [Replace FFaker factory data with sequences](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/29643): <https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10184> - [Transient failure in spec/finders/issues_finder_spec.rb](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30211#note_26707685): <https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10404> +### Order-dependent flaky tests + +These flaky tests can fail depending on the order they run with other tests. For example: + +- <https://gitlab.com/gitlab-org/gitlab/-/issues/327668> + +To identify the tests that lead to such failure, we can use `rspec --bisect`, +which would give us the minimal test combination to reproduce the failure: + +```shell +rspec --bisect ee/spec/services/ee/merge_requests/update_service_spec.rb ee/spec/services/ee/notes/quick_actions_service_spec.rb ee/spec/services/epic_links/create_service_spec.rb ee/spec/services/ee/issuable/bulk_update_service_spec.rb +Bisect started using options: "ee/spec/services/ee/merge_requests/update_service_spec.rb ee/spec/services/ee/notes/quick_actions_service_spec.rb ee/spec/services/epic_links/create_service_spec.rb ee/spec/services/ee/issuable/bulk_update_service_spec.rb" +Running suite to find failures... (2 minutes 18.4 seconds) +Starting bisect with 3 failing examples and 144 non-failing examples. +Checking that failure(s) are order-dependent... failure appears to be order-dependent + +Round 1: bisecting over non-failing examples 1-144 . ignoring examples 1-72 (1 minute 11.33 seconds) +... +Round 7: bisecting over non-failing examples 132-133 . ignoring example 132 (43.78 seconds) +Bisect complete! Reduced necessary non-failing examples from 144 to 1 in 8 minutes 31 seconds. + +The minimal reproduction command is: + rspec ./ee/spec/services/ee/issuable/bulk_update_service_spec.rb[1:2:1:1:1:1,1:2:1:2:1:1,1:2:1:3:1] ./ee/spec/services/epic_links/create_service_spec.rb[1:1:2:2:6:4] +``` + +We can reproduce the test failure with the reproduction command above. If we change the order of the tests, the test would pass. + ### Time-sensitive flaky tests - <https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/10046> diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md index 7289e66a045..911fbd43989 100644 --- a/doc/development/testing_guide/frontend_testing.md +++ b/doc/development/testing_guide/frontend_testing.md @@ -890,8 +890,8 @@ helper method. For example: describe GraphQL::Query, type: :request do include GraphqlHelpers - all_releases_query_path = 'releases/queries/all_releases.query.graphql' - fragment_paths = ['releases/queries/release.fragment.graphql'] + all_releases_query_path = 'releases/graphql/queries/all_releases.query.graphql' + fragment_paths = ['releases/graphql/fragments/release.fragment.graphql'] before(:all) do clean_frontend_fixtures('graphql/releases/') @@ -908,7 +908,7 @@ end ``` This will create a new fixture located at -`tmp/tests/frontend/fixtures-ee/graphql/releases/queries/all_releases.query.graphql.json`. +`tmp/tests/frontend/fixtures-ee/graphql/releases/graphql/queries/all_releases.query.graphql.json`. You will need to provide the paths to all fragments used by the query. `get_graphql_query_as_string` reads all of the provided file paths and returns @@ -1151,8 +1151,8 @@ Both functions run `callback` on the next tick after the requests finish (using ### `shallowMountExtended` and `mountExtended` -The `shallowMountExtended` and `mountExtended` utilities provide you with the ability to perform -any of the available [DOM Testing Library queries](https://testing-library.com/docs/queries/about) +The `shallowMountExtended` and `mountExtended` utilities provide you with the ability to perform +any of the available [DOM Testing Library queries](https://testing-library.com/docs/queries/about) by prefixing them with `find` or `findAll`. ```javascript @@ -1302,7 +1302,7 @@ A good guideline to follow: the more complex the component you may want to steer - To capture large data structures just to have something - To just have some kind of test written -- To capture highly volatile ui elements without stubbing them (Think of GitLab UI version updates) +- To capture highly volatile UI elements without stubbing them (Think of GitLab UI version updates) --- diff --git a/doc/development/usage_ping/dictionary.md b/doc/development/usage_ping/dictionary.md index cb53d088907..75d65f8e5df 100644 --- a/doc/development/usage_ping/dictionary.md +++ b/doc/development/usage_ping/dictionary.md @@ -10,8 +10,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w Please do not edit this file directly, check generate_metrics_dictionary task on lib/tasks/gitlab/usage_data.rake. ---> -<!-- vale gitlab.Spelling = NO --> - # Metrics Dictionary This file is autogenerated, please do not edit directly. @@ -30,6 +28,10 @@ The Metrics Dictionary is based on the following metrics definition YAML files: Each table includes a `milestone`, which corresponds to the GitLab version when the metric was released. +<!-- vale off --> +<!-- Docs linting disabled after this line. --> +<!-- See https://docs.gitlab.com/ee/development/documentation/testing.html#disable-vale-tests --> + ## Metrics Definitions ### `active_user_count` @@ -46,11 +48,11 @@ Tiers: `free`, `premium`, `ultimate` ### `analytics_unique_visits.analytics_unique_visits_for_any_target` -Visits to any of the pages listed above per week +Unique visitors to any analytics feature by week [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216174908_analytics_unique_visits_for_any_target.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -58,11 +60,11 @@ Tiers: `free` ### `analytics_unique_visits.analytics_unique_visits_for_any_target_monthly` -Visits to any of the pages listed above per month +Unique visitors to any analytics feature by month [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216174910_analytics_unique_visits_for_any_target_monthly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -70,11 +72,11 @@ Tiers: `free` ### `analytics_unique_visits.g_analytics_contribution` -Visits to /groups/:group/-/contribution_analytics +Unique visitors to /groups/:group/-/contribution_analytics -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216174836_g_analytics_contribution.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216174836_g_analytics_contribution.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -82,11 +84,11 @@ Tiers: `free` ### `analytics_unique_visits.g_analytics_insights` -Visits to /groups/:group/-/insights +Unique visitors to /groups/:group/-/insights -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216174838_g_analytics_insights.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216174838_g_analytics_insights.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -94,11 +96,11 @@ Tiers: `free` ### `analytics_unique_visits.g_analytics_issues` -Visits to /groups/:group/-/issues_analytics +Unique visitors to /groups/:group/-/issues_analytics -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216174840_g_analytics_issues.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216174840_g_analytics_issues.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -106,23 +108,23 @@ Tiers: `free` ### `analytics_unique_visits.g_analytics_merge_request` -Visits to /groups/:group/-/analytics/merge_request_analytics +Unique visitors to /groups/:group/-/analytics/merge_request_analytics [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216174902_g_analytics_merge_request.yml) -Group: `group::analytics` +Group: `group::optimize` -Status: `data_available` +Status: `removed` Tiers: `free` ### `analytics_unique_visits.g_analytics_productivity` -Visits to /groups/:group/-/analytics/productivity_analytics +Unique visitors to /groups/:group/-/analytics/productivity_analytics -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216174842_g_analytics_productivity.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216174842_g_analytics_productivity.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -130,11 +132,11 @@ Tiers: `free` ### `analytics_unique_visits.g_analytics_valuestream` -Visits to /groups/:group/-/analytics/value_stream_analytics +Unique visitors to /groups/:group/-/analytics/value_stream_analytics -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216174844_g_analytics_valuestream.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216174844_g_analytics_valuestream.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -142,23 +144,35 @@ Tiers: `free` ### `analytics_unique_visits.i_analytics_cohorts` -Visits to /-/instance_statistics/cohorts +Unique visitors to /-/instance_statistics/cohorts [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216174858_i_analytics_cohorts.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` Tiers: `free` +### `analytics_unique_visits.i_analytics_dev_ops_adoption` + +Missing description + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210423005644_i_analytics_dev_ops_adoption.yml) + +Group: `` + +Status: `implemented` + +Tiers: + ### `analytics_unique_visits.i_analytics_dev_ops_score` -Visits to /-/instance_statistics/dev_ops_score +Unique visitors to /-/instance_statistics/dev_ops_score [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216174900_i_analytics_dev_ops_score.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -166,11 +180,11 @@ Tiers: `free` ### `analytics_unique_visits.i_analytics_instance_statistics` -Visit to /admin/instance_statistics +Unique visitors to/admin/usage_trends [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216174906_i_analytics_instance_statistics.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -178,11 +192,11 @@ Tiers: `free` ### `analytics_unique_visits.p_analytics_code_reviews` -Visits to /:group/:project/-/analytics/code_reviews +Unique visitors to /:group/:project/-/analytics/code_reviews -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216174848_p_analytics_code_reviews.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216174848_p_analytics_code_reviews.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -190,11 +204,11 @@ Tiers: `free` ### `analytics_unique_visits.p_analytics_insights` -Visits to /:group/:project/insights +Unique visitors to /:group/:project/insights -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216174852_p_analytics_insights.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216174852_p_analytics_insights.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -202,11 +216,11 @@ Tiers: `free` ### `analytics_unique_visits.p_analytics_issues` -Visits to /:group/:project/-/analytics/issues_analytics +Unique visitors to /:group/:project/-/analytics/issues_analytics -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216174854_p_analytics_issues.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216174854_p_analytics_issues.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -214,11 +228,11 @@ Tiers: `free` ### `analytics_unique_visits.p_analytics_merge_request` -Visits to /:group/:project/-/analytics/merge_request_analytics +Unique visitors to /:group/:project/-/analytics/merge_request_analytics -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216174904_p_analytics_merge_request.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216174904_p_analytics_merge_request.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -226,11 +240,11 @@ Tiers: `free` ### `analytics_unique_visits.p_analytics_pipelines` -Visits to /:group/:project/pipelines/charts +Unique visitors to /:group/:project/pipelines/charts [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216174846_p_analytics_pipelines.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -238,11 +252,11 @@ Tiers: `free` ### `analytics_unique_visits.p_analytics_repo` -Visits to /:group/:project/-/graphs/master/charts +Unique visitors to /:group/:project/-/graphs/master/charts [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216174856_p_analytics_repo.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -250,16 +264,28 @@ Tiers: `free` ### `analytics_unique_visits.p_analytics_valuestream` -Visits to /:group/:project/-/value_stream_analytics +Unique visitors to /:group/:project/-/value_stream_analytics [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216174850_p_analytics_valuestream.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` Tiers: `free` +### `analytics_unique_visits.users_viewing_analytics_group_devops_adoption` + +Missing description + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210428142406_users_viewing_analytics_group_devops_adoption.yml) + +Group: `` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + ### `compliance_unique_visits.a_compliance_audit_events_api` Missing description @@ -454,7 +480,7 @@ Tiers: `free` ### `counts.auto_devops_enabled` -Projects with Auto DevOps template enabled +Projects with Auto DevOps template enabled (excluding implicit Auto DevOps enabled and Auto DevOps template includes) [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175229_auto_devops_enabled.yml) @@ -462,11 +488,11 @@ Group: `group::configure` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.boards` -Count of total Boards created +Count of Boards created [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216181252_boards.yml) @@ -486,7 +512,7 @@ Group: `group::continuous integration` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.ci_external_pipelines` @@ -510,7 +536,7 @@ Group: `group::continuous integration` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.ci_pipeline_config_auto_devops` @@ -518,11 +544,11 @@ Total pipelines from an Auto DevOps template [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175516_ci_pipeline_config_auto_devops.yml) -Group: `group::continuous integration` +Group: `group::configure` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.ci_pipeline_config_repository` @@ -534,7 +560,7 @@ Group: `group::continuous integration` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.ci_pipeline_schedules` @@ -546,7 +572,7 @@ Group: `group::continuous integration` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.ci_runners` @@ -558,7 +584,91 @@ Group: `group::continuous integration` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` + +### `counts.ci_runners_group_type_active` + +Total active instance Runners + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210502050341_ci_runners_group_type_active.yml) + +Group: `group::continuous integration` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.ci_runners_group_type_active_online` + +Total active and online group Runners + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210502051922_ci_runners_group_type_active_online.yml) + +Group: `group::continuous integration` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.ci_runners_instance_type_active` + +Total active group Runners + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210502045402_ci_runners_instance_type_active.yml) + +Group: `group::continuous integration` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.ci_runners_instance_type_active_online` + +Total active and online instance Runners + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210502051651_ci_runners_instance_type_active_online.yml) + +Group: `group::continuous integration` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.ci_runners_online` + +Total online Runners + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210502050942_ci_runners_online.yml) + +Group: `group::continuous integration` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.ci_runners_project_type_active` + +Total active project Runners + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210502050834_ci_runners_project_type_active.yml) + +Group: `group::continuous integration` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.ci_runners_project_type_active_online` + +Total active and online project Runners + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210502052036_ci_runners_project_type_active_online.yml) + +Group: `group::continuous integration` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` ### `counts.ci_triggers` @@ -570,7 +680,7 @@ Group: `group::continuous integration` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.clusters` @@ -706,7 +816,7 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.clusters_disabled` -Total GitLab Managed disabled clusters +Number of Kubernetes clusters attached to GitLab currently disabled [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175242_clusters_disabled.yml) @@ -718,7 +828,7 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.clusters_enabled` -Total GitLab Managed clusters currently enabled +Number of Kubernetes clusters attached to GitLab currently enabled [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175234_clusters_enabled.yml) @@ -778,7 +888,7 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.commit_comment` -Missing description +Count of total unique commit comments. Does not include MR diff comments [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182004_commit_comment.yml) @@ -786,7 +896,7 @@ Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.confidential_epics` @@ -830,7 +940,7 @@ Missing description [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216174832_cycle_analytics_views.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -1016,6 +1126,54 @@ Status: `data_available` Tiers: `free` +### `counts.g_project_management_users_checking_epic_task_monthly` + +Counts of MAU checking epic task + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210421080207_g_project_management_users_checking_epic_task_monthly.yml) + +Group: `group::product planning` + +Status: `implemented` + +Tiers: `premium`, `ultimate` + +### `counts.g_project_management_users_checking_epic_task_weekly` + +Counts of WAU checking epic task + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210421075943_g_project_management_users_checking_epic_task_weekly.yml) + +Group: `group::product planning` + +Status: `implemented` + +Tiers: `premium`, `ultimate` + +### `counts.g_project_management_users_unchecking_epic_task_monthly` + +Counts of MAU unchecking epic task + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210421102516_g_project_management_users_unchecking_epic_task_monthly.yml) + +Group: `group::product planning` + +Status: `implemented` + +Tiers: `premium`, `ultimate` + +### `counts.g_project_management_users_unchecking_epic_task_weekly` + +Counts of WAU unchecking epic task + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210421102812_g_project_management_users_unchecking_epic_task_weekly.yml) + +Group: `group::product planning` + +Status: `implemented` + +Tiers: `premium`, `ultimate` + ### `counts.geo_event_log_max_id` Number of replication events on a Geo primary @@ -1042,7 +1200,7 @@ Tiers: `premium`, `ultimate` ### `counts.grafana_integrated_projects` -Missing description +Total Grafana integrations attached to projects [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180927_grafana_integrated_projects.yml) @@ -1300,7 +1458,7 @@ Count of groups with active integrations for HipChat Group: `group::ecosystem` -Status: `data_available` +Status: `removed` Tiers: `free`, `premium`, `ultimate` @@ -1516,7 +1674,7 @@ Count of active groups inheriting integrations for HipChat Group: `group::ecosystem` -Status: `data_available` +Status: `removed` Tiers: `free`, `premium`, `ultimate` @@ -2000,6 +2158,294 @@ Status: `data_available` Tiers: `free`, `premium`, `ultimate` +### `counts.in_product_marketing_email_create_0_cta_clicked` + +Total clicks on the create track's first email + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210510201919_in_product_marketing_email_create_0_cta_clicked.yml) + +Group: `group::activation` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.in_product_marketing_email_create_0_sent` + +Total sent emails of the create track's first email + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210510201537_in_product_marketing_email_create_0_sent.yml) + +Group: `group::activation` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.in_product_marketing_email_create_1_cta_clicked` + +Total clicks on the create track's second email + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210510202356_in_product_marketing_email_create_1_cta_clicked.yml) + +Group: `group::activation` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.in_product_marketing_email_create_1_sent` + +Total sent emails of the create track's second email + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210510202148_in_product_marketing_email_create_1_sent.yml) + +Group: `group::activation` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.in_product_marketing_email_create_2_cta_clicked` + +Total clicks on the create track's third email + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210510202724_in_product_marketing_email_create_2_cta_clicked.yml) + +Group: `group::activation` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.in_product_marketing_email_create_2_sent` + +Total sent emails of the create track's third email + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210510202604_in_product_marketing_email_create_2_sent.yml) + +Group: `group::activation` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.in_product_marketing_email_team_0_cta_clicked` + +Total clicks on the team track's first email + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210510203143_in_product_marketing_email_team_0_cta_clicked.yml) + +Group: `group::activation` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.in_product_marketing_email_team_0_sent` + +Total sent emails of the team track's first email + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210510203134_in_product_marketing_email_team_0_sent.yml) + +Group: `group::activation` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.in_product_marketing_email_team_1_cta_clicked` + +Total clicks on the team track's second email + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210510203203_in_product_marketing_email_team_1_cta_clicked.yml) + +Group: `group::activation` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.in_product_marketing_email_team_1_sent` + +Total sent emails of the team track's second email + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210510203153_in_product_marketing_email_team_1_sent.yml) + +Group: `group::activation` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.in_product_marketing_email_team_2_cta_clicked` + +Total clicks on the team track's third email + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210510203223_in_product_marketing_email_team_2_cta_clicked.yml) + +Group: `group::activation` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.in_product_marketing_email_team_2_sent` + +Total sent emails of the team track's third email + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210510203213_in_product_marketing_email_team_2_sent.yml) + +Group: `group::activation` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.in_product_marketing_email_trial_0_cta_clicked` + +Total clicks on the verify trial's first email + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210510203044_in_product_marketing_email_trial_0_cta_clicked.yml) + +Group: `group::activation` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.in_product_marketing_email_trial_0_sent` + +Total sent emails of the trial track's first email + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210510203035_in_product_marketing_email_trial_0_sent.yml) + +Group: `group::activation` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.in_product_marketing_email_trial_1_cta_clicked` + +Total clicks on the trial track's second email + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210510203104_in_product_marketing_email_trial_1_cta_clicked.yml) + +Group: `group::activation` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.in_product_marketing_email_trial_1_sent` + +Total sent emails of the trial track's second email + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210510203054_in_product_marketing_email_trial_1_sent.yml) + +Group: `group::activation` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.in_product_marketing_email_trial_2_cta_clicked` + +Total clicks on the trial track's third email + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210510203124_in_product_marketing_email_trial_2_cta_clicked.yml) + +Group: `group::activation` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.in_product_marketing_email_trial_2_sent` + +Total sent emails of the trial track's third email + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210510203114_in_product_marketing_email_trial_2_sent.yml) + +Group: `group::activation` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.in_product_marketing_email_verify_0_cta_clicked` + +Total clicks on the verify track's first email + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210510202943_in_product_marketing_email_verify_0_cta_clicked.yml) + +Group: `group::activation` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.in_product_marketing_email_verify_0_sent` + +Total sent emails of the verify track's first email + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210510202807_in_product_marketing_email_verify_0_sent.yml) + +Group: `group::activation` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.in_product_marketing_email_verify_1_cta_clicked` + +Total clicks on the verify track's second email + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210510203005_in_product_marketing_email_verify_1_cta_clicked.yml) + +Group: `group::activation` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.in_product_marketing_email_verify_1_sent` + +Total sent emails of the verify track's second email + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210510202955_in_product_marketing_email_verify_1_sent.yml) + +Group: `group::activation` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.in_product_marketing_email_verify_2_cta_clicked` + +Total clicks on the verify track's third email + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210510203025_in_product_marketing_email_verify_2_cta_clicked.yml) + +Group: `group::activation` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.in_product_marketing_email_verify_2_sent` + +Total sent emails of the verify track's third email + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210510203015_in_product_marketing_email_verify_2_sent.yml) + +Group: `group::activation` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + ### `counts.in_review_folder` Missing description @@ -2356,7 +2802,7 @@ Count of active instance-level integrations for HipChat Group: `group::ecosystem` -Status: `data_available` +Status: `removed` Tiers: `free`, `premium`, `ultimate` @@ -2758,7 +3204,7 @@ Tiers: `free` ### `counts.kubernetes_agent_gitops_sync` -Count of GitOps Sync events +Count of events when an Agent is asked to synchronize the manifests or its configuration [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216175328_kubernetes_agent_gitops_sync.yml) @@ -2768,9 +3214,21 @@ Status: `data_available` Tiers: `premium`, `ultimate` +### `counts.kubernetes_agent_k8s_api_proxy_request` + +Count of Kubernetes API proxy requests + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210505015532_kubernetes_agent_k8s_api_proxy_request.yml) + +Group: `group::configure` + +Status: `implemented` + +Tiers: `premium`, `ultimate` + ### `counts.kubernetes_agents` -Count of Kubernetes agents +Count of Kubernetes registered agents [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216175316_kubernetes_agents.yml) @@ -2890,7 +3348,7 @@ Tiers: `ultimate` ### `counts.merge_request_comment` -Missing description +Count of the number of merge request comments [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175041_merge_request_comment.yml) @@ -2898,11 +3356,11 @@ Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.merge_request_create` -Missing description +Count of the number of merge requests created [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175043_merge_request_create.yml) @@ -2910,11 +3368,11 @@ Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.merge_requests` -Missing description +Count of the number of merge requests [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175039_merge_requests.yml) @@ -2922,7 +3380,7 @@ Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.merged_merge_requests_using_approval_rules` @@ -3018,7 +3476,7 @@ Group: `group::monitor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.operations_dashboard_users_with_projects_added` @@ -3030,7 +3488,7 @@ Group: `group::monitor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.package_events_i_package_composer_delete_package` @@ -3608,6 +4066,42 @@ Status: `data_available` Tiers: `free` +### `counts.package_events_i_package_terraform_module_delete_package` + +Total count of Terraform Module packages delete events + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210410012200_package_events_i_package_terraform_module_delete_package.yml) + +Group: `group::configure` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.package_events_i_package_terraform_module_pull_package` + +Total count of pull Terraform Module packages events + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210410012202_package_events_i_package_terraform_module_pull_package.yml) + +Group: `group::configure` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts.package_events_i_package_terraform_module_push_package` + +Total count of push Terraform Module packages events + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210410012204_package_events_i_package_terraform_module_push_package.yml) + +Group: `group::configure` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + ### `counts.packages` Number of packages @@ -3672,9 +4166,9 @@ Tiers: `free`, `premium`, `ultimate` Missing description -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216174834_productivity_analytics_views.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216174834_productivity_analytics_views.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -3952,7 +4446,7 @@ Count of projects with active integrations for HipChat Group: `group::ecosystem` -Status: `data_available` +Status: `removed` Tiers: `free`, `premium`, `ultimate` @@ -4180,7 +4674,7 @@ Count of active projects inheriting integrations for HipChat Group: `group::ecosystem` -Status: `data_available` +Status: `removed` Tiers: `free`, `premium`, `ultimate` @@ -4560,13 +5054,13 @@ Tiers: `free`, `premium`, `ultimate` Projects with repository mirroring enabled -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216181920_projects_mirrored_with_pipelines_enabled.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216181920_projects_mirrored_with_pipelines_enabled.yml) -Group: `group::release` +Group: `group::continuous integration` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `counts.projects_mock_ci_active` @@ -4756,7 +5250,7 @@ Count of projects that have enabled the Alerts service Group: `group::health` -Status: `data_available` +Status: `removed` Tiers: `free`, `premium`, `ultimate` @@ -5038,15 +5532,15 @@ Tiers: `free` ### `counts.projects_with_repositories_enabled` -Missing description +Count of users creating projects that have a matching Git repository, result of a Git push action. -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216181959_projects_with_repositories_enabled.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216181959_projects_with_repositories_enabled.yml) Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `counts.projects_with_terraform_reports` @@ -5058,7 +5552,7 @@ Group: `group::configure` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_with_terraform_states` @@ -5070,7 +5564,7 @@ Group: `group::configure` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_with_tracing_enabled` @@ -5082,7 +5576,7 @@ Group: `group::monitor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.projects_youtrack_active` @@ -5098,27 +5592,27 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.protected_branches` -Missing description +Count of total protected branches -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182001_protected_branches.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216182001_protected_branches.yml) Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `counts.protected_branches_except_default` -Missing description +Count of branches that have been protected and are not the default branch [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182454_protected_branches_except_default.yml) -Group: `` +Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.releases` @@ -5134,7 +5628,7 @@ Tiers: `free` ### `counts.remote_mirrors` -Missing description +Count of total remote mirrors. Includes both push and pull mirrors [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182002_remote_mirrors.yml) @@ -5142,7 +5636,7 @@ Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.requirement_test_reports_ci` @@ -5290,7 +5784,7 @@ Tiers: `free`, `premium`, `ultimate` ### `counts.source_code_pushes` -Missing description +Count of total Git push operations [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182006_source_code_pushes.yml) @@ -5298,7 +5792,7 @@ Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.static_site_editor_commits` @@ -5398,7 +5892,7 @@ Tiers: `free` ### `counts.suggestions` -Missing description +Count of all comments that contain suggested changes [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175037_suggestions.yml) @@ -5406,19 +5900,19 @@ Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.template_repositories` -Missing description +Count of total repo templates used to aggregate all file templates -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182008_template_repositories.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216182008_template_repositories.yml) Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `counts.templates_asana_active` @@ -5632,7 +6126,7 @@ Count of active service templates for HipChat Group: `group::ecosystem` -Status: `data_available` +Status: `removed` Tiers: `free`, `premium`, `ultimate` @@ -5886,11 +6380,11 @@ Group: `group::configure` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.terraform_states` -Count of GitLab Managed Terraform States used +Count of GitLab Managed Terraform States [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175326_terraform_states.yml) @@ -5898,7 +6392,7 @@ Group: `group::configure` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts.todos` @@ -6092,6 +6586,42 @@ Status: `data_available` Tiers: `free` +### `counts_monthly.aggregated_metrics.code_review_category_monthly_active_users` + +Missing description + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210427102618_code_review_category_monthly_active_users.yml) + +Group: `` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts_monthly.aggregated_metrics.code_review_extension_category_monthly_active_users` + +Missing description + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210427103010_code_review_extension_category_monthly_active_users.yml) + +Group: `` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts_monthly.aggregated_metrics.code_review_group_monthly_active_users` + +Missing description + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210427103119_code_review_group_monthly_active_users.yml) + +Group: `` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + ### `counts_monthly.aggregated_metrics.compliance_features_track_unique_visits_union` Missing description @@ -6226,15 +6756,15 @@ Tiers: `free`, `premium`, `ultimate` ### `counts_monthly.projects_with_alerts_created` -Missing description +Monthly count of unique projects with HTTP alerting enabled [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216183159_projects_with_alerts_created.yml) -Group: `` +Group: `group::monitor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `counts_monthly.snippets` @@ -6260,6 +6790,42 @@ Status: `data_available` Tiers: `free` +### `counts_weekly.aggregated_metrics.code_review_category_monthly_active_users` + +Missing description + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210427103407_code_review_category_monthly_active_users.yml) + +Group: `` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts_weekly.aggregated_metrics.code_review_extension_category_monthly_active_users` + +Missing description + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210427103452_code_review_extension_category_monthly_active_users.yml) + +Group: `` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `counts_weekly.aggregated_metrics.code_review_group_monthly_active_users` + +Missing description + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210427103328_code_review_group_monthly_active_users.yml) + +Group: `` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + ### `counts_weekly.aggregated_metrics.compliance_features_track_unique_visits_union` Missing description @@ -6346,11 +6912,11 @@ Tiers: `free`, `premium`, `ultimate` ### `database.pg_system_id` -Missing description +TBD -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216183248_pg_system_id.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/settings/20210216183248_pg_system_id.yml) -Group: `` +Group: `group::distribution` Status: `data_available` @@ -6360,13 +6926,13 @@ Tiers: `free` The version of the PostgreSQL database. -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/license/20210216175609_version.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/settings/20210216175609_version.yml) Group: `group::distribution` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `dependency_proxy_enabled` @@ -6382,9 +6948,9 @@ Tiers: `free` ### `edition` -Edition of GitLab such as EE, CE, Bronze, Silver, Gold +Edition of GitLab such as EE or CE -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/license/20210216175604_edition.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/settings/20210216175604_edition.yml) Group: `group::distribution` @@ -6444,7 +7010,7 @@ Tiers: `free` Missing description -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216183241_filesystems.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/settings/20210216183241_filesystems.yml) Group: `` @@ -6506,11 +7072,11 @@ Whether shared runners is enabled [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/settings/20210204124902_gitlab_shared_runners_enabled.yml) -Group: `group::product intelligence` +Group: `group::runner` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `gitpod_enabled` @@ -6602,11 +7168,11 @@ Whether auto DevOps is enabled [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/settings/20210204124856_instance_auto_devops_enabled.yml) -Group: `group::product intelligence` +Group: `group::configure` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `ldap_enabled` @@ -6840,7 +7406,7 @@ Tiers: `free`, `premium`, `ultimate` What Object Storage provider has been configured for Artifacts -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180843_provider.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/settings/20210216180843_provider.yml) Group: `group::memory` @@ -6900,7 +7466,7 @@ Tiers: `free`, `premium`, `ultimate` What Object Storage provider has been configured for External Diffs -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180852_provider.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/settings/20210216180852_provider.yml) Group: `group::memory` @@ -6960,7 +7526,7 @@ Tiers: `free`, `premium`, `ultimate` What Object Storage provider has been configured for LFS -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180902_provider.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/settings/20210216180902_provider.yml) Group: `group::memory` @@ -7020,7 +7586,7 @@ Tiers: `free`, `premium`, `ultimate` What Object Storage provider has been configured for Packages -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180920_provider.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/settings/20210216180920_provider.yml) Group: `group::memory` @@ -7032,7 +7598,7 @@ Tiers: `free`, `premium`, `ultimate` Whether Object Storage is enabled for Uploads -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180903_enabled.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/settings/20210216180903_enabled.yml) Group: `group::memory` @@ -7080,7 +7646,7 @@ Tiers: `free`, `premium`, `ultimate` What Object Storage provider has been configured for Uploads -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180911_provider.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/settings/20210216180911_provider.yml) Group: `group::memory` @@ -7162,11 +7728,11 @@ Tiers: ### `redis_hll_counters.analytics.analytics_total_unique_counts_monthly` -Missing description +The number of unique users who visited any analytics feature by month [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175016_analytics_total_unique_counts_monthly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7174,11 +7740,11 @@ Tiers: `free` ### `redis_hll_counters.analytics.analytics_total_unique_counts_weekly` -Missing description +The number of unique users who visited any analytics feature by week -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216175014_analytics_total_unique_counts_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216175014_analytics_total_unique_counts_weekly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7186,11 +7752,11 @@ Tiers: ### `redis_hll_counters.analytics.g_analytics_contribution_monthly` -Missing description +Unique visitors to /groups/:group/-/contribution_analytics by month -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216174914_g_analytics_contribution_monthly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216174914_g_analytics_contribution_monthly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7198,11 +7764,11 @@ Tiers: `free` ### `redis_hll_counters.analytics.g_analytics_contribution_weekly` -Missing description +Unique visitors to /groups/:group/-/contribution_analytics by week [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216174912_g_analytics_contribution_weekly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7210,11 +7776,11 @@ Tiers: ### `redis_hll_counters.analytics.g_analytics_insights_monthly` -Missing description +Unique visitors to /groups/:group/-/insights/ by month -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216174918_g_analytics_insights_monthly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216174918_g_analytics_insights_monthly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7222,11 +7788,11 @@ Tiers: `free` ### `redis_hll_counters.analytics.g_analytics_insights_weekly` -Missing description +Unique visitors to /groups/:group/-/insights/ by week [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216174916_g_analytics_insights_weekly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7234,11 +7800,11 @@ Tiers: ### `redis_hll_counters.analytics.g_analytics_issues_monthly` -Missing description +Unique visitors to /groups/:group/-/issues_analytics by month -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216174921_g_analytics_issues_monthly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216174921_g_analytics_issues_monthly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7246,11 +7812,11 @@ Tiers: `free` ### `redis_hll_counters.analytics.g_analytics_issues_weekly` -Missing description +Unique visitors to /groups/:group/-/issues_analytics by week [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216174919_g_analytics_issues_weekly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7262,9 +7828,9 @@ Missing description [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175004_g_analytics_merge_request_monthly.yml) -Group: `group::analytics` +Group: `group::optimize` -Status: `data_available` +Status: `removed` Tiers: `free` @@ -7274,19 +7840,19 @@ Missing description [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216175002_g_analytics_merge_request_weekly.yml) -Group: `group::analytics` +Group: `group::optimize` -Status: `data_available` +Status: `removed` Tiers: ### `redis_hll_counters.analytics.g_analytics_productivity_monthly` -Missing description +Unique visitors to /groups/:group/-/analytics/productivity_analytics by month -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216174926_g_analytics_productivity_monthly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216174926_g_analytics_productivity_monthly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7294,11 +7860,11 @@ Tiers: `free` ### `redis_hll_counters.analytics.g_analytics_productivity_weekly` -Missing description +Unique visitors to /groups/:group/-/analytics/productivity_analytics by week [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216174923_g_analytics_productivity_weekly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7306,11 +7872,11 @@ Tiers: ### `redis_hll_counters.analytics.g_analytics_valuestream_monthly` -Missing description +Unique visitors to /groups/:group/-/analytics/value_stream_analytics by month -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216174929_g_analytics_valuestream_monthly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216174929_g_analytics_valuestream_monthly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7318,11 +7884,11 @@ Tiers: `free` ### `redis_hll_counters.analytics.g_analytics_valuestream_weekly` -Missing description +Unique visitors to /groups/:group/-/analytics/value_stream_analytics by week [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216174927_g_analytics_valuestream_weekly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7334,7 +7900,7 @@ Missing description [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216174956_i_analytics_cohorts_monthly.yml) -Group: `group::analytics` +Group: `group::utilization` Status: `data_available` @@ -7346,7 +7912,7 @@ Missing description [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216174955_i_analytics_cohorts_weekly.yml) -Group: `group::analytics` +Group: `group::utilization` Status: `data_available` @@ -7378,11 +7944,11 @@ Tiers: `premium`, `ultimate` ### `redis_hll_counters.analytics.i_analytics_dev_ops_score_monthly` -Missing description +Unique visitors to /admin/dev_ops_report by month [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175000_i_analytics_dev_ops_score_monthly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7390,11 +7956,11 @@ Tiers: `free` ### `redis_hll_counters.analytics.i_analytics_dev_ops_score_weekly` -Missing description +Unique visitors to /admin/dev_ops_report by week [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216174958_i_analytics_dev_ops_score_weekly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7402,11 +7968,11 @@ Tiers: ### `redis_hll_counters.analytics.i_analytics_instance_statistics_monthly` -Missing description +Unique visitors to /admin/usage_trends by month [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175012_i_analytics_instance_statistics_monthly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7414,11 +7980,11 @@ Tiers: `free` ### `redis_hll_counters.analytics.i_analytics_instance_statistics_weekly` -Missing description +Unique visitors to /admin/usage_trends by week -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216175010_i_analytics_instance_statistics_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216175010_i_analytics_instance_statistics_weekly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7426,11 +7992,11 @@ Tiers: ### `redis_hll_counters.analytics.p_analytics_code_reviews_monthly` -Missing description +Unique visitors to /:group/:project/-/analytics/code_reviews by month -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216174937_p_analytics_code_reviews_monthly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216174937_p_analytics_code_reviews_monthly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7438,11 +8004,11 @@ Tiers: `free` ### `redis_hll_counters.analytics.p_analytics_code_reviews_weekly` -Missing description +Unique visitors to /:group/:project/-/analytics/code_reviews by week [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216174935_p_analytics_code_reviews_weekly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7450,11 +8016,11 @@ Tiers: ### `redis_hll_counters.analytics.p_analytics_insights_monthly` -Missing description +Unique visitors to /:group/:project/insights/ by month -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216174945_p_analytics_insights_monthly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216174945_p_analytics_insights_monthly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7462,11 +8028,11 @@ Tiers: `free` ### `redis_hll_counters.analytics.p_analytics_insights_weekly` -Missing description +Unique visitors to /:group/:project/insights/ by week [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216174943_p_analytics_insights_weekly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7474,11 +8040,11 @@ Tiers: ### `redis_hll_counters.analytics.p_analytics_issues_monthly` -Missing description +Unique visitors to /:group/:project/-/analytics/issues_analytics by week -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216174949_p_analytics_issues_monthly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216174949_p_analytics_issues_monthly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7486,11 +8052,11 @@ Tiers: `free` ### `redis_hll_counters.analytics.p_analytics_issues_weekly` -Missing description +Unique visitors to /:group/:project/-/analytics/issues_analytics by week [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216174947_p_analytics_issues_weekly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7498,11 +8064,11 @@ Tiers: ### `redis_hll_counters.analytics.p_analytics_merge_request_monthly` -Missing description +Unique visitors to /:group/:project/-/analytics/merge_request_analytics by month -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175008_p_analytics_merge_request_monthly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216175008_p_analytics_merge_request_monthly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7510,11 +8076,11 @@ Tiers: `free` ### `redis_hll_counters.analytics.p_analytics_merge_request_weekly` -Missing description +Unique visitors to /:group/:project/-/analytics/merge_request_analytics by week [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216175006_p_analytics_merge_request_weekly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7522,11 +8088,11 @@ Tiers: ### `redis_hll_counters.analytics.p_analytics_pipelines_monthly` -Missing description +Unique visitors to /groups/:group/-/analytics/ci_cd by month [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216174933_p_analytics_pipelines_monthly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7534,11 +8100,11 @@ Tiers: `free` ### `redis_hll_counters.analytics.p_analytics_pipelines_weekly` -Missing description +Unique visitors to /groups/:group/-/analytics/ci_cd by week [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216174931_p_analytics_pipelines_weekly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7546,11 +8112,11 @@ Tiers: ### `redis_hll_counters.analytics.p_analytics_repo_monthly` -Missing description +Unique visitors to /:group/:project/-/graphs/master/charts by month -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216174953_p_analytics_repo_monthly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216174953_p_analytics_repo_monthly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7558,11 +8124,11 @@ Tiers: `free` ### `redis_hll_counters.analytics.p_analytics_repo_weekly` -Missing description +Unique visitors to /:group/:project/-/graphs/master/charts by week [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216174951_p_analytics_repo_weekly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7570,11 +8136,11 @@ Tiers: ### `redis_hll_counters.analytics.p_analytics_valuestream_monthly` -Missing description +Unique visitors to /:group/:project/-/value_stream_analytics by month [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216174941_p_analytics_valuestream_monthly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` @@ -7582,27 +8148,51 @@ Tiers: `free` ### `redis_hll_counters.analytics.p_analytics_valuestream_weekly` -Missing description +Unique visitors to /:group/:project/-/value_stream_analytics by week [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216174939_p_analytics_valuestream_weekly.yml) -Group: `group::analytics` +Group: `group::optimize` Status: `data_available` Tiers: +### `redis_hll_counters.analytics.users_viewing_analytics_group_devops_adoption_monthly` + +Counts visits to DevOps Adoption page per month + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210419105414_users_viewing_analytics_group_devops_adoption_monthly.yml) + +Group: `group::optimize` + +Status: `implemented` + +Tiers: `premium`, `ultimate` + +### `redis_hll_counters.analytics.users_viewing_analytics_group_devops_adoption_weekly` + +Counts visits to DevOps Adoption page per week + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210419105408_users_viewing_analytics_group_devops_adoption_weekly.yml) + +Group: `group::optimize` + +Status: `implemented` + +Tiers: `premium`, `ultimate` + ### `redis_hll_counters.ci_secrets_management.i_ci_secrets_management_vault_build_created_monthly` -Missing description +Monthly active users creating pipelines that that have the Vault JWT with it.' -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184251_i_ci_secrets_management_vault_build_created_monthly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216184251_i_ci_secrets_management_vault_build_created_monthly.yml) -Group: `` +Group: `group::configure` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `redis_hll_counters.ci_secrets_management.i_ci_secrets_management_vault_build_created_weekly` @@ -7642,39 +8232,39 @@ Tiers: ### `redis_hll_counters.ci_templates.p_ci_templates_5_min_production_app_monthly` -Missing description +Number of projects using 5 min production app CI template in last 7 days. [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184517_p_ci_templates_5_min_production_app_monthly.yml) -Group: `` +Group: `group::5-min-app` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ci_templates.p_ci_templates_5_min_production_app_weekly` -Missing description +Number of projects using 5 min production app CI template in last 7 days. -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184515_p_ci_templates_5_min_production_app_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184515_p_ci_templates_5_min_production_app_weekly.yml) -Group: `` +Group: `group::5-min-app` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ci_templates.p_ci_templates_auto_devops_build_monthly` -Missing description +Count of pipelines using the Auto Build template [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184534_p_ci_templates_auto_devops_build_monthly.yml) -Group: `` +Group: `group::configure` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ci_templates.p_ci_templates_auto_devops_build_weekly` @@ -7690,15 +8280,15 @@ Tiers: ### `redis_hll_counters.ci_templates.p_ci_templates_auto_devops_deploy_latest_monthly` -Missing description +Count of pipelines using the latest Auto Deploy template [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184542_p_ci_templates_auto_devops_deploy_latest_monthly.yml) -Group: `` +Group: `group::configure` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ci_templates.p_ci_templates_auto_devops_deploy_latest_weekly` @@ -7714,15 +8304,15 @@ Tiers: ### `redis_hll_counters.ci_templates.p_ci_templates_auto_devops_deploy_monthly` -Missing description +Count of pipelines using the stable Auto Deploy template [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184538_p_ci_templates_auto_devops_deploy_monthly.yml) -Group: `` +Group: `group::configure` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ci_templates.p_ci_templates_auto_devops_deploy_weekly` @@ -7738,15 +8328,15 @@ Tiers: ### `redis_hll_counters.ci_templates.p_ci_templates_auto_devops_monthly` -Missing description +Count of pipelines using the Auto DevOps template [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184523_p_ci_templates_auto_devops_monthly.yml) -Group: `` +Group: `group::configure` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ci_templates.p_ci_templates_auto_devops_weekly` @@ -7762,63 +8352,63 @@ Tiers: ### `redis_hll_counters.ci_templates.p_ci_templates_aws_cf_deploy_ec2_monthly` -Missing description +Count of projects using `AWS/CF-Provision-and-Deploy-EC2.gitlab-ci.yml` template in last 28 days. [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184526_p_ci_templates_aws_cf_deploy_ec2_monthly.yml) -Group: `` +Group: `group::release` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ci_templates.p_ci_templates_aws_cf_deploy_ec2_weekly` -Missing description +Count of projects using `AWS/CF-Provision-and-Deploy-EC2.gitlab-ci.yml` template in last 7 days. -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184524_p_ci_templates_aws_cf_deploy_ec2_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184524_p_ci_templates_aws_cf_deploy_ec2_weekly.yml) -Group: `` +Group: `group::release` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ci_templates.p_ci_templates_aws_deploy_ecs_monthly` -Missing description +Count of projects using `AWS/Deploy-ECS.gitlab-ci.yml` template in last 28 days. [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184530_p_ci_templates_aws_deploy_ecs_monthly.yml) -Group: `` +Group: `group::release` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ci_templates.p_ci_templates_aws_deploy_ecs_weekly` -Missing description +Count of projects using `AWS/Deploy-ECS.gitlab-ci.yml` template in last 7 days. -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184528_p_ci_templates_aws_deploy_ecs_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184528_p_ci_templates_aws_deploy_ecs_weekly.yml) -Group: `` +Group: `group::release` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ci_templates.p_ci_templates_implicit_auto_devops_build_monthly` -Missing description +Count of pipelines with implicit Auto Build runs [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184502_p_ci_templates_implicit_auto_devops_build_monthly.yml) -Group: `` +Group: `group::configure` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ci_templates.p_ci_templates_implicit_auto_devops_build_weekly` @@ -7834,15 +8424,15 @@ Tiers: ### `redis_hll_counters.ci_templates.p_ci_templates_implicit_auto_devops_deploy_monthly` -Missing description +Count of pipelines with implicit Auto Deploy runs [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184506_p_ci_templates_implicit_auto_devops_deploy_monthly.yml) -Group: `` +Group: `group::configure` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ci_templates.p_ci_templates_implicit_auto_devops_deploy_weekly` @@ -7858,15 +8448,15 @@ Tiers: ### `redis_hll_counters.ci_templates.p_ci_templates_implicit_auto_devops_monthly` -Missing description +Count of pipelines with implicit Auto DevOps runs [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184458_p_ci_templates_implicit_auto_devops_monthly.yml) -Group: `` +Group: `group::configure` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ci_templates.p_ci_templates_implicit_auto_devops_weekly` @@ -7978,15 +8568,15 @@ Tiers: ### `redis_hll_counters.ci_templates.p_ci_templates_terraform_base_latest_monthly` -Missing description +Count of pipelines that include the terraform base template from GitLab [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184555_p_ci_templates_terraform_base_latest_monthly.yml) -Group: `` +Group: `group::configure` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.ci_templates.p_ci_templates_terraform_base_latest_weekly` @@ -8002,79 +8592,343 @@ Tiers: ### `redis_hll_counters.code_review.code_review_total_unique_counts_monthly` -Missing description +Count of unique users per month who interact with a merge request [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184454_code_review_total_unique_counts_monthly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.code_review_total_unique_counts_weekly` -Missing description +Count of unique users per week who interact with a merge request -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184452_code_review_total_unique_counts_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184452_code_review_total_unique_counts_weekly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.code_review.i_code_review_click_file_browser_setting_monthly` + +Count of users clicking merge request file browser setting + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210421145818_i_code_review_click_file_browser_setting_monthly.yml) + +Group: `group::code review` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.code_review.i_code_review_click_file_browser_setting_weekly` + +Count of users with merge request file list setting + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210421145814_i_code_review_click_file_browser_setting_weekly.yml) + +Group: `group::code review` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.code_review.i_code_review_click_single_file_mode_setting_monthly` + +Count of users clicking single file mode setting + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210421144352_i_code_review_click_single_file_mode_setting_monthly.yml) + +Group: `group::code review` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.code_review.i_code_review_click_single_file_mode_setting_weekly` + +Count of users clicking single file mode setting + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210421144349_i_code_review_click_single_file_mode_setting_weekly.yml) + +Group: `group::code review` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.code_review.i_code_review_click_whitespace_setting_monthly` + +Count of users clicking merge request whitespae setting + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210421145945_i_code_review_click_whitespace_setting_monthly.yml) + +Group: `group::code review` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.code_review.i_code_review_click_whitespace_setting_weekly` + +Count of users clicking merge request whitespae setting + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210421145942_i_code_review_click_whitespace_setting_weekly.yml) + +Group: `group::code review` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.code_review.i_code_review_diff_hide_whitespace_monthly` + +Count of users with show whitespace disabled + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210422102010_i_code_review_diff_hide_whitespace_monthly.yml) + +Group: `group::code review` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.code_review.i_code_review_diff_hide_whitespace_weekly` + +Count of users with show whitespace disabled + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210422102007_i_code_review_diff_hide_whitespace_weekly.yml) + +Group: `group::code review` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.code_review.i_code_review_diff_multiple_files_monthly` + +Count of users with single mode disabled + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210422102202_i_code_review_diff_multiple_files_monthly.yml) + +Group: `group::code review` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.code_review.i_code_review_diff_multiple_files_weekly` + +Count of users with single mode disabled + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210422102159_i_code_review_diff_multiple_files_weekly.yml) + +Group: `group::code review` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.code_review.i_code_review_diff_show_whitespace_monthly` + +Count of users with show whitespace enabled + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210422101928_i_code_review_diff_show_whitespace_monthly.yml) + +Group: `group::code review` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.code_review.i_code_review_diff_show_whitespace_weekly` + +Count of users with show whitespace enabled + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210422101925_i_code_review_diff_show_whitespace_weekly.yml) + +Group: `group::code review` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.code_review.i_code_review_diff_single_file_monthly` + +Count of users with single file mode enabled + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210422102121_i_code_review_diff_single_file_monthly.yml) + +Group: `group::code review` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.code_review.i_code_review_diff_single_file_weekly` + +Count of users with single file mode enabled + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210422102118_i_code_review_diff_single_file_weekly.yml) + +Group: `group::code review` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.code_review.i_code_review_diff_view_inline_monthly` + +Count of users with merge request view type as inline + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210422101516_i_code_review_diff_view_inline_monthly.yml) + +Group: `group::code review` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.code_review.i_code_review_diff_view_inline_weekly` + +Count of users with merge request view type as inline + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210422101512_i_code_review_diff_view_inline_weekly.yml) + +Group: `group::code review` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.code_review.i_code_review_diff_view_parallel_monthly` + +Count of users with merge request view type as parallel + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210422101613_i_code_review_diff_view_parallel_monthly.yml) + +Group: `group::code review` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.code_review.i_code_review_diff_view_parallel_weekly` + +Count of users with merge request view type as parallel + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210422101609_i_code_review_diff_view_parallel_weekly.yml) + +Group: `group::code review` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_edit_mr_desc_monthly` -Missing description +Count of unique users per month who edit the description of a merge request [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184342_i_code_review_edit_mr_desc_monthly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_edit_mr_desc_weekly` -Missing description +Count of unique users per week who edit the description of a merge request -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184340_i_code_review_edit_mr_desc_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184340_i_code_review_edit_mr_desc_weekly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_edit_mr_title_monthly` -Missing description +Count of unique users per month who edit the title of a merge request [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184338_i_code_review_edit_mr_title_monthly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_edit_mr_title_weekly` -Missing description +Count of unique users per week who edit the title of a merge request -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184336_i_code_review_edit_mr_title_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184336_i_code_review_edit_mr_title_weekly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.code_review.i_code_review_file_browser_list_view_monthly` + +Count of users with merge request file list setting + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210422101852_i_code_review_file_browser_list_view_monthly.yml) + +Group: `group::code review` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.code_review.i_code_review_file_browser_list_view_weekly` + +Count of users with merge request file list setting + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210422101849_i_code_review_file_browser_list_view_weekly.yml) + +Group: `group::code review` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.code_review.i_code_review_file_browser_tree_view_monthly` + +Count of users with merge request file tree setting + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210422101753_i_code_review_file_browser_tree_view_monthly.yml) + +Group: `group::code review` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.code_review.i_code_review_file_browser_tree_view_weekly` + +Count of users with merge request file tree setting + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210422101750_i_code_review_file_browser_tree_view_weekly.yml) + +Group: `group::code review` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_mr_diffs_monthly` -Count of unique merge requests per week|month with diffs viewed +Count of unique merge requests per month with diffs viewed [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175120_i_code_review_mr_diffs_monthly.yml) @@ -8082,23 +8936,23 @@ Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_mr_diffs_weekly` -Count of unique merge requests per week|month with diffs viewed +Count of unique merge requests per week with diffs viewed -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216175118_i_code_review_mr_diffs_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216175118_i_code_review_mr_diffs_weekly.yml) Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_mr_single_file_diffs_monthly` -Count of unique merge requests per week|month with diffs viewed file by file +Count of unique merge requests per month with diffs viewed file by file [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175128_i_code_review_mr_single_file_diffs_monthly.yml) @@ -8106,19 +8960,19 @@ Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_mr_single_file_diffs_weekly` -Count of unique merge requests per week|month with diffs viewed file by file +Count of unique merge requests per week with diffs viewed file by file -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216175126_i_code_review_mr_single_file_diffs_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216175126_i_code_review_mr_single_file_diffs_weekly.yml) Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_add_suggestion_monthly` @@ -8130,19 +8984,19 @@ Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_add_suggestion_weekly` Count of unique users per week who added a suggestion -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216175158_i_code_review_user_add_suggestion_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216175158_i_code_review_user_add_suggestion_weekly.yml) Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_apply_suggestion_monthly` @@ -8154,139 +9008,139 @@ Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_apply_suggestion_weekly` Count of unique users per week who applied a suggestion -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216175201_i_code_review_user_apply_suggestion_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216175201_i_code_review_user_apply_suggestion_weekly.yml) Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_approval_rule_added_monthly` -Missing description +Count of unique users per month who add an approval rule to a merge request [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184434_i_code_review_user_approval_rule_added_monthly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_approval_rule_added_weekly` -Missing description +Count of unique users per week who add an approval rule to a merge request -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184432_i_code_review_user_approval_rule_added_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184432_i_code_review_user_approval_rule_added_weekly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_approval_rule_deleted_monthly` -Missing description +Count of unique users per month who delete an approval rule to a merge request [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184438_i_code_review_user_approval_rule_deleted_monthly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_approval_rule_deleted_weekly` -Missing description +Count of unique users per week who delete an approval rule to a merge request -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184436_i_code_review_user_approval_rule_deleted_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184436_i_code_review_user_approval_rule_deleted_weekly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_approval_rule_edited_monthly` -Missing description +Count of unique users per month who delete an approval rule to a merge request [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184442_i_code_review_user_approval_rule_edited_monthly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_approval_rule_edited_weekly` -Missing description +Count of unique users per week who edit an approval rule to a merge request -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184440_i_code_review_user_approval_rule_edited_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184440_i_code_review_user_approval_rule_edited_weekly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_approve_mr_monthly` -Missing description +Count of unique users per month who approve a merge request [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184322_i_code_review_user_approve_mr_monthly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_approve_mr_weekly` -Missing description +Count of unique users per week who approve a merge request -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184320_i_code_review_user_approve_mr_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184320_i_code_review_user_approve_mr_weekly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_assigned_monthly` -Missing description +Count of unique users per month who are assigned to a merge request [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184418_i_code_review_user_assigned_monthly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_assigned_weekly` -Missing description +Count of unique users per week who are assigned to a merge request -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184416_i_code_review_user_assigned_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184416_i_code_review_user_assigned_weekly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_assignees_changed_monthly` @@ -8314,7 +9168,7 @@ Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_close_mr_monthly` -Count of unique users per week|month who closed a MR +Count of unique users per month who closed a MR [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175136_i_code_review_user_close_mr_monthly.yml) @@ -8322,23 +9176,23 @@ Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_close_mr_weekly` -Count of unique users per week|month who closed a MR +Count of unique users per week who closed a MR -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216175134_i_code_review_user_close_mr_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216175134_i_code_review_user_close_mr_weekly.yml) Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_create_mr_comment_monthly` -Count of unique users per week|month who commented on a MR +Count of unique users per month who commented on a MR [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175148_i_code_review_user_create_mr_comment_monthly.yml) @@ -8346,47 +9200,47 @@ Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_create_mr_comment_weekly` -Count of unique users per week|month who commented on a MR +Count of unique users per week who commented on a MR -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216175146_i_code_review_user_create_mr_comment_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216175146_i_code_review_user_create_mr_comment_weekly.yml) Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_create_mr_from_issue_monthly` -Missing description +Count of unique users per month who create a merge request from an issue [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184450_i_code_review_user_create_mr_from_issue_monthly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_create_mr_from_issue_weekly` -Missing description +Count of unique users per week who create a merge request from an issue -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184448_i_code_review_user_create_mr_from_issue_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184448_i_code_review_user_create_mr_from_issue_weekly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_create_mr_monthly` -Count of unique users per week|month who created a MR +Count of unique users per month who created a MR [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175132_i_code_review_user_create_mr_monthly.yml) @@ -8394,71 +9248,71 @@ Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_create_mr_weekly` -Count of unique users per week|month who created a MR +Count of unique users per week who created a MR -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216175130_i_code_review_user_create_mr_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216175130_i_code_review_user_create_mr_weekly.yml) Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_create_multiline_mr_comment_monthly` -Missing description +Count of unique users per month who create a multiline comment in a merge request [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184401_i_code_review_user_create_multiline_mr_comment_monthly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_create_multiline_mr_comment_weekly` -Missing description +Count of unique users per week who create a multiline comment in a merge request -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184359_i_code_review_user_create_multiline_mr_comment_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184359_i_code_review_user_create_multiline_mr_comment_weekly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_create_review_note_monthly` -Missing description +Count of unique users per month who create a note as part of a merge request review [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184353_i_code_review_user_create_review_note_monthly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_create_review_note_weekly` -Missing description +Count of unique users per week who create a note as part of a merge request review -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184351_i_code_review_user_create_review_note_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184351_i_code_review_user_create_review_note_weekly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_edit_mr_comment_monthly` -Count of unique users per week|month who edited a comment on a MR +Count of unique users per month who edited a comment on a MR [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175152_i_code_review_user_edit_mr_comment_monthly.yml) @@ -8466,43 +9320,43 @@ Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_edit_mr_comment_weekly` -Count of unique users per week|month who edited a comment on a MR +Count of unique users per week who edited a comment on a MR -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216175150_i_code_review_user_edit_mr_comment_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216175150_i_code_review_user_edit_mr_comment_weekly.yml) Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_edit_multiline_mr_comment_monthly` -Missing description +Count of unique users per week who edit a multiline comment in a merge request [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184405_i_code_review_user_edit_multiline_mr_comment_monthly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_edit_multiline_mr_comment_weekly` -Missing description +Count of unique users per week who edit a multiline comment in a merge request -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184403_i_code_review_user_edit_multiline_mr_comment_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184403_i_code_review_user_edit_multiline_mr_comment_weekly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_labels_changed_monthly` @@ -8530,31 +9384,31 @@ Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_marked_as_draft_monthly` -Missing description +Count of unique users per month who mark a merge request as a draft [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184422_i_code_review_user_marked_as_draft_monthly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_marked_as_draft_weekly` -Missing description +Count of unique users per week who mark a merge request as a draft -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184420_i_code_review_user_marked_as_draft_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184420_i_code_review_user_marked_as_draft_weekly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_merge_mr_monthly` -Count of unique users per week|month who merged a MR +Count of unique users per month who merged a MR [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175144_i_code_review_user_merge_mr_monthly.yml) @@ -8562,19 +9416,19 @@ Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_merge_mr_weekly` -Count of unique users per week|month who merged a MR +Count of unique users per week who merged a MR -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216175142_i_code_review_user_merge_mr_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216175142_i_code_review_user_merge_mr_weekly.yml) Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_milestone_changed_monthly` @@ -8650,31 +9504,31 @@ Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_publish_review_monthly` -Missing description +Count of unique users per month who publish their review as part of a merge request review [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184357_i_code_review_user_publish_review_monthly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_publish_review_weekly` -Missing description +Count of unique users per week who publish their review as part of a merge request review -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184355_i_code_review_user_publish_review_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184355_i_code_review_user_publish_review_weekly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_remove_mr_comment_monthly` -Count of unique users per week|month who removed a comment on a MR +Count of unique users per month who removed a comment on a MR [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175156_i_code_review_user_remove_mr_comment_monthly.yml) @@ -8682,47 +9536,47 @@ Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_remove_mr_comment_weekly` -Count of unique users per week|month who removed a comment on a MR +Count of unique users per month who removed a comment on a MR -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216175154_i_code_review_user_remove_mr_comment_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216175154_i_code_review_user_remove_mr_comment_weekly.yml) Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_remove_multiline_mr_comment_monthly` -Missing description +Count of unique users per month who remove a multiline comment in a merge request [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184409_i_code_review_user_remove_multiline_mr_comment_monthly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_remove_multiline_mr_comment_weekly` -Missing description +Count of unique users per week who remove a multiline comment in a merge request -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184407_i_code_review_user_remove_multiline_mr_comment_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184407_i_code_review_user_remove_multiline_mr_comment_weekly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_reopen_mr_monthly` -Count of unique users per week|month who reopened a MR +Count of unique users per month who reopened a MR [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175140_i_code_review_user_reopen_mr_monthly.yml) @@ -8730,67 +9584,67 @@ Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_reopen_mr_weekly` -Count of unique users per week|month who reopened a MR +Count of unique users per week who reopened a MR -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216175138_i_code_review_user_reopen_mr_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216175138_i_code_review_user_reopen_mr_weekly.yml) Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_resolve_thread_monthly` -Missing description +Count of unique users per month who resolve a thread in a merge request [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184330_i_code_review_user_resolve_thread_monthly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_resolve_thread_weekly` -Missing description +Count of unique users per week who resolve a thread in a merge request -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184328_i_code_review_user_resolve_thread_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184328_i_code_review_user_resolve_thread_weekly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_review_requested_monthly` -Missing description +Count of unique users per month who request a review of a merge request [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184430_i_code_review_user_review_requested_monthly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_review_requested_weekly` -Missing description +Count of unique users per week who request a review of a merge request -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184428_i_code_review_user_review_requested_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184428_i_code_review_user_review_requested_weekly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_reviewers_changed_monthly` @@ -8818,7 +9672,7 @@ Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_single_file_diffs_monthly` -Count of unique users per week|month with diffs viewed file by file +Count of unique users per month with diffs viewed file by file [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175124_i_code_review_user_single_file_diffs_monthly.yml) @@ -8826,19 +9680,19 @@ Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_single_file_diffs_weekly` -Count of unique users per week|month with diffs viewed file by file +Count of unique users per week with diffs viewed file by file -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216175122_i_code_review_user_single_file_diffs_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216175122_i_code_review_user_single_file_diffs_weekly.yml) Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_time_estimate_changed_monthly` @@ -8890,123 +9744,123 @@ Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_toggled_task_item_status_monthly` -Missing description +Count of unique users per month who toggled a task item in a merge request [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184312_i_code_review_user_toggled_task_item_status_monthly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_toggled_task_item_status_weekly` -Missing description +Count of unique users per week who toggled a task item in a merge request -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184310_i_code_review_user_toggled_task_item_status_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184310_i_code_review_user_toggled_task_item_status_weekly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_unapprove_mr_monthly` -Missing description +Count of unique users per month who unapprove a merge request [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184326_i_code_review_user_unapprove_mr_monthly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_unapprove_mr_weekly` -Missing description +Count of unique users per week who unapprove a merge request -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184324_i_code_review_user_unapprove_mr_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184324_i_code_review_user_unapprove_mr_weekly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_unmarked_as_draft_monthly` -Missing description +Count of unique users per month who unmark a merge request as a draft [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184426_i_code_review_user_unmarked_as_draft_monthly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_unmarked_as_draft_weekly` -Missing description +Count of unique users per week who unmark a merge request as a draft -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184424_i_code_review_user_unmarked_as_draft_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184424_i_code_review_user_unmarked_as_draft_weekly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_unresolve_thread_monthly` -Missing description +Count of unique users per month who unresolve a thread in a merge request [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184334_i_code_review_user_unresolve_thread_monthly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_unresolve_thread_weekly` -Missing description +Count of unique users per week who unresolve a thread in a merge request -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184332_i_code_review_user_unresolve_thread_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184332_i_code_review_user_unresolve_thread_weekly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_vs_code_api_request_monthly` -Missing description +Count of unique users per month who use GitLab Workflow for VS Code [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184446_i_code_review_user_vs_code_api_request_monthly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.code_review.i_code_review_user_vs_code_api_request_weekly` -Missing description +Count of unique users per week who use GitLab Workflow for VS Code -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184444_i_code_review_user_vs_code_api_request_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184444_i_code_review_user_vs_code_api_request_weekly.yml) -Group: `` +Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.compliance.a_compliance_audit_events_api_monthly` @@ -9464,6 +10318,30 @@ Status: `data_available` Tiers: +### `redis_hll_counters.deploy_token_packages.i_package_terraform_module_deploy_token_monthly` + +Number of distinct users authorized via deploy token creating Terraform Module packages in recent 28 days + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210410012206_i_package_terraform_module_deploy_token_monthly.yml) + +Group: `group::configure` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.deploy_token_packages.i_package_terraform_module_deploy_token_weekly` + +Number of distinct users authorized via deploy token creating Terraform Module packages in recent 7 days + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210410012207_i_package_terraform_module_deploy_token_weekly.yml) + +Group: `group::configure` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + ### `redis_hll_counters.ecosystem.ecosystem_total_unique_counts_monthly` Missing description @@ -9800,6 +10678,78 @@ Status: `data_available` Tiers: `free`, `premium`, `ultimate` +### `redis_hll_counters.epic_boards_usage.g_project_management_users_creating_epic_boards_monthly` + +Count of MAU creating epic boards + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210428072511_g_project_management_users_creating_epic_boards_monthly.yml) + +Group: `group::product planning` + +Status: `implemented` + +Tiers: `premium`, `ultimate` + +### `redis_hll_counters.epic_boards_usage.g_project_management_users_creating_epic_boards_weekly` + +Count of WAU creating epic boards + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210428072508_g_project_management_users_creating_epic_boards_weekly.yml) + +Group: `group::product planning` + +Status: `implemented` + +Tiers: `premium`, `ultimate` + +### `redis_hll_counters.epic_boards_usage.g_project_management_users_updating_epic_board_names_monthly` + +Count of MAU updating epic board names + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210428073607_g_project_management_users_updating_epic_board_names_monthly.yml) + +Group: `group::product planning` + +Status: `implemented` + +Tiers: `premium`, `ultimate` + +### `redis_hll_counters.epic_boards_usage.g_project_management_users_updating_epic_board_names_weekly` + +Count of WAU updating epic board names + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210428073604_g_project_management_users_updating_epic_board_names_weekly.yml) + +Group: `group::product planning` + +Status: `implemented` + +Tiers: `premium`, `ultimate` + +### `redis_hll_counters.epic_boards_usage.g_project_management_users_viewing_epic_boards_monthly` + +Count of MAU viewing epic boards + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210428073329_g_project_management_users_viewing_epic_boards_monthly.yml) + +Group: `group::product planning` + +Status: `implemented` + +Tiers: `premium`, `ultimate` + +### `redis_hll_counters.epic_boards_usage.g_project_management_users_viewing_epic_boards_weekly` + +Count of WAU viewing epic boards + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210428073327_g_project_management_users_viewing_epic_boards_weekly.yml) + +Group: `group::product planning` + +Status: `implemented` + +Tiers: `premium`, `ultimate` + ### `redis_hll_counters.epics_usage.epics_usage_total_unique_counts_monthly` Total monthly users count for epics_usage @@ -9872,6 +10822,30 @@ Status: `data_available` Tiers: `premium`, `ultimate` +### `redis_hll_counters.epics_usage.g_project_management_epic_cross_referenced_monthly` + +Count of MAU cross referencing epics + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210430174100_g_project_management_epic_cross_referenced_monthly.yml) + +Group: `group::product planning` + +Status: `implemented` + +Tiers: `premium`, `ultimate` + +### `redis_hll_counters.epics_usage.g_project_management_epic_cross_referenced_weekly` + +Counts of WAU cross referencing epics + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210430173650_g_project_management_epic_cross_referenced_weekly.yml) + +Group: `group::product planning` + +Status: `implemented` + +Tiers: `premium`, `ultimate` + ### `redis_hll_counters.epics_usage.g_project_management_epic_destroyed_monthly` Count of MAU destroying epics @@ -10040,6 +11014,30 @@ Status: `implemented` Tiers: `premium`, `ultimate` +### `redis_hll_counters.epics_usage.g_project_management_users_awarding_epic_emoji_monthly` + +Counts of MAU awarding emoji on epic + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210503011217_g_project_management_users_awarding_epic_emoji_monthly.yml) + +Group: `group::product planning` + +Status: `implemented` + +Tiers: `premium`, `ultimate` + +### `redis_hll_counters.epics_usage.g_project_management_users_awarding_epic_emoji_weekly` + +Counts of WAU awarding emoji on epic + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210503011355_g_project_management_users_awarding_epic_emoji_weekly.yml) + +Group: `group::product planning` + +Status: `implemented` + +Tiers: `premium`, `ultimate` + ### `redis_hll_counters.epics_usage.g_project_management_users_creating_epic_notes_monthly` Counts of MAU adding epic notes @@ -10088,6 +11086,30 @@ Status: `implemented` Tiers: `premium`, `ultimate` +### `redis_hll_counters.epics_usage.g_project_management_users_removing_epic_emoji_monthly` + +Counts of MAU removing emoji on epic + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210505071850_g_project_management_users_removing_epic_emoji_monthly.yml) + +Group: `group::product planning` + +Status: `implemented` + +Tiers: `premium`, `ultimate` + +### `redis_hll_counters.epics_usage.g_project_management_users_removing_epic_emoji_weekly` + +Counts of WAU removing emoji on epic + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210505071932_g_project_management_users_removing_epic_emoji_weekly.yml) + +Group: `group::product planning` + +Status: `implemented` + +Tiers: `premium`, `ultimate` + ### `redis_hll_counters.epics_usage.g_project_management_users_setting_epic_confidential_monthly` Count of MAU making epics confidential @@ -10280,6 +11302,30 @@ Status: `implemented` Tiers: `premium`, `ultimate` +### `redis_hll_counters.epics_usage.g_project_management_users_updating_epic_parent_monthly` + +Counts of MAU updating parent on epic + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210423011841_g_project_management_users_updating_epic_parent_monthly.yml) + +Group: `group::product planning` + +Status: `implemented` + +Tiers: `premium`, `ultimate` + +### `redis_hll_counters.epics_usage.g_project_management_users_updating_epic_parent_weekly` + +Counts of WAU updating parent on epic + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210423012053_g_project_management_users_updating_epic_parent_weekly.yml) + +Group: `group::product planning` + +Status: `implemented` + +Tiers: `premium`, `ultimate` + ### `redis_hll_counters.epics_usage.g_project_management_users_updating_epic_titles_monthly` Counts of MAU changing epic titles @@ -10472,30 +11518,6 @@ Status: `data_available` Tiers: -### `redis_hll_counters.incident_management.i_incident_management_oncall_notification_sent_monthly` - -Count of unique users to receive a notification while on-call - -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210405222005_i_incident_management_oncall_notification_sent_monthly.yml) - -Group: `group::monitor` - -Status: `implemented` - -Tiers: `premium`, `ultimate` - -### `redis_hll_counters.incident_management.i_incident_management_oncall_notification_sent_weekly` - -Count of unique users to receive a notification while on-call - -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210405220139_i_incident_management_oncall_notification_sent_weekly.yml) - -Group: `group::monitor` - -Status: `implemented` - -Tiers: `premium`, `ultimate` - ### `redis_hll_counters.incident_management.incident_management_alert_assigned_monthly` Missing description @@ -10880,6 +11902,30 @@ Status: `data_available` Tiers: +### `redis_hll_counters.incident_management_oncall.i_incident_management_oncall_notification_sent_monthly` + +Count of unique users to receive a notification while on-call + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210405222005_i_incident_management_oncall_notification_sent_monthly.yml) + +Group: `group::monitor` + +Status: `implemented` + +Tiers: `premium`, `ultimate` + +### `redis_hll_counters.incident_management_oncall.i_incident_management_oncall_notification_sent_weekly` + +Count of unique users to receive a notification while on-call + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210405220139_i_incident_management_oncall_notification_sent_weekly.yml) + +Group: `group::monitor` + +Status: `implemented` + +Tiers: `premium`, `ultimate` + ### `redis_hll_counters.issues_edit.g_project_management_issue_added_to_epic_monthly` Count of MAU adding an issue to an epic @@ -11744,6 +12790,30 @@ Status: `data_available` Tiers: `free`, `premium`, `ultimate` +### `redis_hll_counters.pipeline_authoring.pipeline_authoring_total_unique_counts_monthly` + +Missing description + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210427105033_pipeline_authoring_total_unique_counts_monthly.yml) + +Group: `` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.pipeline_authoring.pipeline_authoring_total_unique_counts_weekly` + +Missing description + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210427105030_pipeline_authoring_total_unique_counts_weekly.yml) + +Group: `` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + ### `redis_hll_counters.quickactions.i_quickactions_approve_monthly` Count of MAU using the `/approve` quick action @@ -13522,7 +14592,7 @@ Tiers: ### `redis_hll_counters.source_code.design_action_monthly` -Missing description +Count of total design actions (upload, delete, comment, reply) [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216182106_design_action_monthly.yml) @@ -13530,71 +14600,71 @@ Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.source_code.design_action_weekly` -Missing description +Count of total design actions (upload, delete, comment, reply) -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216182104_design_action_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216182104_design_action_weekly.yml) Group: `group::source code` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.source_code.git_write_action_monthly` -Missing description +Count of unique Git write actions [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184047_git_write_action_monthly.yml) -Group: `` +Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.source_code.git_write_action_weekly` -Missing description +Count of unique Git write actions -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216184045_git_write_action_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184045_git_write_action_weekly.yml) -Group: `` +Group: `group::source code` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.source_code.i_source_code_code_intelligence_monthly` -Missing description +Count of unique users who use code intelligence [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175117_i_source_code_code_intelligence_monthly.yml) -Group: `group::code review` +Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.source_code.i_source_code_code_intelligence_weekly` -Missing description +Count of unique users who use code intelligence -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216175114_i_source_code_code_intelligence_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216175114_i_source_code_code_intelligence_weekly.yml) -Group: `group::code review` +Group: `group::source code` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.source_code.merge_request_action_monthly` -Missing description +Count of unique users who perform an action on a merge request [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175113_merge_request_action_monthly.yml) @@ -13602,23 +14672,23 @@ Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.source_code.merge_request_action_weekly` -Missing description +Count of unique users who perform an action on a merge request -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216175111_merge_request_action_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216175111_merge_request_action_weekly.yml) Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.source_code.project_action_monthly` -Missing description +Count of unique actions done on projects and related resources (create, edit, delete, comment) [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216182109_project_action_monthly.yml) @@ -13626,23 +14696,23 @@ Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.source_code.project_action_weekly` -Missing description +Count of unique actions done on projects and related resources (create, edit, delete, comment) -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216182107_project_action_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216182107_project_action_weekly.yml) Group: `group::source code` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.source_code.wiki_action_monthly` -Missing description +Count of unique actions done on a wiki (create, edit, delete) [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216182102_wiki_action_monthly.yml) @@ -13650,31 +14720,31 @@ Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.source_code.wiki_action_weekly` -Missing description +Count of unique actions done on a wiki (create, edit, delete) -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_7d/20210216182100_wiki_action_weekly.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216182100_wiki_action_weekly.yml) Group: `group::source code` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.terraform.p_terraform_state_api_unique_users_monthly` -Missing description +Monthly active users of GitLab Managed Terraform states [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184259_p_terraform_state_api_unique_users_monthly.yml) -Group: `` +Group: `group::configure` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `redis_hll_counters.terraform.p_terraform_state_api_unique_users_weekly` @@ -14264,6 +15334,30 @@ Status: `data_available` Tiers: +### `redis_hll_counters.user_packages.i_package_terraform_module_user_monthly` + +Number of distinct users creating Terraform Module packages in recent 28 days + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210410012208_i_package_terraform_module_user_monthly.yml) + +Group: `group::configure` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + +### `redis_hll_counters.user_packages.i_package_terraform_module_user_weekly` + +Number of distinct users creating Terraform Module packages in recent 7 days + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210410012209_i_package_terraform_module_user_weekly.yml) + +Group: `group::configure` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + ### `redis_hll_counters.user_packages.user_packages_total_unique_counts_monthly` Missing description @@ -14360,6 +15454,18 @@ Status: `data_available` Tiers: `free`, `premium`, `ultimate` +### `settings.gitaly_apdex` + +Gitaly application performance + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/settings/20210321224827_gitaly_apdex.yml) + +Group: `group::gitaly` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + ### `settings.ldap_encrypted_secrets_enabled` Is encrypted LDAP secrets configured? @@ -14640,7 +15746,7 @@ Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.create.approval_project_rules` -Number of project approval rules +Total number of project approval rules [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216182030_approval_project_rules.yml) @@ -14648,47 +15754,47 @@ Group: `group::source code` Status: `data_available` -Tiers: +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage.create.approval_project_rules_with_exact_required_approvers` -Missing description +Number of approval rules with the exact number of required approvers. -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216183355_approval_project_rules_with_exact_required_approvers.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216183355_approval_project_rules_with_exact_required_approvers.yml) -Group: `` +Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage.create.approval_project_rules_with_less_approvers_than_required` -Missing description +Number of approval rules with fewer approvers than required. -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216183354_approval_project_rules_with_less_approvers_than_required.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216183354_approval_project_rules_with_less_approvers_than_required.yml) -Group: `` +Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage.create.approval_project_rules_with_more_approvers_than_required` -Missing description +Number of approval rules with more approvers than required. -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216183352_approval_project_rules_with_more_approvers_than_required.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216183352_approval_project_rules_with_more_approvers_than_required.yml) -Group: `` +Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage.create.approval_project_rules_with_target_branch` -Number of project approval rules with not default target branch +Number of project approval rules scoped to a specific repo branch. [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216182032_approval_project_rules_with_target_branch.yml) @@ -14696,11 +15802,11 @@ Group: `group::source code` Status: `data_available` -Tiers: +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage.create.deploy_keys` -Missing description +Count of users creating deploy keys. [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182010_deploy_keys.yml) @@ -14708,11 +15814,11 @@ Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.create.keys` -Missing description +Count of users creating regular keys. [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182012_keys.yml) @@ -14720,11 +15826,11 @@ Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.create.merge_requests` -Missing description +Count of the number of users creating merge requests [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175045_merge_requests.yml) @@ -14732,7 +15838,7 @@ Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.create.merge_requests_with_added_rules` @@ -14744,55 +15850,55 @@ Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage.create.merge_requests_with_optional_codeowners` -Missing description +Count of merge requests with optional codeowner approval rules [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216175049_merge_requests_with_optional_codeowners.yml) -Group: `group::code review` +Group: `group::source code` Status: `data_available` -Tiers: +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage.create.merge_requests_with_overridden_project_rules` -Missing description +Number of merge requests that have overridden rules created at the project level. -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216183339_merge_requests_with_overridden_project_rules.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216183339_merge_requests_with_overridden_project_rules.yml) -Group: `` +Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage.create.merge_requests_with_required_codeowners` -Missing description +Count of merge requests with required codeowner approval rules [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216175051_merge_requests_with_required_codeowners.yml) -Group: `group::code review` +Group: `group::source code` Status: `data_available` -Tiers: +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage.create.projects_enforcing_code_owner_approval` -Missing description +Count of users creating projects that require approval by code owners for code changes. -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182019_projects_enforcing_code_owner_approval.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216182019_projects_enforcing_code_owner_approval.yml) Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage.create.projects_imported_from_github` @@ -14808,7 +15914,7 @@ Tiers: `free` ### `usage_activity_by_stage.create.projects_with_disable_overriding_approvers_per_merge_request` -Missing description +Total count of projects that do not allow overriding approvers on discrete merge requests [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182014_projects_with_disable_overriding_approvers_per_merge_request.yml) @@ -14816,35 +15922,35 @@ Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.create.projects_with_repositories_enabled` -Missing description +Count of projects that have a matching Git repository, result of a Git push action -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182023_projects_with_repositories_enabled.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216182023_projects_with_repositories_enabled.yml) Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage.create.projects_with_sectional_code_owner_rules` -Missing description +Count of projects using code owners with code owners section feature -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182021_projects_with_sectional_code_owner_rules.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216182021_projects_with_sectional_code_owner_rules.yml) Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage.create.projects_without_disable_overriding_approvers_per_merge_request` -Missing description +Count of total projects that do not disable overriding approvers per discrete merge request [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182015_projects_without_disable_overriding_approvers_per_merge_request.yml) @@ -14852,23 +15958,23 @@ Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.create.protected_branches` -Missing description +Count of users creating projects with repositories making use of at least one protected branch. -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182025_protected_branches.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216182025_protected_branches.yml) Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage.create.remote_mirrors` -Missing description +Count of users creating projects with remote mirrors. [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182017_remote_mirrors.yml) @@ -14876,7 +15982,7 @@ Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.create.snippets` @@ -14892,7 +15998,7 @@ Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.create.suggestions` -Missing description +Count of unique users who create suggestions in merge request comments [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175053_suggestions.yml) @@ -14900,55 +16006,55 @@ Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.create.total_number_of_locked_files` -The total number of exclusive file locks (through the CLI) +The total number of files which have been locked via the GitLab UI -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182028_total_number_of_locked_files.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216182028_total_number_of_locked_files.yml) Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage.create.total_number_of_path_locks` -The total number of default branch locks done through the GitLab UI +Number of paths/directories manually locked through the UI -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216182027_total_number_of_path_locks.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216182027_total_number_of_path_locks.yml) Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage.create.users_using_lfs_locks` -Missing description +Number of unique users who have locked files or directories using LFS via the command line -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216183346_users_using_lfs_locks.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216183346_users_using_lfs_locks.yml) -Group: `` +Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage.create.users_using_path_locks` -Missing description +Number of users who have manually locked paths/directories through the UI -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216183344_users_using_path_locks.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216183344_users_using_path_locks.yml) -Group: `` +Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage.enablement.counts.geo_node_usage.git_fetch_event_count_weekly` @@ -14962,6 +16068,18 @@ Status: `data_available` Tiers: `premium`, `ultimate` +### `usage_activity_by_stage.enablement.geo_secondary_web_oauth_users` + +Missing description + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210427212450_geo_secondary_web_oauth_users.yml) + +Group: `` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` + ### `usage_activity_by_stage.manage.bulk_imports.gitlab` Distinct count of users that triggered an import using the Group Migration tool @@ -14986,6 +16104,18 @@ Status: `data_available` Tiers: `free` +### `usage_activity_by_stage.manage.custom_compliance_frameworks` + +Total count of all custom compliance framework labels + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210430081610_custom_compliance_frameworks.yml) + +Group: `compliance` + +Status: `implemented` + +Tiers: `premium`, `ultimate` + ### `usage_activity_by_stage.manage.events` Missing description @@ -15552,7 +16682,7 @@ Tiers: ### `usage_activity_by_stage.monitor.clusters` -Total GitLab Managed clusters both enabled and disabled +Users creating clusters. [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180945_clusters.yml) @@ -15560,11 +16690,11 @@ Group: `group::monitor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.monitor.clusters_applications_prometheus` -Total GitLab Managed clusters with Prometheus enabled +Users creating clusters with Prometheus enabled. [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216180947_clusters_applications_prometheus.yml) @@ -15572,7 +16702,7 @@ Group: `group::monitor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.monitor.operations_dashboard_default_dashboard` @@ -15584,7 +16714,7 @@ Group: `group::monitor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium` ### `usage_activity_by_stage.monitor.operations_dashboard_users_with_projects_added` @@ -15596,7 +16726,7 @@ Group: `group::monitor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.monitor.projects_incident_sla_enabled` @@ -15626,6 +16756,8 @@ Tiers: `free` Histogram (buckets 1 to 100) of projects with at least 1 enabled integration. +[Object JSON schema](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/objects_schemas/projects_with_enabled_alert_integrations_histogram.json) + [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210309165717_projects_with_enabled_alert_integrations_histogram.yml) Group: `group::monitor` @@ -15668,7 +16800,7 @@ Group: `group::monitor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.package.projects_with_packages` @@ -15864,15 +16996,15 @@ Tiers: `free` ### `usage_activity_by_stage.release.projects_mirrored_with_pipelines_enabled` -Projects with repository mirroring enabled +Count creator_id from projects with repository mirroring enabled. -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216181934_projects_mirrored_with_pipelines_enabled.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216181934_projects_mirrored_with_pipelines_enabled.yml) -Group: `group::release` +Group: `group::continuous integration` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage.release.releases` @@ -16116,7 +17248,7 @@ Tiers: `free` ### `usage_activity_by_stage.verify.ci_builds` -Unique builds in project +Unique count of builds in project [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175525_ci_builds.yml) @@ -16124,7 +17256,7 @@ Group: `group::continuous integration` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.verify.ci_external_pipelines` @@ -16136,7 +17268,7 @@ Group: `group::continuous integration` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.verify.ci_internal_pipelines` @@ -16148,7 +17280,7 @@ Group: `group::continuous integration` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.verify.ci_pipeline_config_auto_devops` @@ -16156,11 +17288,11 @@ Total pipelines from an Auto DevOps template [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216175531_ci_pipeline_config_auto_devops.yml) -Group: `group::continuous integration` +Group: `group::configure` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.verify.ci_pipeline_config_repository` @@ -16172,7 +17304,7 @@ Group: `group::continuous integration` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.verify.ci_pipeline_schedules` @@ -16184,7 +17316,7 @@ Group: `group::continuous integration` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.verify.ci_pipelines` @@ -16196,7 +17328,7 @@ Group: `group::continuous integration` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.verify.ci_triggers` @@ -16208,15 +17340,15 @@ Group: `group::continuous integration` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage.verify.clusters_applications_runner` -Total GitLab Managed clusters with Runner enabled +Count of users creating managed clusters with Runner enabled [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_all/20210216181949_clusters_applications_runner.yml) -Group: `group::runner` +Group: `group::configure` Status: `data_available` @@ -16308,7 +17440,7 @@ Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.configure.clusters_management_project` -Total GitLab Managed clusters with defined cluster management project +Number of Kubernetes clusters with clusters management project being set [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175413_clusters_management_project.yml) @@ -16428,7 +17560,7 @@ Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.configure.projects_slack_notifications_active` -Unique projects with Slack webhook enabled +Unique projects created in the past 28 days that have Slack notifications enabled [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216175436_projects_slack_notifications_active.yml) @@ -16436,11 +17568,11 @@ Group: `group::configure` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.configure.projects_slack_slash_active` -Unique projects with Slack ‘/’ commands enabled +Unique projects created in the past 28 days that have Slack ‘/’ commands enabled [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216175437_projects_slack_slash_active.yml) @@ -16448,7 +17580,7 @@ Group: `group::configure` Status: `data_available` -Tiers: +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.configure.projects_with_prometheus_alerts` @@ -16460,7 +17592,7 @@ Group: `group::monitor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.action_monthly_active_users_design_management` @@ -16476,7 +17608,7 @@ Tiers: `free` ### `usage_activity_by_stage_monthly.create.action_monthly_active_users_git_write` -Aggregated value for wiki, design and project repo actions +Aggregated value for wiki, design, and project repo Git write actions [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216182041_action_monthly_active_users_git_write.yml) @@ -16484,7 +17616,7 @@ Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.action_monthly_active_users_ide_edit` @@ -16500,7 +17632,7 @@ Tiers: `free` ### `usage_activity_by_stage_monthly.create.action_monthly_active_users_project_repo` -Missing description +Count of monthly active users who have performed any Git operation (read/write/push) [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216182040_action_monthly_active_users_project_repo.yml) @@ -16508,7 +17640,7 @@ Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.action_monthly_active_users_sfe_edit` @@ -16572,7 +17704,7 @@ Tiers: `free` ### `usage_activity_by_stage_monthly.create.approval_project_rules` -Number of project approval rules +Total number of project approval rules [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216182056_approval_project_rules.yml) @@ -16580,47 +17712,47 @@ Group: `group::source code` Status: `data_available` -Tiers: +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.approval_project_rules_with_exact_required_approvers` -Missing description +Number of approval rules with the exact number of required approvers. -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216183622_approval_project_rules_with_exact_required_approvers.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216183622_approval_project_rules_with_exact_required_approvers.yml) -Group: `` +Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.approval_project_rules_with_less_approvers_than_required` -Missing description +Number of approval rules with fewer approvers than required. -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216183620_approval_project_rules_with_less_approvers_than_required.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216183620_approval_project_rules_with_less_approvers_than_required.yml) -Group: `` +Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.approval_project_rules_with_more_approvers_than_required` -Missing description +Number of approval rules with more approvers than required. -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216183618_approval_project_rules_with_more_approvers_than_required.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216183618_approval_project_rules_with_more_approvers_than_required.yml) -Group: `` +Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.approval_project_rules_with_target_branch` -Number of project approval rules with not default target branch +Number of project approval rules scoped to a specific repo branch. [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216182058_approval_project_rules_with_target_branch.yml) @@ -16628,11 +17760,11 @@ Group: `group::source code` Status: `data_available` -Tiers: +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.deploy_keys` -Missing description +Count of users creating deploy keys in last 28 days. [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216182034_deploy_keys.yml) @@ -16640,11 +17772,11 @@ Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.keys` -Missing description +Count of users creating regular keys in last 28 days. [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216182036_keys.yml) @@ -16652,11 +17784,11 @@ Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.merge_requests` -Missing description +Count of the number of users creating merge requests [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175055_merge_requests.yml) @@ -16664,11 +17796,11 @@ Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.merge_requests_users` -Missing description +Monthly count of the number of merge request users [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175101_merge_requests_users.yml) @@ -16676,7 +17808,7 @@ Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.merge_requests_with_added_rules` @@ -16688,23 +17820,23 @@ Group: `group::code review` Status: `data_available` -Tiers: +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.merge_requests_with_optional_codeowners` -Missing description +Count of merge requests with optional codeowner approval rules [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216175105_merge_requests_with_optional_codeowners.yml) -Group: `group::code review` +Group: `group::source code` Status: `data_available` -Tiers: +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.merge_requests_with_overridden_project_rules` -Number of merge requests that have local rules that have overwritten a project rule +Number of merge requests which have overriden rules created at the project level [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216182047_merge_requests_with_overridden_project_rules.yml) @@ -16712,31 +17844,31 @@ Group: `group::source code` Status: `data_available` -Tiers: +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.merge_requests_with_required_codeowners` -Missing description +Count of merge requests with required codeowner approval rules [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216175107_merge_requests_with_required_codeowners.yml) -Group: `group::code review` +Group: `group::source code` Status: `data_available` -Tiers: +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.projects_enforcing_code_owner_approval` -Missing description +Count of total projects that require approval by code owners for code changes -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216182043_projects_enforcing_code_owner_approval.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216182043_projects_enforcing_code_owner_approval.yml) Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.projects_imported_from_github` @@ -16752,55 +17884,55 @@ Tiers: `free` ### `usage_activity_by_stage_monthly.create.projects_with_disable_overriding_approvers_per_merge_request` -Missing description +Count of the number of projects with setting to disable overriding approvers per merge request [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175057_projects_with_disable_overriding_approvers_per_merge_request.yml) -Group: `group::code review` +Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.projects_with_repositories_enabled` -Missing description +Count of users creating projects that have a matching Git repository, result of a Git push action, for last 28 days. -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216182049_projects_with_repositories_enabled.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216182049_projects_with_repositories_enabled.yml) Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.projects_with_sectional_code_owner_rules` -Missing description +Count of projects using code owners with code owners section feature -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216182045_projects_with_sectional_code_owner_rules.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216182045_projects_with_sectional_code_owner_rules.yml) Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.projects_without_disable_overriding_approvers_per_merge_request` -Missing description +Count of the number of projects without setting to disable overriding approvers per merge request [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175059_projects_without_disable_overriding_approvers_per_merge_request.yml) -Group: `group::code review` +Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.protected_branches` -Missing description +Count of users creating projects with repositories making use of at least one protected branch in last 28 days. [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216182051_protected_branches.yml) @@ -16808,11 +17940,11 @@ Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.remote_mirrors` -Missing description +Count of users creating projects with remote mirrors. Includes both push and pull mirrors. [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216182038_remote_mirrors.yml) @@ -16820,7 +17952,7 @@ Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.snippets` @@ -16836,7 +17968,7 @@ Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.suggestions` -Missing description +Count of unique users per month who create suggestions in merge request comments [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175109_suggestions.yml) @@ -16844,35 +17976,35 @@ Group: `group::code review` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.total_number_of_locked_files` -Missing description +The total number of files which have been locked via the GitLab UI -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216183614_total_number_of_locked_files.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216183614_total_number_of_locked_files.yml) -Group: `` +Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.total_number_of_path_locks` -Missing description +Number of paths/directories manually locked through the UI -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216183613_total_number_of_path_locks.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216183613_total_number_of_path_locks.yml) -Group: `` +Group: `group::source code` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.users_using_lfs_locks` -Number of users that have used default branch locks through the UI +Number of unique users who have locked files or directories using LFS via the command line [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216182054_users_using_lfs_locks.yml) @@ -16880,11 +18012,11 @@ Group: `group::source code` Status: `data_available` -Tiers: +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage_monthly.create.users_using_path_locks` -Number of users that have used exclusive file locks through the CLI +Number of users creating path_locks in last 28 days. [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216182053_users_using_path_locks.yml) @@ -16892,7 +18024,19 @@ Group: `group::source code` Status: `data_available` -Tiers: +Tiers: `premium`, `ultimate` + +### `usage_activity_by_stage_monthly.enablement.geo_secondary_web_oauth_users` + +Missing description + +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210427213346_geo_secondary_web_oauth_users.yml) + +Group: `` + +Status: `implemented` + +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.manage.bulk_imports.gitlab` @@ -17484,7 +18628,7 @@ Tiers: ### `usage_activity_by_stage_monthly.monitor.clusters` -Total GitLab Managed clusters both enabled and disabled +Count users creating clusters in last 28 days. [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216180956_clusters.yml) @@ -17492,11 +18636,11 @@ Group: `group::monitor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.monitor.clusters_applications_prometheus` -Total GitLab Managed clusters with Prometheus enabled +Users creating clusters with Prometheus enabled in last 28 days. [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216180958_clusters_applications_prometheus.yml) @@ -17504,7 +18648,7 @@ Group: `group::monitor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.monitor.operations_dashboard_default_dashboard` @@ -17516,7 +18660,7 @@ Group: `group::monitor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.monitor.operations_dashboard_users_with_projects_added` @@ -17528,19 +18672,19 @@ Group: `group::monitor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.monitor.projects_incident_sla_enabled` -Missing description +Count of projects with Incident SLA enabled -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216183753_projects_incident_sla_enabled.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_all/20210216183753_projects_incident_sla_enabled.yml) -Group: `` +Group: `group::monitor` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage_monthly.monitor.projects_with_alert_incidents` @@ -17556,7 +18700,7 @@ Tiers: `free` ### `usage_activity_by_stage_monthly.monitor.projects_with_error_tracking_enabled` -Missing description +Count of users creating projects with error tracking enabled. [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216181004_projects_with_error_tracking_enabled.yml) @@ -17564,7 +18708,7 @@ Group: `group::monitor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.monitor.projects_with_incidents` @@ -17588,7 +18732,7 @@ Group: `group::monitor` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.package.projects_with_packages` @@ -17628,7 +18772,7 @@ Tiers: `free` ### `usage_activity_by_stage_monthly.plan.issues` -Count of MAU creating issues +Count of users creating Issues in last 28 days. [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216181139_issues.yml) @@ -17784,15 +18928,15 @@ Tiers: `free` ### `usage_activity_by_stage_monthly.release.projects_mirrored_with_pipelines_enabled` -Projects with repository mirroring enabled +Count creator_id from projects with repository mirroring enabled. -[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216181943_projects_mirrored_with_pipelines_enabled.yml) +[YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216181943_projects_mirrored_with_pipelines_enabled.yml) -Group: `group::release` +Group: `group::continuous integration` Status: `data_available` -Tiers: `free` +Tiers: `premium`, `ultimate` ### `usage_activity_by_stage_monthly.release.releases` @@ -18120,7 +19264,7 @@ Tiers: `free` ### `usage_activity_by_stage_monthly.verify.ci_builds` -Unique builds in project +Unique monthly builds in project [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175542_ci_builds.yml) @@ -18128,11 +19272,11 @@ Group: `group::continuous integration` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.verify.ci_external_pipelines` -Total pipelines in external repositories +Total pipelines in external repositories in a month [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175544_ci_external_pipelines.yml) @@ -18140,11 +19284,11 @@ Group: `group::continuous integration` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.verify.ci_internal_pipelines` -Total pipelines in GitLab repositories +Total pipelines in GitLab repositories in a month [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175546_ci_internal_pipelines.yml) @@ -18152,7 +19296,7 @@ Group: `group::continuous integration` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.verify.ci_pipeline_config_auto_devops` @@ -18160,15 +19304,15 @@ Total pipelines from an Auto DevOps template [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175548_ci_pipeline_config_auto_devops.yml) -Group: `group::continuous integration` +Group: `group::configure` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.verify.ci_pipeline_config_repository` -Total Pipelines from templates in repository +Total Monthly Pipelines from templates in repository [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175550_ci_pipeline_config_repository.yml) @@ -18176,11 +19320,11 @@ Group: `group::continuous integration` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.verify.ci_pipeline_schedules` -Pipeline schedules in GitLab +Total monthly Pipeline schedules in GitLab [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175552_ci_pipeline_schedules.yml) @@ -18188,11 +19332,11 @@ Group: `group::continuous integration` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.verify.ci_pipelines` - Distinct users triggering pipelines in a month +Distinct users triggering pipelines in a month [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216175554_ci_pipelines.yml) @@ -18200,7 +19344,7 @@ Group: `group::continuous integration` Status: `data_available` -Tiers: `free` +Tiers: `free`, `premium`, `ultimate`, `free` ### `usage_activity_by_stage_monthly.verify.ci_triggers` @@ -18228,7 +19372,7 @@ Tiers: `free`, `premium`, `ultimate` ### `usage_activity_by_stage_monthly.verify.projects_reporting_ci_cd_back_to_github` -Projects with a GitHub service pipeline enabled +Projects with a GitHub repository mirror pipeline enabled [YAML definition](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/counts_28d/20210216175558_projects_reporting_ci_cd_back_to_github.yml) diff --git a/doc/development/usage_ping/index.md b/doc/development/usage_ping/index.md index bf423d68700..292e1256cb8 100644 --- a/doc/development/usage_ping/index.md +++ b/doc/development/usage_ping/index.md @@ -178,10 +178,132 @@ The correct approach is to add a new metric for GitLab 12.6 release with updated and update existing business analysis artefacts to use `example_metric_without_archived` instead of `example_metric` -### 3. Metrics deprecation and removal +### 3. Deprecate a metric -The process for deprecating and removing metrics is under development. For -more information, see the following [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/284637). +If a metric is obsolete and you no longer use it, you can mark it as deprecated. + +For an example of the metric deprecation process take a look at this [example merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/59899) + +To deprecate a metric: + +1. Check the following YAML files and verify the metric is not used in an aggregate: + - [`config/metrics/aggregates/*.yaml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/aggregates/) + - [`ee/config/metrics/aggregates/*.yaml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/config/metrics/aggregates/) + +1. Create an issue in the [GitLab Data Team + project](https://gitlab.com/gitlab-data/analytics/-/issues). Ask for + confirmation that the metric is not used by other teams, or in any of the SiSense + dashboards. + +1. Verify the metric is not used to calculate the conversational index. The + conversational index is a measure that reports back to self-managed instances + to inform administrators of the progress of DevOps adoption for the instance. + + You can check + [`CalculateConvIndexService`](https://gitlab.com/gitlab-services/version-gitlab-com/-/blob/master/app/services/calculate_conv_index_service.rb) + to view the metrics that are used. The metrics are represented + as the keys that are passed as a field argument into the `get_value` method. + +1. Document the deprecation in the metric's YAML definition. Set + the `status:` attribute to `deprecated`, for example: + + ```yaml + --- + key_path: analytics_unique_visits.analytics_unique_visits_for_any_target_monthly + description: Visits to any of the pages listed above per month + product_section: dev + product_stage: manage + product_group: group::analytics + product_category: + value_type: number + status: deprecated + time_frame: 28d + data_source: + distribution: + - ce + tier: + - free + ``` + +1. Replace the metric's instrumentation with a fixed value. This avoids wasting + resources to calculate the deprecated metric. In + [`lib/gitlab/usage_data.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data.rb) + or + [`ee/lib/ee/gitlab/usage_data.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/ee/gitlab/usage_data.rb), + replace the code that calculates the metric's value with a fixed value that + indicates it's deprecated: + + ```ruby + module Gitlab + class UsageData + DEPRECATED_VALUE = -1000 + + def analytics_unique_visits_data + results['analytics_unique_visits_for_any_target'] = redis_usage_data { unique_visit_service.unique_visits_for(targets: :analytics) } + results['analytics_unique_visits_for_any_target_monthly'] = DEPRECATED_VALUE + + { analytics_unique_visits: results } + end + # ... + end + end + ``` + +1. Update the Metrics Dictionary following [guidelines instructions](dictionary.md). + +### 4. Remove a metric + +Only deprecated metrics can be removed from Usage Ping. + +For an example of the metric removal process take a look at this [example issue](https://gitlab.com/gitlab-org/gitlab/-/issues/297029) + +To remove a deprecated metric: + +1. Verify that removing the metric from the Usage Ping payload does not cause + errors in [Version App](https://gitlab.com/gitlab-services/version-gitlab-com) + when the updated payload is collected and processed. Version App collects + and persists all Usage Ping reports. To do that you can modify + [fixtures](https://gitlab.com/gitlab-services/version-gitlab-com/-/blob/master/spec/support/usage_data_helpers.rb#L540) + used to test + [`UsageDataController#create`](https://gitlab.com/gitlab-services/version-gitlab-com/-/blob/3760ef28/spec/controllers/usage_data_controller_spec.rb#L75) + endpoint, and assure that test suite does not fail when metric that you wish to remove is not included into test payload. + +1. Create an issue in the + [GitLab Data Team project](https://gitlab.com/gitlab-data/analytics/-/issues). + Ask for confirmation that the metric is not referred to in any SiSense dashboards and + can be safely removed from Usage Ping. Use this + [example issue](https://gitlab.com/gitlab-data/analytics/-/issues/7539) for guidance. + This step can be skipped if verification done during [deprecation process](#3-deprecate-a-metric) + reported that metric is not required by any data transformation in Snowflake data warehouse nor it is + used by any of SiSense dashboards. + +1. After you verify the metric can be safely removed, + update the attributes of the metric's YAML definition: + + - Set the `status:` to `removed`. + - Set `milestone_removed:` to the number of the + milestone in which the metric was removed. + + Do not remove the metric's YAML definition altogether. Some self-managed + instances might not immediately update to the latest version of GitLab, and + therefore continue to report the removed metric. The Product Intelligence team + requires a record of all removed metrics in order to identify and filter them. + + For example please take a look at this [merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60149/diffs#b01f429a54843feb22265100c0e4fec1b7da1240_10_10). + +1. After you verify the metric can be safely removed, + remove the metric's instrumentation from + [`lib/gitlab/usage_data.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data.rb) + or + [`ee/lib/ee/gitlab/usage_data.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/ee/gitlab/usage_data.rb). + + For example please take a look at this [merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60149/diffs#6335dc533bd21df26db9de90a02dd66278c2390d_167_167). + +1. Remove any other records related to the metric: + - The feature flag YAML file at [`config/feature_flags/*/*.yaml`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/config/feature_flags). + - The entry in the known events YAML file at [`lib/gitlab/usage_data_counters/known_events/*.yaml`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/usage_data_counters/known_events). + +1. Update the Metrics Dictionary following [guidelines instructions](dictionary.md). ## Implementing Usage Ping @@ -492,39 +614,33 @@ Implemented using Redis methods [PFADD](https://redis.io/commands/pfadd) and [PF Example event: ```yaml - - name: i_compliance_credential_inventory - category: compliance - redis_slot: compliance - expiry: 42 # 6 weeks + - name: users_creating_epics + category: epics_usage + redis_slot: users aggregation: weekly - feature_flag: usage_data_i_compliance_credential_inventory + feature_flag: track_epics_activity ``` Keys: - `name`: unique event name. - Name format `<prefix>_<redis_slot>_name`. + Name format for Redis HLL events `<name>_<redis_slot>`. - Use one of the following prefixes for the event's name: - - - `g_` for group, as an event which is tracked for group. - - `p_` for project, as an event which is tracked for project. - - `i_` for instance, as an event which is tracked for instance. - - `a_` for events encompassing all `g_`, `p_`, `i_`. - - `o_` for other. + [See Metric name](metrics_dictionary.md#metric-name) for a complete guide on metric naming suggestion. Consider including in the event's name the Redis slot to be able to count totals for a specific category. - Example names: `i_compliance_credential_inventory`, `g_analytics_contribution`. + Example names: `users_creating_epics`, `users_triggering_security_scans`. - `category`: event category. Used for getting total counts for events in a category, for easier access to a group of events. - - `redis_slot`: optional Redis slot; default value: event name. Used if needed to calculate totals - for a group of metrics. Ensure keys are in the same slot. For example: - `i_compliance_credential_inventory` with `redis_slot: 'compliance'` builds Redis key - `i_{compliance}_credential_inventory-2020-34`. If `redis_slot` is not defined the Redis key will - be `{i_compliance_credential_inventory}-2020-34`. + - `redis_slot`: optional Redis slot. Default value: event name. Only event data that is stored in the same slot + can be aggregated. Ensure keys are in the same slot. For example: + `users_creating_epics` with `redis_slot: 'users'` builds Redis key + `{users}_creating_epics-2020-34`. If `redis_slot` is not defined the Redis key will + be `{users_creating_epics}-2020-34`. + Recommended slots to use are: `users`, `projects`. This is the value we count. - `expiry`: expiry time in days. Default: 29 days for daily aggregation and 6 weeks for weekly aggregation. - `aggregation`: may be set to a `:daily` or `:weekly` key. Defines how counting data is stored in Redis. @@ -550,7 +666,7 @@ Use one of the following methods to track events: include RedisTracking skip_before_action :authenticate_user!, only: :show - track_redis_hll_event :index, :show, name: 'g_compliance_example_feature_visitors' + track_redis_hll_event :index, :show, name: 'users_visiting_projects' def index render html: 'index' @@ -581,7 +697,7 @@ Use one of the following methods to track events: user: current_user, subject: user_group ).execute - increment_unique_values('i_list_repositories', current_user.id) + increment_unique_values('users_listing_repositories', current_user.id) present paginate(repositories), with: Entities::ContainerRegistry::Repository, tags: params[:tags], tags_count: params[:tags_count] end @@ -655,15 +771,15 @@ Use one of the following methods to track events: Trigger events in rails console by using `track_event` method ```ruby - Gitlab::UsageDataCounters::HLLRedisCounter.track_event('g_compliance_audit_events', values: 1) - Gitlab::UsageDataCounters::HLLRedisCounter.track_event('g_compliance_audit_events', values: [2, 3]) + Gitlab::UsageDataCounters::HLLRedisCounter.track_event('users_viewing_compliance_audit_events', values: 1) + Gitlab::UsageDataCounters::HLLRedisCounter.track_event('users_viewing_compliance_audit_events', values: [2, 3]) ``` Next, get the unique events for the current week. ```ruby # Get unique events for metric for current_week - Gitlab::UsageDataCounters::HLLRedisCounter.unique_events(event_names: 'g_compliance_audit_events', + Gitlab::UsageDataCounters::HLLRedisCounter.unique_events(event_names: 'users_viewing_compliance_audit_events', start_date: Date.current.beginning_of_week, end_date: Date.current.next_week) ``` @@ -681,7 +797,7 @@ We have the following recommendations for [Adding new events](#adding-new-events ##### Enable/Disable Redis HLL tracking -Events are tracked behind [feature flags](../feature_flags/index.md) due to concerns for Redis performance and scalability. +Events are tracked behind optional [feature flags](../feature_flags/index.md) due to concerns for Redis performance and scalability. For a full list of events and corresponding feature flags see, [known_events](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/) files. @@ -693,6 +809,13 @@ To enable or disable tracking for specific event in <https://gitlab.com> or <htt /chatops run feature set <feature_name> false ``` +We can also disable tracking completely by using the global flag: + +```shell +/chatops run feature set redis_hll_tracking true +/chatops run feature set redis_hll_tracking false +``` + ##### Known events are added automatically in usage 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 usage 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). @@ -711,29 +834,24 @@ Example of `redis_hll_counters` data: ```ruby {:redis_hll_counters=> {"compliance"=> - {"g_compliance_dashboard_weekly"=>0, - "g_compliance_dashboard_monthly"=>0, - "g_compliance_audit_events_weekly"=>0, - "g_compliance_audit_events_monthly"=>0, + {"users_viewing_compliance_dashboard_weekly"=>0, + "users_viewing_compliance_dashboard_monthly"=>0, + "users_viewing_compliance_audit_events_weekly"=>0, + "users_viewing_audit_events_monthly"=>0, "compliance_total_unique_counts_weekly"=>0, "compliance_total_unique_counts_monthly"=>0}, - "analytics"=> - {"g_analytics_contribution_weekly"=>0, - "g_analytics_contribution_monthly"=>0, - "g_analytics_insights_weekly"=>0, - "g_analytics_insights_monthly"=>0, + "analytics"=> + {"users_viewing_analytics_group_devops_adoption_weekly"=>0, + "users_viewing_analytics_group_devops_adoption_monthly"=>0, "analytics_total_unique_counts_weekly"=>0, "analytics_total_unique_counts_monthly"=>0}, "ide_edit"=> - {"g_edit_by_web_ide_weekly"=>0, - "g_edit_by_web_ide_monthly"=>0, - "g_edit_by_sfe_weekly"=>0, - "g_edit_by_sfe_monthly"=>0, + {"users_editing_by_web_ide_weekly"=>0, + "users_editing_by_web_ide_monthly"=>0, + "users_editing_by_sfe_weekly"=>0, + "users_editing_by_sfe_monthly"=>0, "ide_edit_total_unique_counts_weekly"=>0, - "ide_edit_total_unique_counts_monthly"=>0}, - "search"=> - {"i_search_total_weekly"=>0, "i_search_total_monthly"=>0, "i_search_advanced_weekly"=>0, "i_search_advanced_monthly"=>0, "i_search_paid_weekly"=>0, "i_search_paid_monthly"=>0, "search_total_unique_counts_weekly"=>0, "search_total_unique_counts_monthly"=>0}, - "source_code"=>{"wiki_action_weekly"=>0, "wiki_action_monthly"=>0} + "ide_edit_total_unique_counts_monthly"=>0} } ``` @@ -747,10 +865,10 @@ redis_usage_data { ::Gitlab::UsageCounters::PodLogs.usage_totals[:total] } # Define events in common.yml https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/common.yml # Tracking events -Gitlab::UsageDataCounters::HLLRedisCounter.track_event('expand_vulnerabilities', values: visitor_id) +Gitlab::UsageDataCounters::HLLRedisCounter.track_event('users_expanding_vulnerabilities', values: visitor_id) # Get unique events for metric -redis_usage_data { Gitlab::UsageDataCounters::HLLRedisCounter.unique_events(event_names: 'expand_vulnerabilities', start_date: 28.days.ago, end_date: Date.current) } +redis_usage_data { Gitlab::UsageDataCounters::HLLRedisCounter.unique_events(event_names: 'users_expanding_vulnerabilities', start_date: 28.days.ago, end_date: Date.current) } ``` ### Alternative Counters @@ -824,7 +942,6 @@ We return fallback values in these cases: Add the metric in one of the top level keys -- `license`: for license related metrics. - `settings`: for settings related metrics. - `counts_weekly`: for counters that have data for the most recent 7 days. - `counts_monthly`: for counters that have data for the most recent 28 days. @@ -907,15 +1024,21 @@ On GitLab.com, we have DangerBot setup to monitor Product Intelligence related f ### 10. Verify your metric -On GitLab.com, the Product Intelligence team regularly monitors Usage Ping. They may alert you that your metrics need further optimization to run quicker and with greater success. You may also use the [Usage Ping QA dashboard](https://app.periscopedata.com/app/gitlab/632033/Usage-Ping-QA) to check how well your metric performs. The dashboard allows filtering by GitLab version, by "Self-managed" & "SaaS" and shows you how many failures have occurred for each metric. Whenever you notice a high failure rate, you may re-optimize your metric. +On GitLab.com, the Product Intelligence team regularly [monitors Usage Ping](https://gitlab.com/groups/gitlab-org/-/epics/6000). +They may alert you that your metrics need further optimization to run quicker and with greater success. + +The Usage Ping JSON payload for GitLab.com is shared in the +[#g_product_intelligence](https://gitlab.slack.com/archives/CL3A7GFPF) Slack channel every week. + +You may also use the [Usage Ping QA dashboard](https://app.periscopedata.com/app/gitlab/632033/Usage-Ping-QA) to check how well your metric performs. The dashboard allows filtering by GitLab version, by "Self-managed" & "SaaS" and shows you how many failures have occurred for each metric. Whenever you notice a high failure rate, you may re-optimize your metric. ### Usage Ping local setup To set up Usage Ping locally, you must: -1. [Set up local repositories]#(set-up-local-repositories) -1. [Test local setup](#test-local-setup) -1. (Optional) [Test Prometheus-based usage ping](#test-prometheus-based-usage-ping) +1. [Set up local repositories](#set-up-local-repositories). +1. [Test local setup](#test-local-setup). +1. (Optional) [Test Prometheus-based usage ping](#test-prometheus-based-usage-ping). #### Set up local repositories @@ -981,7 +1104,7 @@ build in a [downstream pipeline of the `omnibus-gitlab-mirror` project](https:// This is the less recommended approach, because it comes with a number of difficulties when emulating a real GitLab deployment. The [GDK](https://gitlab.com/gitlab-org/gitlab-development-kit) is not set up to run a Prometheus server or `node_exporter` alongside other GitLab components. If you would -like to do so, [Monitoring the GDK with Prometheus](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/prometheus/index.md#monitoring-the-gdk-with-prometheus) is a good start. +like to do so, [Monitoring the GDK with Prometheus](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/prometheus/index.md#monitoring-the-gdk-with-prometheus) is a good start. The [GCK](https://gitlab.com/gitlab-org/gitlab-compose-kit) has limited support for testing Prometheus based Usage Ping. By default, it already comes with a fully configured Prometheus service that is set up to scrape a number of components, @@ -1030,9 +1153,9 @@ Example aggregated metric entries: - name: example_metrics_union operator: OR events: - - 'i_search_total' - - 'i_search_advanced' - - 'i_search_paid' + - 'users_expanding_secure_security_report' + - 'users_expanding_testing_code_quality_report' + - 'users_expanding_testing_accessibility_report' source: redis time_frame: - 7d diff --git a/doc/development/usage_ping/metrics_dictionary.md b/doc/development/usage_ping/metrics_dictionary.md index b55d4714580..40beee3c408 100644 --- a/doc/development/usage_ping/metrics_dictionary.md +++ b/doc/development/usage_ping/metrics_dictionary.md @@ -36,12 +36,14 @@ Each metric is defined in a separate YAML file consisting of a number of fields: | `value_type` | yes | `string`; one of [`string`, `number`, `boolean`, `object`](https://json-schema.org/understanding-json-schema/reference/type.html). | | `status` | yes | `string`; [status](#metric-statuses) of the metric, may be set to `data_available`, `implemented`, `not_used`, `deprecated`, `removed`. | | `time_frame` | yes | `string`; may be set to a value like `7d`, `28d`, `all`, `none`. | -| `data_source` | yes | `string`; may be set to a value like `database`, `redis`, `redis_hll`, `prometheus`, `ruby`. | +| `data_source` | yes | `string`; may be set to a value like `database`, `redis`, `redis_hll`, `prometheus`, `system`. | +| `instrumentation_class` | no | `string`; [the class that implements the metric](metrics_instrumentation.md). | | `distribution` | yes | `array`; may be set to one of `ce, ee` or `ee`. The [distribution](https://about.gitlab.com/handbook/marketing/strategic-marketing/tiers/#definitions) where the tracked feature is available. | | `tier` | yes | `array`; may be set to one of `free, premium, ultimate`, `premium, ultimate` or `ultimate`. The [tier]( https://about.gitlab.com/handbook/marketing/strategic-marketing/tiers/) where the tracked feature is available. | | `milestone` | no | The milestone when the metric is introduced. | | `milestone_removed` | no | The milestone when the metric is removed. | | `introduced_by_url` | no | The URL to the Merge Request that introduced the metric. | +| `extra` | no | `object`: extra information needed to calculate the metric value. | | `skip_validation` | no | This should **not** be set. [Used for imported metrics until we review, update and make them valid](https://gitlab.com/groups/gitlab-org/-/epics/5425). | ### Metric statuses @@ -119,10 +121,10 @@ only the single prompt to be replaced by the person working with metrics YAML. `{subject}_{verb}{ing|ed}_{object}`, such as `user_creating_epics`, `users_triggering_security_scans`, or `merge_requests_viewed_in_single_file_mode` -#### Metric with `data_source: prometheus` or `ruby` +#### Metric with `data_source: prometheus` or `system` -For metrics instrumented with Prometheus or Ruby, the suggested name includes only -the single prompt by person working with metrics YAML. +For metrics instrumented with Prometheus or coming from the operating system, +the suggested name includes only the single prompt by person working with metrics YAML. - **Prompt**: `<please fill metric name>` - **Final metric name**: Due to the variety of cases that can apply to this kind of metric, @@ -194,3 +196,11 @@ bundle exec rails generate gitlab:usage_metric_definition:redis_hll issues i_clo create config/metrics/counts_7d/i_closed_weekly.yml create config/metrics/counts_28d/i_closed_monthly.yml ``` + +To create a metric definition used in EE, add the `--ee` flag. + +```shell +bundle exec rails generate gitlab:usage_metric_definition:redis_hll issues users_closing_issues --ee +create config/metrics/counts_7d/i_closed_weekly.yml +create config/metrics/counts_28d/i_closed_monthly.yml +``` diff --git a/doc/development/usage_ping/metrics_instrumentation.md b/doc/development/usage_ping/metrics_instrumentation.md new file mode 100644 index 00000000000..2cb24fab6cc --- /dev/null +++ b/doc/development/usage_ping/metrics_instrumentation.md @@ -0,0 +1,90 @@ +--- +stage: Growth +group: Product Intelligence +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Metrics instrumentation guide + +This guide describes how to develop Usage Ping metrics using metrics instrumentation. + +## Nomenclature + +- **Instrumentation class**: + - Inherits one of the metric classes: `DatabaseMetric`, `RedisHLLMetric` or `GenericMetric`. + - Implements the logic that calculates the value for a Usage Ping metric. + +- **Metric definition** + The Usage Data metric YAML definition. + +- **Hardening**: + Hardening a method is the process that ensures the method fails safe, returning a fallback value like -1. + +## How it works + +A metric definition has the [`instrumentation_class`](metrics_dictionary.md) field, which can be set to a class. + +The defined instrumentation class should have one of the existing metric classes: `DatabaseMetric`, `RedisHLLMetric`, or `GenericMetric`. + +Using the instrumentation classes ensures that metrics can fail safe individually, without breaking the entire + process of Usage Ping generation. + +We have built a domain-specific language (DSL) to define the metrics instrumentation. + +## Database metrics + +[Example of a merge request that adds a database metric](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60022). + +```ruby +module Gitlab + module Usage + module Metrics + module Instrumentations + class CountBoardsMetric < DatabaseMetric + operation :count + + relation { Board } + end + end + end + end +end +``` + +## Redis HyperLogLog metrics + +[Example of a merge request that adds a `RedisHLL` metric](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60089/diffs). + +```ruby +module Gitlab + module Usage + module Metrics + module Instrumentations + class CountUsersUsingApproveQuickActionMetric < RedisHLLMetric + event_names :i_quickactions_approve + end + end + end + end +end +``` + +## Generic metrics + +[Example of a merge request that adds a generic metric](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60256). + +```ruby +module Gitlab + module Usage + module Metrics + module Instrumentations + class UuidMetric < GenericMetric + value do + Gitlab::CurrentSettings.uuid + end + end + end + end + end +end +``` diff --git a/doc/development/usage_ping/product_intelligence_review.md b/doc/development/usage_ping/product_intelligence_review.md index 3a8f9143b70..0e86a116bca 100644 --- a/doc/development/usage_ping/product_intelligence_review.md +++ b/doc/development/usage_ping/product_intelligence_review.md @@ -48,7 +48,7 @@ Product Intelligence files. [Metrics Dictionary](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/development/usage_ping/dictionary.md) if it is needed. - Add a changelog [according to guidelines](../changelog.md). -##### When adding or modifiying Snowplow events +##### When adding or modifying Snowplow events - For frontend events, when relevant, add a screenshot of the event in the [testing tool](../snowplow/index.md#developing-and-testing-snowplow) used. @@ -81,7 +81,7 @@ Any of the Product Intelligence engineers can be assigned for the Product Intell - Check if a [feature flag is needed](index.md#recommendations). - For tracking with Snowplow: - Check that the [event taxonomy](../snowplow/index.md#structured-event-taxonomy) is correct. - - Check the [usage recomendations](../snowplow/index.md#usage-recommendations). + - Check the [usage recommendations](../snowplow/index.md#usage-recommendations). - Metrics YAML definitions: - Check the metric `description`. - Check the metrics `key_path`. |
