diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-02-18 13:34:06 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-02-18 13:34:06 +0300 |
commit | 859a6fb938bb9ee2a317c46dfa4fcc1af49608f0 (patch) | |
tree | d7f2700abe6b4ffcb2dcfc80631b2d87d0609239 /doc/operations/incident_management | |
parent | 446d496a6d000c73a304be52587cd9bbc7493136 (diff) |
Add latest changes from gitlab-org/gitlab@13-9-stable-eev13.9.0-rc42
Diffstat (limited to 'doc/operations/incident_management')
-rw-r--r-- | doc/operations/incident_management/alert_details.md | 8 | ||||
-rw-r--r-- | doc/operations/incident_management/alert_integrations.md | 199 | ||||
-rw-r--r-- | doc/operations/incident_management/alert_notifications.md | 36 | ||||
-rw-r--r-- | doc/operations/incident_management/alerts.md | 11 | ||||
-rw-r--r-- | doc/operations/incident_management/generic_alerts.md | 8 | ||||
-rw-r--r-- | doc/operations/incident_management/img/alert_detail_add_todo_v13_1.png | bin | 16822 -> 0 bytes | |||
-rw-r--r-- | doc/operations/incident_management/img/alert_detail_add_todo_v13_9.png | bin | 0 -> 26763 bytes | |||
-rw-r--r-- | doc/operations/incident_management/incidents.md | 24 | ||||
-rw-r--r-- | doc/operations/incident_management/index.md | 6 | ||||
-rw-r--r-- | doc/operations/incident_management/integrations.md | 187 | ||||
-rw-r--r-- | doc/operations/incident_management/paging.md | 36 | ||||
-rw-r--r-- | doc/operations/incident_management/status_page.md | 2 |
12 files changed, 254 insertions, 263 deletions
diff --git a/doc/operations/incident_management/alert_details.md b/doc/operations/incident_management/alert_details.md deleted file mode 100644 index cd73e9e7e1f..00000000000 --- a/doc/operations/incident_management/alert_details.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: alerts.md ---- - -This document was moved to [another location](alerts.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/operations/incident_management/alert_integrations.md b/doc/operations/incident_management/alert_integrations.md index 0f695e7a6c9..bec0653d464 100644 --- a/doc/operations/incident_management/alert_integrations.md +++ b/doc/operations/incident_management/alert_integrations.md @@ -1,199 +1,8 @@ --- -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/#assignments +redirect_to: 'integrations.md' --- -# Alert integrations +This document was moved to [another location](integrations.md). -> - [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. - -GitLab can accept alerts from any source via a webhook receiver. This can be configured -generically or, in GitLab versions 13.1 and greater, you can configure -[External Prometheus instances](../metrics/alerts.md#external-prometheus-instances) -to use this endpoint. - -## Integrations list - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/245331) in [GitLab Core](https://about.gitlab.com/pricing/) 13.5. - -With Maintainer or higher [permissions](../../user/permissions.md), you can view -the list of configured alerts integrations by navigating to -**Settings > Operations** in your project's sidebar menu, and expanding **Alerts** section. -The list displays the integration name, type, and status (enabled or disabled): - -![Current Integrations](img/integrations_list_v13_5.png) - -## Configuration - -GitLab can receive alerts via a HTTP endpoint that you configure, -or the [Prometheus integration](#external-prometheus-integration). - -### Single HTTP Endpoint **CORE** - -Enabling the HTTP Endpoint in a GitLab projects activates it to -receive alert payloads in JSON format. You can always -[customize the payload](#customize-the-alert-payload-outside-of-gitlab) to your liking. - -1. Sign in to GitLab as a user with maintainer [permissions](../../user/permissions.md) - for a project. -1. Navigate to **Settings > Operations** in your project. -1. Expand the **Alerts** section, and in the **Integration** dropdown menu, select **Generic**. -1. Toggle the **Active** alert setting to display the **URL** and **Authorization Key** - for the webhook configuration. - -### HTTP Endpoints **PREMIUM** - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4442) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.6. - -In [GitLab Premium](https://about.gitlab.com/pricing/), you can create multiple -unique HTTP endpoints to receive alerts from any external source in JSON format, -and you can [customize the payload](#customize-the-alert-payload-outside-of-gitlab). - -1. Sign in to GitLab as a user with maintainer [permissions](../../user/permissions.md) - for a project. -1. Navigate to **Settings > Operations** in your project. -1. Expand the **Alerts** section. -1. For each endpoint you want to create: - - 1. In the **Integration** dropdown menu, select **HTTP Endpoint**. - 1. Name the integration. - 1. Toggle the **Active** alert setting to display the **URL** and **Authorization Key** - for the webhook configuration. You must also input the URL and Authorization Key - in your external service. - 1. _(Optional)_ To generate a test alert to test the new integration, enter a - sample payload, then click **Save and test alert payload**. Valid JSON is required. - 1. Click **Save Integration**. - -The new HTTP Endpoint displays in the [integrations list](#integrations-list). -You can edit the integration by selecting the **{pencil}** pencil icon on the right -side of the integrations list. - -### External Prometheus integration - -For GitLab versions 13.1 and greater, please read -[External Prometheus Instances](../metrics/alerts.md#external-prometheus-instances) -to configure alerts for this integration. - -## Customize the alert payload outside of GitLab - -For all integration types, you can customize the payload by sending the following -parameters. All fields are optional. If the incoming alert does not contain a value for the `Title` field, a default value of `New: Incident` will be applied. - -| Property | Type | Description | -| ------------------------- | --------------- | ----------- | -| `title` | String | The title of the incident. | -| `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 is used. | -| `end_time` | DateTime | For existing alerts only. When provided, the alert is resolved and the associated incident is closed. | -| `service` | String | The affected service. | -| `monitoring_tool` | String | The name of the associated monitoring tool. | -| `hosts` | String or Array | One or more hosts, as to where this incident occurred. | -| `severity` | String | The severity of the alert. Must be one of `critical`, `high`, `medium`, `low`, `info`, `unknown`. Default is `critical`. | -| `fingerprint` | String or Array | The unique identifier of the alert. This can be used to group occurrences of the same alert. | -| `gitlab_environment_name` | String | The name of the associated GitLab [environment](../../ci/environments/index.md). This can be used to associate your alert to your environment. | - -You can also add custom fields to the alert's payload. The values of extra -parameters aren't limited to primitive types (such as strings or numbers), but -can be a nested JSON object. For example: - -```json -{ "foo": { "bar": { "baz": 42 } } } -``` - -NOTE: -Ensure your requests are smaller than the -[payload application limits](../../administration/instance_limits.md#generic-alert-json-payloads). - -Example request: - -```shell -curl --request POST \ - --data '{"title": "Incident title"}' \ - --header "Authorization: Bearer <authorization_key>" \ - --header "Content-Type: application/json" \ - <url> -``` - -The `<authorization_key>` and `<url>` values can be found when configuring an alert integration. - -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", - "severity": "high", - "fingerprint": "d19381d4e8ebca87b55cda6e8eee7385", - "foo": { - "bar": { - "baz": 42 - } - } -} -``` - -## Triggering test alerts - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in GitLab Core in 13.2. - -After a [project maintainer or owner](../../user/permissions.md) -configures an integration, 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 > 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](incidents.md) -and details pages. - -If the existing alert is already `resolved`, GitLab creates a new alert instead. - -![Alert Management List](img/alert_list_v13_1.png) - -## Link to your Opsgenie Alerts - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. - -WARNING: -We are building deeper integration with Opsgenie and other alerting tools through -[HTTP endpoint integrations](#single-http-endpoint) so you can see alerts in -the GitLab interface. As a result, the previous direct link to Opsgenie Alerts from -the GitLab alerts list is deprecated in -GitLab versions [13.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/273657). - -You can monitor alerts using a GitLab integration with [Opsgenie](https://www.atlassian.com/software/opsgenie). - -If you enable the Opsgenie integration, you can't have other GitLab alert -services -active at the same time. - -To enable Opsgenie integration: - -1. Sign in as a user with Maintainer or Owner [permissions](../../user/permissions.md). -1. Navigate to **Operations > Alerts**. -1. In the **Integrations** select box, select **Opsgenie**. -1. Select the **Active** toggle. -1. In the **API URL** field, enter the base URL for your Opsgenie integration, - such as `https://app.opsgenie.com/alert/list`. -1. Select **Save changes**. - -After you enable the integration, navigate to the Alerts list page at -**Operations > Alerts**, and then select **View alerts in Opsgenie**. +<!-- This redirect file can be deleted after <2021-05-03>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/operations/incident_management/alert_notifications.md b/doc/operations/incident_management/alert_notifications.md index eaf606105d6..4f46c2bec71 100644 --- a/doc/operations/incident_management/alert_notifications.md +++ b/doc/operations/incident_management/alert_notifications.md @@ -1,36 +1,8 @@ --- -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/#assignments +redirect_to: 'paging.md' --- -# Paging and notifications +This document was moved to [another location](paging.md). -When there is a new alert or incident, it is important for a responder to be notified -immediately so they can triage and respond to the problem. Responders can receive -notifications using the methods described on this page. - -## Slack notifications - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216326) in GitLab 13.1. - -Responders can be paged via Slack using the -[Slack Notifications Service](../../user/project/integrations/slack.md), which you -can configure for new alerts and new incidents. After configuring, responders -receive a **single** page via Slack. To set up Slack notifications on your mobile -device, make sure to enable notifications for the Slack app on your phone so -you never miss a page. - -## Email notifications - -Email notifications are available in projects that have been -[configured to create incidents automatically](incidents.md#create-incidents-automatically) -for triggered alerts. Project members with the **Owner** or **Maintainer** roles are -sent an email notification automatically. (This is not configurable.) To optionally -send additional email notifications to project members with the **Developer** role: - -1. Navigate to **Settings > Operations**. -1. Expand the **Incidents** section. -1. In the **Alert Integration** tab, select the **Send a separate email notification to Developers** - check box. -1. Select **Save changes**. +<!-- This redirect file can be deleted after 2021-04-21 --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/operations/incident_management/alerts.md b/doc/operations/incident_management/alerts.md index a8852a02f2b..3c60c737309 100644 --- a/doc/operations/incident_management/alerts.md +++ b/doc/operations/incident_management/alerts.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Alerts +# 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. @@ -102,8 +102,9 @@ To view the metrics for an alert: #### 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. +> - [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. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25455) to GitLab Free 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) @@ -196,9 +197,9 @@ add a to-do item: 1. To display the list of current alerts, navigate to **Operations > Alerts**. 1. Select your desired alert to display its **Alert Management Details View**. -1. Select the **Add a To-Do** button in the right sidebar: +1. Select the **Add a to do** button in the right sidebar: - ![Alert Details Add a To-Do](img/alert_detail_add_todo_v13_1.png) + ![Alert Details Add a to do](img/alert_detail_add_todo_v13_9.png) Select the **To-Do List** **{todo-done}** in the navigation bar to view your current to-do list. diff --git a/doc/operations/incident_management/generic_alerts.md b/doc/operations/incident_management/generic_alerts.md deleted file mode 100644 index 44b1f4b088a..00000000000 --- a/doc/operations/incident_management/generic_alerts.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: alert_integrations.md ---- - -This document was moved to [another location](alert_integrations.md). - -<!-- This redirect file can be deleted after February 1, 2021. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/operations/incident_management/img/alert_detail_add_todo_v13_1.png b/doc/operations/incident_management/img/alert_detail_add_todo_v13_1.png Binary files differdeleted file mode 100644 index 39aa9e33728..00000000000 --- a/doc/operations/incident_management/img/alert_detail_add_todo_v13_1.png +++ /dev/null diff --git a/doc/operations/incident_management/img/alert_detail_add_todo_v13_9.png b/doc/operations/incident_management/img/alert_detail_add_todo_v13_9.png Binary files differnew file mode 100644 index 00000000000..5beb1cd0bfb --- /dev/null +++ b/doc/operations/incident_management/img/alert_detail_add_todo_v13_9.png diff --git a/doc/operations/incident_management/incidents.md b/doc/operations/incident_management/incidents.md index 3f6522b3f90..f0bb9a8e950 100644 --- a/doc/operations/incident_management/incidents.md +++ b/doc/operations/incident_management/incidents.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Incidents +# Incidents **(FREE)** Incidents are critical entities in incident management workflows. They represent a service disruption or outage that needs to be restored urgently. GitLab provides @@ -24,7 +24,7 @@ Incident, you have two options to do this manually. **From the Incidents List:** -> [Moved](https://gitlab.com/gitlab-org/monitor/health/-/issues/24) to GitLab core in 13.3. +> [Moved](https://gitlab.com/gitlab-org/monitor/health/-/issues/24) to GitLab Free in 13.3. - Navigate to **Operations > Incidents** and click **Create Incident**. - Create a new issue using the `incident` template available when creating it. @@ -36,9 +36,11 @@ Incident, you have two options to do this manually. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230857) in GitLab 13.4. -- Navigate to **Issues > List** and click **Create Issue**. -- Create a new issue using the `type` drop-down and select `Incident`. -- The page refreshes and the page only displays fields relevant to Incidents. +1. Go to **Issues > List**, and select **New issue**. +1. In the **Type** dropdown, select **Incident**. Only fields relevant to + incidents are displayed on the page. +1. Create the incident as needed, and select **Submit issue** to save the + incident. ![Incident List Create](img/new_incident_create_v13_4.png) @@ -53,7 +55,7 @@ With Maintainer or higher [permissions](../../user/permissions.md), you can enab 1. Check the **Create an incident** checkbox. 1. To customize the incident, select an [issue template](../../user/project/description_templates.md#creating-issue-templates). -1. To send [an email notification](alert_notifications.md#email-notifications) to users +1. To send [an email notification](paging.md#email-notifications) to users with [Developer permissions](../../user/permissions.md), select **Send a separate email notification to Developers**. Email notifications are also sent to users with **Maintainer** and **Owner** permissions. @@ -115,7 +117,7 @@ in your project's sidebar. The list contains the following metrics: to a [Status Page](status_page.md). **(ULTIMATE)** The Incident list displays incidents sorted by incident created date. -([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229534) to GitLab core in 13.3.) +([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229534) to GitLab Free in 13.3.) To see if a column is sortable, point your mouse at the header. Sortable columns display an arrow next to the column name. @@ -185,7 +187,7 @@ field populated. ![Incident alert details](img/incident_alert_details_v13_4.png) -### Timeline view +### Timeline view **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227836) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. @@ -195,7 +197,7 @@ un-threaded and ordered chronologically, newest to oldest: ![Timeline view toggle](img/timeline_view_toggle_v13_5.png) -### Service Level Agreement countdown timer +### Service Level Agreement countdown timer **(PREMIUM)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241663) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. @@ -225,6 +227,10 @@ There are different actions available to help triage and respond to incidents. Assign incidents to users that are actively responding. Select **Edit** in the right-hand side bar to select or deselect assignees. +### Associate a milestone + +Associate an incident to a milestone by selecting **Edit** next to the milestone feature in the right-hand side bar. + ### Change severity See [Incident List](#incident-list) for a full description of the severity levels available. diff --git a/doc/operations/incident_management/index.md b/doc/operations/incident_management/index.md index b0274537941..6e285300b12 100644 --- a/doc/operations/incident_management/index.md +++ b/doc/operations/incident_management/index.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Incident management +# Incident management **(FREE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2877) in GitLab 13.0. @@ -12,7 +12,7 @@ Incident Management enables developers to easily triage and view the alerts and generated by their application. By surfacing alerts and incidents where the code is being developed, efficiency and awareness can be increased. Check out the following sections for more information: -- [Integrate your monitoring tools](alert_integrations.md). -- Receive [notifications](alert_notifications.md) for triggered alerts. +- [Integrate your monitoring tools](integrations.md). +- Receive [notifications](paging.md) for triggered alerts. - Triage [Alerts](alerts.md) and [Incidents](incidents.md). - Inform stakeholders with [Status Page](status_page.md). diff --git a/doc/operations/incident_management/integrations.md b/doc/operations/incident_management/integrations.md index 8c2159c130b..b3e7d9c544d 100644 --- a/doc/operations/incident_management/integrations.md +++ b/doc/operations/incident_management/integrations.md @@ -4,9 +4,19 @@ 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/#assignments --- -# Integrations +# Alert integrations **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/245331) in [GitLab Core](https://about.gitlab.com/pricing/) 13.5. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13203) in GitLab Ultimate 12.4. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/42640) to GitLab Free in 12.8. + +GitLab can accept alerts from any source via a webhook receiver. This can be configured +generically or, in GitLab versions 13.1 and greater, you can configure +[External Prometheus instances](../metrics/alerts.md#external-prometheus-instances) +to use this endpoint. + +## Integrations list + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/245331) in GitLab Free 13.5. With Maintainer or higher [permissions](../../user/permissions.md), you can view the list of configured alerts integrations by navigating to @@ -14,3 +24,176 @@ the list of configured alerts integrations by navigating to The list displays the integration name, type, and status (enabled or disabled): ![Current Integrations](img/integrations_list_v13_5.png) + +## Configuration + +GitLab can receive alerts via a HTTP endpoint that you configure, +or the [Prometheus integration](#external-prometheus-integration). + +### Single HTTP Endpoint **(FREE)** + +Enabling the HTTP Endpoint in a GitLab projects activates it to +receive alert payloads in JSON format. You can always +[customize the payload](#customize-the-alert-payload-outside-of-gitlab) to your liking. + +1. Sign in to GitLab as a user with maintainer [permissions](../../user/permissions.md) + for a project. +1. Navigate to **Settings > Operations** in your project. +1. Expand the **Alerts** section, and in the **Integration** dropdown menu, select **Generic**. +1. Toggle the **Active** alert setting to display the **URL** and **Authorization Key** + for the webhook configuration. + +### HTTP Endpoints **(PREMIUM)** + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4442) in GitLab Premium 13.6. + +In [GitLab Premium](https://about.gitlab.com/pricing/), you can create multiple +unique HTTP endpoints to receive alerts from any external source in JSON format, +and you can [customize the payload](#customize-the-alert-payload-outside-of-gitlab). + +1. Sign in to GitLab as a user with maintainer [permissions](../../user/permissions.md) + for a project. +1. Navigate to **Settings > Operations** in your project. +1. Expand the **Alerts** section. +1. For each endpoint you want to create: + + 1. In the **Integration** dropdown menu, select **HTTP Endpoint**. + 1. Name the integration. + 1. Toggle the **Active** alert setting to display the **URL** and **Authorization Key** + for the webhook configuration. You must also input the URL and Authorization Key + in your external service. + 1. _(Optional)_ To generate a test alert to test the new integration, enter a + sample payload, then click **Save and test alert payload**. Valid JSON is required. + 1. Click **Save Integration**. + +The new HTTP Endpoint displays in the [integrations list](#integrations-list). +You can edit the integration by selecting the **{pencil}** pencil icon on the right +side of the integrations list. + +### External Prometheus integration + +For GitLab versions 13.1 and greater, read +[External Prometheus Instances](../metrics/alerts.md#external-prometheus-instances) +to configure alerts for this integration. + +## Customize the alert payload outside of GitLab + +For all integration types, you can customize the payload by sending the following +parameters. All fields are optional. If the incoming alert does not contain a value for the `Title` field, a default value of `New: Incident` will be applied. + +| Property | Type | Description | +| ------------------------- | --------------- | ----------- | +| `title` | String | The title of the incident. | +| `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 is used. | +| `end_time` | DateTime | For existing alerts only. When provided, the alert is resolved and the associated incident is closed. | +| `service` | String | The affected service. | +| `monitoring_tool` | String | The name of the associated monitoring tool. | +| `hosts` | String or Array | One or more hosts, as to where this incident occurred. | +| `severity` | String | The severity of the alert. Case-insensitive. Can be one of: `critical`, `high`, `medium`, `low`, `info`, `unknown`. Defaults to `critical` if missing or value is not in this list. | +| `fingerprint` | String or Array | The unique identifier of the alert. This can be used to group occurrences of the same alert. | +| `gitlab_environment_name` | String | The name of the associated GitLab [environment](../../ci/environments/index.md). Required to [display alerts on a dashboard](../../user/operations_dashboard/index.md#adding-a-project-to-the-dashboard). | + +You can also add custom fields to the alert's payload. The values of extra +parameters aren't limited to primitive types (such as strings or numbers), but +can be a nested JSON object. For example: + +```json +{ "foo": { "bar": { "baz": 42 } } } +``` + +NOTE: +Ensure your requests are smaller than the +[payload application limits](../../administration/instance_limits.md#generic-alert-json-payloads). + +Example request: + +```shell +curl --request POST \ + --data '{"title": "Incident title"}' \ + --header "Authorization: Bearer <authorization_key>" \ + --header "Content-Type: application/json" \ + <url> +``` + +The `<authorization_key>` and `<url>` values can be found when configuring an alert integration. + +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", + "severity": "high", + "fingerprint": "d19381d4e8ebca87b55cda6e8eee7385", + "foo": { + "bar": { + "baz": 42 + } + } +} +``` + +## Triggering test alerts + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in GitLab Free in 13.2. + +After a [project maintainer or owner](../../user/permissions.md) +configures an integration, 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 > 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 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](incidents.md) +and details pages. + +If the existing alert is already `resolved`, GitLab creates a new alert instead. + +![Alert Management List](img/alert_list_v13_1.png) + +## Link to your Opsgenie Alerts + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in GitLab Premium 13.2. + +WARNING: +We are building deeper integration with Opsgenie and other alerting tools through +[HTTP endpoint integrations](#single-http-endpoint) so you can see alerts in +the GitLab interface. As a result, the previous direct link to Opsgenie Alerts from +the GitLab alerts list is deprecated in +GitLab versions [13.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/273657). + +You can monitor alerts using a GitLab integration with [Opsgenie](https://www.atlassian.com/software/opsgenie). + +If you enable the Opsgenie integration, you can't have other GitLab alert +services +active at the same time. + +To enable Opsgenie integration: + +1. Sign in as a user with Maintainer or Owner [permissions](../../user/permissions.md). +1. Navigate to **Operations > Alerts**. +1. In the **Integrations** select box, select **Opsgenie**. +1. Select the **Active** toggle. +1. In the **API URL** field, enter the base URL for your Opsgenie integration, + such as `https://app.opsgenie.com/alert/list`. +1. Select **Save changes**. + +After you enable the integration, navigate to the Alerts list page at +**Operations > Alerts**, and then select **View alerts in Opsgenie**. diff --git a/doc/operations/incident_management/paging.md b/doc/operations/incident_management/paging.md new file mode 100644 index 00000000000..dd04cd63a54 --- /dev/null +++ b/doc/operations/incident_management/paging.md @@ -0,0 +1,36 @@ +--- +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/#assignments +--- + +# Paging and notifications **(FREE)** + +When there is a new alert or incident, it is important for a responder to be notified +immediately so they can triage and respond to the problem. Responders can receive +notifications using the methods described on this page. + +## Slack notifications + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216326) in GitLab 13.1. + +Responders can be paged via Slack using the +[Slack Notifications Service](../../user/project/integrations/slack.md), which you +can configure for new alerts and new incidents. After configuring, responders +receive a **single** page via Slack. To set up Slack notifications on your mobile +device, make sure to enable notifications for the Slack app on your phone so +you never miss a page. + +## Email notifications + +Email notifications are available in projects that have been +[configured to create incidents automatically](incidents.md#create-incidents-automatically) +for triggered alerts. Project members with the **Owner** or **Maintainer** roles are +sent an email notification automatically. (This is not configurable.) To optionally +send additional email notifications to project members with the **Developer** role: + +1. Navigate to **Settings > Operations**. +1. Expand the **Incidents** section. +1. In the **Alert Integration** tab, select the **Send a separate email notification to Developers** + check box. +1. Select **Save changes**. diff --git a/doc/operations/incident_management/status_page.md b/doc/operations/incident_management/status_page.md index 6514a80a32b..fe0bfa3318b 100644 --- a/doc/operations/incident_management/status_page.md +++ b/doc/operations/incident_management/status_page.md @@ -4,7 +4,7 @@ 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/#assignments --- -# Status Page +# Status Page **(ULTIMATE)** > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2479) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.10. |