diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-11-19 11:27:35 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-11-19 11:27:35 +0300 |
commit | 7e9c479f7de77702622631cff2628a9c8dcbc627 (patch) | |
tree | c8f718a08e110ad7e1894510980d2155a6549197 /doc/operations/incident_management | |
parent | e852b0ae16db4052c1c567d9efa4facc81146e88 (diff) |
Add latest changes from gitlab-org/gitlab@13-6-stable-eev13.6.0-rc42
Diffstat (limited to 'doc/operations/incident_management')
14 files changed, 110 insertions, 93 deletions
diff --git a/doc/operations/incident_management/alert_integrations.md b/doc/operations/incident_management/alert_integrations.md index 58c1e1eae76..7850841d380 100644 --- a/doc/operations/incident_management/alert_integrations.md +++ b/doc/operations/incident_management/alert_integrations.md @@ -9,7 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [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 +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. @@ -26,16 +27,14 @@ The list displays the integration name, type, and status (enabled or disabled): ## Configuration -You can either configure alerts to integrate with an [external Prometheus server](#external-prometheus-integration), -or provide a [generic HTTP endpoint](#generic-http-endpoint) to receive alerts -from other services. +GitLab can receive alerts via a [HTTP endpoint](#generic-http-endpoint) that you configure, +or the [Prometheus integration](#external-prometheus-integration). -### Generic HTTP Endpoint +### Generic HTTP Endpoint **CORE** -Enabling the Generic HTTP Endpoint creates a unique HTTP endpoint that can receive alert payloads in JSON format. You can always -[customize the payload](#customizing-the-payload) to your liking. - -You will need to activate the endpoint and obtain credentials to set up this integration: +Enabling the Generic HTTP Endpoint activates a unique HTTP endpoint that can +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. @@ -44,20 +43,49 @@ You will need to activate the endpoint and obtain credentials to set up this int 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 will 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 see [External Prometheus Instances](../metrics/alerts.md#external-prometheus-instances) to configure alerts for this 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. -## Customizing the payload +## Customize the alert payload outside of GitLab -You can customize the payload by sending the following parameters. This applies to all types of integrations. All fields -other than `title` are optional: +For all integration types, you can customize the payload by sending the following +parameters. All fields other than `title` are optional: | Property | Type | Description | | ------------------------- | --------------- | ----------- | | `title` | String | The title of the incident. Required. | | `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. | +| `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. | @@ -74,8 +102,9 @@ can be a nested JSON object. For example: { "foo": { "bar": { "baz": 42 } } } ``` -TIP: **Payload size:** -Ensure your requests are smaller than the [payload application limits](../../administration/instance_limits.md#generic-alert-json-payloads). +TIP: **Tip:** +Ensure your requests are smaller than the +[payload application limits](../../administration/instance_limits.md#generic-alert-json-payloads). Example request: @@ -132,15 +161,21 @@ GitLab displays an error or success message, depending on the outcome of your te 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) +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) +![Alert Management List](img/alert_list_v13_1.png) ## Link to your Opsgenie Alerts +DANGER: **Deprecated:** +We are building deeper integration with Opsgenie and other alerting tools through +[HTTP endpoint integrations](#generic-http-endpoint) so you can see alerts within +the GitLab interface. As a result, the previous direct link to Opsgenie Alerts from +the GitLab alerts list will be deprecated following the 13.7 release on December 22, 2020. + > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. You can monitor alerts using a GitLab integration with [Opsgenie](https://www.atlassian.com/software/opsgenie). diff --git a/doc/operations/incident_management/alerts.md b/doc/operations/incident_management/alerts.md index a6168386024..37836f4ab50 100644 --- a/doc/operations/incident_management/alerts.md +++ b/doc/operations/incident_management/alerts.md @@ -63,7 +63,7 @@ Alerts contain one of the following icons: ## Alert details page -Navigate to the Alert details view by visiting the [Alert list](./alerts.md) +Navigate to the Alert details view by visiting the [Alert list](alerts.md) and selecting an alert from the list. You need least Developer [permissions](../../user/permissions.md) to access alerts. @@ -142,7 +142,7 @@ There are different actions avilable in GitLab to help triage and respond to ale ### 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. +See [Create and manage alerts in GitLab](alerts.md) for more details. ### Create an incident from an alert @@ -168,11 +168,11 @@ To assign an alert: 1. To display the list of current alerts, navigate to **Operations > Alerts**: - ![Alert List View Assignee(s)](./img/alert_list_assignees_v13_1.png) + ![Alert List View Assignee(s)](img/alert_list_assignees_v13_1.png) 1. Select your desired alert to display its **Alert Details View**: - ![Alert Details View Assignee(s)](./img/alert_details_assignees_v13_1.png) + ![Alert Details View Assignee(s)](img/alert_details_assignees_v13_1.png) 1. If the right sidebar is not expanded, select **{angle-double-right}** **Expand sidebar** to expand it. @@ -180,29 +180,29 @@ To assign an alert: From the dropdown menu, select each user you want to assign to the alert. GitLab creates a [to-do item](../../user/todos.md) for each user. - ![Alert Details View Assignee(s)](./img/alert_todo_assignees_v13_1.png) + ![Alert Details View Assignee(s)](img/alert_todo_assignees_v13_1.png) 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**. -### Create a to do from an alert +### 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 [To-Do list items](../../user/todos.md) for yourself from the Alert details screen, and view them later on your **To-Do List**. To -add a to do: +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: - ![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_1.png) Select the **To-Do List** **{todo-done}** in the navigation bar to view your current to-do list. -![Alert Details Added to do](./img/alert_detail_added_todo_v13_1.png) +![Alert Details Added to do](img/alert_detail_added_todo_v13_1.png) ## Link runbooks to alerts @@ -219,46 +219,10 @@ the correct runbook: ## View the environment that generated the alert -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232492) in GitLab 13.5. -> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-environment-link-in-alert-details). **(CORE ONLY)** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232492) in GitLab 13.5 behind a feature flag, disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/232492) in GitLab 13.6. CAUTION: **Warning:** This feature might not be available to you. Check the **version history** note above for details. The environment information and the link are displayed in the [Alert Details tab](#alert-details-tab). - -### Enable or disable Environment Link in Alert Details **(CORE ONLY)** - -Viewing the environment is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can enable it. - -To enable it: - -```ruby -Feature.enable(:expose_environment_path_in_alert_details) -``` - -To enable for just a particular project: - -```ruby -project = Project.find_by_full_path('your-group/your-project') -Feature.enable(:expose_environment_path_in_alert_details, project) -``` - -To disable it: - -```ruby -Feature.disable(:expose_environment_path_in_alert_details) -``` - -To disable for just a particular project: - -```ruby -project = Project.find_by_full_path('your-group/your-project') -Feature.disable(:expose_environment_path_in_alert_details, project) -``` diff --git a/doc/operations/incident_management/generic_alerts.md b/doc/operations/incident_management/generic_alerts.md index a8f2f9a58a6..29d609f1811 100644 --- a/doc/operations/incident_management/generic_alerts.md +++ b/doc/operations/incident_management/generic_alerts.md @@ -1,5 +1,5 @@ --- -redirect_to: alert_notifications.md +redirect_to: alert_integrations.md --- -This document was moved to [another location](alert_notifications.md). +This document was moved to [another location](alert_integrations.md). diff --git a/doc/operations/incident_management/img/alert_detail_full_v13_1.png b/doc/operations/incident_management/img/alert_detail_full_v13_1.png Binary files differdeleted file mode 100644 index 18a6f4fb67b..00000000000 --- a/doc/operations/incident_management/img/alert_detail_full_v13_1.png +++ /dev/null diff --git a/doc/operations/incident_management/img/alert_detail_overview_v13_1.png b/doc/operations/incident_management/img/alert_detail_overview_v13_1.png Binary files differdeleted file mode 100644 index 10c945d3810..00000000000 --- a/doc/operations/incident_management/img/alert_detail_overview_v13_1.png +++ /dev/null diff --git a/doc/operations/incident_management/img/alert_detail_system_notes_v13_1.png b/doc/operations/incident_management/img/alert_detail_system_notes_v13_1.png Binary files differdeleted file mode 100644 index 2a6d0320a54..00000000000 --- a/doc/operations/incident_management/img/alert_detail_system_notes_v13_1.png +++ /dev/null diff --git a/doc/operations/incident_management/img/alert_list_search_v13_1.png b/doc/operations/incident_management/img/alert_list_search_v13_1.png Binary files differdeleted file mode 100644 index ba993fe530b..00000000000 --- a/doc/operations/incident_management/img/alert_list_search_v13_1.png +++ /dev/null diff --git a/doc/operations/incident_management/img/alert_list_sort_v13_1.png b/doc/operations/incident_management/img/alert_list_sort_v13_1.png Binary files differdeleted file mode 100644 index 8e06c3478f7..00000000000 --- a/doc/operations/incident_management/img/alert_list_sort_v13_1.png +++ /dev/null diff --git a/doc/operations/incident_management/img/incident_highlight_bar_v13_5.png b/doc/operations/incident_management/img/incident_highlight_bar_v13_5.png Binary files differdeleted file mode 100644 index 6a40e97820c..00000000000 --- a/doc/operations/incident_management/img/incident_highlight_bar_v13_5.png +++ /dev/null diff --git a/doc/operations/incident_management/img/incident_list.png b/doc/operations/incident_management/img/incident_list.png Binary files differdeleted file mode 100644 index 0498fec6c9c..00000000000 --- a/doc/operations/incident_management/img/incident_list.png +++ /dev/null diff --git a/doc/operations/incident_management/img/incident_list_search_v13_3.png b/doc/operations/incident_management/img/incident_list_search_v13_3.png Binary files differdeleted file mode 100644 index 293268986cc..00000000000 --- a/doc/operations/incident_management/img/incident_list_search_v13_3.png +++ /dev/null diff --git a/doc/operations/incident_management/img/incident_sla_settings_v13_5.png b/doc/operations/incident_management/img/incident_sla_settings_v13_5.png Binary files differdeleted file mode 100644 index 94c8b840210..00000000000 --- a/doc/operations/incident_management/img/incident_sla_settings_v13_5.png +++ /dev/null diff --git a/doc/operations/incident_management/incidents.md b/doc/operations/incident_management/incidents.md index 3d85fa0ebd8..13a755bbb6f 100644 --- a/doc/operations/incident_management/incidents.md +++ b/doc/operations/incident_management/incidents.md @@ -6,7 +6,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Incidents -Incidents are critical entities in incident management workflows. They represent a service disruption or outage that needs to be restored urgently. GitLab provides tools for the triage, response, and remediation of incidents. +Incidents are critical entities in incident management workflows. They represent +a service disruption or outage that needs to be restored urgently. GitLab provides +tools for the triage, response, and remediation of incidents. ## Incident Creation @@ -14,7 +16,8 @@ You can create an incident manually or automatically. ### Create incidents manually -If you have at least Guest [permissions](../../user/permissions.md), to create an Incident, you have two options to do this manually. +If you have at least Guest [permissions](../../user/permissions.md), to create an +Incident, you have two options to do this manually. **From the Incidents List:** @@ -24,7 +27,7 @@ If you have at least Guest [permissions](../../user/permissions.md), to create a - Create a new issue using the `incident` template available when creating it. - Create a new issue and assign the `incident` label to it. -![Incident List Create](./img/incident_list_create_v13_3.png) +![Incident List Create](img/incident_list_create_v13_3.png) **From the Issues List:** @@ -34,7 +37,7 @@ If you have at least Guest [permissions](../../user/permissions.md), to create a - Create a new issue using the `type` drop-down and select `Incident`. - The page refreshes and the page only displays fields relevant to Incidents. -![Incident List Create](./img/new_incident_create_v13_4.png) +![Incident List Create](img/new_incident_create_v13_4.png) ### Create incidents automatically @@ -43,17 +46,17 @@ If you have at least Guest [permissions](../../user/permissions.md), to create a With Maintainer or higher [permissions](../../user/permissions.md), you can enable GitLab to create incident automatically whenever an alert is triggered: -1. Navigate to **Settings > Operations > Incidents** and expand - **Incidents**: +1. Navigate to **Settings > Operations > Incidents** and expand **Incidents**: - ![Incident Management Settings](./img/incident_management_settings_v13_3.png) + ![Incident Management Settings](img/incident_management_settings_v13_3.png) -1. Check the **Create an incident** - checkbox. -1. To customize the incident, select an [issue templates](../../user/project/description_templates.md#creating-issue-templates). +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 with [Developer permissions](../../user/permissions.md), select - **Send a separate email notification to Developers**. Email notifications will also be sent to users with **Maintainer** and **Owner** permissions. + **Send a separate email notification to Developers**. Email notifications are + also sent to users with **Maintainer** and **Owner** permissions. 1. Click **Save changes**. ### Create incidents via the PagerDuty webhook @@ -68,7 +71,7 @@ in both PagerDuty and GitLab: 1. Navigate to **Settings > Operations > Incidents** and expand **Incidents**. 1. Select the **PagerDuty integration** tab: - ![PagerDuty incidents integration](./img/pagerduty_incidents_integration_v13_3.png) + ![PagerDuty incidents integration](img/pagerduty_incidents_integration_v13_3.png) 1. Activate the integration, and save the changes in GitLab. 1. Copy the value of **Webhook URL** for use in a later step. @@ -167,7 +170,7 @@ tab, the incident must have been created with a linked alert. Incidents created automatically from alerts have this field populated. -![Incident alert details](./img/incident_alert_details_v13_4.png) +![Incident alert details](img/incident_alert_details_v13_4.png) ### Timeline view @@ -177,32 +180,47 @@ To quickly see the latest updates on an incident, click **{comments}** **Turn timeline view on** in the comment bar to display comments un-threaded and ordered chronologically, newest to oldest: -![Timeline view toggle](./img/timeline_view_toggle_v13_5.png) +![Timeline view toggle](img/timeline_view_toggle_v13_5.png) ### Service Level Agreement countdown timer > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241663) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.5. -After enabling **Incident SLA** in the Incident Management configuration, newly-created -incidents display a SLA (Service Level Agreement) timer showing the time remaining before -the SLA period expires. If the incident is not closed before the SLA period ends, GitLab -adds a `missed::SLA` label to the incident. +You can enable the Service Level Agreement Countdown timer on incidents to track +the Service Level Agreements (SLAs) you hold with your customers. The timer is +automatically started when the incident is created, and shows the time +remaining before the SLA period expires. To configure the timer: + +1. Navigate to **Settings > Operations**. +1. Scroll to **Incidents** and click **Expand**, then select the + **Incident settings** tab. +1. Select **Activate "time to SLA" countdown timer**. +1. Set a time limit in increments of 15 minutes. +1. Click **Save changes**. + +After you enable the SLA countdown timer, the **Time to SLA** attribute is displayed +as a column in the Incidents List, and as a field on newly created Incidents. If +the incident isn't closed before the SLA period ends, GitLab adds a `missed::SLA` +label to the incident. ## Incident Actions -There are different actions avilable to help triage and respond to incidents. +There are different actions available to help triage and respond to incidents. ### Assign incidents -Assign incidents to users that are actively responding. Select **Edit** in the right-hand side bar to select or deselect assignees. +Assign incidents to users that are actively responding. Select **Edit** in the +right-hand side bar to select or deselect assignees. ### Change severity -See [Incident List](#incident-list) for a full description of the severities available. Select **Edit** in the right-hand side bar to change the severity of an incident. +See [Incident List](#incident-list) for a full description of the severity levels available. +Select **Edit** in the right-hand side bar to change the severity of an incident. -### Add a to do +### Add a to-do item -Add a to-do for incidents that you want to track in your to-do list. Clicke the **Add a to do** button at the top of the right-hand side bar to add a to do. +Add a to-do for incidents that you want to track in your to-do list. Click the +**Add a to do** button at the top of the right-hand side bar to add a to-do item. ### Manage incidents from Slack diff --git a/doc/operations/incident_management/status_page.md b/doc/operations/incident_management/status_page.md index e5d0ae1ddbb..4230091866e 100644 --- a/doc/operations/incident_management/status_page.md +++ b/doc/operations/incident_management/status_page.md @@ -12,11 +12,11 @@ With a GitLab Status Page, you can create and deploy a static website to communi efficiently to users during an incident. The Status Page landing page displays an overview of recent incidents: -![Status Page landing page](./img/status_page_incidents_v12_10.png) +![Status Page landing page](img/status_page_incidents_v12_10.png) Clicking an incident displays a detail page with more information about a particular incident: -![Status Page detail](./img/status_page_detail_v12_10.png) +![Status Page detail](img/status_page_detail_v12_10.png) - Status on the incident, including when the incident was last updated. - The incident title, including any emojis. @@ -138,7 +138,7 @@ you provided during setup. As part of publication, GitLab will: After publication, you can access the incident's details page by clicking the **Published on status page** button displayed under the Incident's title. -![Status Page detail link](./img/status_page_detail_link_v13_1.png) +![Status Page detail link](img/status_page_detail_link_v13_1.png) ### Update an incident |