debian-mirror-gitlab/doc/user/project/integrations/generic_alerts.md

125 lines
5.3 KiB
Markdown
Raw Normal View History

2020-05-24 23:13:21 +05:30
---
stage: Monitor
group: Health
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
---
2020-03-13 15:44:24 +05:30
# Generic alerts integration
2019-12-04 20:38:33 +05:30
2020-06-23 00:09:42 +05:30
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13203) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.4.
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/42640) to [GitLab Core](https://about.gitlab.com/pricing/) in 12.8.
2019-12-04 20:38:33 +05:30
GitLab can accept alerts from any source via a generic webhook receiver.
When you set up the generic alerts integration, a unique endpoint will
be created which can receive a payload in JSON format, and will in turn
create an issue with the payload in the body of the issue. You can always
[customize the payload](#customizing-the-payload) to your liking.
The entire payload will be posted in the issue discussion as a comment
authored by the GitLab Alert Bot.
2020-07-28 23:09:34 +05:30
NOTE: **Note:**
In GitLab versions 13.1 and greater, you can configure
[External Prometheus instances](../../../operations/metrics/alerts.md#external-prometheus-instances)
to use this endpoint.
2020-06-23 00:09:42 +05:30
2019-12-04 20:38:33 +05:30
## Setting up generic alerts
2020-07-28 23:09:34 +05:30
To obtain credentials for setting up a generic alerts integration:
2019-12-04 20:38:33 +05:30
2020-07-28 23:09:34 +05:30
- Sign in to GitLab as a user with maintainer [permissions](../../permissions.md) for a project.
- Navigate to the **Operations** page for your project, depending on your installed version of GitLab:
- *In GitLab versions 13.1 and greater,* navigate to **{settings}** **Settings > Operations** in your project.
- *In GitLab versions prior to 13.1,* navigate to **{settings}** **Settings > Integrations** in your project. GitLab will display a banner encouraging you to enable the Alerts endpoint in **{settings}** **Settings > Operations** instead.
- Click **Alerts endpoint**.
- Toggle the **Active** alert setting to display the **URL** and **Authorization Key** for the webhook configuration.
2019-12-04 20:38:33 +05:30
## Customizing the payload
2020-06-23 00:09:42 +05:30
You can customize the payload by sending the following parameters. All fields other than `title` are optional:
2019-12-04 20:38:33 +05:30
| Property | Type | Description |
| -------- | ---- | ----------- |
2020-05-24 23:13:21 +05:30
| `title` | String | The title of the incident. Required. |
2019-12-04 20:38:33 +05:30
| `description` | String | A high-level summary of the problem. |
| `start_time` | DateTime | The time of the incident. If none is provided, a timestamp of the issue will be used. |
| `service` | String | The affected service. |
| `monitoring_tool` | String | The name of the associated monitoring tool. |
2020-03-13 15:44:24 +05:30
| `hosts` | String or Array | One or more hosts, as to where this incident occurred. |
2020-05-24 23:13:21 +05:30
| `severity` | String | The severity of the alert. Must be one of `critical`, `high`, `medium`, `low`, `info`, `unknown`. Default is `critical`. |
2020-06-23 00:09:42 +05:30
| `fingerprint` | String or Array | The unique identifier of the alert. This can be used to group occurrences of the same alert. |
2020-05-24 23:13:21 +05:30
2020-07-28 23:09:34 +05:30
You can also add custom fields to the alert's payload. The values of extra parameters
are not limited to primitive types, such as strings or numbers, but can be a nested
JSON object. For example:
```json
{ "foo": { "bar": { "baz": 42 } } }
```
2020-05-24 23:13:21 +05:30
TIP: **Payload size:**
Ensure your requests are smaller than the [payload application limits](../../../administration/instance_limits.md#generic-alert-json-payloads).
2019-12-04 20:38:33 +05:30
Example request:
2020-03-13 15:44:24 +05:30
```shell
2019-12-21 20:55:43 +05:30
curl --request POST \
--data '{"title": "Incident title"}' \
2019-12-26 22:10:19 +05:30
--header "Authorization: Bearer <authorization_key>" \
2019-12-21 20:55:43 +05:30
--header "Content-Type: application/json" \
<url>
2019-12-04 20:38:33 +05:30
```
2019-12-26 22:10:19 +05:30
The `<authorization_key>` and `<url>` values can be found when [setting up generic alerts](#setting-up-generic-alerts).
2019-12-04 20:38:33 +05:30
Example payload:
```json
{
"title": "Incident title",
"description": "Short description of the incident",
"start_time": "2019-09-12T06:00:55Z",
"service": "service affected",
"monitoring_tool": "value",
"hosts": "value",
2020-06-23 00:09:42 +05:30
"severity": "high",
2020-07-28 23:09:34 +05:30
"fingerprint": "d19381d4e8ebca87b55cda6e8eee7385",
"foo": {
"bar": {
"baz": 42
}
}
2019-12-04 20:38:33 +05:30
}
```
2020-07-28 23:09:34 +05:30
## Triggering test alerts
> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in GitLab Core in 13.2.
After a [project maintainer or owner](#setting-up-generic-alerts)
[configures generic alerts](#setting-up-generic-alerts), you can trigger a
test alert to confirm your integration works properly.
1. Sign in as a user with Developer or greater [permissions](../../../user/permissions.md).
1. Navigate to **{settings}** **Settings > Operations** in your project.
1. Click **Alerts endpoint** to expand the section.
1. Enter a sample payload in **Alert test payload** (valid JSON is required).
1. Click **Test alert payload**.
GitLab displays an error or success message, depending on the outcome of your test.
## Automatic grouping of identical alerts **(PREMIUM)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214557) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2.
In GitLab versions 13.2 and greater, GitLab groups alerts based on their payload.
When an incoming alert contains the same payload as another alert (excluding the
`start_time` and `hosts` attributes), GitLab groups these alerts together and
displays a counter on the
[Alert Management List](../operations/alert_management.md#alert-management-list)
and details pages.
If the existing alert is already `resolved`, then a new alert will be created instead.
![Alert Management List](../operations/img/alert_list_v13_1.png)