Merge branch 'sarahwaldner-master-patch-33437' into 'master'

Updates to alerts page in docs

See merge request gitlab-org/gitlab!45319

doc/operations/incident_management/alerts.md

@@ -76,22 +76,75 @@ page.
 Alerts provide **Overview** and **Alert details** tabs to give you the right
 amount of information you need.
 
-### Alert overview tab
+### Alert details tab
 
-The **Overview** tab provides basic information about the alert:
+The **Alert details** tab has two sections. The top section provides a short list of critical details such as the severity, start time, number of events, and originating monitorting tool. The second section displays the full alert payload.
 
-![Alert Detail Overview](./img/alert_detail_overview_v13_1.png)
+### Metrics tab
 
-### Alert details tab
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217768) in GitLab 13.2.
+
+The **Metrics** tab will display a metrics chart for alerts coming from Prometheus. If the alert originated from any other tool, the **Metrics** tab will be empty. To set up alerts for GitLab-managed Prometheus instances, see [Managed Prometheus instances](../metrics/alerts.md#managed-prometheus-instances). For externally-managed Prometheus instances, you will need to configure your alerting
+rules to display a chart in the alert. For information about how to configure
+your alerting rules, see [Embedding metrics based on alerts in incident issues](../metrics/embed.md#embedding-metrics-based-on-alerts-in-incident-issues). See
+[External Prometheus instances](../metrics/alerts.md#external-prometheus-instances)
+for information about setting up alerts for your self-managed Prometheus
+instance.
+
+To view the metrics for an alert:
+
+1. Sign in as a user with Developer or higher [permissions](../../user/permissions.md).
+1. Navigate to **Operations > Alerts**.
+1. Select the alert you want to view.
+1. Below the title of the alert, select the **Metrics** tab.
+
+![Alert Metrics View](img/alert_detail_metrics_v13_2.png)
+
+#### View an alert's logs
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/201846) in GitLab Ultimate 12.8. and [improved](https://gitlab.com/gitlab-org/gitlab/-/issues/217768) in GitLab 13.3.
+> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25455) to [GitLab Core](https://about.gitlab.com/pricing/) 12.9.
+
+Viewing logs from a metrics panel can be useful if you're triaging an
+application incident and need to [explore logs](../metrics/dashboards/index.md#chart-context-menu)
+from across your application. These logs help you understand what's affecting
+your application's performance and how to resolve any problems.
 
-![Alert Full Details](./img/alert_detail_full_v13_1.png)
+To view the logs for an alert:
+
+1. Sign in as a user with Developer or higher [permissions](../../user/permissions.md).
+1. Navigate to **Operations > Alerts**.
+1. Select the alert you want to view.
+1. Below the title of the alert, select the **Metrics** tab.
+1. Select the [menu](../metrics/dashboards/index.md#chart-context-menu) of
+   the metric chart to view options.
+1. Select **View logs**.
+
+### Activity feed tab
+
+> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in GitLab 13.1.
+
+The **Activity feed** tab is a log of activity on the alert. When you take action on an alert, this is logged as a system note. This gives you a linear
+timeline of the alert's investigation and assignment history.
+
+The following actions will 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)
 
-#### Update an alert's status
+![Alert Details Activity Feed](img/alert_detail_activity_feed_v13_5.png)
+
+## Alert actions
+
+There are different actions avilable in GitLab to help triage and respond to alerts.
+
+### 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.
 
-#### Create an issue from an alert
+### Create an incident from an alert
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217745) in GitLab 13.1.
 
@@ -104,16 +157,14 @@ 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
 about alert statuses.
 
-#### Update an alert's assignee
+### Assign an alert
 
 > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in GitLab 13.1.
 
-The Alert detail view allows users to update the Alert assignee.
-GitLab supports only a single assignee per alert.
-
 In large teams, where there is shared ownership of an alert, it can be
-difficult to track who is investigating and working on it. The Alert detail
-view enables you to update the Alert assignee:
+difficult to track who is investigating and working on it. Assigning alerts eases collaboration and delegation by indicating which user is owning the alert. GitLab supports only a single assignee per alert.
+
+To assign an alert:
 
 1. To display the list of current alerts, navigate to **Operations > Alerts**:
 
@@ -131,26 +182,11 @@ view enables you to update the Alert assignee:
 
    ![Alert Details View Assignee(s)](./img/alert_todo_assignees_v13_1.png)
 
-To remove an assignee, select **Edit** next to the **Assignee** dropdown menu
+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**.
 
-#### Alert system notes
-
-> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in GitLab 13.1.
-
-When you take action on an alert, this is logged as a system note,
-which is visible in the Alert Details view. This gives you a linear
-timeline of the alert's investigation and assignment history.
-
-The following actions will result in a system note:
-
-- [Updating the status of an alert](#update-an-alerts-status)
-- [Creating an issue based on an alert](#create-an-issue-from-an-alert)
-- [Assignment of an alert to a user](#update-an-alerts-assignee)
-
-![Alert Details View System Notes](./img/alert_detail_system_notes_v13_1.png)
-
-#### Create a to do from an alert
+### Create a to do from an alert
 
 > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in GitLab 13.1.
 
@@ -168,91 +204,6 @@ Select the **To-Do List** **{todo-done}** in the navigation bar to view your cur
 
 ![Alert Details Added to do](./img/alert_detail_added_todo_v13_1.png)
 
-#### View an alert's metrics data
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217768) in GitLab 13.2.
-
-To view the metrics for an alert:
-
-   1. Sign in as a user with Developer or higher [permissions](../../user/permissions.md).
-   1. Navigate to **Operations > Alerts**.
-   1. Select the alert you want to view.
-   1. Below the title of the alert, select the **Metrics** tab.
-
-![Alert Metrics View](img/alert_detail_metrics_v13_2.png)
-
-For GitLab-managed Prometheus instances, metrics data is available for the
-alert, making it easy to see surrounding behavior. For information about
-setting up alerts, see [Managed Prometheus instances](../metrics/alerts.md#managed-prometheus-instances).
-
-For externally-managed Prometheus instances, you can configure your alerting
-rules to display a chart in the alert. For information about how to configure
-your alerting rules, see [Embedding metrics based on alerts in incident issues](../metrics/embed.md#embedding-metrics-based-on-alerts-in-incident-issues). See
-[External Prometheus instances](../metrics/alerts.md#external-prometheus-instances)
-for information about setting up alerts for your self-managed Prometheus
-instance.
-
-### Use cases for assigning alerts
-
-Consider a team formed by different sections of monitoring, collaborating on a
-single application. After an alert surfaces, it's extremely important to route
-the alert to the team members who can address and resolve the alert.
-
-Assigning Alerts eases collaboration and delegation. All assignees are shown in
-your team's work-flows, and all assignees receive notifications, simplifying
-communication and ownership of the alert.
-
-After completing their portion of investigating or fixing the alert, users can
-unassign their account from the alert when their role is complete. You can
-update the alert on the [Alert list](./alerts.md) to reflect if the alert has
-been resolved.
-
-### View an alert's logs
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217768) in GitLab 13.3.
-
-To view the logs for an alert:
-
-   1. Sign in as a user with Developer or higher [permissions](../../user/permissions.md).
-   1. Navigate to **Operations > Alerts**.
-   1. Select the alert you want to view.
-   1. Below the title of the alert, select the **Metrics** tab.
-   1. Select the [menu](../metrics/dashboards/index.md#chart-context-menu) of
-      the metric chart to view options.
-   1. Select **View logs**.
-
-For additional information, see [View logs from metrics panel](#view-logs-from-metrics-panel).
-
-### Embed metrics in incidents and issues
-
-You can embed metrics anywhere [GitLab Markdown](../../user/markdown.md) is
-used, such as descriptions, comments on issues, and merge requests. Embedding
-metrics helps you share them when discussing incidents or performance issues.
-You can output the dashboard directly into any issue, merge request, epic, or
-any other Markdown text field in GitLab by
-[copying and pasting the link to the metrics dashboard](../metrics/embed.md#embedding-gitlab-managed-kubernetes-metrics).
-
-You can embed both [GitLab-hosted metrics](../metrics/embed.md) and
-[Grafana metrics](../metrics/embed_grafana.md) in incidents and issue
-templates.
-
-#### Context menu
-
-You can view more details about an embedded metrics panel from the context
-menu. To access the context menu, select the **{ellipsis_v}** **More actions**
-dropdown box above the upper right corner of the panel. For a list of options,
-see [Chart context menu](../metrics/dashboards/index.md#chart-context-menu).
-
-##### View logs from metrics panel
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/201846) in GitLab Ultimate 12.8.
-> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25455) to [GitLab Core](https://about.gitlab.com/pricing/) 12.9.
-
-Viewing logs from a metrics panel can be useful if you're triaging an
-application incident and need to [explore logs](../metrics/dashboards/index.md#chart-context-menu)
-from across your application. These logs help you understand what's affecting
-your application's performance and how to resolve any problems.
-
 ## View the environment that generated the alert
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232492) in GitLab 13.5.

doc/operations/incident_management/index.md

@@ -12,10 +12,6 @@ Incident Management enables developers to easily discover and view the alerts
 generated by their application. By surfacing alert information where the code is
 being developed, efficiency and awareness can be increased.
 
-GitLab offers solutions for handling incidents in your applications and services,
-such as [setting up Prometheus alerts](#configure-prometheus-alerts),
-[displaying metrics](./alerts.md#embed-metrics-in-incidents-and-issues), and sending notifications.
-
 ## Configure Prometheus alerts
 
 You can set up Prometheus alerts in: