diff options
Diffstat (limited to 'doc/user/project/operations')
| -rw-r--r-- | doc/user/project/operations/alert_management.md | 130 | ||||
| -rw-r--r-- | doc/user/project/operations/dashboard_settings.md | 5 | ||||
| -rw-r--r-- | doc/user/project/operations/feature_flags.md | 260 | ||||
| -rw-r--r-- | doc/user/project/operations/img/alert_detail_metrics_v13_2.png | bin | 0 -> 27616 bytes | |||
| -rw-r--r-- | doc/user/project/operations/img/alert_list_search_v13_1.png | bin | 0 -> 12166 bytes | |||
| -rw-r--r-- | doc/user/project/operations/img/alert_list_sort_v13_1.png | bin | 0 -> 13919 bytes | |||
| -rw-r--r-- | doc/user/project/operations/img/alert_list_v13_1.png | bin | 0 -> 38265 bytes | |||
| -rw-r--r-- | doc/user/project/operations/img/alert_management_1_v13_0.png | bin | 19152 -> 0 bytes | |||
| -rw-r--r-- | doc/user/project/operations/img/alert_management_1_v13_1.png | bin | 40053 -> 0 bytes | |||
| -rw-r--r-- | doc/user/project/operations/index.md | 16 | ||||
| -rw-r--r-- | doc/user/project/operations/tracing.md | 39 |
11 files changed, 130 insertions, 320 deletions
diff --git a/doc/user/project/operations/alert_management.md b/doc/user/project/operations/alert_management.md index 411b36411af..3e4b94473bc 100644 --- a/doc/user/project/operations/alert_management.md +++ b/doc/user/project/operations/alert_management.md @@ -17,16 +17,64 @@ being developed, efficiency and awareness can be increased. NOTE: **Note:** You will need at least Maintainer [permissions](../../permissions.md) to enable the Alert Management feature. -1. Follow the [instructions for toggling generic alerts](../integrations/generic_alerts.md#setting-up-generic-alerts) -1. You can now visit **{cloud-gear}** **Operations > Alerts** in your project's sidebar to [view a list](#alert-management-list) of alerts. +There are several ways to accept alerts into your GitLab project, as outlined below. +Enabling any of these methods will allow the Alerts list to display. After configuring +alerts, visit **{cloud-gear}** **Operations > Alerts** in your project's sidebar +to [view the list](#alert-management-list) of alerts. - +### Opsgenie integration **(PREMIUM)** -## Populate Alert data +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. -To populate data, see the instructions for -[customizing the payload](../integrations/generic_alerts.md) and making a -request to the alerts endpoint. +A new way of monitoring Alerts via a GitLab integration is with +[Opsgenie](https://www.atlassian.com/software/opsgenie). + +NOTE: **Note:** +If you enable the Opsgenie integration, you cannot have other GitLab alert services, +such as [Generic Alerts](../integrations/generic_alerts.md) or +Prometheus alerts, active at the same time. + +To enable Opsgenie integration: + +1. Sign in as a user with Maintainer or Owner [permissions](../../permissions.md). +1. Navigate to **{cloud-gear}** **Operations > Alerts**. +1. In the **Integrations** select box, select Opsgenie. +1. Click the **Active** toggle. +1. In the **API URL**, enter the base URL for your Opsgenie integration, such + as `https://app.opsgenie.com/alert/list`. +1. Click **Save changes**. + +After enabling the integration, navigate to the Alerts list page at **{cloud-gear}** **Operations > Alerts**, and click **View alerts in Opsgenie**. + +### Enable a Generic Alerts endpoint + +GitLab provides the Generic Alerts endpoint so you can accept alerts from a third-party +alerts service. See the +[instructions for toggling generic alerts](../integrations/generic_alerts.md#setting-up-generic-alerts) +to add this option. After configuring the endpoint, the +[Alerts list](#alert-management-list) is enabled. + +To populate the alerts with data, see [Customizing the payload](../integrations/generic_alerts.md#customizing-the-payload) for requests to the alerts endpoint. + +### Enable GitLab-managed Prometheus alerts + +You can install the GitLab-managed Prometheus application on your Kubernetes +cluster. For more information, see +[Managed Prometheus on Kubernetes](../integrations/prometheus.md#managed-prometheus-on-kubernetes). +When GitLab-managed Prometheus is installed, the [Alerts list](#alert-management-list) +is also enabled. + +To populate the alerts with data, see +[GitLab-Managed Prometheus instances](../../../operations/metrics/alerts.md#managed-prometheus-instances). + +### Enable external Prometheus alerts + +You can configure an externally-managed Prometheus instance to send alerts +to GitLab. To set up this configuration, see the [configuring Prometheus](../../../operations/metrics/alerts.md#external-prometheus-instances) documentation. Activating the external Prometheus +configuration also enables the [Alerts list](#alert-management-list). + +To populate the alerts with data, see +[External Prometheus instances](../../../operations/metrics/alerts.md#external-prometheus-instances). ## Alert Management severity @@ -55,15 +103,42 @@ You will need at least Developer [permissions](../../permissions.md) to view the You can find the Alert Management list at **{cloud-gear}** **Operations > Alerts** in your project's sidebar. Each alert contains the following metrics: - + - **Severity** - The current importance of a alert and how much attention it should receive. - **Start time** - How long ago the alert fired. This field uses the standard GitLab pattern of `X time ago`, but is supported by a granular date/time tooltip depending on the user's locale. -- **End time** - How long ago the alert fired was resolved. This field uses the standard GitLab pattern of `X time ago`, but is supported by a granular date/time tooltip depending on the user's locale. - **Alert description** - The description of the alert, which attempts to capture the most meaningful data. - **Event count** - The number of times that an alert has fired. +- **Issue** - A link to the incident issue that has been created for the alert. - **Status** - The [current status](#alert-management-statuses) of the alert. +### Alert Management list sorting + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217745) in GitLab 13.1. + +The Alert Management list displays alerts sorted by start time, but you can +change the sort order by clicking the headers in the Alert Management list. + +To see if a column is sortable, point your mouse at the header. Sortable columns +display an arrow next to the column name, as shown in this example: + + + +### Searching alerts + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213884) in GitLab 13.1. + +The alert list supports a simple free text search. + + + +This search filters on the following fields: + +- Title +- Description +- Monitoring tool +- Service + ### Alert Management statuses Each alert contains a status dropdown to indicate which alerts need investigation. @@ -138,14 +213,43 @@ deselect the user from the list of assignees, or click **Unassigned**. > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3066) in GitLab 13.1. -NOTE: **Note:** -GitLab currently only supports creating system notes when assigning an Alert. +When you take action on an alert, this is logged as a system note, +which is visible in the Alert Details view. This gives you a linear +timeline of the alert's investigation and assignment history. -Assigning a user an Alert creates a system note, visible in the Alert Details view, -giving you a linear timeline of the alert's investigation and assignment history. +The following actions will result in a system note: + +- [Updating the status of an alert](#update-an-alerts-status) +- [Creating an issue based on an alert](#create-an-issue-from-an-alert) +- [Assignment of an alert to a user](#update-an-alerts-assignee)  +### View an Alert's metrics data + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217768) in GitLab 13.2. + +To view the metrics for an alert: + + 1. Sign in as a user with Developer or higher [permissions](../../permissions.md). + 1. Navigate to **{cloud-gear}** **Operations > Alerts**. + 1. Click the alert you want to view. + 1. Below the title of the alert, click the **Metrics** tab. + + + +For GitLab-managed Prometheus instances, metrics data is automatically available +for the alert, making it easy to see surrounding behavior. See +[Managed Prometheus instances](../../../operations/metrics/alerts.md#managed-prometheus-instances) +for information on setting up alerts. + +For externally-managed Prometheus instances, you can configure your alerting rules to +display a chart in the alert. See +[Embedding metrics based on alerts in incident issues](../../../operations/metrics/embed.md#embedding-metrics-based-on-alerts-in-incident-issues) +for information on how to appropriately configure your alerting rules. See +[External Prometheus instances](../../../operations/metrics/alerts.md#external-prometheus-instances) +for information on setting up alerts for your self-managed Prometheus instance. + ## Use cases for assigning alerts Consider a team formed by different sections of monitoring, collaborating on a diff --git a/doc/user/project/operations/dashboard_settings.md b/doc/user/project/operations/dashboard_settings.md index e14c478ab7a..f30ce5024d6 100644 --- a/doc/user/project/operations/dashboard_settings.md +++ b/doc/user/project/operations/dashboard_settings.md @@ -9,6 +9,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can configure your [Monitoring dashboard](../integrations/prometheus.md) to display the time zone of your choice, and the links of your choice. +To configure these settings you must have Manage Project +Operations [permissions](../../permissions.md). + ## Change the dashboard time zone > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214370) in GitLab 13.1. @@ -17,6 +20,7 @@ By default, your monitoring dashboard displays dates and times in your local time zone, but you can display dates and times in UTC format. To change the time zone: +1. Sign in as a user with Manage Project Operations [permissions](../../permissions.md). 1. Navigate to **{settings}** **Settings > Operations**, and scroll to **Metrics Dashboard**. 1. In the **Dashboard timezone** select box, select *User's local timezone* @@ -32,6 +36,7 @@ time zone: You can add a button on your monitoring dashboard that links directly to your existing external dashboards: +1. Sign in as a user with Manage Project Operations [permissions](../../permissions.md). 1. Navigate to **{settings}** **Settings > Operations**, and scroll to **Metrics Dashboard**. 1. In **External dashboard URL**, provide the URL to your external dashboard: diff --git a/doc/user/project/operations/feature_flags.md b/doc/user/project/operations/feature_flags.md index a9729204cd7..b0f7cfc966a 100644 --- a/doc/user/project/operations/feature_flags.md +++ b/doc/user/project/operations/feature_flags.md @@ -1,261 +1,5 @@ --- -stage: Release -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 +redirect_to: '../../../operations/feature_flags.md' --- -# Feature Flags **(PREMIUM)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7433) in GitLab 11.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. -Feature flags help reduce risk, allowing you to do controlled testing, and separate feature -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). - -## How it works - -GitLab uses [Unleash](https://github.com/Unleash/unleash), a feature -toggle service. - -By enabling or disabling a flag in GitLab, your application -can determine which features to enable or disable. - -You can create feature flags in GitLab and use the API from your application -to get the list of feature flags and their statuses. The application must be configured to communicate -with GitLab, so it's up to developers to use a compatible client library and -[integrate the feature flags in your app](#integrate-feature-flags-with-your-application). - -## Create a feature flag - -To create and enable a feature flag: - -1. Navigate to your project's **Operations > Feature Flags**. -1. Click the **New feature flag** button. -1. Enter a name that starts with a letter and contains only lowercase letters, digits, underscores (`_`) - and dashes (`-`), and does not end with a dash (`-`) or underscore (`_`). -1. Enter a description (optional, 255 characters max). -1. Enter details about how the flag should be applied: - - In GitLab 13.0 and earlier: Enter an environment spec, - enable or disable the flag in this environment, and select a rollout strategy. - - In GitLab 13.1 and later (when [this feature flag](#feature-flag-behavior-change-in-130) is enabled): Select a strategy and then - the environments to apply the strategy to. -1. Click **Create feature flag**. - -The feature flag is displayed in the list. It is enabled by default. - -## Disable a feature flag for a specific environment - -In [GitLab 13.0 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/8621), -to disable a feature flag for a specific environment: - -1. Navigate to your project's **Operations > Feature Flags**. -1. For the feature flag you want to disable, click the Pencil icon. -1. To disable the flag: - - In GitLab 13.0 and earlier: Slide the Status toggle for the environment. Or, to delete the - environment spec, on the right, click the **Remove (X)** icon. - - In GitLab 13.1 and later (when [this feature flag](#feature-flag-behavior-change-in-130) is - enabled): For each strategy it applies to, under **Environments**, delete the environment. -1. Click **Save changes**. - -## Disable a feature flag for all environments - -To disable a feature flag for all environments: - -1. Navigate to your project's **Operations > Feature Flags**. -1. For the feature flag you want to disable, slide the Status toggle to **Disabled**. - -The feature flag is displayed on the **Disabled** tab. - -## Feature flag behavior change in 13.0 - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35555) in GitLab 13.0. - -Starting in GitLab 13.0, you can apply a feature flag strategy across multiple environments, -without defining the strategy multiple times. - -This feature 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 for your instance. - -To enable it: - -```ruby -Feature.enable(:feature_flags_new_version) -``` - -To disable it: - -```ruby -Feature.disable(:feature_flags_new_version) -``` - -## Feature flag strategies - -GitLab Feature Flag uses [Unleash](https://unleash.github.io) -as the feature flag engine. In Unleash, there is a concept of rulesets for granular feature flag controls, -called [strategies](https://unleash.github.io/docs/activation_strategy). -Supported strategies for GitLab Feature Flags are described below. - -### Rollout strategy - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8240) in GitLab 12.2. - -The selected rollout strategy affects which users will experience the feature as enabled. - -The status of an environment spec ultimately determines whether or not a feature is enabled at all. -For instance, a feature will always be disabled for every user if the matching environment spec has a disabled status, regardless of the chosen rollout strategy. -However, a feature will be enabled for 50% of logged-in users if the matching environment spec has an enabled status along with a **Percent rollout (logged in users)** strategy set to 50%. - -#### All users - -Enables the feature for all users. It is implemented using the Unleash -[`default`](https://unleash.github.io/docs/activation_strategy#default) -activation strategy. - -#### Percent rollout (logged in users) - -Enables the feature for a percentage of authenticated users. It is -implemented using the Unleash -[`gradualRolloutUserId`](https://unleash.github.io/docs/activation_strategy#gradualrolloutuserid) -activation strategy. - -Set a value of 15%, for example, to enable the feature for 15% of authenticated users. - -A rollout percentage may be between 0% and 100%. - -CAUTION: **Caution:** -If this strategy is selected, then the Unleash client **must** be given a user -ID for the feature to be enabled. See the [Ruby example](#ruby-application-example) below. - -#### User IDs - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8240) in GitLab 12.2. [Updated](https://gitlab.com/gitlab-org/gitlab/-/issues/34363) to be defined per environment in GitLab 12.6. - -A feature flag may be enabled for a list of target users. It is implemented -using the Unleash [`userWithId`](https://unleash.github.io/docs/activation_strategy#userwithid) -activation strategy. - -User IDs should be a comma-separated list of values. For example, `user@example.com, user2@example.com`, or `username1,username2,username3`, etc. - -CAUTION: **Caution:** -The Unleash client **must** be given a user ID for the feature to be enabled for -target users. See the [Ruby example](#ruby-application-example) below. - -## Integrate feature flags with your application - -To use feature flags with your application, get access credentials from GitLab. -Then prepare your application with a client library. - -### Get access credentials - -To get the access credentials that your application needs to communicate with GitLab: - -1. Navigate to your project's **Operations > Feature Flags**. -1. Click the **Configure** button to view the following: - - **API URL**: URL where the client (application) connects to get a list of feature flags. - - **Instance ID**: Unique token that authorizes the retrieval of the feature flags. - - **Application name**: The name of the running environment. For instance, - if the application runs for a production server, the application name would be - `production` or similar. This value is used for the environment spec evaluation. - -NOTE: **Note:** -The meaning of these fields might change over time. For example, we are not sure -if **Instance ID** will be single token or multiple tokens, assigned to the -**Environment**. Also, **Application name** could describe the version of -application instead of the running environment. - -### Choose a client library - -GitLab implements a single backend that is compatible with Unleash clients. - -With the Unleash client, developers can define, in the application code, the default values for flags. -Each feature flag evaluation can express the desired outcome if the flag isn't present in the -provided configuration file. - -Unleash currently [offers many SDKs for various languages and frameworks](https://github.com/Unleash/unleash#client-implementations). - -### Feature flags API information - -For API content, see: - -- [Feature Flags API](../../../api/feature_flags.md) -- [Feature Flag Specs API](../../../api/feature_flag_specs.md) (Deprecated and [scheduled for removal in GitLab 14.0](https://gitlab.com/gitlab-org/gitlab/-/issues/213369).) -- [Feature Flag User Lists API](../../../api/feature_flag_user_lists.md) -- [Legacy Feature Flags API](../../../api/feature_flags_legacy.md) - -### Golang application example - -Here's an example of how to integrate feature flags in a Golang application: - -```golang -package main - -import ( - "io" - "log" - "net/http" - - "github.com/Unleash/unleash-client-go" -) - -type metricsInterface struct { -} - -func init() { - unleash.Initialize( - unleash.WithUrl("https://gitlab.com/api/v4/feature_flags/unleash/42"), - unleash.WithInstanceId("29QmjsW6KngPR5JNPMWx"), - unleash.WithAppName("production"), - unleash.WithListener(&metricsInterface{}), - ) -} - -func helloServer(w http.ResponseWriter, req *http.Request) { - if unleash.IsEnabled("my_feature_name") { - io.WriteString(w, "Feature enabled\n") - } else { - io.WriteString(w, "hello, world!\n") - } -} - -func main() { - http.HandleFunc("/", helloServer) - log.Fatal(http.ListenAndServe(":8080", nil)) -} -``` - -### Ruby application example - -Here's an example of how to integrate feature flags in a Ruby application. - -The Unleash client is given a user ID for use with a **Percent rollout (logged in users)** rollout strategy or a list of **Target Users**. - -```ruby -#!/usr/bin/env ruby - -require 'unleash' -require 'unleash/context' - -unleash = Unleash::Client.new({ - url: 'http://gitlab.com/api/v4/feature_flags/unleash/42', - app_name: 'production', - instance_id: '29QmjsW6KngPR5JNPMWx' -}) - -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: -# https://unleash.github.io/docs/unleash_context -unleash_context.user_id = "123" - -if unleash.is_enabled?("my_feature_name", unleash_context) - puts "Feature enabled" -else - puts "hello, world!" -end -``` +This document was moved to [another location](../../../operations/feature_flags.md). diff --git a/doc/user/project/operations/img/alert_detail_metrics_v13_2.png b/doc/user/project/operations/img/alert_detail_metrics_v13_2.png Binary files differnew file mode 100644 index 00000000000..84d83365ea8 --- /dev/null +++ b/doc/user/project/operations/img/alert_detail_metrics_v13_2.png diff --git a/doc/user/project/operations/img/alert_list_search_v13_1.png b/doc/user/project/operations/img/alert_list_search_v13_1.png Binary files differnew file mode 100644 index 00000000000..ba993fe530b --- /dev/null +++ b/doc/user/project/operations/img/alert_list_search_v13_1.png diff --git a/doc/user/project/operations/img/alert_list_sort_v13_1.png b/doc/user/project/operations/img/alert_list_sort_v13_1.png Binary files differnew file mode 100644 index 00000000000..8e06c3478f7 --- /dev/null +++ b/doc/user/project/operations/img/alert_list_sort_v13_1.png diff --git a/doc/user/project/operations/img/alert_list_v13_1.png b/doc/user/project/operations/img/alert_list_v13_1.png Binary files differnew file mode 100644 index 00000000000..7a1a5f5191e --- /dev/null +++ b/doc/user/project/operations/img/alert_list_v13_1.png diff --git a/doc/user/project/operations/img/alert_management_1_v13_0.png b/doc/user/project/operations/img/alert_management_1_v13_0.png Binary files differdeleted file mode 100644 index dbc1e795b16..00000000000 --- a/doc/user/project/operations/img/alert_management_1_v13_0.png +++ /dev/null diff --git a/doc/user/project/operations/img/alert_management_1_v13_1.png b/doc/user/project/operations/img/alert_management_1_v13_1.png Binary files differdeleted file mode 100644 index 00aa56a6050..00000000000 --- a/doc/user/project/operations/img/alert_management_1_v13_1.png +++ /dev/null diff --git a/doc/user/project/operations/index.md b/doc/user/project/operations/index.md index ca38eab9455..9cec578bc5e 100644 --- a/doc/user/project/operations/index.md +++ b/doc/user/project/operations/index.md @@ -1,13 +1,5 @@ -# Project operations +--- +redirect_to: '../../../operations/index.md' +--- -GitLab provides a variety of tools to help operate and maintain -your applications: - -- Collect [Prometheus metrics](../integrations/prometheus_library/index.md). -- Deploy to different [environments](../../../ci/environments/index.md). -- Connect your project to a [Kubernetes cluster](../clusters/index.md). -- Manage your infrastructure with [Infrastructure as Code](../../infrastructure/index.md) approaches. -- Discover and view errors generated by your applications with [Error Tracking](error_tracking.md). -- Create, toggle, and remove [Feature Flags](feature_flags.md). **(PREMIUM)** -- [Trace](tracing.md) the performance and health of a deployed application. **(ULTIMATE)** -- Change the [settings of the Monitoring Dashboard](dashboard_settings.md). +This document was moved to [another location](../../../operations/index.md). diff --git a/doc/user/project/operations/tracing.md b/doc/user/project/operations/tracing.md index 07f60c37f1b..87567f45560 100644 --- a/doc/user/project/operations/tracing.md +++ b/doc/user/project/operations/tracing.md @@ -1,40 +1,5 @@ --- -stage: Monitor -group: APM -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 +redirect_to: '../../../operations/tracing.md' --- -# Tracing **(ULTIMATE)** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/7903) in GitLab Ultimate 11.5. - -Tracing provides insight into the performance and health of a deployed application, -tracking each function or microservice which handles a given request. - -This makes it easy to -understand the end-to-end flow of a request, regardless of whether you are using a monolithic or distributed system. - -## Jaeger tracing - -[Jaeger](https://www.jaegertracing.io/) is an open source, end-to-end distributed -tracing system used for monitoring and troubleshooting microservices-based distributed -systems. - -### Deploying Jaeger - -To learn more about deploying Jaeger, read the official -[Getting Started documentation](https://www.jaegertracing.io/docs/latest/getting-started/). -There is an easy to use [all-in-one Docker image](https://www.jaegertracing.io/docs/latest/getting-started/#AllinoneDockerimage), -as well as deployment options for [Kubernetes](https://github.com/jaegertracing/jaeger-kubernetes) -and [OpenShift](https://github.com/jaegertracing/jaeger-openshift). - -### Enabling Jaeger - -GitLab provides an easy way to open the Jaeger UI from within your project: - -1. [Set up Jaeger](https://www.jaegertracing.io) and configure your application using one of the - [client libraries](https://www.jaegertracing.io/docs/latest/client-libraries/). -1. Navigate to your project's **Settings > Operations** and provide the Jaeger URL. -1. Click **Save changes** for the changes to take effect. -1. You can now visit **Operations > Tracing** in your project's sidebar and - GitLab will redirect you to the configured Jaeger URL. +This document was moved to [another location](../../../operations/tracing.md). |
