Add latest changes from gitlab-org/gitlab@14-9-stable-eev14.9.0-rc42

11 files changed, 180 insertions, 82 deletions

diff --git a/doc/operations/error_tracking.md b/doc/operations/error_tracking.md
index 6f97f002a32..907c59adacb 100644
--- a/doc/operations/error_tracking.md
+++ b/doc/operations/error_tracking.md
@@ -41,8 +41,10 @@ least Maintainer [permissions](../user/permissions.md) to enable the Sentry inte
 
 1. Sign up to Sentry.io or [deploy your own](#deploying-sentry) Sentry instance.
 1. [Create](https://docs.sentry.io/product/sentry-basics/guides/integrate-frontend/create-new-project/) a new Sentry project. For each GitLab project that you want to integrate, we recommend that you create a new Sentry project.
-1. [Find or generate](https://docs.sentry.io/api/auth/) a Sentry auth token for your Sentry project.
-   Make sure to give the token at least the following scopes: `event:read`, `project:read`, and `event:write` (for resolving events).
+1. Find or generate a [Sentry auth token](https://docs.sentry.io/api/auth/#auth-tokens).
+   For the SaaS version of Sentry, you can find or generate the auth token at [https://sentry.io/api/](https://sentry.io/api/).
+   Make sure to give the token at least the following scopes: `project:read`, `event:read`, and
+   `event:write` (for resolving events).
 1. In GitLab, enable error tracking:
    1. On the top bar, select **Menu > Projects** and find your project.
    1. On the left sidebar, select **Monitor > Error Tracking**.
@@ -127,7 +129,17 @@ If another event occurs, the error reverts to unresolved.
 
 ## Integrated error tracking
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/329596) in GitLab 14.4.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/329596) in GitLab 14.4.
+> - [Disabled](https://gitlab.com/gitlab-org/gitlab/-/issues/353639) in GitLab 14.9 [with a flag](../administration/feature_flags.md) named `integrated_error_tracking`. Disabled by default.
+
+FLAG:
+By default this feature is not available. To make it available on self-managed GitLab, ask an
+administrator to [enable the feature flag](../administration/feature_flags.md)
+named `integrated_error_tracking`. The feature is not ready for production use.
+On GitLab.com, this feature is not available.
+
+WARNING:
+Turning on integrated error tracking may impact performance, depending on your error rates.
 
 Integrated error tracking is a lightweight alternative to Sentry backend.
 You still use Sentry SDK with your application. But you don't need to deploy Sentry
diff --git a/doc/operations/feature_flags.md b/doc/operations/feature_flags.md
index 8903e99ab3b..e7d78beb0b9 100644
--- a/doc/operations/feature_flags.md
+++ b/doc/operations/feature_flags.md
@@ -43,12 +43,7 @@ To create and enable a feature flag:
 1. Enter a name that starts with a letter and contains only lowercase letters, digits, underscores (`_`),
    or dashes (`-`), and does not end with a dash (`-`) or underscore (`_`).
 1. Optional. Enter a description (255 characters maximum).
-1. Enter details about how the flag should be applied:
-   - In GitLab 13.0 and earlier, add **Environment specs**. For each environment,
-     include the **Status** (default enabled) and [**Rollout strategy**](#rollout-strategy-legacy)
-     (defaults to **All users**).
-   - In GitLab 13.1 and later, add Feature Flag [**Strategies**](#feature-flag-strategies).
-     For each strategy, include the **Type** (defaults to [**All users**](#all-users))
+1. Add Feature Flag [**Strategies**](#feature-flag-strategies) to define how the flag should be applied. For each strategy, include the **Type** (defaults to [**All users**](#all-users))
      and **Environments** (defaults to all environments).
 1. Select **Create feature flag**.
 
@@ -163,21 +158,6 @@ WARNING:
 The Unleash client **must** be given a user ID for the feature to be enabled for
 target users. See the [Ruby example](#ruby-application-example) below.
 
-## Search for Code References **(PREMIUM)**
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/300299) in GitLab 14.4.
-
-Search your project and find any references of a feature flag in your
-code so that you can clean it up when it's time to remove the feature flag.
-
-To search for code references of a feature flag:
-
-1. On the top bar, select **Menu > Projects** and find your project.
-1. On the left sidebar, select **Deployments > Feature Flags**.
-1. Edit the feature flag you want to remove.
-1. Select **More actions** (**{ellipsis_v}**).
-1. Select **Search code references**.
-
 ### User List
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35930) in GitLab 13.1.
@@ -235,34 +215,20 @@ To remove users from a user list:
 1. Select **Edit** (**{pencil}**) next to the list you want to change.
 1. Select **Remove** (**{remove}**) next to the ID you want to remove.
 
-## Rollout strategy (legacy)
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8240) in GitLab 12.2.
-> - [Made read-only](https://gitlab.com/gitlab-org/gitlab/-/issues/220228) in GitLab 13.4.
-
-In GitLab 13.0 and earlier, the **Rollout strategy** setting affects which users experience
-the feature as enabled. Choose the percentage of users that the feature is enabled
-for. The rollout strategy has no effect if the environment spec is disabled.
-
-It can be set to:
-
-- All users
-- [Percent of users](#percent-of-users)
-  - Optionally, you can click the **Include additional user IDs** checkbox and add a list
-    of specific users IDs to enable the feature for.
-- [User IDs](#user-ids)
+## Search for Code References **(PREMIUM)**
 
-## Legacy feature flag migration
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/300299) in GitLab 14.4.
 
-Legacy feature flags became read-only in GitLab 13.4. GitLab 14.0 removes support for legacy feature
-flags. You must migrate your legacy feature flags to the new version. To do so, follow these steps:
+Search your project and find any references of a feature flag in your
+code so that you can clean it up when it's time to remove the feature flag.
 
-1. Take a screenshot of the legacy flag for tracking.
-1. Delete the flag through the API or UI (you don't need to alter the code).
-1. Create a new feature flag with the same name as the legacy flag you deleted. Make sure the
-   strategies and environments match the deleted flag.
+To search for code references of a feature flag:
 
-See [this video tutorial](https://www.youtube.com/watch?v=CAJY2IGep7Y) for help with this migration.
+1. On the top bar, select **Menu > Projects** and find your project.
+1. On the left sidebar, select **Deployments > Feature Flags**.
+1. Edit the feature flag you want to remove.
+1. Select **More actions** (**{ellipsis_v}**).
+1. Select **Search code references**.
 
 ## Disable a feature flag for a specific environment
 
@@ -441,3 +407,49 @@ click the `+` button and input the issue reference number or the full URL of the
 The issues then appear in the related feature flag and the other way round.
 
 This feature is similar to the [linked issues](../user/project/issues/related_issues.md) feature.
+
+## Performance factors
+
+In general, GitLab Feature Flags can be used in any applications,
+however, if it's a large application, it could require an additional configuration in advance.
+This section explains the performance factors to help your organization to identify
+what's needed to be done before using the feature.
+Please read [How it works](#how-it-works) section before diving into the details.
+
+### Maximum supported clients in application nodes
+
+GitLab accepts client requests as much as possible until it hits the [rate limiting](../security/rate_limits.md).
+At the moment, the Feature Flag API falls into **Unauthenticated traffic (from a given IP address)**
+in the [GitLab.com specific limits](../user/gitlab_com/index.md),
+so it's **500 requests per minute**.
+
+Please note that the polling rate is configurable in SDKs. Provided that all clients are requesting from the same IP:
+
+- Request once per minute ... 500 clients can be supported.
+- Request once per 15 sec ... 125 clients can be supported.
+
+For applications looking for more scalable solution, we recommend to use [Unleash Proxy](#unleash-proxy-example).
+This proxy server sits between the server and clients. It requests to the server as a behalf of the client groups,
+so the nubmer of outbound requests can be greatly reduced.
+
+There is also an [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/295472) to give more
+capacity to the current rate limit.
+
+### Recovering from network errors
+
+In general, [Unleash clients](https://github.com/Unleash/unleash#unleash-sdks) have
+a fall-back mechanism when the server returns an error code.
+For example, `unleash-ruby-client` reads flag data from the local backup so that
+application can keep running in the current state.
+
+Please reads the documentation in a SDK project for more information.
+
+### Self-managed GitLab
+
+Functionality-wise, there are no differences. Both SaaS and self-managed behave the same.
+
+In terms of scalability, it's up to the spec of the GitLab instance.
+For example, GitLab.com runs on HA architecture so that it can handle a lot of requests concurrently,
+however, a self-managed instance runs on a low spec machine can't expect the same result.
+Please see [Reference architectures](../administration/reference_architectures/index.md)
+for more information.
diff --git a/doc/operations/incident_management/alerts.md b/doc/operations/incident_management/alerts.md
index b03955edf87..0ad2b5ecf3b 100644
--- a/doc/operations/incident_management/alerts.md
+++ b/doc/operations/incident_management/alerts.md
@@ -144,6 +144,7 @@ The following actions result in a system note:
 - [Updating the status of an alert](#update-an-alerts-status)
 - [Creating an incident based on an alert](#create-an-incident-from-an-alert)
 - [Assignment of an alert to a user](#assign-an-alert)
+- [Escalation of an alert to on-call responders](paging.md#escalating-an-alert)
 
 ![Alert Details Activity Feed](img/alert_detail_activity_feed_v13_5.png)
 
@@ -153,8 +154,26 @@ There are different actions available in GitLab to help triage and respond to al
 
 ### Update an alert's status
 
-The Alert detail view enables you to update the Alert Status.
-See [Create and manage alerts in GitLab](alerts.md) for more details.
+**Triggered** is the default status for new alerts. For users with the Developer role or higher, the
+alert status can be updated from these locations:
+
+- [Alert list](#alert-list): select the status dropdown corresponding to an alert, then select an
+  alternate status.
+- [Alert details page](#alert-details-page): select **Edit** in the right-hand side bar, then select
+  an alternate status.
+
+To stop email notifications for alert reoccurrences in projects with [email notifications enabled](paging.md#email-notifications-for-alerts),
+[change the alert's status](alerts.md#update-an-alerts-status) away from **Triggered**.
+
+In projects with GitLab Premium, on-call responders can respond to [alert pages](paging.md#escalating-an-alert)
+by changing the status. Setting the status to:
+
+- **Resolved** silences all on-call pages for the alert.
+- **Acknowledged** limits on-call pages based on the project's [escalation policy](escalation_policies.md).
+- **Triggered** from **Resolved** restarts the alert escalating from the beginning.
+
+For [alerts with an associated incident](alerts.md#create-an-incident-from-an-alert),
+updating the alert status also updates the incident status.
 
 ### Create an incident from an alert
 
@@ -165,8 +184,10 @@ description populated from an alert. To create the issue,
 select the **Create Issue** button. You can then view the issue from the
 alert by selecting the **View Issue** button.
 
-Closing a GitLab issue associated with an alert changes the alert's status to
-Resolved. See [Create and manage alerts in GitLab](alerts.md) for more details
+You can also [create incidents for alerts automatically](incidents.md#create-incidents-automatically).
+
+Closing a GitLab issue associated with an alert [changes the alert's status](#update-an-alerts-status) to
+**Resolved**. See [Alert List](#alert-list) for more details
 about alert statuses.
 
 ### Assign an alert
@@ -196,7 +217,7 @@ To assign an alert:
 
 After completing their portion of investigating or fixing the alert, users can
 unassign themselves from the alert. To remove an assignee, select **Edit** next to the **Assignee** dropdown menu
-and deselect the user from the list of assignees, or select **Unassigned**.
+and clear the user from the list of assignees, or select **Unassigned**.
 
 ### Create a to-do item from an alert
 
@@ -217,13 +238,3 @@ add a to-do item:
    ![Alert Details Add a to do](img/alert_detail_add_todo_v13_9.png)
 
 To view your To-Do List, on the top bar, select **To-Do List** (**{todo-done}**).
-
-## View the environment that generated the alert
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232492) in GitLab 13.5 behind a feature flag, disabled by default.
-> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/232492) in GitLab 13.6.
-
-WARNING:
-This feature might not be available to you. Check the **version history** note above for details.
-
-The environment information and the link are displayed in the [Alert Details tab](#alert-details-tab).
diff --git a/doc/operations/incident_management/img/incident_list_v14_9.png b/doc/operations/incident_management/img/incident_list_v14_9.png
new file mode 100644
index 00000000000..4cf6f0e6522
--- /dev/null
+++ b/doc/operations/incident_management/img/incident_list_v14_9.png
diff --git a/doc/operations/incident_management/img/incident_metrics_tab_text_link_modal_v14_9.png b/doc/operations/incident_management/img/incident_metrics_tab_text_link_modal_v14_9.png
new file mode 100644
index 00000000000..1b045a13fc5
--- /dev/null
+++ b/doc/operations/incident_management/img/incident_metrics_tab_text_link_modal_v14_9.png
diff --git a/doc/operations/incident_management/img/metric_image_url_dialog_v13_8.png b/doc/operations/incident_management/img/metric_image_url_dialog_v13_8.png
deleted file mode 100644
index 732921bbb9f..00000000000
--- a/doc/operations/incident_management/img/metric_image_url_dialog_v13_8.png
+++ /dev/null
diff --git a/doc/operations/incident_management/incidents.md b/doc/operations/incident_management/incidents.md
index e142d060d87..c7ed386f505 100644
--- a/doc/operations/incident_management/incidents.md
+++ b/doc/operations/incident_management/incidents.md
@@ -54,7 +54,7 @@ GitLab to create incident automatically whenever an alert is triggered:
 1. Check the **Create an incident** checkbox.
 1. To customize the incident, select an
    [issue template](../../user/project/description_templates.md#create-an-issue-template).
-1. To send [an email notification](paging.md#email-notifications) to users
+1. To send [an email notification](paging.md#email-notifications-for-alerts) to users
    with the Developer role, select
    **Send a separate email notification to Developers**. Email notifications are
    also sent to users with the **Maintainer** and **Owner** roles.
@@ -89,9 +89,9 @@ For users with at least Guest [permissions](../../user/permissions.md), the
 Incident list is available at **Monitor > Incidents**
 in your project's sidebar. The list contains the following metrics:
 
-![Incident List](img/incident_list_v13_5.png)
+![Incident List](img/incident_list_v14_9.png)
 
-- **Status** - To filter incidents by their status, click **Open**, **Closed**,
+- **State** - To filter incidents by their state, select **Open**, **Closed**,
   or **All** above the incident list.
 - **Search** - The Incident list supports a simple free text search, which filters
   on the **Title** and **Incident** fields.
@@ -108,6 +108,13 @@ in your project's sidebar. The list contains the following metrics:
 
 - **Incident** - The description of the incident, which attempts to capture the
   most meaningful data.
+- **Status** - The status of the incident, which can be one of the following values:
+  - **Triggered**
+  - **Acknowledged**
+  - **Resolved**
+
+  In GitLab Premium, this field is also linked to [on-call escalation](paging.md#escalating-an-incident) for the incident.
+
 - **Date created** - How long ago the incident was created. This field uses the
   standard GitLab pattern of `X time ago`, but is supported by a granular date/time
   tooltip depending on the user's locale.
@@ -173,9 +180,11 @@ charts in the **Metrics** tab:
 
 ![Incident Metrics tab](img/incident_metrics_tab_v13_8.png)
 
-When you upload an image, you can associate it with a URL to the original graph. Users can access the original graph by clicking the image:
+When you upload an image, you can associate the image with text or a link to the original graph.  
 
-![Metric image URL dialog](img/metric_image_url_dialog_v13_8.png)
+![Text link modal](img/incident_metrics_tab_text_link_modal_v14_9.png)
+
+If you add a link, you can access the original graph by clicking the hyperlink above the uploaded image.
 
 ### Alert details
 
@@ -226,7 +235,7 @@ There are different actions available to help triage and respond to incidents.
 ### Assign incidents
 
 Assign incidents to users that are actively responding. Select **Edit** in the
-right-hand side bar to select or deselect assignees.
+right-hand side bar to select or clear assignees.
 
 ### Associate a milestone
 
@@ -244,6 +253,40 @@ You can also change the severity using the [`/severity` quick action](../../user
 Add a to-do for incidents that you want to track in your to-do list. Click the
 **Add a to do** button at the top of the right-hand side bar to add a to-do item.
 
+### Change incident status
+
+> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5716) in GitLab 14.9.
+
+For users with the Developer role or higher, select **Edit** in the **Status** section of the
+right-hand side bar of an incident, then select a status. **Triggered** is the default status for
+new incidents.
+
+In projects with GitLab Premium, on-call responders can respond to [incident pages](paging.md#escalating-an-incident)
+by changing the status. Setting the status to:
+
+- **Resolved** silences on-call pages for the alert.
+- **Acknowledged** limits on-call pages based on the selected [escalation policy](#change-escalation-policy).
+- **Triggered** from **Resolved** restarts the incident escalating from the beginning.
+
+For [incidents created from alerts](alerts.md#create-an-incident-from-an-alert),
+updating the incident status also updates the alert status.
+
+## Change escalation policy **(PREMIUM)**
+
+> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5716) in GitLab 14.9.
+
+For users with the Developer role or higher, select **Edit** in the **Escalation policy** section of
+the right-hand side bar of an incident, then select a policy. By default, new incidents do not have
+an escalation policy selected.
+
+Selecting an escalation policy updates the incident status to **Triggered** and begins
+[escalating the incident to on-call responders](paging.md#escalating-an-incident).
+Deselecting an escalation policy halts escalation. Refer to the [incident status](#change-incident-status)
+to manage on-call paging once escalation has begun.
+
+For [incidents created from alerts](alerts.md#create-an-incident-from-an-alert),
+the incident's escalation policy reflects the alert's escalation policy and cannot be changed.
+
 ### Manage incidents from Slack
 
 Slack slash commands allow you to control GitLab and view GitLab content without leaving Slack.
diff --git a/doc/operations/incident_management/oncall_schedules.md b/doc/operations/incident_management/oncall_schedules.md
index 84ab5da77df..9b2e9159429 100644
--- a/doc/operations/incident_management/oncall_schedules.md
+++ b/doc/operations/incident_management/oncall_schedules.md
@@ -10,8 +10,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 Use on-call schedule management to create schedules for responders to rotate on-call
 responsibilities. Maintain the availability of your software services by putting your teams on-call.
-With an on-call schedule, your team is notified immediately when things go wrong so they can quickly
-respond to service outages and disruptions.
+With [escalation policies](escalation_policies.md) and on-call schedules, your team is notified immediately
+when things go wrong so they can quickly respond to service outages and disruptions.
 
 To use on-call schedules:
 
@@ -111,9 +111,7 @@ Hover over any rotation shift participants in the schedule to view their individ
 
 ## Page an on-call responder
 
-When an alert is created in a project, GitLab sends an email to the on-call responder(s) in the
-on-call schedule for that project. If there is no schedule or no one on-call in that schedule at the
-time the alert is triggered, no email is sent.
+See [Paging](paging.md#paging) for more details.
 
 ## Removal or deletion of on-call user
 
diff --git a/doc/operations/incident_management/paging.md b/doc/operations/incident_management/paging.md
index b6f77de3b4f..27854a9e201 100644
--- a/doc/operations/incident_management/paging.md
+++ b/doc/operations/incident_management/paging.md
@@ -21,7 +21,7 @@ receive a **single** page via Slack. To set up Slack notifications on your mobil
 device, make sure to enable notifications for the Slack app on your phone so
 you never miss a page.
 
-## Email notifications
+## Email notifications for alerts
 
 Email notifications are available in projects for triggered alerts. Project
 members with the **Owner** or **Maintainer** roles have the option to receive
@@ -34,8 +34,30 @@ a single email notification for new alerts.
    **Send a single email notification to Owners and Maintainers for new alerts** checkbox.
 1. Select **Save changes**.
 
+[Update the alert's status](alerts.md#update-an-alerts-status) to manage email notifications for an alert.
+
 ## Paging **(PREMIUM)**
 
-In projects that have an [on-call schedule](oncall_schedules.md) configured, on-call responders are
-paged through email for triggered alerts. The on-call responder(s) receive one email for triggered
-alerts.
+In projects that have an [escalation policy](escalation_policies.md) configured, on-call responder(s)
+can be automatically paged about critical problems through email.
+
+### Escalating an alert
+
+When an alert is triggered, it begins escalating to the on-call responders immediately.
+For each escalation rule in the project's escalation policy, the designated on-call
+responders receive one email when the rule fires. You can respond to a page
+or stop alert escalations by [updating the alert's status](alerts.md#update-an-alerts-status).
+
+### Escalating an incident
+
+> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5716) in GitLab 14.9.
+
+For incidents, paging on-call responders is optional for each individual incident.
+To begin escalating the incident, [set the incident's escalation policy](incidents.md#change-escalation-policy).
+For each escalation rule, the designated on-call responders receive one email when
+the rule fires. You can respond to a page or stop incident escalations by
+[updating the incident's status](incidents.md#change-incident-status) or, if applicable,
+[unsetting the incident's escalation policy](incidents.md#change-escalation-policy).
+
+To avoid duplicate pages, [incidents created from alerts](alerts.md#create-an-incident-from-an-alert) do not support independent escalation.
+Instead, the status and escalation policy fields are synced between the alert and the incident.
diff --git a/doc/operations/metrics/dashboards/panel_types.md b/doc/operations/metrics/dashboards/panel_types.md
index 09e969e8af6..734b560bf13 100644
--- a/doc/operations/metrics/dashboards/panel_types.md
+++ b/doc/operations/metrics/dashboards/panel_types.md
@@ -234,7 +234,7 @@ For example, if you have a query value of `53.6`, adding `%` as the unit results
 ## Gauge
 
 WARNING:
-This panel type is an _alpha_ feature, and is subject to change at any time
+This panel type is an [Alpha](../../../policy/alpha-beta-support.md#alpha-features) feature, and is subject to change at any time
 without prior notice!
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207044) in GitLab 13.3.
diff --git a/doc/operations/metrics/dashboards/templating_variables.md b/doc/operations/metrics/dashboards/templating_variables.md
index 531693d032f..d751a96f379 100644
--- a/doc/operations/metrics/dashboards/templating_variables.md
+++ b/doc/operations/metrics/dashboards/templating_variables.md
@@ -27,7 +27,7 @@ described [in Using Variables](variables.md).
 ## `text` variable type
 
 WARNING:
-This variable type is an _alpha_ feature, and is subject to change at any time
+This variable type is an [Alpha](../../../policy/alpha-beta-support.md#alpha-features) feature, and is subject to change at any time
 without prior notice!
 
 For each `text` variable defined in the dashboard YAML, a free text field displays
@@ -64,7 +64,7 @@ templating:
 ## `custom` variable type
 
 WARNING:
-This variable type is an _alpha_ feature, and is subject to change at any time
+This variable type is an [Alpha](../../../policy/alpha-beta-support.md#alpha-features) feature, and is subject to change at any time
 without prior notice!
 
 Each `custom` variable defined in the dashboard YAML creates a dropdown
@@ -112,7 +112,7 @@ templating:
 ## `metric_label_values` variable type
 
 WARNING:
-This variable type is an _alpha_ feature, and is subject to change at any time
+This variable type is an [Alpha](../../../policy/alpha-beta-support.md#alpha-features) feature, and is subject to change at any time
 without prior notice!
 
 ### Full syntax