2020-08-18 17:09:57 -04:00
---
stage: Monitor
2022-01-27 13:14:37 -05:00
group: Respond
2020-11-26 01:09:20 -05:00
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
2020-08-18 17:09:57 -04:00
---
2021-01-28 01:08:59 -05:00
# Alerts **(FREE)**
2020-10-13 20:08:48 -04:00
2020-11-18 10:09:08 -05:00
Alerts are a critical entity in your incident management workflow. They represent a notable event that might indicate a service outage or disruption. GitLab provides a list view for triage and detail view for deeper investigation of what happened.
2020-10-13 20:08:48 -04:00
## Alert List
2020-08-18 17:09:57 -04:00
2022-01-30 19:14:49 -05:00
Users with at least the Developer role can
2021-06-15 14:09:57 -04:00
access the Alert list at **Monitor > Alerts** in your project's
2020-10-13 20:08:48 -04:00
sidebar. The Alert list displays alerts sorted by start time, but
you can change the sort order by clicking the headers in the Alert list.
2020-08-18 17:09:57 -04:00
The alert list displays the following information:
2020-09-24 14:09:51 -04:00
![Alert List ](img/alert_list_v13_1.png )
2020-08-18 17:09:57 -04:00
2020-09-30 20:10:16 -04:00
- **Search**: The alert list supports a simple free text search on the title,
2020-08-18 17:09:57 -04:00
description, monitoring tool, and service fields.
([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213884) in GitLab 13.1.)
2020-09-30 20:10:16 -04:00
- **Severity**: The current importance of a alert and how much attention it
should receive. For a listing of all statuses, read [Alert Management severity ](#alert-severity ).
- **Start time**: How long ago the alert fired. 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.
- **Alert description**: The description of the alert, which attempts to
capture the most meaningful data.
- **Event count**: The number of times that an alert has fired.
- **Issue**: A link to the incident issue that has been created for the alert.
- **Status**: The current status of the alert:
2021-04-27 17:10:09 -04:00
- **Triggered**: Investigation has not started.
2020-08-18 17:09:57 -04:00
- **Acknowledged**: Someone is actively investigating the problem.
- **Resolved**: No further work is required.
2021-04-27 17:10:09 -04:00
- **Ignored**: No action will be taken on the alert.
2020-09-24 14:09:51 -04:00
2020-12-07 22:09:37 -05:00
NOTE:
2020-09-24 14:09:51 -04:00
Check out a live example available from the
[`tanuki-inc` project page ](https://gitlab-examples-ops-incident-setup-everyone-tanuki-inc.34.69.64.147.nip.io/ )
2020-09-03 14:08:29 -04:00
in GitLab to examine alerts in action.
2020-08-18 17:09:57 -04:00
## Alert severity
Each level of alert contains a uniquely shaped and color-coded icon to help
you identify the severity of a particular alert. These severity icons help you
immediately identify which alerts you should prioritize investigating:
2020-09-24 14:09:51 -04:00
![Alert Management Severity System ](img/alert_management_severity_v13_0.png )
2020-08-18 17:09:57 -04:00
Alerts contain one of the following icons:
2021-09-29 17:12:32 -04:00
<!-- vale gitlab.SubstitutionWarning = NO -->
2020-09-30 20:10:16 -04:00
| Severity | Icon | Color (hexadecimal) |
|----------|-------------------------|---------------------|
| Critical | ** {severity-critical}** | `#8b2615` |
| High | ** {severity-high}** | `#c0341d` |
| Medium | ** {severity-medium}** | `#fca429` |
| Low | ** {severity-low}** | `#fdbc60` |
| Info | ** {severity-info}** | `#418cd8` |
| Unknown | ** {severity-unknown}** | `#bababa` |
2021-09-29 17:12:32 -04:00
<!-- vale gitlab.SubstitutionWarning = YES -->
2020-09-30 20:10:16 -04:00
## Alert details page
2020-11-08 22:09:03 -05:00
Navigate to the Alert details view by visiting the [Alert list ](alerts.md )
2022-01-30 19:14:49 -05:00
and selecting an alert from the list. You need at least the Developer role
2020-09-30 20:10:16 -04:00
to access alerts.
2020-12-07 22:09:37 -05:00
NOTE:
2020-09-30 20:10:16 -04:00
To review live examples of GitLab alerts, visit the
[alert list ](https://gitlab.com/gitlab-examples/ops/incident-setup/everyone/tanuki-inc/-/alert_management )
for this demo project. Select any alert in the list to examine its alert details
page.
Alerts provide **Overview** and **Alert details** tabs to give you the right
amount of information you need.
2020-10-15 20:08:56 -04:00
### Alert details tab
2020-09-30 20:10:16 -04:00
2020-12-09 07:09:42 -05:00
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 monitoring tool. The second section displays the full alert payload.
2020-09-30 20:10:16 -04:00
2020-10-15 20:08:56 -04:00
### Metrics tab
2020-09-30 20:10:16 -04:00
2020-10-15 20:08:56 -04:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217768) in GitLab 13.2.
2021-06-18 14:10:13 -04:00
The **Metrics** tab displays a metrics chart for alerts coming from Prometheus. If the alert originated from any other tool, the **Metrics** tab is empty.
For externally-managed Prometheus instances, you must configure your alerting rules to display a chart in the alert. For information about how to configure
2020-10-15 20:08:56 -04:00
your alerting rules, see [Embedding metrics based on alerts in incident issues ](../metrics/embed.md#embedding-metrics-based-on-alerts-in-incident-issues ). See
2021-06-18 14:10:13 -04:00
[External Prometheus instances ](../metrics/alerts.md#external-prometheus-instances ) for information about setting up alerts for your self-managed Prometheus
2020-10-15 20:08:56 -04:00
instance.
2021-08-13 20:10:05 -04:00
Prerequisite:
2022-01-30 19:14:49 -05:00
- You must have at least the Developer role.
2021-08-13 20:10:05 -04:00
2020-10-15 20:08:56 -04:00
To view the metrics for an alert:
2021-08-13 20:10:05 -04:00
1. On the top bar, select **Menu > Projects** and find your project.
1. On the left sidebar, select **Monitor > Alerts** .
2020-10-15 20:08:56 -04:00
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
2021-01-29 19:09:06 -05:00
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/201846) in GitLab Ultimate 12.8.
> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/217768) in GitLab 13.3.
2021-10-01 20:10:00 -04:00
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25455) from GitLab Ultimate to GitLab Free in 12.9.
2020-10-15 20:08:56 -04:00
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.
2020-09-30 20:10:16 -04:00
2021-08-13 20:10:05 -04:00
Prerequisite:
2022-01-30 19:14:49 -05:00
- You must have at least the Developer role.
2021-08-13 20:10:05 -04:00
2020-10-15 20:08:56 -04:00
To view the logs for an alert:
2021-08-13 20:10:05 -04:00
1. On the top bar, select **Menu > Projects** and find your project.
1. On the left sidebar, select **Monitor > Alerts** .
2020-10-15 20:08:56 -04:00
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.
2020-11-18 10:09:08 -05:00
The following actions result in a system note:
2020-10-15 20:08:56 -04:00
- [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 )
2020-09-30 20:10:16 -04:00
2020-10-15 20:08:56 -04:00
![Alert Details Activity Feed ](img/alert_detail_activity_feed_v13_5.png )
## Alert actions
2020-11-18 10:09:08 -05:00
There are different actions available in GitLab to help triage and respond to alerts.
2020-10-15 20:08:56 -04:00
### Update an alert's status
2020-09-30 20:10:16 -04:00
The Alert detail view enables you to update the Alert Status.
2020-11-08 22:09:03 -05:00
See [Create and manage alerts in GitLab ](alerts.md ) for more details.
2020-09-30 20:10:16 -04:00
2020-10-15 20:08:56 -04:00
### Create an incident from an alert
2020-09-30 20:10:16 -04:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217745) in GitLab 13.1.
The Alert detail view enables you to create an issue with a
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
about alert statuses.
2020-10-15 20:08:56 -04:00
### Assign an alert
2020-09-30 20:10:16 -04:00
> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in GitLab 13.1.
In large teams, where there is shared ownership of an alert, it can be
2020-10-15 20:08:56 -04:00
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:
2020-09-30 20:10:16 -04:00
2021-08-13 20:10:05 -04:00
1. Display the list of current alerts:
1. On the top bar, select **Menu > Projects** and find your project.
1. On the left sidebar, select **Monitor > Alerts** .
2020-09-30 20:10:16 -04:00
2021-04-22 11:09:56 -04:00
1. Select your desired alert to display its details.
2020-09-30 20:10:16 -04:00
2020-11-08 22:09:03 -05:00
![Alert Details View Assignee(s) ](img/alert_details_assignees_v13_1.png )
2020-09-30 20:10:16 -04:00
1. If the right sidebar is not expanded, select
2021-08-13 20:10:05 -04:00
**Expand sidebar** (**{angle-double-right}**) to expand it.
2021-04-22 11:09:56 -04:00
2021-08-13 20:10:05 -04:00
1. On the right sidebar, locate the **Assignee** , and then select **Edit** .
From the list, select each user you want to assign to the alert.
2020-10-02 14:08:56 -04:00
GitLab creates a [to-do item ](../../user/todos.md ) for each user.
2020-09-30 20:10:16 -04:00
2020-10-15 20:08:56 -04:00
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
2020-09-30 20:10:16 -04:00
and deselect the user from the list of assignees, or select **Unassigned** .
2020-10-28 14:08:52 -04:00
### Create a to-do item from an alert
2020-09-30 20:10:16 -04:00
> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in GitLab 13.1.
You can manually create [To-Do list items ](../../user/todos.md ) for yourself
from the Alert details screen, and view them later on your **To-Do List** . To
2020-10-28 14:08:52 -04:00
add a to-do item:
2020-09-30 20:10:16 -04:00
2021-08-13 20:10:05 -04:00
1. Display the list of current alerts:
1. On the top bar, select **Menu > Projects** and find your project.
1. On the left sidebar, select **Monitor > Alerts** .
2020-09-30 20:10:16 -04:00
1. Select your desired alert to display its **Alert Management Details View** .
2021-08-13 20:10:05 -04:00
1. On the right sidebar, select **Add a to do** :
2020-09-30 20:10:16 -04:00
2021-01-28 01:08:59 -05:00
![Alert Details Add a to do ](img/alert_detail_add_todo_v13_9.png )
2020-09-30 20:10:16 -04:00
2021-08-13 20:10:05 -04:00
To view your To-Do List, on the top bar, select **To-Do List** (**{todo-done}**).