1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
---
stage: Monitor
group: Respond
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
---
# Alerts **(FREE)**
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.
## Alert list
Users with at least the Developer role can
access the Alert list at **Monitor > Alerts** in your project's
sidebar. The Alert list displays alerts sorted by start time, but
you can change the sort order by selecting the headers in the Alert list.
The alert list displays the following information:
- **Search**: The alert list supports a simple free text search on the title,
description, monitoring tool, and service fields.
([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213884) in GitLab 13.1.)
- **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:
- **Triggered**: Investigation has not started.
- **Acknowledged**: Someone is actively investigating the problem.
- **Resolved**: No further work is required.
- **Ignored**: No action is taken on the alert.
## 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:
Alerts contain one of the following icons:
<!-- vale gitlab.SubstitutionWarning = NO -->
| 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` |
<!-- vale gitlab.SubstitutionWarning = YES -->
## Alert details page
Navigate to the Alert details view by visiting the [Alert list](alerts.md)
and selecting an alert from the list. You need at least the Developer role
to access alerts.
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.
### Alert details tab
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.
### Metrics tab
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217768) in GitLab 13.2.
> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/340852) in GitLab 14.10. In GitLab 14.9 and earlier, this tab shows a metrics chart for alerts coming from Prometheus.
In many cases, alerts are associated to metrics. You can upload screenshots of metric
charts in the **Metrics** tab.
To do so, either:
- Select **upload** and then select an image from your file browser.
- Drag a file from your file browser and drop it in the drop zone.
When you upload an image, you can add text to the image and link it to the original graph.
If you add a link, it is shown above the uploaded image.
### 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 result in a system note:
- [Updating the status of an alert](#change-an-alerts-status)
- [Creating an incident based on an alert](manage_incidents.md#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 actions
There are different actions available in GitLab to help triage and respond to alerts.
### Change an alert's status
You can change the status of an alert.
The available statuses are:
- Triggered (default for new alerts)
- Acknowledged
- Resolved
Prerequisites:
- You must have at least the Developer role.
To change an alert's status:
- From the [alert list](#alert-list):
1. In the **Status** column, next to an alert, select the status dropdown list.
1. Select a status.
- From the [alert details page](#alert-details-page):
1. On the right sidebar, select **Edit**.
1. Select a status.
To stop email notifications for alert recurrences in projects with [email notifications enabled](paging.md#email-notifications-for-alerts),
change the alert's status away from **Triggered**.
#### Resolve an alert by closing the linked incident
Prerequisites:
- You must have at least the Reporter role.
When you [close an incident](manage_incidents.md#close-an-incident) that is linked to an alert,
GitLab [changes the alert's status](#change-an-alerts-status) to **Resolved**.
You are then credited with the alert's status change.
#### As an on-call responder **(PREMIUM)**
On-call responders can respond to [alert pages](paging.md#escalating-an-alert)
by changing the alert status.
Changing the status has the following effects:
- To **Acknowledged**: limits on-call pages based on the project's [escalation policy](escalation_policies.md).
- To **Resolved**: silences all on-call pages for the alert.
- From **Resolved** to **Triggered**: restarts the alert escalating.
In GitLab 15.1 and earlier, updating the status of an [alert with an associated incident](manage_incidents.md#from-an-alert)
also updates the incident status. In [GitLab 15.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/356057),
the incident status is independent and does not update when the alert status changes.
### Assign an alert
> [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
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. Display the list of current alerts:
1. On the top bar, select **Main menu > Projects** and find your project.
1. On the left sidebar, select **Monitor > Alerts**.
1. Select your desired alert to display its details.
1. If the right sidebar is not expanded, select
**Expand sidebar** (**{chevron-double-lg-right}**) to expand it.
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.
GitLab creates a [to-do item](../../user/todos.md) for each user.
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 list
and clear the user from the list of assignees, or select **Unassigned**.
### Create a to-do item from an alert
> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in GitLab 13.1.
You can manually create a [to-do item](../../user/todos.md) for yourself
from an alert, and view it later on your **To-Do List**.
To add a to-do item, on the right sidebar, select **Add a to do**.
|
