diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-09-19 04:45:44 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-09-19 04:45:44 +0300 |
commit | 85dc423f7090da0a52c73eb66faf22ddb20efff9 (patch) | |
tree | 9160f299afd8c80c038f08e1545be119f5e3f1e1 /doc/operations | |
parent | 15c2c8c66dbe422588e5411eee7e68f1fa440bb8 (diff) |
Add latest changes from gitlab-org/gitlab@13-4-stable-ee
Diffstat (limited to 'doc/operations')
21 files changed, 316 insertions, 84 deletions
diff --git a/doc/operations/feature_flags.md b/doc/operations/feature_flags.md index 46a57e72484..fe7be48270a 100644 --- a/doc/operations/feature_flags.md +++ b/doc/operations/feature_flags.md @@ -4,9 +4,10 @@ group: Progressive Delivery 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 --- -# Feature Flags **(PREMIUM)** +# Feature Flags **(STARTER)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7433) in GitLab 11.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7433) in GitLab 11.4. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212318) to [GitLab Starter](https://about.gitlab.com/pricing/) in 13.4 With Feature Flags, you can deploy your application's new features to production in smaller batches. You can toggle a feature on and off to subsets of users, helping you achieve Continuous Delivery. @@ -16,6 +17,10 @@ delivery from customer launch. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> For an example of feature flags in action, see [GitLab for Deploys, Feature Flags, and Error Tracking](https://www.youtube.com/embed/5tw2p6lwXxo). +NOTE: **Note:** +The Feature Flags GitLab offer as a feature (described in this document) is not the same method +used for the [development of GitLab](../development/feature_flags/index.md). + ## How it works GitLab uses [Unleash](https://github.com/Unleash/unleash), a feature @@ -50,22 +55,6 @@ To create and enable a feature flag: You can change these settings by clicking the **{pencil}** (edit) button next to any feature flag in the list. -## Rollout strategy (legacy) - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8240) in GitLab 12.2. - -In GitLab 13.0 and earlier, the **Rollout strategy** setting affects which users will experience -the feature as enabled. Choose the percentage of users that the feature will be enabled -for. The rollout strategy will have no effect if the environment spec is disabled. - -It can be set to: - -- All users -- [Percent of users](#percent-of-users) - - Optionally, you can click the **Include additional user IDs** checkbox and add a list - of specific users IDs to enable the feature for. -- [User IDs](#user-ids) - ## Feature flag strategies > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35555) in GitLab 13.0. @@ -204,6 +193,23 @@ To enable it: Feature.enable(:feature_flags_new_version) ``` +## Rollout strategy (legacy) + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8240) in GitLab 12.2. +> - [Made read-only](https://gitlab.com/gitlab-org/gitlab/-/issues/220228) in GitLab 13.4. + +In GitLab 13.0 and earlier, the **Rollout strategy** setting affects which users will experience +the feature as enabled. Choose the percentage of users that the feature will be enabled +for. The rollout strategy will have no effect if the environment spec is disabled. + +It can be set to: + +- All users +- [Percent of users](#percent-of-users) + - Optionally, you can click the **Include additional user IDs** checkbox and add a list + of specific users IDs to enable the feature for. +- [User IDs](#user-ids) + ## Disable a feature flag for a specific environment In [GitLab 13.0 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/8621), @@ -332,8 +338,8 @@ unleash = Unleash::Client.new({ }) unleash_context = Unleash::Context.new -# Replace "123" with the id of an authenticated user. -# Note that the context's user id must be a string: +# Replace "123" with the ID of an authenticated user. +# Note that the context's user ID must be a string: # https://unleash.github.io/docs/unleash_context unleash_context.user_id = "123" @@ -344,7 +350,7 @@ else end ``` -## Feature Flag Related Issues +## Feature Flag Related Issues **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36617) in GitLab 13.2. > - It's deployed behind a feature flag, enabled by default. diff --git a/doc/operations/incident_management/alertdetails.md b/doc/operations/incident_management/alert_details.md index 774eaee286f..860e6d32ae4 100644 --- a/doc/operations/incident_management/alertdetails.md +++ b/doc/operations/incident_management/alert_details.md @@ -7,10 +7,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Alert details page Navigate to the Alert details view by visiting the -[Alert list](alerts.md) and selecting an alert from the +[Alert list](./alerts.md) and selecting an alert from the list. You need least Developer [permissions](../../user/permissions.md) to access alerts. +TIP: **Tip:** +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. Click 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. @@ -18,18 +24,18 @@ amount of information you need. The **Overview** tab provides basic information about the alert: -![Alert Detail Overview](img/alert_detail_overview_v13_1.png) +![Alert Detail Overview](./img/alert_detail_overview_v13_1.png) ## Alert details tab -![Alert Full Details](img/alert_detail_full_v13_1.png) +![Alert Full Details](./img/alert_detail_full_v13_1.png) -### Update an Alert's status +### 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 Issue from an Alert +### Create an issue from an alert > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217745) in GitLab 13.1. @@ -41,7 +47,7 @@ alert by clicking 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. -### Update an Alert's assignee +### Update an alert's assignee > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in GitLab 13.1. @@ -57,19 +63,19 @@ GitLab currently only supports a single assignee per alert. 1. To display the list of current alerts, click **{cloud-gear}** **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, click **{angle-double-right}** **Expand sidebar** to expand it. 1. In the right sidebar, locate the **Assignee** and click **Edit**. From the dropdown menu, select each user you want to assign to the alert. GitLab creates - a [To-Do list item](../../user/todos.md) for each user. + a [to-do list 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) To remove an assignee, click **Edit** next to the **Assignee** dropdown menu and deselect the user from the list of assignees, or click **Unassigned**. @@ -88,27 +94,27 @@ The following actions will result in a system note: - [Creating an issue based on an alert](#create-an-issue-from-an-alert) - [Assignment of an alert to a user](#update-an-alerts-assignee) -![Alert Details View System Notes](img/alert_detail_system_notes_v13_1.png) +![Alert Details View System Notes](./img/alert_detail_system_notes_v13_1.png) -### Create a To-Do from an Alert +### Create a to-do 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: +Alert details screen, and view them later on your **To-Do List**. To add a to-do: 1. To display the list of current alerts, click **{cloud-gear}** **Operations > Alerts**. 1. Select your desired alert to display its **Alert Management Details View**. 1. Click 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) -Click the **To-Do** **{todo-done}** in the navigation bar to view your current To-Do list. +Click the **To-Do** **{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) -### View an Alert's metrics data +### View an alert's metrics data > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217768) in GitLab 13.2. @@ -145,10 +151,10 @@ notifications, simplifying communication and ownership of the alert. After completing their portion of investigating or fixing the alert, users can unassign their account from the alert when their role is complete. -The alert status can be updated on the [Alert list](alerts.md) to +The alert status can be updated on the [Alert list](./alerts.md) to reflect if the alert has been resolved. -## View an Alert's logs +## View an alert's logs > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217768) in GitLab 13.3. diff --git a/doc/operations/incident_management/alerts.md b/doc/operations/incident_management/alerts.md index 5a5fc59d5e3..d908af63000 100644 --- a/doc/operations/incident_management/alerts.md +++ b/doc/operations/incident_management/alerts.md @@ -14,7 +14,7 @@ but you can change the sort order by clicking the headers in the Alert Managemen The alert list displays the following information: -![Alert List](../../user/project/operations/img/alert_list_v13_1.png) +![Alert List](./img/alert_list_v13_1.png) - **Search** - The alert list supports a simple free text search on the title, description, monitoring tool, and service fields. @@ -31,6 +31,10 @@ The alert list displays the following information: - **Triggered**: No one has begun investigation. - **Acknowledged**: Someone is actively investigating the problem. - **Resolved**: No further work is required. + +TIP: **Tip:** +Check out a [live example](https://gitlab.com/gitlab-examples/ops/incident-setup/everyone/tanuki-inc/-/alert_management) +in GitLab to examine alerts in action. ## Enable Alerts @@ -58,7 +62,7 @@ To populate the alerts with data, read You can configure an externally-managed Prometheus instance to send alerts to GitLab. To set up this configuration, read the [configuring Prometheus](../metrics/alerts.md#external-prometheus-instances) documentation. Activating the external Prometheus -configuration also enables the [Alerts list](alerts.md). +configuration also enables the [Alerts list](./alerts.md). To populate the alerts with data, read [External Prometheus instances](../metrics/alerts.md#external-prometheus-instances). @@ -67,11 +71,11 @@ To populate the alerts with data, read GitLab provides the Generic Alerts endpoint so you can accept alerts from a third-party alerts service. Read the -[instructions for toggling generic alerts](../../user/project/integrations/generic_alerts.md#setting-up-generic-alerts) +[instructions for toggling generic alerts](generic_alerts.md#setting-up-generic-alerts) to add this option. After configuring the endpoint, the -[Alerts list](alerts.md) is enabled. +[Alerts list](./alerts.md) is enabled. -To populate the alerts with data, read [Customizing the payload](../../user/project/integrations/generic_alerts.md#customizing-the-payload) for requests to the alerts endpoint. +To populate the alerts with data, read [Customizing the payload](./generic_alerts.md#customizing-the-payload) for requests to the alerts endpoint. ### Opsgenie integration **(PREMIUM)** @@ -82,7 +86,7 @@ A new way of monitoring Alerts via a GitLab integration is with NOTE: **Note:** If you enable the Opsgenie integration, you can't have other GitLab alert services, -such as [Generic Alerts](../../user/project/integrations/generic_alerts.md) or +such as [Generic Alerts](./generic_alerts.md) or Prometheus alerts, active at the same time. To enable Opsgenie integration: @@ -104,7 +108,7 @@ 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: -![Alert Management Severity System](img/alert_management_severity_v13_0.png) +![Alert Management Severity System](./img/alert_management_severity_v13_0.png) Alerts contain one of the following icons: diff --git a/doc/operations/incident_management/generic_alerts.md b/doc/operations/incident_management/generic_alerts.md new file mode 100644 index 00000000000..11d4dbc6924 --- /dev/null +++ b/doc/operations/incident_management/generic_alerts.md @@ -0,0 +1,126 @@ +--- +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 +--- + +# Generic alerts integration + +> - [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 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. + +NOTE: **Note:** +In GitLab versions 13.1 and greater, you can configure +[External Prometheus instances](../metrics/alerts.md#external-prometheus-instances) +to use this endpoint. + +## Setting up generic alerts + +To obtain credentials for setting up a generic alerts integration: + +- Sign in to GitLab as a user with maintainer [permissions](../../user/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 > Operations** in your project. + - *In GitLab versions prior to 13.1,* navigate to **Settings > Integrations** in your project. GitLab will display a banner encouraging you to enable the Alerts endpoint in **Settings > Operations** instead. +- Click **Alerts endpoint**. +- Toggle the **Active** alert setting to display the **URL** and **Authorization Key** for the webhook configuration. + +## Customizing the payload + +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. | +| `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 +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 } } } +``` + +TIP: **Payload size:** +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 [setting up generic alerts](#setting-up-generic-alerts). + +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](#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 > 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`, then a new alert will be created instead. + +![Alert Management List](./img/alert_list_v13_1.png) diff --git a/doc/operations/incident_management/img/alert_list_v13_1.png b/doc/operations/incident_management/img/alert_list_v13_1.png Binary files differnew file mode 100644 index 00000000000..7a1a5f5191e --- /dev/null +++ b/doc/operations/incident_management/img/alert_list_v13_1.png diff --git a/doc/operations/incident_management/img/incident_alert_details_v13_4.png b/doc/operations/incident_management/img/incident_alert_details_v13_4.png Binary files differnew file mode 100644 index 00000000000..d98ab99a4ff --- /dev/null +++ b/doc/operations/incident_management/img/incident_alert_details_v13_4.png diff --git a/doc/operations/incident_management/img/incident_list_sort_v13_3.png b/doc/operations/incident_management/img/incident_list_sort_v13_3.png Binary files differdeleted file mode 100644 index 4a263aa188e..00000000000 --- a/doc/operations/incident_management/img/incident_list_sort_v13_3.png +++ /dev/null diff --git a/doc/operations/incident_management/img/incident_list_v13_4.png b/doc/operations/incident_management/img/incident_list_v13_4.png Binary files differnew file mode 100644 index 00000000000..bf00e630c67 --- /dev/null +++ b/doc/operations/incident_management/img/incident_list_v13_4.png diff --git a/doc/operations/incident_management/img/new_incident_create_v13_4.png b/doc/operations/incident_management/img/new_incident_create_v13_4.png Binary files differnew file mode 100644 index 00000000000..458532736bd --- /dev/null +++ b/doc/operations/incident_management/img/new_incident_create_v13_4.png diff --git a/doc/operations/incident_management/incidents.md b/doc/operations/incident_management/incidents.md index 0668dc72c22..3ff02b3dc6b 100644 --- a/doc/operations/incident_management/incidents.md +++ b/doc/operations/incident_management/incidents.md @@ -13,12 +13,23 @@ For users with at least Developer [permissions](../../user/permissions.md), the Incident Management list is available at **Operations > Incidents** in your project's sidebar. The list contains the following metrics: -![Incident List](img/incident_list_sort_v13_3.png) +![Incident List](img/incident_list_v13_4.png) - **Status** - To filter incidents by their status, click **Open**, **Closed**, or **All** above the incident list. - **Search** - The Incident list supports a simple free text search, which filters on the **Title** and **Incident** fields. +- **Severity** - Severity of a particular incident, which can be one of the following + values: + - **{severity-critical}** **Critical - S1** + - **{severity-high}** **High - S2** + - **{severity-medium}** **Medium - S3** + - **{severity-low}** **Low - S4** + - **{severity-unknown}** **Unknown** + + NOTE: **Note:** + Editing incident severity on the incident details page was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/229402) in GitLab 13.4. + - **Incident** - The description of the incident, which attempts to capture the most meaningful data. - **Date created** - How long ago the incident was created. This field uses the @@ -26,13 +37,17 @@ in your project's sidebar. The list contains the following metrics: tooltip depending on the user's locale. - **Assignees** - The user assigned to the incident. - **Published** - Displays a green check mark (**{check-circle}**) if the incident is published - to a [Status Page](status_page.md).. **(ULTIMATE)** + 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 core 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. +TIP: **Tip:** +For a live example of the incident list in action, visit this +[demo project](https://gitlab.com/gitlab-examples/ops/incident-setup/everyone/tanuki-inc/-/incidents). + NOTE: **Note:** Incidents share the [Issues API](../../user/project/issues/index.md). @@ -47,13 +62,13 @@ to create issues when alerts are triggered: 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. For GitLab versions 11.11 and greater, you can select the **Create an issue** checkbox to create an issue based on your own [issue templates](../../user/project/description_templates.md#creating-issue-templates). For more information, see - [Trigger actions from alerts](../metrics/alerts.md#trigger-actions-from-alerts-ultimate) **(ULTIMATE)**. + [Trigger actions from alerts](../metrics/alerts.md#trigger-actions-from-alerts) **(ULTIMATE)**. 1. To create issues from alerts, select the template in the **Issue Template** select box. 1. To send [separate email notifications](index.md#notify-developers-of-alerts) to users @@ -64,20 +79,32 @@ to create issues when alerts are triggered: Appropriately configured alerts include an [embedded chart](../metrics/embed.md#embedding-metrics-based-on-alerts-in-incident-issues) for the query corresponding to the alert. You can also configure GitLab to -[close issues](../metrics/alerts.md#trigger-actions-from-alerts-ultimate) +[close issues](../metrics/alerts.md#trigger-actions-from-alerts) when you receive notification that the alert is resolved. ## Create an incident manually -> [Moved](https://gitlab.com/gitlab-org/monitor/health/-/issues/24) to GitLab core in 13.3. +If you have at least Developer [permissions](../../user/permissions.md), to create an Incident, you have two options. -For users with at least Developer [permissions](../../user/permissions.md), to create a Incident you can take any of the following actions: +### From the Incidents List + +> [Moved](https://gitlab.com/gitlab-org/monitor/health/-/issues/24) to GitLab core in 13.3. - Navigate to **Operations > Incidents** and click **Create Incident**. - 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 + +> [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. + +![Incident List Create](./img/new_incident_create_v13_4.png) ## Configure PagerDuty integration @@ -91,7 +118,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. @@ -101,3 +128,29 @@ in both PagerDuty and GitLab: To confirm the integration is successful, trigger a test incident from PagerDuty to confirm that a GitLab issue is created from the incident. + +## Incident details + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230847) in GitLab 13.4. + +### Summary + +The summary section for incidents provides both critical details about and the +contents of the issue template (if one was used). The highlighted bar at the top +of the incident displays from left to right: the link to the original alert, the +alert start time, and the event count. Beneath the highlight bar, GitLab +displays a summary that includes the following fields: + +- Start time +- Severity +- `full_query` +- Monitoring tool + +### Alert details + +Incidents show the details of linked alerts in a separate tab. To populate this +tab, the incident must have been created with a linked alert. Incidents +[created automatically](#configure-incidents) from alerts will have this +field populated. + +![Incident alert details](./img/incident_alert_details_v13_4.png) diff --git a/doc/operations/incident_management/index.md b/doc/operations/incident_management/index.md index 53a6b47ec4b..28e69a6bbfe 100644 --- a/doc/operations/incident_management/index.md +++ b/doc/operations/incident_management/index.md @@ -8,13 +8,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2877) in GitLab 13.0. -Alert Management enables developers to easily discover and view the alerts +Incident Management enables developers to easily discover and view the alerts generated by their application. By surfacing alert information where the code is being developed, efficiency and awareness can be increased. GitLab offers solutions for handling incidents in your applications and services, such as [setting up Prometheus alerts](#configure-prometheus-alerts), -[displaying metrics](alertdetails.md#embed-metrics-in-incidents-and-issues), and sending notifications. +[displaying metrics](./alert_details.md#embed-metrics-in-incidents-and-issues), and sending notifications. ## Alert notifications @@ -35,7 +35,7 @@ These emails contain details of the alert, and a link for more information. To send separate email notifications to users with [Developer permissions](../../user/permissions.md), see -[Configure incidents](incidents.md#configure-incidents). +[Configure incidents](./incidents.md#configure-incidents). ## Configure Prometheus alerts @@ -49,16 +49,19 @@ user, but it does not count toward your license limit. ## Configure external generic alerts -GitLab can accept alerts from any source through a generic webhook receiver. When -[configuring the generic alerts integration](../../user/project/integrations/generic_alerts.md), -GitLab creates a unique endpoint which receives a JSON-formatted, customizable payload. +GitLab can accept alerts from any source through a generic webhook receiver. +When [configuring the generic alerts integration](./generic_alerts.md), GitLab +creates a unique endpoint which receives a JSON-formatted, customizable payload. + +After configuration, you can manage your alerts using either the +[alerts section](./alerts.md) or the [alert details section](./alert_details.md). ## Integrate incidents with Slack Slack slash commands allow you to control GitLab and view GitLab content without leaving Slack. Learn how to [set up Slack slash commands](../../user/project/integrations/slack_slash_commands.md) -and how to [use the available slash commands](../../user/project/slash_commands.md). +and how to [use the available slash commands](../../integration/slash_commands.md). ## Integrate issues with Zoom @@ -66,3 +69,13 @@ GitLab enables you to [associate a Zoom meeting with an issue](../../user/projec for synchronous communication during incident management. After starting a Zoom call for an incident, you can associate the conference call with an issue. Your team members can join the Zoom call without requesting a link. + +## More information + +For information about GitLab and incident management, see: + +- [Generic alerts](generic_alerts.md) +- [Alerts](alerts.md) +- [Alert details](alert_details.md) +- [Incidents](incidents.md) +- [Status page](status_page.md) diff --git a/doc/operations/incident_management/status_page.md b/doc/operations/incident_management/status_page.md index e376607d86f..9db3593caec 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. @@ -144,7 +144,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 diff --git a/doc/operations/index.md b/doc/operations/index.md index bcc3f89f47f..7ab34502277 100644 --- a/doc/operations/index.md +++ b/doc/operations/index.md @@ -36,7 +36,7 @@ Are your alerts too noisy? Alerts configured on GitLab metrics can configured and fine-tuned in GitLab immediately following a fire-fight. - [Manage alerts and incidents](../user/incident_management/index.md) in GitLab. -- [Configure alerts for metrics](metrics/alerts.md#set-up-alerts-for-prometheus-metrics-core) in GitLab. +- [Configure alerts for metrics](metrics/alerts.md#set-up-alerts-for-prometheus-metrics) in GitLab. - Create a [status page](incident_management/status_page.md) to communicate efficiently to your users during an incident. diff --git a/doc/operations/metrics/alerts.md b/doc/operations/metrics/alerts.md index 2ed8de9396a..5b880ab9746 100644 --- a/doc/operations/metrics/alerts.md +++ b/doc/operations/metrics/alerts.md @@ -6,14 +6,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Set up alerts for Prometheus metrics **(CORE)** +> [Moved from Ultimate to Core](https://gitlab.com/gitlab-org/gitlab/-/issues/42640) in GitLab 12.10. + After [configuring metrics for your CI/CD environment](index.md), you can set up alerting for Prometheus metrics depending on the location of your instances, and -[trigger actions from alerts](#trigger-actions-from-alerts-ultimate) to notify +[trigger actions from alerts](#trigger-actions-from-alerts) to notify your team when environment performance falls outside of the boundaries you set. ## Managed Prometheus instances -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6590) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.2 for [custom metrics](index.md#adding-custom-metrics), and GitLab 11.3 for [library metrics](../../user/project/integrations/prometheus_library/metrics.md). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6590) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.2 for [custom metrics](index.md#adding-custom-metrics), and GitLab 11.3 for [library metrics](../../user/project/integrations/prometheus_library/metrics.md). For managed Prometheus instances using auto configuration, you can [configure alerts for metrics](index.md#adding-custom-metrics) directly in the @@ -33,7 +35,7 @@ To remove the alert, click back on the alert icon for the desired metric, and cl ### Link runbooks to alerts -> - Runbook URLs [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39315) in GitLab 13.3. +> Runbook URLs [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39315) in GitLab 13.3. When creating alerts from the metrics dashboard for [managed Prometheus instances](#managed-prometheus-instances), you can also link a runbook. When the alert triggers, the @@ -45,8 +47,8 @@ as soon as the alert fires: ## External Prometheus instances ->- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9258) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.8. ->- [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/42640) to [GitLab Core](https://about.gitlab.com/pricing/) in 12.10. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9258) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.8. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/42640) to [GitLab Core](https://about.gitlab.com/pricing/) in 12.10. For manually configured Prometheus servers, GitLab provides a notify endpoint for use with Prometheus webhooks. If you have manual configuration enabled, an @@ -78,12 +80,12 @@ Prometheus. The value of this should match the name of your environment in GitLa NOTE: **Note:** In GitLab versions 13.1 and greater, you can configure your manually configured Prometheus server to use the -[Generic alerts integration](../../user/project/integrations/generic_alerts.md). +[Generic alerts integration](../incident_management/generic_alerts.md). ## Trigger actions from alerts **(ULTIMATE)** ->- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4925) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.11. ->- [From GitLab Ultimate 12.5](https://gitlab.com/gitlab-org/gitlab/-/issues/13401), when GitLab receives a recovery alert, it will automatically close the associated issue. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4925) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.11. +> - [From GitLab Ultimate 12.5](https://gitlab.com/gitlab-org/gitlab/-/issues/13401), when GitLab receives a recovery alert, it will automatically close the associated issue. Alerts can be used to trigger actions, like opening an issue automatically (disabled by default since `13.1`). To configure the actions: diff --git a/doc/operations/metrics/dashboards/variables.md b/doc/operations/metrics/dashboards/variables.md index 8b0d7f37052..22c8814e8bd 100644 --- a/doc/operations/metrics/dashboards/variables.md +++ b/doc/operations/metrics/dashboards/variables.md @@ -18,6 +18,7 @@ Queries that continue to use the old format will show no data. GitLab supports a limited set of [CI variables](../../../ci/variables/README.md) in the Prometheus query. This is particularly useful for identifying a specific environment, for example with `ci_environment_slug`. The supported variables are: +- `environment_filter` - `ci_environment_slug` - `kube_namespace` - `ci_project_name` @@ -29,6 +30,14 @@ GitLab supports a limited set of [CI variables](../../../ci/variables/README.md) NOTE: **Note:** Variables for Prometheus queries must be lowercase. +### environment_filter + +`environment_filter` is automatically expanded to `container_name!="POD",environment="ENVIRONMENT_NAME"` +where `ENVIRONMENT_NAME` is the name of the current environment. + +For example, a Prometheus query like `container_memory_usage_bytes{ {{environment_filter}} }` +becomes `container_memory_usage_bytes{ container_name!="POD",environment="production" }`. + ### __range The `__range` variable is useful in Prometheus diff --git a/doc/operations/metrics/embed.md b/doc/operations/metrics/embed.md index 62d60921c85..fcf9679d164 100644 --- a/doc/operations/metrics/embed.md +++ b/doc/operations/metrics/embed.md @@ -20,15 +20,28 @@ metrics to others, and you want to have relevant information directly available. NOTE: **Note:** Requires [Kubernetes](../../user/project/integrations/prometheus_library/kubernetes.md) metrics. +Note: **Note:** +In GitLab versions 13.3 and earlier, metrics dashboard links were in the form +`https://<root_url>/<project>/-/environments/<environment_id>/metrics`. These links +are still supported, and can be used to embed metric charts. + To display metric charts, include a link of the form -`https://<root_url>/<project>/-/environments/<environment_id>/metrics` in a field +`https://<root_url>/<project>/-/metrics?environment=<environment_id>` in a field that supports GitLab-flavored Markdown: -![Embedded Metrics Markdown](img/embedded_metrics_markdown_v12_8.png) +```markdown +### Summary + +**Start time:** 2020-01-21T12:00:31+00:00 + +### Metrics + +https://gitlab.com/gitlab-org/monitor/tanuki-inc/-/metrics?environment=1118134 +``` GitLab unfurls the link as an embedded metrics panel: -![Embedded Metrics Rendered](img/embedded_metrics_rendered_v12_8.png) +![Embedded Metrics Rendered](img/embedded_metrics_rendered_v13_4.png) You can also embed a single chart. To get a link to a chart, click the **{ellipsis_v}** **More actions** menu in the upper right corner of the chart, diff --git a/doc/operations/metrics/img/embedded_metrics_markdown_v12_8.png b/doc/operations/metrics/img/embedded_metrics_markdown_v12_8.png Binary files differdeleted file mode 100644 index ffd34705464..00000000000 --- a/doc/operations/metrics/img/embedded_metrics_markdown_v12_8.png +++ /dev/null diff --git a/doc/operations/metrics/img/embedded_metrics_rendered_v12_8.png b/doc/operations/metrics/img/embedded_metrics_rendered_v12_8.png Binary files differdeleted file mode 100644 index b024daaaa8e..00000000000 --- a/doc/operations/metrics/img/embedded_metrics_rendered_v12_8.png +++ /dev/null diff --git a/doc/operations/metrics/img/embedded_metrics_rendered_v13_4.png b/doc/operations/metrics/img/embedded_metrics_rendered_v13_4.png Binary files differnew file mode 100644 index 00000000000..876972dc721 --- /dev/null +++ b/doc/operations/metrics/img/embedded_metrics_rendered_v13_4.png diff --git a/doc/operations/metrics/index.md b/doc/operations/metrics/index.md index 92c4a4986bc..742e6acef0e 100644 --- a/doc/operations/metrics/index.md +++ b/doc/operations/metrics/index.md @@ -46,7 +46,7 @@ For GitLab-managed Prometheus, you can set up [Auto DevOps](../../topics/autodev to quickly create a deployment: 1. Navigate to your project's **Operations > Kubernetes** page. -1. Ensure that, in addition to Prometheus, you also have Runner and Ingress +1. Ensure that, in addition to Prometheus, you also have GitLab Runner and Ingress installed. 1. After installing Ingress, copy its endpoint. 1. Navigate to your project's **Settings > CI/CD** page. In the @@ -118,7 +118,7 @@ After creating your dashboard, you can customize it to meet your needs: [create custom metrics](#adding-custom-metrics) and display them on your metrics dashboard. - **Configure alerts for metrics**: [Configure custom alerts](alerts.md) for your team when environment performance falls outside of the boundaries you set. -- **Trigger actions from alerts**: [Open new issues for your team](alerts.md#trigger-actions-from-alerts-ultimate) **(ULTIMATE)** +- **Trigger actions from alerts**: [Open new issues for your team](alerts.md#trigger-actions-from-alerts) **(ULTIMATE)** when environment performance falls outside of the boundaries you set. ## Metrics dashboard visibility diff --git a/doc/operations/product_analytics.md b/doc/operations/product_analytics.md index 96f1a45167b..8f660a16b47 100644 --- a/doc/operations/product_analytics.md +++ b/doc/operations/product_analytics.md @@ -33,7 +33,7 @@ To enable it: # Instance-wide Feature.enable(:product_analytics) # or by project -Feature.enable(:product_analytics, Project.find(<project id>)) +Feature.enable(:product_analytics, Project.find(<project ID>)) ``` To disable it: @@ -42,7 +42,7 @@ To disable it: # Instance-wide Feature.disable(:product_analytics) # or by project -Feature.disable(:product_analytics, Project.find(<project id>)) +Feature.disable(:product_analytics, Project.find(<project ID>)) ``` ## Access Product Analytics |