diff options
Diffstat (limited to 'doc/operations')
64 files changed, 390 insertions, 2023 deletions
diff --git a/doc/operations/error_tracking.md b/doc/operations/error_tracking.md index 0be2f087c62..db68abf0778 100644 --- a/doc/operations/error_tracking.md +++ b/doc/operations/error_tracking.md @@ -6,12 +6,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Error Tracking **(FREE)** -> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/389991) in GitLab 15.9. - -WARNING: -This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/389991) -for use in GitLab 15.9, and is planned for removal in GitLab 16.0. We are replacing this feature with functionality in the [GitLab Observability UI](https://gitlab.com/gitlab-org/opstrace/opstrace-ui). Please also reference our direction for [Observability](https://about.gitlab.com/direction/monitor/observability/) and [data visualization](https://about.gitlab.com/direction/monitor/observability/data-visualization/). - Error Tracking allows developers to discover and view errors generated by their application. Because error information is surfaced where the code is being developed, efficiency and awareness are increased. ## How error tracking works @@ -34,15 +28,15 @@ For error tracking to work, you need two pieces: ## Sentry error tracking -[Sentry](https://sentry.io/) is an open source error tracking system. GitLab allows administrators to connect Sentry to GitLab, to allow users to view a list of Sentry errors in GitLab. +[Sentry](https://sentry.io/) is an open source error tracking system. GitLab allows administrators to connect Sentry to GitLab so users can view a list of Sentry errors in GitLab. ### Deploying Sentry -You can sign up to the cloud hosted [Sentry](https://sentry.io) or deploy your own [on-premise instance](https://github.com/getsentry/onpremise/). +You can sign up to the cloud-hosted [Sentry](https://sentry.io) or deploy your own [on-premise instance](https://github.com/getsentry/onpremise/). ### Enabling Sentry -GitLab provides an easy way to connect Sentry to your project. You need at +GitLab provides a way to connect Sentry to your project. You need at least Maintainer [permissions](../user/permissions.md) to enable the Sentry integration. 1. Sign up to Sentry.io or [deploy your own](#deploying-sentry) Sentry instance. @@ -84,7 +78,7 @@ DSN in **Sentry.io > Project Settings > Client Keys (DSN) > Show deprecated DSN* ERROR: Sentry failure builds=0 error=raven: dsn missing private key ``` -## Error Tracking List +## Error Tracking list Users with at least Reporter [permissions](../user/permissions.md) can find the Error Tracking list at **Monitor > Error Tracking** in your project's sidebar. @@ -92,11 +86,11 @@ Here, you can filter errors by title or by status (one of Ignored , Resolved, or  -## Error Details +## Error details -From error list, users can navigate to the error details page by selecting the title of any error. +From error list, users can go to the error details page by selecting the title of any error. -This page has: +This page includes: - A link to the Sentry issue. - A link to the GitLab commit if the Sentry [release ID/version](https://docs.sentry.io/product/releases/?platform=javascript#configure-sdk) on the Sentry Issue's first release matches a commit SHA in your GitLab hosted project. @@ -108,26 +102,26 @@ By default, a **Create issue** button is displayed:  If you create a GitLab issue from the error, the **Create issue** button changes to a **View issue** -button and a link to the GitLab issue displays within the error detail section. +button and a link to the GitLab issue displays in the error detail section. -## Taking Action on errors +## Taking action on errors -You can take action on Sentry Errors from within the GitLab UI. Marking errors ignored or resolved require at least Developer role. +You can take action on Sentry Errors in the GitLab UI. Marking errors as ignored or resolved requires at least Developer role. ### Ignoring errors > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39665) in GitLab 12.7. -From within the [Error Details](#error-details) page you can ignore a Sentry error by selecting the **Ignore** button near the top of the page. +In the [Error Details](#error-details) page you can ignore a Sentry error by selecting **Ignore** near the top of the page. -Ignoring an error prevents it from appearing in the [Error Tracking List](#error-tracking-list), and silences notifications that were set up within Sentry. +Ignoring an error prevents it from appearing in the [Error Tracking List](#error-tracking-list), and silences notifications that were set up in Sentry. ### Resolving errors > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/39825) in GitLab 12.7. -From within the [Error Details](#error-details) page you can resolve a Sentry error by -selecting the **Resolve** button near the top of the page. +In the [Error Details](#error-details) page you can resolve a Sentry error by +selecting **Resolve** near the top of the page. Marking an error as resolved indicates that the error has stopped firing events. If a GitLab issue is linked to the error, then the issue closes. @@ -140,53 +134,225 @@ If another event occurs, the error reverts to unresolved. > - [Enabled on GitLab.com](https://gitlab.com/gitlab-com/gl-infra/production/-/issues/7586) in GitLab 15.6. NOTE: -Available only on GitLab.com. This feature is currently in [Open Beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#open-beta). +Available only on GitLab.com. This feature is in [Open Beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#open-beta). + +### Known limitations + +Only basic support is provided with `capture_exception` as the holding method. +Additional features requests (see this [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/340178)) are added on a case-by-case basis. + +### Debugging issues + +The majority of languages are supported by Sentry expose `debug` option as part of initialization. +It is also possible to output JSON before it is sent to the API. +See the [Go example](#go) below for a suggested solution. + +### Enabling error tracking + +Regardless of the programming language, you need to enable error tracking for your project. This doc assumes you already have a project for which you want to enable error tracking. +This example uses the `gitlab.com` instance. + +To enable error tracking, follow these steps: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Monitor**. +1. Expand the **Error Tracking** tab. +1. Under **Enable error tracking**, select the **Active** checkbox. +1. Under **Error tracking backend**, select **GitLab**. +1. Select **Save changes**. +1. Copy the DSN string to use later. + +### Listing captured errors + +Once your application has emitted errors to the Error Tracking API through the Sentry SDK, they should be available under **Monitor > Error Tracking** tab/section. + +For more details, refer to the [GitLab error tracking documentation](https://gitlab.com/help/operations/error_tracking#error-tracking-list). + +This process assumes the GDK feature flag `integrated_error_tracking` is enabled. If you are running GDK locally and you do not see the option for error tracking, you can enable it by running the following commands: + +```linux +cd <PATH_TO_GDK> +gdk rails console +Feature.enable(:integrated_error_tracking) +``` + +### Emitting errors + +#### Supported Sentry types + +According to the [data model](https://develop.sentry.dev/sdk/envelopes/#data-model), the available item types are: + +- [Event](https://develop.sentry.dev/sdk/event-payloads/) +- [Transactions](https://develop.sentry.dev/sdk/event-payloads/transaction/) +- Attachment +- [Session](https://develop.sentry.dev/sdk/sessions/) +- [Sessions](https://develop.sentry.dev/sdk/sessions/) +- [User feedback](https://develop.sentry.dev/sdk/envelopes/#user-feedback) (also known as user report) +- [Client report](https://develop.sentry.dev/sdk/client-reports/) + +Items of various types can be sent to the error tracking app, using either the Store endpoint, the envelope endpoint, or both. The following table lists all event types available through Sentry SDK. It also explains which endpoint can be used for ingestion and whether it is supported by GitLab Observability Backend. + +Event item types can contain various interfaces, such as exception, message, stack trace, and template. You can read more about the core data interfaces in [Sentry documentation](https://develop.sentry.dev/sdk/event-payloads/#core-interfaces). + +| Item type | Interface | Can be sent through the Store endpoint | Can be sent through the Envelope endpoint | Supported | +| --------------- | ----------- | -------------------------------------- | ----------------------------------------- | ---------------------- | +| `event` | exception | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| `event` | message | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| `event` | stack trace | **{check-circle}** Yes | **{check-circle}** Yes | **{check-circle}** Yes | +| `event` | template | **{check-circle}** Yes | **{check-circle}** Yes | **{dotted-circle}** No | +| `transaction` | N/A | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | +| `attachment` | N/A | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | +| `session` | N/A | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | +| `sessions` | N/A | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | +| `user_report` | N/A | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | +| `client_report` | N/A | **{dotted-circle}** No | **{check-circle}** Yes | **{dotted-circle}** No | + +#### Supported languages + +Each language shows a basic example of how to capture exceptions with the respective SDK. +For more in-depth documentation, see [documentation for Sentry SDK](https://docs.sentry.io/). You can also find information for additional programming languages. + +Only a subset of languages is supported. + +The following table lists them: + +| Sentry SDK | Supported? | +| ----------- | ----------- | +| Ruby | Yes | +| Go | Yes | +| JavaScript | Yes | +| Java | Yes | +| Python | Yes | +| PHP | Yes | +| .NET | Not tested | +| Android | Not tested | +| Apple | Not tested | +| Perl | Not tested | + +A more up-to-date version of [this matrix can be found in this doc](https://gitlab.com/gitlab-org/opstrace/opstrace/-/issues/1737). -Integrated error tracking is a lightweight alternative to Sentry backend. -You still use Sentry SDK with your application. But you don't need to deploy Sentry -or set up for cloud-hosted Sentry. Instead, you use GitLab as a backend for it. +#### Go -Sentry backend automatically assigns a Data Source Name (DSN) for every project you create. -GitLab does the same. You should be able to find a DSN for your project in the GitLab error tracking -settings. By using a GitLab-provided DSN, your application connects to GitLab to report an error. -Those errors are stored in the GitLab database and rendered by the GitLab UI, in the same way as -Sentry integration. +1. `chdir` into folder `docs/guides/user/error_tracking_examples/go/` +1. Install the dependencies with the following command: + + ```shell + go mod tidy + ``` + +1. Run the following command: + + ```shell + export SENTRY_DSN="<DSN string>" + go run main.go <DSN string> + ``` + +After you've run this program, there should be an error visible in the Error tracking tab from `Listing captured errors` section of this document. + +#### Ruby + +1. `chdir` into folder `docs/guides/user/error_tracking_examples/ruby/` +1. Install the dependencies with the following command: + + ```shell + gem install bundler + bundle install + ``` + +1. Execute the example with the following command: + + ```shell + export SENTRY_DSN="<DSN string>" + ruby app.rb + ``` + +After you've run this program, there should be an error visible in the Error tracking tab from `Listing captured errors` section of this document. + +#### PHP + +1. `chdir` into folder `docs/guides/user/error_tracking_examples/php/` + +1. Build and run the Docker container with the following commands: + +```shell +export SENTRY_DSN="<DSN string>" +docker build -t sentry-php . +docker run -e SENTRY_DSN --rm sentry-php +``` + +After you've run this program, there should be an error visible in the Error tracking tab from `Listing captured errors` section of this document. + +#### Python + +1. `chdir` into folder `docs/guides/user/error_tracking_examples/python/` + +1. Install the dependencies with the following commands: + + ```shell + virtualenv env + source env/bin/activate + pip install -r requirements.txt + ``` + +1. Run the following commands: + +```shell +export SENTRY_DSN="<DSN string>" +python send_exception.py +``` + +After you've run this program, there should be an error visible in the Error tracking tab from `Listing captured errors` section of this document. + +#### Java + +1. `chdir` into folder `docs/guides/user/error_tracking_examples/python/` + +1. Run the following command: + +```shell +export SENTRY_DSN="<DSN string>" +./gradlew run +``` -In GitLab 15.6 and later, the integrated error tracking -uses a new backend based on the ClickHouse database that enables better scalability. -Integrated error tracking remains limited in comparison to the Sentry backend, as only a small subset of the -Sentry API is implemented. +#### Node.js -Changing the GitLab error UI to use the GitLab Observability UI is tracked in epic [19](https://gitlab.com/groups/gitlab-org/opstrace/-/epics/32). +1. `chdir` into folder `docs/guides/user/error_tracking_examples/nodejs/` -### Project settings +1. Install the dependencies with the following command: -You can find the feature configuration at **Settings > Monitor > Error Tracking**. + ```shell + npm install --save @sentry/node @sentry/tracing + ``` -#### How to enable +1. Run the following command: -1. Select **GitLab** as the error tracking backend for your project: + ```shell + export SENTRY_DSN="<DSN string>" + node ./test.js + ``` -  +After you've run this program, there should be an error visible in the Error tracking tab from `Listing captured errors` section of this document. -1. Select **Save changes**. After page reload you should see a text field with the DSN string. Copy it. +### Rotating Sentry DSN -  +The Sentry DSN (client key) is a secret and it should not be exposed to the public. If it's leaked, you can rotate the Sentry DSN with the following steps: -1. Take the DSN from the previous step and configure your Sentry SDK with it. Errors are now - reported to the GitLab collector and are visible in the [GitLab UI](#error-tracking-list). +1. [Create an access token](../user/profile/personal_access_tokens.md#create-a-personal-access-token) by clicking your profile picture in GitLab.com. Then choose Preferences,then Access Token. Make sure you add the API scope. +1. Using the [error tracking API](../api/error_tracking.md), create a new Sentry DSN with the following command: -#### Managing DSN + ```shell + curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \ + "https://gitlab.example.com/api/v4/projects/<your_project_number>/error_tracking/client_keys" + ``` -When you enable the feature you receive a DSN. It includes a hash used for authentication. This hash -is a client key. GitLab uses client keys to authenticate error tracking requests from your -application to the GitLab backend. +1. Get the available client keys (Sentry DSNs). Ensure that the newly created Sentry DSN is in place. Then note down the key ID of the old client key: -In some situations, you may want to create a new client key and remove an existing one. -You can do so by managing client keys with the [error tracking API](../api/error_tracking.md). + ```shell + curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<your_project_number>/error_tracking/client_keys" + ``` -#### Limitations +1. Delete the old client key with the following command: -The Integrated Error Tracking feature was built and tested with Sentry SDK for Ruby on Rails. -Support for other languages and frameworks is not guaranteed. For up-to-date information, see the -[compatibility issue](https://gitlab.com/gitlab-org/gitlab/-/issues/340178). + ```shell + curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<your_project_number>/error_tracking/client_keys/<key_id>" + ``` diff --git a/doc/operations/feature_flags.md b/doc/operations/feature_flags.md index 68fc0fb9499..a3874b54ccd 100644 --- a/doc/operations/feature_flags.md +++ b/doc/operations/feature_flags.md @@ -1,6 +1,6 @@ --- -stage: Release -group: Release +stage: Deploy +group: Environments info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -38,7 +38,7 @@ with GitLab, so it's up to developers to use a compatible client library and To create and enable a feature flag: 1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Deployments > Feature Flags**. +1. On the left sidebar, select **Deployments > Feature flags**. 1. Select **New feature flag**. 1. Enter a name that starts with a letter and contains only lowercase letters, digits, underscores (`_`), or dashes (`-`), and does not end with a dash (`-`) or underscore (`_`). @@ -85,7 +85,7 @@ and the supported strategies are: - [User List](#user-list) Strategies can be added to feature flags when [creating a feature flag](#create-a-feature-flag), -or by editing an existing feature flag after creation by navigating to **Deployments > Feature Flags** +or by editing an existing feature flag after creation by navigating to **Deployments > Feature flags** and selecting **Edit** (**{pencil}**). ### All users @@ -151,7 +151,7 @@ Enables the feature for a list of target users. It is implemented using the Unleash UserIDs (`userWithId`) activation [strategy](https://docs.getunleash.io/reference/activation-strategies#userids). Enter user IDs as a comma-separated list of values (for example, -`user@example.com, user2@example.com`, or `username1,username2,username3`, and so on). +`user@example.com, user2@example.com`, or `username1,username2,username3`, and so on). User IDs are identifiers for your application users. They do not need to be GitLab users. WARNING: @@ -181,7 +181,7 @@ For example: To create a user list: 1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Deployments > Feature Flags**. +1. On the left sidebar, select **Deployments > Feature flags**. 1. Select **View user lists** 1. Select **New user list**. 1. Enter a name for the list. @@ -197,7 +197,7 @@ When viewing a list, you can rename it by selecting **Edit** (**{pencil}**). To add users to a user list: 1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Deployments > Feature Flags**. +1. On the left sidebar, select **Deployments > Feature flags**. 1. Select **Edit** (**{pencil}**) next to the list you want to add users to. 1. Select **Add Users**. 1. Enter the user IDs as a comma-separated list of values. For example, @@ -211,7 +211,7 @@ To add users to a user list: To remove users from a user list: 1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Deployments > Feature Flags**. +1. On the left sidebar, select **Deployments > Feature flags**. 1. Select **Edit** (**{pencil}**) next to the list you want to change. 1. Select **Remove** (**{remove}**) next to the ID you want to remove. @@ -225,7 +225,7 @@ code so that you can clean it up when it's time to remove the feature flag. To search for code references of a feature flag: 1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Deployments > Feature Flags**. +1. On the left sidebar, select **Deployments > Feature flags**. 1. Edit the feature flag you want to remove. 1. Select **More actions** (**{ellipsis_v}**). 1. Select **Search code references**. @@ -236,7 +236,7 @@ In [GitLab 13.0 and earlier](https://gitlab.com/gitlab-org/gitlab/-/issues/8621) to disable a feature flag for a specific environment: 1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Deployments > Feature Flags**. +1. On the left sidebar, select **Deployments > Feature flags**. 1. For the feature flag you want to disable, select **Edit** (**{pencil}**). 1. To disable the flag: @@ -251,7 +251,7 @@ to disable a feature flag for a specific environment: To disable a feature flag for all environments: 1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Deployments > Feature Flags**. +1. On the left sidebar, select **Deployments > 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. @@ -266,7 +266,7 @@ Then prepare your application with a client library. To get the access credentials that your application needs to communicate with GitLab: 1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Deployments > Feature Flags**. +1. On the left sidebar, select **Deployments > Feature flags**. 1. Select **Configure** 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. @@ -295,14 +295,13 @@ Unleash currently [offers many SDKs for various languages and frameworks](https: 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](https://gitlab.com/gitlab-org/gitlab/-/issues/213369) in GitLab 14.0.) - [Feature flag user lists API](../api/feature_flag_user_lists.md) -### Golang application example +### Go application example -Here's an example of how to integrate feature flags in a Golang application: +Here's an example of how to integrate feature flags in a Go application: -```golang +```go package main import ( diff --git a/doc/operations/img/copy-group-id.png b/doc/operations/img/copy-group-id.png Binary files differdeleted file mode 100644 index 7837f49c3e3..00000000000 --- a/doc/operations/img/copy-group-id.png +++ /dev/null diff --git a/doc/operations/img/create-gitlab-application.png b/doc/operations/img/create-gitlab-application.png Binary files differdeleted file mode 100644 index 430b830cdb2..00000000000 --- a/doc/operations/img/create-gitlab-application.png +++ /dev/null diff --git a/doc/operations/img/error_tracking_setting_dsn_v14_4.png b/doc/operations/img/error_tracking_setting_dsn_v14_4.png Binary files differdeleted file mode 100644 index b7ecaa047b2..00000000000 --- a/doc/operations/img/error_tracking_setting_dsn_v14_4.png +++ /dev/null diff --git a/doc/operations/img/error_tracking_setting_v14_3.png b/doc/operations/img/error_tracking_setting_v14_3.png Binary files differdeleted file mode 100644 index 14306130c97..00000000000 --- a/doc/operations/img/error_tracking_setting_v14_3.png +++ /dev/null diff --git a/doc/operations/img/listing_groups.png b/doc/operations/img/listing_groups.png Binary files differdeleted file mode 100644 index 1094bf4ff28..00000000000 --- a/doc/operations/img/listing_groups.png +++ /dev/null diff --git a/doc/operations/incident_management/alerts.md b/doc/operations/incident_management/alerts.md index 6d6fde45de7..74e0ed5f06a 100644 --- a/doc/operations/incident_management/alerts.md +++ b/doc/operations/incident_management/alerts.md @@ -205,3 +205,28 @@ You can manually create a [to-do item](../../user/todos.md) for yourself from an alert, and view it later on your **To-Do List**. To add a to-do item, on the right sidebar, select **Add a to do**. + +### Trigger actions from alerts **(ULTIMATE)** + +> - Introduced in GitLab 13.1: incidents are not created automatically by default. +> - Mapping common severity values from the alert payload [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50871) in GitLab 13.9. + +Turn on creating [incidents](incidents.md) automatically whenever an alert is triggered. + +Prerequisites: + +- You must have at least the Maintainer role for the project. + +To configure the actions: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Monitor**. +1. Expand the **Alerts** section, then select the **Alert settings** tab. +1. Select the **Create an incident** checkbox. +1. Optional. To customize the incident, from the **Incident template**, select a template to be + appended to the [incident summary](incidents.md#summary). + If the dropdown list is empty, + [create an issue template](../../user/project/description_templates.md#create-an-issue-template) first. +1. Optional. To send [an email notification](paging.md#email-notifications-for-alerts), select the + **Send a single email notification to Owners and Maintainers for new alerts** checkbox. +1. Select **Save changes**. diff --git a/doc/operations/incident_management/incident_timeline_events.md b/doc/operations/incident_management/incident_timeline_events.md index e79f36884cb..d509061eca0 100644 --- a/doc/operations/incident_management/incident_timeline_events.md +++ b/doc/operations/incident_management/incident_timeline_events.md @@ -83,6 +83,17 @@ of an incident.  +### When labels change (Experiment) + +> [Introduced]([issue-link](https://gitlab.com/gitlab-org/gitlab/-/issues/365489)) in GitLab 15.3 [with a flag](../../administration/feature_flags.md) named `incident_timeline_events_from_labels`. Disabled by default. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available per project or for your entire instance, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `incident_timeline_events_from_labels`. +On GitLab.com, this feature is not available. +This feature is not ready for production use. + +A new timeline event is created when someone adds or removes [labels](../../user/project/labels.md) on an incident. + ## Delete an event > Ability to delete an event when editing it [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/372265) in GitLab 15.7. @@ -110,12 +121,10 @@ Alternatively: ## Incident tags -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8741) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `incident_event_tags`. Disabled by default. - -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `incident_event_tags`. -On GitLab.com, this feature is not available. -This feature is not ready for production use. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/8741) in GitLab 15.9 [with a flag](../../administration/feature_flags.md) named `incident_event_tags`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/387647) in GitLab 15.9. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/387647) in GitLab 15.10. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/387647) in GitLab 15.11. Feature flag `incident_event_tags` removed. [When creating an event using the form](#using-the-form) or editing it, you can specify incident tags to capture relevant incident timestamps. diff --git a/doc/operations/incident_management/incidents.md b/doc/operations/incident_management/incidents.md index 45f1e10d2f1..5f1a2880c4b 100644 --- a/doc/operations/incident_management/incidents.md +++ b/doc/operations/incident_management/incidents.md @@ -70,7 +70,7 @@ To filter the incident list by author or assignee, enter these values in the sea ### Summary The summary section for incidents provides critical details about the -incident and the contents of the issue template (if [selected](../metrics/alerts.md#trigger-actions-from-alerts)). The highlighted +incident and the contents of the issue template (if [selected](alerts.md#trigger-actions-from-alerts)). The highlighted bar at the top of the incident displays from left to right: - The link to the original alert. @@ -87,14 +87,14 @@ Below the highlight bar, a summary includes the following fields: The incident summary can be further customized using [GitLab Flavored Markdown](../../user/markdown.md). -If an incident is [created from an alert](../metrics/alerts.md#trigger-actions-from-alerts) +If an incident is [created from an alert](alerts.md#trigger-actions-from-alerts) that provided Markdown for the incident, then the Markdown is appended to the summary. If an incident template is configured for the project, then the template content is appended at the end. Comments are displayed in threads, but can be displayed chronologically [by toggling on the recent updates view](#recent-updates-view). -When you make changes to an incident, GitLab creates system notes and +When you make changes to an incident, GitLab creates [system notes](../../user/project/system_notes.md) and displays them below the summary. ### Metrics **(PREMIUM)** @@ -169,14 +169,13 @@ label to the incident. ## Related topics - [Create an incident](manage_incidents.md#create-an-incident) -- [Create an incident automatically](../metrics/alerts.md#trigger-actions-from-alerts) +- [Create an incident automatically](alerts.md#trigger-actions-from-alerts) whenever an alert is triggered - [View incidents list](manage_incidents.md#view-incidents-list) - [Assign to a user](manage_incidents.md#assign-to-a-user) - [Change incident severity](manage_incidents.md#change-severity) - [Change incident status](manage_incidents.md#change-status) - [Change escalation policy](manage_incidents.md#change-escalation-policy) -- [Embed metrics](manage_incidents.md#embed-metrics) - [Close an incident](manage_incidents.md#close-an-incident) - [Automatically close incidents via recovery alerts](manage_incidents.md#automatically-close-incidents-via-recovery-alerts) - [Add a to-do item](../../user/todos.md#create-a-to-do-item) @@ -187,7 +186,7 @@ label to the incident. - [Toggle notifications](../../user/profile/notifications.md#edit-notification-settings-for-issues-merge-requests-and-epics) - [Track spent time](../../user/project/time_tracking.md) - [Add a Zoom meeting to an incident](../../user/project/issues/associate_zoom_meeting.md) the same - way you add it to an issue. + way you add it to an issue - [Linked resources in incidents](linked_resources.md) -- Create incidents and receive incident notifications [directly from Slack](slack.md). -- Use the [Issues API](../../api/issues.md) to interact with incidents. +- Create incidents and receive incident notifications [directly from Slack](slack.md) +- Use the [Issues API](../../api/issues.md) to interact with incidents diff --git a/doc/operations/incident_management/manage_incidents.md b/doc/operations/incident_management/manage_incidents.md index ad4de8641e5..187a398b1ee 100644 --- a/doc/operations/incident_management/manage_incidents.md +++ b/doc/operations/incident_management/manage_incidents.md @@ -70,7 +70,7 @@ You are then credited with the alert's status change. ### Automatically, when an alert is triggered **(ULTIMATE)** -In the project settings, you can turn on [creating an incident automatically](../metrics/alerts.md#trigger-actions-from-alerts) +In the project settings, you can turn on [creating an incident automatically](alerts.md#trigger-actions-from-alerts) whenever an alert is triggered. ### Using the PagerDuty webhook @@ -201,18 +201,14 @@ In GitLab 15.1 and earlier, the escalation policy for [incidents created from al reflects the alert's escalation policy and cannot be changed. In [GitLab 15.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/356057), the incident escalation policy is independent and can be changed. -## Embed metrics +<!--- start_remove The following content will be removed on remove_date: '2023-08-22' --> -You can embed metrics anywhere [GitLab Flavored Markdown](../../user/markdown.md) is -used, like descriptions or comments. Embedding -metrics helps you share them when discussing incidents or performance issues. +## Embed metrics (removed) -To embed metrics in a Markdown text box in GitLab, -[paste the link to the dashboard](../metrics/embed.md#embedding-gitlab-managed-kubernetes-metrics). +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. -You can embed both [GitLab-hosted metrics](../metrics/embed.md) (deprecated) and -[Grafana metrics](../metrics/embed_grafana.md) in incidents and issue -templates. +<!--- end_remove --> ## Close an incident @@ -220,12 +216,16 @@ Prerequisites: - You must have at least the Reporter role for the project. -To close an incident, in the upper right, select **Close incident**. +To close an incident, in the upper-right corner, select **Close incident**. When you close an incident that is linked to an [alert](alerts.md), the linked alert's status changes to **Resolved**. You are then credited with the alert's status change. +<!-- Delete when the `moved_mr_sidebar` feature flag is removed --> +If you don't see this action at the top of an incident, your project or instance might have +enabled a feature flag for [moved actions](../../user/project/merge_requests/index.md#move-sidebar-actions) + ### Automatically close incidents via recovery alerts > [Introduced for HTTP integrations](https://gitlab.com/gitlab-org/gitlab/-/issues/13402) in GitLab 13.4. @@ -249,6 +249,22 @@ When GitLab receives a recovery alert, it closes the associated incident. This action is recorded as a system note on the incident indicating that it was closed automatically by the GitLab Alert bot. +## Delete an incident + +Prerequisites: + +- You must have the Owner role for a project. + +To delete an incident: + +1. In an incident, select **Incident actions** (**{ellipsis_v}**). +1. Select **Delete incident**. + +Alternatively: + +1. In an incident, select **Edit title and description** (**{pencil}**). +1. Select **Delete incident**. + ## Other actions Because incidents in GitLab are built on top of [issues](../../user/project/issues/index.md), diff --git a/doc/operations/incident_management/slack.md b/doc/operations/incident_management/slack.md index 434c481900c..1f6097ccbdb 100644 --- a/doc/operations/incident_management/slack.md +++ b/doc/operations/incident_management/slack.md @@ -4,13 +4,14 @@ group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# Incident management for Slack **(FREE SAAS)** +# Incident management for Slack (Beta) **(FREE SAAS)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344856) in GitLab 15.7 [with a flag](../../administration/feature_flags.md) named `incident_declare_slash_command`. Disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/344856) in GitLab 15.7 [with a flag](../../administration/feature_flags.md) named `incident_declare_slash_command`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/378072) in GitLab 15.10 in [Beta](../../policy/alpha-beta-support.md#beta). FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `incident_declare_slash_command`. -On GitLab.com, this feature is not available. +On self-managed GitLab, this feature is not available. +On GitLab.com, this feature is available. The feature is not ready for production use. Many teams receive alerts and collaborate in real time during incidents in Slack. @@ -68,7 +69,7 @@ To declare a GitLab incident from Slack: - The project where the incident should be created. - The severity of the incident. - If there is an existing [incident template](../metrics/alerts.md#trigger-actions-from-alerts) for your + If there is an existing [incident template](alerts.md#trigger-actions-from-alerts) for your project, that template is automatically applied to the description text box. The template is applied only if the description text box is empty. diff --git a/doc/operations/incident_management/status_page.md b/doc/operations/incident_management/status_page.md index 5dd690a1c9f..fd37279806f 100644 --- a/doc/operations/incident_management/status_page.md +++ b/doc/operations/incident_management/status_page.md @@ -159,13 +159,13 @@ To publish comments to the Status Page Incident: - Create a comment on the incident issue. - When you're ready to publish the comment, mark the comment for publication by - adding a microphone [award emoji](../../user/award_emojis.md) + adding a microphone [emoji reaction](../../user/award_emojis.md) reaction (`:microphone:` 🎤) to the comment. - Any files attached to the comment (up to 5000 per issue) are also published. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/205166) in GitLab 13.1.) WARNING: -Anyone with access to view the Issue can add an emoji award to a comment, so +Anyone with access to view the Issue can add an emoji reaction to a comment, so consider limiting access to issues to team members only. ### Update the incident status diff --git a/doc/operations/index.md b/doc/operations/index.md index ff13c617ea7..922ec557c4c 100644 --- a/doc/operations/index.md +++ b/doc/operations/index.md @@ -9,40 +9,26 @@ info: To determine the technical writer assigned to the Stage/Group associated w GitLab provides a variety of tools to help operate and maintain your applications. -## Measure reliability and stability with metrics (DEPRECATED) +<!--- start_remove The following content will be removed on remove_date: '2023-08-22' --> -> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. +## Measure reliability and stability with metrics (removed) -WARNING: -This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -for use in GitLab 14.7, and is planned for removal in GitLab 16.0. +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. -Metrics help you understand the health and performance of your infrastructure, -applications, and systems by providing insights into your application's reliability, -stability, and performance. GitLab provides a default dashboard that you -can extend with custom metrics, and augment with additional custom dashboards. You -can track the metrics that matter most to your team, generate automated alerts when -performance degrades, and manage those alerts - all within GitLab. - -- Collect [Prometheus metrics](../user/project/integrations/prometheus_library/index.md). -- Monitor application status with the [out-of-the-box metrics dashboard](metrics/index.md), - which you can [customize](metrics/dashboards/settings.md). -- Create [custom performance alerts](metrics/alerts.md). -- Create [custom metrics](metrics/index.md#adding-custom-metrics) and - [custom dashboards](metrics/dashboards/index.md). +<!--- end_remove --> ## Manage alerts and incidents GitLab helps reduce alert fatigue for IT responders by providing tools to identify issues across multiple systems and aggregate alerts in a centralized place. Your -team needs a single, central interface where they can easily investigate alerts +team needs a single, central interface where they can investigate alerts and promote the critical alerts to incidents. -Are your alerts too noisy? Alerts configured on GitLab metrics can configured +Are your alerts too noisy? Alerts can be configured and fine-tuned in GitLab immediately following a fire-fight. - [Manage alerts and incidents](incident_management/index.md) in GitLab. -- [Configure alerts for metrics](metrics/alerts.md) in GitLab. (DEPRECATED) - Create a [status page](incident_management/status_page.md) to communicate efficiently to your users during an incident. @@ -76,4 +62,4 @@ an environment. - Deploy to different [environments](../ci/environments/index.md). - Connect your project to a [Kubernetes cluster](../user/infrastructure/clusters/index.md). -- Create, toggle, and remove [Feature Flags](feature_flags.md). +- Create, toggle, and remove [feature flags](feature_flags.md). diff --git a/doc/operations/metrics/alerts.md b/doc/operations/metrics/alerts.md index 44cd683bc4f..44a257f532b 100644 --- a/doc/operations/metrics/alerts.md +++ b/doc/operations/metrics/alerts.md @@ -2,81 +2,11 @@ stage: Monitor group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +remove_date: '2023-08-22' +redirect_to: '../index.md' --- -# Set up alerts for Prometheus metrics **(FREE)** +# Set up alerts for Prometheus metrics (removed) **(FREE)** -After [configuring metrics for your CI/CD environment](index.md), you can set up -alerting for Prometheus metrics, and -[trigger actions from alerts](#trigger-actions-from-alerts) to notify -your team when environment performance falls outside of the boundaries you set. - -## Prometheus cluster integrations - -Alerts are not supported for [Prometheus cluster integrations](../../user/clusters/integrations.md). - -## Trigger actions from alerts **(ULTIMATE)** - -> - Introduced in GitLab 13.1: incidents are not created automatically by default . -> - Mapping common severity values from the alert payload ([introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/50871) in GitLab 13.9. - -Turn on creating [incidents](../incident_management/incidents.md) automatically whenever an alert is triggered. - -Prerequisites: - -- You must have at least the Maintainer role for the project. - -To configure the actions: - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Monitor**. -1. Expand the **Alerts** section, then select the **Alert settings** tab. -1. Select the **Create an incident** checkbox. -1. Optional. To customize the incident, from the **Incident template**, select a template to be - appended to the [incident summary](../incident_management/incidents.md#summary). - If the dropdown list is empty, - [create an issue template](../../user/project/description_templates.md#create-an-issue-template) first. -1. Optional. To send [an email notification](../incident_management/paging.md#email-notifications-for-alerts), select the - **Send a single email notification to Owners and Maintainers for new alerts** checkbox. -1. Select **Save changes**. - -### Fields in automatically created incidents - -Incidents [created automatically from an alert](#trigger-actions-from-alerts) are filled with -values extracted from the `alerts` field in the -[webhook payload](https://prometheus.io/docs/alerting/latest/configuration/#webhook_config): - -- Incident author: `GitLab Alert Bot` -- Incident title: Extracted from the alert payload fields `annotations/title`, `annotations/summary`, or `labels/alertname`. -- Incident description: Extracted from alert payload field `annotations/description`. -- Alert `Summary`: A list of properties from the alert's payload. - - `starts_at`: Alert start time from the payload's `startsAt` field - - `full_query`: Alert query extracted from the payload's `generatorURL` field - - Optional list of attached annotations extracted from `annotations/*` -- Alert [GLFM](../../user/markdown.md): GitLab Flavored Markdown from the payload's `annotations/gitlab_incident_markdown` field. -- Alert severity: - Extracted from the alert payload field `labels/severity`. Maps case-insensitive - value to [Alert's severity](../incident_management/alerts.md#alert-severity): - - | Alert payload | Mapped to alert severity | - | ------------- | --------------------------------------------------------------------------- | - | Critical | `critical`, `s1`, `p1`, `emergency`, `fatal`, or any value not in this list | - | High | `high`, `s2`, `p2`, `major`, `page` | - | Medium | `medium`, `s3`, `p3`, `error`, `alert` | - | Low | `low`, `s4`, `p4`, `warn`, `warning` | - | Info | `info`, `s5`, `p5`, `debug`, `information`, `notice` | - -To further customize the incident, you can add labels, mentions, or any other supported -[quick action](../../user/project/quick_actions.md) in the selected issue template, -which applies to all incidents. To limit quick actions or other information to -only specific types of alerts, use the `annotations/gitlab_incident_markdown` field. - -GitLab tags each incident issue with the `incident` label automatically. If the label -does not yet exist, it's created automatically. - -### Recovery alerts - -The alert in GitLab is automatically resolved when Prometheus -sends a payload with the field `status` set to `resolved`. - -You can also configure the associated [incident to be closed automatically](../incident_management/manage_incidents.md#automatically-close-incidents-via-recovery-alerts) when the alert resolves. +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/operations/metrics/dashboards/default.md b/doc/operations/metrics/dashboards/default.md index e22b1096023..28a3adc5051 100644 --- a/doc/operations/metrics/dashboards/default.md +++ b/doc/operations/metrics/dashboards/default.md @@ -2,42 +2,11 @@ stage: Monitor group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +remove_date: '2023-08-22' +redirect_to: '../../index.md' --- -# GitLab-defined metrics dashboards (DEPRECATED) **(FREE)** +# GitLab-defined metrics dashboards (removed) **(FREE)** -> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. - -WARNING: -This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -in GitLab 14.7, and is planned for removal in GitLab 16.0. - -GitLab provides some dashboards out-of-the-box for any project with -[Prometheus available](../../../user/project/integrations/prometheus.md). You can -[duplicate these GitLab-defined dashboards](index.md#duplicate-a-gitlab-defined-dashboard): - -- [Overview dashboard](#overview-dashboard). -- [Kubernetes pod health dashboard](#kubernetes-pod-health-dashboard). - -To learn about the components of a dashboard, read -[Metrics dashboard for your CI/CD environment](../index.md). - -## Overview dashboard - -This dashboard is the default metrics dashboard. It displays a large number of -metrics about the [deployed application](../index.md#configure-prometheus-to-gather-metrics). - - - -## Kubernetes pod health dashboard - -This dashboard requires Kubernetes v1.14 or higher, due to the -[change in metric labels](https://github.com/kubernetes/kubernetes/pull/69099) -in Kubernetes 1.14. - -This dashboard displays CPU, memory, network and disk metrics for the pods in your -[connected Kubernetes cluster](../../../user/infrastructure/clusters/index.md). It provides a -[variable selector](templating_variables.md#metric_label_values-variable-type) -at the top of the dashboard to select which pod's metrics to display. - - +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/operations/metrics/dashboards/develop.md b/doc/operations/metrics/dashboards/develop.md index fe14ec1dc3d..b7912e164d7 100644 --- a/doc/operations/metrics/dashboards/develop.md +++ b/doc/operations/metrics/dashboards/develop.md @@ -2,38 +2,11 @@ stage: Monitor group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +remove_date: '2023-08-22' +redirect_to: '../../index.md' --- -# Developing templates for custom dashboards (DEPRECATED) **(FREE)** +# Developing templates for custom dashboards (removed) **(FREE)** -> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. - -WARNING: -This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -in GitLab 14.7, and is planned for removal in GitLab 16.0. - -GitLab provides a template to make it easier for you to create templates for -[custom dashboards](index.md). Templates provide helpful guidance and -commented-out examples you can use. - -## Apply a dashboard template - -Go to the browser-based editor of your choice: - -- In the **Repository view**: - - 1. Go to **Repository > Files**. - 1. Select **Add to tree** and select **New file**, - then select **Select a template type** to see a list of available templates: -  - -- In the **[Web IDE](../../../user/project/web_ide/index.md)**: - - 1. Select **Web IDE** when viewing your repository. - 1. Select **New file**, then select **Choose a template** to see a list of available templates: -  - -## Custom dashboard templates **(PREMIUM SELF)** - -To enable and use a custom dashboard templates on your GitLab instance, read the -[guide for creating custom templates](../../../user/admin_area/settings/instance_template_repository.md). +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/operations/metrics/dashboards/img/actions_menu_create_add_panel_v13_3.png b/doc/operations/metrics/dashboards/img/actions_menu_create_add_panel_v13_3.png Binary files differdeleted file mode 100644 index e03fbef3b35..00000000000 --- a/doc/operations/metrics/dashboards/img/actions_menu_create_add_panel_v13_3.png +++ /dev/null diff --git a/doc/operations/metrics/dashboards/img/actions_menu_create_new_dashboard_v13_3.png b/doc/operations/metrics/dashboards/img/actions_menu_create_new_dashboard_v13_3.png Binary files differdeleted file mode 100644 index ba4780b730b..00000000000 --- a/doc/operations/metrics/dashboards/img/actions_menu_create_new_dashboard_v13_3.png +++ /dev/null diff --git a/doc/operations/metrics/dashboards/img/dashboard_external_link_v13_1.png b/doc/operations/metrics/dashboards/img/dashboard_external_link_v13_1.png Binary files differdeleted file mode 100644 index 3e8d792c53e..00000000000 --- a/doc/operations/metrics/dashboards/img/dashboard_external_link_v13_1.png +++ /dev/null diff --git a/doc/operations/metrics/dashboards/img/dashboard_local_timezone_v13_1.png b/doc/operations/metrics/dashboards/img/dashboard_local_timezone_v13_1.png Binary files differdeleted file mode 100644 index 8d45607a940..00000000000 --- a/doc/operations/metrics/dashboards/img/dashboard_local_timezone_v13_1.png +++ /dev/null diff --git a/doc/operations/metrics/dashboards/img/external_dashboard_link.png b/doc/operations/metrics/dashboards/img/external_dashboard_link.png Binary files differdeleted file mode 100644 index 82c5e05e467..00000000000 --- a/doc/operations/metrics/dashboards/img/external_dashboard_link.png +++ /dev/null diff --git a/doc/operations/metrics/dashboards/img/heatmap_chart_too_much_data_v_13_2.png b/doc/operations/metrics/dashboards/img/heatmap_chart_too_much_data_v_13_2.png Binary files differdeleted file mode 100644 index c3a391b06c7..00000000000 --- a/doc/operations/metrics/dashboards/img/heatmap_chart_too_much_data_v_13_2.png +++ /dev/null diff --git a/doc/operations/metrics/dashboards/img/heatmap_panel_type.png b/doc/operations/metrics/dashboards/img/heatmap_panel_type.png Binary files differdeleted file mode 100644 index a2b3911ec68..00000000000 --- a/doc/operations/metrics/dashboards/img/heatmap_panel_type.png +++ /dev/null diff --git a/doc/operations/metrics/dashboards/img/k8s_pod_health_dashboard_v13_3.png b/doc/operations/metrics/dashboards/img/k8s_pod_health_dashboard_v13_3.png Binary files differdeleted file mode 100644 index dc0bc951500..00000000000 --- a/doc/operations/metrics/dashboards/img/k8s_pod_health_dashboard_v13_3.png +++ /dev/null diff --git a/doc/operations/metrics/dashboards/img/metrics_dashboard_annotations_ui_v13.0.png b/doc/operations/metrics/dashboards/img/metrics_dashboard_annotations_ui_v13.0.png Binary files differdeleted file mode 100644 index a042fbbcf4e..00000000000 --- a/doc/operations/metrics/dashboards/img/metrics_dashboard_annotations_ui_v13.0.png +++ /dev/null diff --git a/doc/operations/metrics/dashboards/img/metrics_dashboard_panel_preview_v13_3.png b/doc/operations/metrics/dashboards/img/metrics_dashboard_panel_preview_v13_3.png Binary files differdeleted file mode 100644 index 3c3203265e1..00000000000 --- a/doc/operations/metrics/dashboards/img/metrics_dashboard_panel_preview_v13_3.png +++ /dev/null diff --git a/doc/operations/metrics/dashboards/img/metrics_dashboard_template_selection_v13_3.png b/doc/operations/metrics/dashboards/img/metrics_dashboard_template_selection_v13_3.png Binary files differdeleted file mode 100644 index 1571ab9de90..00000000000 --- a/doc/operations/metrics/dashboards/img/metrics_dashboard_template_selection_v13_3.png +++ /dev/null diff --git a/doc/operations/metrics/dashboards/img/metrics_dashboard_template_selection_web_ide_v13_3.png b/doc/operations/metrics/dashboards/img/metrics_dashboard_template_selection_web_ide_v13_3.png Binary files differdeleted file mode 100644 index 650f66e9a30..00000000000 --- a/doc/operations/metrics/dashboards/img/metrics_dashboard_template_selection_web_ide_v13_3.png +++ /dev/null diff --git a/doc/operations/metrics/dashboards/img/panel_context_menu_v14_0.png b/doc/operations/metrics/dashboards/img/panel_context_menu_v14_0.png Binary files differdeleted file mode 100644 index 78cce5d30b7..00000000000 --- a/doc/operations/metrics/dashboards/img/panel_context_menu_v14_0.png +++ /dev/null diff --git a/doc/operations/metrics/dashboards/img/prometheus_dashboard_anomaly_panel_type.png b/doc/operations/metrics/dashboards/img/prometheus_dashboard_anomaly_panel_type.png Binary files differdeleted file mode 100644 index 5cba6fa9038..00000000000 --- a/doc/operations/metrics/dashboards/img/prometheus_dashboard_anomaly_panel_type.png +++ /dev/null diff --git a/doc/operations/metrics/dashboards/img/prometheus_dashboard_area_panel_type_v12_8.png b/doc/operations/metrics/dashboards/img/prometheus_dashboard_area_panel_type_v12_8.png Binary files differdeleted file mode 100644 index 8c5663fef12..00000000000 --- a/doc/operations/metrics/dashboards/img/prometheus_dashboard_area_panel_type_v12_8.png +++ /dev/null diff --git a/doc/operations/metrics/dashboards/img/prometheus_dashboard_bar_chart_panel_type_v12.10.png b/doc/operations/metrics/dashboards/img/prometheus_dashboard_bar_chart_panel_type_v12.10.png Binary files differdeleted file mode 100644 index 593e31477f4..00000000000 --- a/doc/operations/metrics/dashboards/img/prometheus_dashboard_bar_chart_panel_type_v12.10.png +++ /dev/null diff --git a/doc/operations/metrics/dashboards/img/prometheus_dashboard_column_panel_type.png b/doc/operations/metrics/dashboards/img/prometheus_dashboard_column_panel_type.png Binary files differdeleted file mode 100644 index 985f2b04ef3..00000000000 --- a/doc/operations/metrics/dashboards/img/prometheus_dashboard_column_panel_type.png +++ /dev/null diff --git a/doc/operations/metrics/dashboards/img/prometheus_dashboard_gauge_panel_type_v13_3.png b/doc/operations/metrics/dashboards/img/prometheus_dashboard_gauge_panel_type_v13_3.png Binary files differdeleted file mode 100644 index 547c565c6f9..00000000000 --- a/doc/operations/metrics/dashboards/img/prometheus_dashboard_gauge_panel_type_v13_3.png +++ /dev/null diff --git a/doc/operations/metrics/dashboards/img/prometheus_dashboard_label_variable_shorthand.png b/doc/operations/metrics/dashboards/img/prometheus_dashboard_label_variable_shorthand.png Binary files differdeleted file mode 100644 index 15111a97464..00000000000 --- a/doc/operations/metrics/dashboards/img/prometheus_dashboard_label_variable_shorthand.png +++ /dev/null diff --git a/doc/operations/metrics/dashboards/img/prometheus_dashboard_label_variables.png b/doc/operations/metrics/dashboards/img/prometheus_dashboard_label_variables.png Binary files differdeleted file mode 100644 index 9b94d0c6afa..00000000000 --- a/doc/operations/metrics/dashboards/img/prometheus_dashboard_label_variables.png +++ /dev/null diff --git a/doc/operations/metrics/dashboards/img/prometheus_dashboard_repeated_label.png b/doc/operations/metrics/dashboards/img/prometheus_dashboard_repeated_label.png Binary files differdeleted file mode 100644 index d43a890f0fa..00000000000 --- a/doc/operations/metrics/dashboards/img/prometheus_dashboard_repeated_label.png +++ /dev/null diff --git a/doc/operations/metrics/dashboards/img/prometheus_dashboard_single_stat_panel_type.png b/doc/operations/metrics/dashboards/img/prometheus_dashboard_single_stat_panel_type.png Binary files differdeleted file mode 100644 index 2d7dfb27b49..00000000000 --- a/doc/operations/metrics/dashboards/img/prometheus_dashboard_single_stat_panel_type.png +++ /dev/null diff --git a/doc/operations/metrics/dashboards/img/prometheus_dashboard_stacked_column_panel_type_v12_8.png b/doc/operations/metrics/dashboards/img/prometheus_dashboard_stacked_column_panel_type_v12_8.png Binary files differdeleted file mode 100644 index ba67509bcf3..00000000000 --- a/doc/operations/metrics/dashboards/img/prometheus_dashboard_stacked_column_panel_type_v12_8.png +++ /dev/null diff --git a/doc/operations/metrics/dashboards/img/prometheus_dashboard_yaml_validation_v13_1.png b/doc/operations/metrics/dashboards/img/prometheus_dashboard_yaml_validation_v13_1.png Binary files differdeleted file mode 100644 index 08d7d6603d2..00000000000 --- a/doc/operations/metrics/dashboards/img/prometheus_dashboard_yaml_validation_v13_1.png +++ /dev/null diff --git a/doc/operations/metrics/dashboards/img/related_links_v13_1.png b/doc/operations/metrics/dashboards/img/related_links_v13_1.png Binary files differdeleted file mode 100644 index 4dc141f0e7f..00000000000 --- a/doc/operations/metrics/dashboards/img/related_links_v13_1.png +++ /dev/null diff --git a/doc/operations/metrics/dashboards/index.md b/doc/operations/metrics/dashboards/index.md index 09bb8cedbf6..a4cf12cc64a 100644 --- a/doc/operations/metrics/dashboards/index.md +++ b/doc/operations/metrics/dashboards/index.md @@ -2,267 +2,11 @@ stage: Monitor group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +remove_date: '2023-08-22' +redirect_to: '../../index.md' --- -# Custom dashboards (DEPRECATED) **(FREE)** +# Custom dashboards (removed) **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/59974) in GitLab 12.1. -> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. - -WARNING: -This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -in GitLab 14.7, and is planned for removal in GitLab 16.0. - -By default, all projects include a [GitLab-defined Prometheus dashboard](default.md), which -includes a few key metrics, but you can also define your own custom dashboards. - -You may create a [new dashboard from scratch](#add-a-new-dashboard-to-your-project) -or [duplicate a GitLab-defined Prometheus dashboard](#duplicate-a-gitlab-defined-dashboard). - -## Add a new dashboard to your project - -> UI option [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/228856) in GitLab 13.3. - -You can configure a custom dashboard by adding a new YAML file into your project's -`.gitlab/dashboards/` directory. For the dashboard to display on your project's -**Monitor > Metrics** page, the files must have a `.yml` -extension and be present in your project's **default** branch. - -To create a new dashboard from the GitLab user interface: - -1. Sign in to GitLab as a user with Maintainer or Owner - [permissions](../../../user/permissions.md#project-members-permissions). -1. Navigate to your dashboard at **Monitor > Metrics**. -1. In the upper-right corner of your dashboard, select the **{ellipsis_v}** **More actions** menu, - and select **Create new**: -  -1. In the modal window, select **Open Repository**, then follow the instructions - for creating a new dashboard from the command line. - -To create a new dashboard from the command line: - -1. Create `.gitlab/dashboards/prom_alerts.yml` under your repository's root - directory. Each YAML file should define the layout of the dashboard and the - Prometheus queries used to populate data. This example dashboard displays a - single area chart: - - ```yaml - dashboard: 'Dashboard Title' - panel_groups: - - group: 'Group Title' - panels: - - type: area-chart - title: 'Chart Title' - y_label: 'Y-Axis' - y_axis: - format: number - precision: 0 - metrics: - - id: my_metric_id - query_range: 'http_requests_total' - label: 'Instance: {{instance}}, method: {{method}}' - unit: 'count' - ``` - -1. Save the file, commit, and push to your repository. The file must be present in your **default** branch. -1. Navigate to your project's **Monitor > Metrics** and choose the custom - dashboard from the dropdown list. - -Your custom dashboard is available at `https://example.com/project/-/metrics/custom_dashboard_name.yml`. - -NOTE: -Configuration files nested under subdirectories of `.gitlab/dashboards` aren't -supported or available in the UI. - -## Add a new metrics panel to a dashboard - -> UI option [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/228761) in GitLab 13.3. - -The metrics dashboard supports various [multiple panel types](../../../operations/metrics/dashboards/panel_types.md). -You can quickly test how a panel configuration would display in your metrics dashboard -with the **Add Panel** page: - -1. Sign in to GitLab as a user with Maintainer or Owner - [permissions](../../../user/permissions.md#project-members-permissions). -1. Select **Add panel** in the **{ellipsis_v}** **More actions** menu. - - NOTE: - You can only add panels to custom dashboards. - -  -1. In the **Define and preview panel** section, paste in the YAML you want to - preview in the **Panel YAML** field. -1. Select **Preview panel**, and GitLab displays a preview of the chart below the - `Define and preview panel` section: -  - -## Duplicate a GitLab-defined dashboard - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/37238) in GitLab 12.7. -> - [GitLab versions 12.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/39505), custom metrics are also duplicated when you duplicate a dashboard. - -You can save a complete copy of a GitLab-defined dashboard along with all custom metrics added to it. -The resulting `.yml` file can be customized and adapted to your project. -You can decide to save the dashboard `.yml` file in the project's **default** branch or in a -new branch. To duplicate a GitLab-defined dashboard: - -1. Select **Duplicate current dashboard** in the **{ellipsis_v}** **More actions** menu. -1. Enter the filename and other information, such as the new commit's message, and select **Duplicate**. -1. Select a branch to add your dashboard to: - - *If you select your **default** branch,* the new dashboard becomes immediately available. - - *If you select another branch,* this branch should be merged to your **default** branch first. - -Your custom dashboard is available at `https://example.com/project/-/metrics/custom_dashboard_name.yml`. - -## Manage the metrics dashboard settings - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223204) in GitLab 13.2. - -Users with project Maintainer or Administrator -[permissions](../../../user/permissions.md#project-members-permissions) -can manage [the settings](settings.md) for your metrics dashboard. - -## Chart Context Menu - -You can take action related to a chart's data by selecting the -**{ellipsis_v}** **More actions** dropdown list above the upper right corner of -any chart on a dashboard: - - - -The options are: - -- **Expand panel** - Displays a larger version of a visualization. To return to - the dashboard, select the **Back** button in your browser, or press the <kbd>Escape</kbd> key. - ([Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3100) in GitLab 13.0.) -- **Download CSV** - Data from Prometheus charts on the metrics dashboard can be downloaded as CSV. -- [Copy link to chart](../embed.md#embedding-gitlab-managed-kubernetes-metrics) - -### Timeline zoom and URL sharing - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/198910) in GitLab 12.8. - -You can use the **Timeline zoom** function at the bottom of a chart to zoom in -on a date and time of your choice. When you select and drag the sliders to select -a different beginning or end date of data to display, GitLab adds your selected start -and end times to the URL, enabling you to share specific time frames more easily. - -## Dashboard Annotations - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211330) in GitLab 12.10 (enabled by feature flag `metrics_dashboard_annotations`). -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/215224) in GitLab 13.0. - -You can use **Metrics Dashboard Annotations** to mark any important events on -every metrics dashboard by adding annotations to it. While viewing a dashboard, -annotation entries assigned to the selected time range are automatically -fetched and displayed on every chart within that dashboard. On mouse hover, each -annotation presents additional details, including the exact time of an event and -its description. - -You can create annotations by making requests to the -[Metrics dashboard annotations API](../../../api/metrics_dashboard_annotations.md) - - - -### Annotation retention policy - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211433) in GitLab 13.01. - -To avoid excessive storage space consumption by stale annotations, records attached -to time periods older than two weeks are removed daily. This recurring background -job runs at 1:00 a.m. local server time. - -## Add related links to custom dashboards - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216385) in GitLab 13.1. - -You can embed links to other dashboards or external services in your custom -dashboard by adding **Related links** to your dashboard's YAML file. Related links -open in the same tab as the dashboard. Related links can be displayed in the -following locations on your dashboard: - -- At the top of your dashboard as the top level [`links` dashboard property](../../../operations/metrics/dashboards/yaml.md#dashboard-top-level-properties). -- In charts context menus as the [`links` property of a panel](../../../operations/metrics/dashboards/yaml.md#panel-panels-properties). - -Related links can contain the following attributes: - -- `url`: The full URL to the link. Required. -- `title`: A phrase describing the link. Optional. If this attribute is not set, - the full URL is used for the link title. -- `type`: A string declaring the type of link. Optional. If set to `grafana`, the - dashboard's time range values are converted to the Grafana time range format and - appended to the `url`. - -The dashboard's time range is appended to the `url` as URL parameters. - -The following example shows two related links (`GitLab.com` and `GitLab Documentation`) -added to a dashboard: - - - -### Links Syntax - -```yaml -links: - - title: GitLab.com - url: https://gitlab.com - - title: GitLab Documentation - url: https://docs.gitlab.com - - title: Public Grafana playground dashboard - url: https://play.grafana.org/d/000000012/grafana-play-home?orgId=1 - type: grafana -``` - -## Troubleshooting - -### Accessing the UI of Prometheus in Kubernetes - -When troubleshooting issues with an in-cluster Prometheus, it can help to -view the Prometheus UI. In the example below, we assume the Prometheus -server to be the pod `prometheus-prometheus-server` in the `gitlab-managed-apps` -namespace: - -1. Find the name of the Prometheus pod in the user interface of your Kubernetes - provider, such as GKE, or by running the following `kubectl` command in your - terminal. For example: - - ```shell - kubectl get pods -n gitlab-managed-apps | grep 'prometheus-prometheus-server' - ``` - - The command should return a result like the following example, where - `prometheus-prometheus-server-55b4bd64c9-dpc6b` is the name of the Prometheus pod: - - ```plaintext - gitlab-managed-apps prometheus-prometheus-server-55b4bd64c9-dpc6b 2/2 Running 0 71d - ``` - -1. Run a `kubectl port-forward` command. In the following example, `9090` is the - Prometheus server's listening port: - - ```shell - kubectl port-forward prometheus-prometheus-server-55b4bd64c9-dpc6b 9090:9090 -n gitlab-managed-apps - ``` - - The `port-forward` command forwards all requests sent to your system's `9090` port - to the `9090` port of the Prometheus pod. If the `9090` port on your system is used - by another application, you can change the port number before the colon to your - desired port. For example, to forward port `8080` of your local system, change the - command to: - - ```shell - kubectl port-forward prometheus-prometheus-server-55b4bd64c9-dpc6b 8080:9090 -n gitlab-managed-apps - ``` - -1. Open `localhost:9090` in your browser to display the Prometheus user interface. - -### "No data found" error on Metrics dashboard page - -If the "No data found" screen continues to appear, it could be due to: - -- No successful deployments have occurred to this environment. -- Prometheus does not have performance data for this environment, or the metrics - are not labeled correctly. To test this, connect to the Prometheus server and - [run a query](../../../user/project/integrations/prometheus_library/kubernetes.md#metrics-supported), replacing `$CI_ENVIRONMENT_SLUG` - with the name of your environment. -- You may need to re-add the GitLab predefined common metrics. This can be done by running the [import common metrics Rake task](../../../administration/raketasks/maintenance.md#import-common-metrics). +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/operations/metrics/dashboards/panel_types.md b/doc/operations/metrics/dashboards/panel_types.md index 177a55fb85b..c789e99052c 100644 --- a/doc/operations/metrics/dashboards/panel_types.md +++ b/doc/operations/metrics/dashboards/panel_types.md @@ -2,316 +2,11 @@ stage: Monitor group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +remove_date: '2023-08-22' +redirect_to: '../../index.md' --- -# Panel types for dashboards (DEPRECATED) **(FREE)** +# Panel types for dashboards (removed) **(FREE)** -> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. - -WARNING: -This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -in GitLab 14.7, and is planned for removal in GitLab 16.0. - -The below panel types are supported in monitoring dashboards. - -## Area or Line Chart - -To add an area chart panel type to a dashboard, look at the following sample dashboard file: - -```yaml -dashboard: 'Dashboard Title' -panel_groups: - - group: 'Group Title' - panels: - - type: area-chart # or line-chart - title: 'Area Chart Title' - y_label: 'Y-Axis' - y_axis: - format: number - precision: 0 - metrics: - - id: area_http_requests_total - query_range: 'http_requests_total' - label: 'Instance: {{instance}}, Method: {{method}}' - unit: "count" -``` - -Note the following properties: - -| Property | Type | Required | Description | -| ------ | ------ | ------ | ------ | -| `type` | string | no | Type of panel to be rendered. Optional for area panel types | -| `query_range` | string | required | For area panel types, you must use a [range query](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) | - - - -Starting in [version 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/202696), the y-axis values scale according to the data. Previously, it always started from 0. - -## Anomaly chart - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16530) in GitLab 12.5. - -To add an anomaly chart panel type to a dashboard, add a panel with *exactly* 3 metrics. - -The first metric represents the current state, and the second and third metrics represent the upper and lower limit respectively: - -```yaml -dashboard: 'Dashboard Title' -panel_groups: - - group: 'Group Title' - panels: - - type: anomaly-chart - title: 'Chart Title' - y_label: "Y-Axis" - metrics: - - id: anomaly_requests_normal - query_range: 'http_requests_total' - label: '# of Requests' - unit: 'count' - - id: anomaly_requests_upper_limit - query_range: 10000 - label: 'Max # of requests' - unit: 'count' - - id: anomaly_requests_lower_limit - query_range: 2000 - label: 'Min # of requests' - unit: 'count' -``` - -Note the following properties: - -| Property | Type | Required | Description | -| ------ | ------ | ------ | ------ | -| `type` | string | required | Must be `anomaly-chart` for anomaly panel types | -| `query_range` | yes | required | For anomaly panel types, you must use a [range query](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) in every metric. | - - - -## Bar chart - -To add a bar chart to a dashboard, look at the following sample dashboard file: - -```yaml -dashboard: 'Dashboard Title' -panel_groups: - - group: 'Group title' - panels: - - type: bar - title: 'HTTP Handlers' - x_label: 'Response Size' - y_axis: - name: 'Handlers' - metrics: - - id: prometheus_http_response_size_bytes_bucket - query_range: 'sum(increase(prometheus_http_response_size_bytes_bucket[1d])) by (handler)' - unit: 'Bytes' -``` - -Note the following properties: - -| Property | Type | Required | Description | -| ------ | ------ | ------ | ------ | -| `type` | string | yes | Type of panel to be rendered. For bar chart types, set to `bar` | -| `query_range` | yes | yes | For bar chart, you must use a [range query](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) - - - -## Column chart - -To add a column panel type to a dashboard, look at the following sample dashboard file: - -```yaml -dashboard: 'Dashboard Title' -panel_groups: - - group: 'Group title' - panels: - - title: 'Column' - type: 'column' - metrics: - - id: 1024_memory - query: 'avg(sum(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}) by (job)) without (job) / count(avg(container_memory_usage_bytes{container_name!="POD",pod_name=~"^%{ci_environment_slug}-([^c].*|c([^a]|a([^n]|n([^a]|a([^r]|r[^y])))).*|)-(.*)",namespace="%{kube_namespace}"}) without (job)) /1024/1024' - unit: MB - label: 'Memory Usage' -``` - -Note the following properties: - -| Property | Type | Required | Description | -| ------ | ------ | ------ | ------ | -| `type` | string | yes | Type of panel to be rendered. For column panel types, set to `column` | -| `query_range` | yes | yes | For column panel types, you must use a [range query](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) | - - - -## Stacked column - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30583) in GitLab 12.8. - -To add a stacked column panel type to a dashboard, look at the following sample dashboard file: - -```yaml -dashboard: 'Dashboard title' -priority: 1 -panel_groups: - - group: 'Group Title' - priority: 5 - panels: - - type: 'stacked-column' - title: 'Stacked column' - y_label: 'y label' - x_label: 'x label' - metrics: - - id: memory_1 - query_range: 'memory_query' - label: 'memory query 1' - unit: 'count' - series_name: 'group 1' - - id: memory_2 - query_range: 'memory_query_2' - label: 'memory query 2' - unit: 'count' - series_name: 'group 2' -``` - - - -| Property | Type | Required | Description | -| ------ | ------ | ------ | ------ | -| `type` | string | yes | Type of panel to be rendered. For stacked column panel types, set to `stacked-column` | -| `query_range` | yes | yes | For stacked column panel types, you must use a [range query](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) | - -## Single Stat - -To add a single stat panel type to a dashboard, look at the following sample dashboard file: - -```yaml -dashboard: 'Dashboard Title' -panel_groups: - - group: 'Group Title' - panels: - - title: 'Single Stat' - type: 'single-stat' - metrics: - - id: 10 - query: 'max(go_memstats_alloc_bytes{job="prometheus"})' - unit: MB - label: 'Total' -``` - -Note the following properties: - -| Property | Type | Required | Description | -| ------- | ------ | ------ | ------ | -| `type` | string | yes | Type of panel to be rendered. For single stat panel types, set to `single-stat` | -| `field` | string | no | Panels display the value of a metric. For a panel to display the value of a label instead, put the name of the label in this key. | -| `query` | string | yes | For single stat panel types, you must use an [instant query](https://prometheus.io/docs/prometheus/latest/querying/api/#instant-queries). | - - - -## Percentile based results - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/201946) in GitLab 12.8. - -Query results sometimes need to be represented as a percentage value out of 100. You can use the `max_value` property at the root of the panel definition: - -```yaml -dashboard: 'Dashboard Title' -panel_groups: - - group: 'Group Title' - panels: - - title: 'Single Stat' - type: 'single-stat' - max_value: 100 - metrics: - - id: 10 - query: 'max(go_memstats_alloc_bytes{job="prometheus"})' - unit: '%' - label: 'Total' -``` - -For example, if you have a query value of `53.6`, adding `%` as the unit results in a single stat value of `53.6%`, but if the maximum expected value of the query is `120`, the value would be `44.6%`. Adding the `max_value` causes the correct percentage value to display. - -## Gauge - -WARNING: -This panel type is an [Alpha](../../../policy/alpha-beta-support.md#alpha-features) feature, and is subject to change at any time -without prior notice! - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207044) in GitLab 13.3. - -To add a gauge panel type to a dashboard, look at the following sample dashboard file: - -```yaml -dashboard: 'Dashboard Title' -panel_groups: - - group: 'Group Title' - panels: - - title: 'Gauge' - type: 'gauge' - min_value: 0 - max_value: 1000 - split: 5 - thresholds: - values: [60, 90] - mode: 'percentage' - format: 'kilobytes' - metrics: - - id: 10 - query: 'floor(max(prometheus_http_response_size_bytes_bucket)/1000)' - unit: 'kb' -``` - -Note the following properties: - -| Property | Type | Required | Description | -| ------------ | ------ | ------ | ------ | -| `type` | string | yes | Type of panel to be rendered. For gauge panel types, set to `gauge`. | -| `min_value` | number | no, defaults to `0` | The minimum value of the gauge chart axis. If either of `min_value` or `max_value` are not set, they both get their default values. | -| `max_value` | number | no, defaults to `100` | The maximum value of the gauge chart axis. If either of `min_value` or `max_value` are not set, they both get their default values. | -| `split` | number | no, defaults to `10` | The amount of split segments on the gauge chart axis. | -| `thresholds` | object | no | Thresholds configuration for the gauge chart axis. | -| `format` | string | no, defaults to `engineering` | Unit format used. See the [full list of units](yaml_number_format.md). | -| `query` | string | yes | For gauge panel types, you must use an [instant query](https://prometheus.io/docs/prometheus/latest/querying/api/#instant-queries). | - -### Thresholds properties - -| Property | Type | Required | Description | -| ------ | ------ | ------ | ------ | -| values | array | no, defaults to 95% of the range between `min_value` and `max_value`| An array of gauge chart axis threshold values. | -| mode | string | no, defaults to `absolute` | The mode in which the thresholds are interpreted in relation to `min_value` and `max_value`. Can be either `percentage` or `absolute`. | - - - -## Heatmaps - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30581) in GitLab 12.5. - -To add a heatmap panel type to a dashboard, look at the following sample dashboard file: - -```yaml -dashboard: 'Dashboard Title' -panel_groups: - - group: 'Group Title' - panels: - - title: 'Heatmap' - type: 'heatmap' - metrics: - - id: 10 - query: 'sum(rate(nginx_upstream_responses_total{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[60m])) by (status_code)' - unit: req/sec - label: 'Status code' -``` - -Note the following properties: - -| Property | Type | Required | Description | -| ------ | ------ | ------ | ------ | -| `type` | string | yes | Type of panel to be rendered. For heatmap panel types, set to `heatmap` | -| `query_range` | yes | yes | For area panel types, you must use a [range query](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) | - - - -WARNING: -When a query returns too many data points, the heatmap data bucket dimensions tend downwards to 0, making the chart's data invisible, as shown in the image below. To fix this problem, limit the amount of data returned by changing the time range filter on the metrics dashboard UI, or adding the **step** property to your dashboard's YAML file. - - +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/operations/metrics/dashboards/settings.md b/doc/operations/metrics/dashboards/settings.md index 5fb0476e164..5572dfa360f 100644 --- a/doc/operations/metrics/dashboards/settings.md +++ b/doc/operations/metrics/dashboards/settings.md @@ -2,57 +2,11 @@ stage: Monitor group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +remove_date: '2023-08-22' +redirect_to: '../../index.md' --- -# Dashboard settings (DEPRECATED) **(FREE)** +# Dashboard settings (removed) **(FREE)** -> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. - -WARNING: -This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -in GitLab 14.7, and is planned for removal in GitLab 16.0. - -You can configure your [Monitoring dashboard](../index.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](../../../user/permissions.md). - -## Change the dashboard time zone - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214370) in GitLab 13.1. - -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](../../../user/permissions.md). -1. Navigate to **Settings > Monitor**. -1. Scroll to **Metrics Dashboard** and select **Expand**. -1. In the **Dashboard timezone** select box, select *User's local timezone* - or *UTC*: - -  -1. Select **Save changes**. - -## Link to an external dashboard - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/57171) in GitLab 12.0. - -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](../../../user/permissions.md). -1. Navigate to **Settings > Monitor**. -1. Scroll to **Metrics Dashboard** and select **Expand**. -1. In **External dashboard URL**, provide the URL to your external dashboard: - -  - -1. Select **Save changes**. - -GitLab displays a **View full dashboard** button in the upper-right corner of your -[monitoring dashboard](../../../ci/environments/index.md#monitor-environments) -which opens the URL you provided: - - +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/operations/metrics/dashboards/templating_variables.md b/doc/operations/metrics/dashboards/templating_variables.md index a1c2ce063bc..a93c559c98c 100644 --- a/doc/operations/metrics/dashboards/templating_variables.md +++ b/doc/operations/metrics/dashboards/templating_variables.md @@ -2,132 +2,11 @@ stage: Monitor group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +remove_date: '2023-08-22' +redirect_to: '../../index.md' --- -# Templating variables for metrics dashboards (DEPRECATED) **(FREE)** +# Templating variables for metrics dashboards (removed) **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214539) in GitLab 13.0. -> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. - -WARNING: -This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -in GitLab 14.7, and is planned for removal in GitLab 16.0. - -Templating variables can be used to make your metrics dashboard more versatile. - -`templating` is a top-level key in the -[dashboard YAML](yaml.md#dashboard-top-level-properties). -Define your variables in the `variables` key, under `templating`. The value of -the `variables` key should be a hash, and each key under `variables` -defines a templating variable on the dashboard, and may contain alphanumeric and underscore characters. - -A variable can be used in a Prometheus query in the same dashboard using the syntax -described [in Using Variables](variables.md). - -## `text` variable type - -WARNING: -This variable type is an [Alpha](../../../policy/alpha-beta-support.md#alpha-features) feature, and is subject to change at any time -without prior notice! - -For each `text` variable defined in the dashboard YAML, a free text field displays -on the dashboard UI, allowing you to enter a value for each variable. - -The `text` variable type supports a simple and a full syntax. - -### Simple syntax - -This example creates a variable called `variable1`, with a default value -of `default value`: - -```yaml -templating: - variables: - variable1: 'default value' # `text` type variable with `default value` as its default. -``` - -### Full syntax - -This example creates a variable called `variable1`, with a default value of `default`. -The label for the text box on the UI is the value of the `label` key: - -```yaml -templating: - variables: - variable1: # The variable name that can be used in queries. - label: 'Variable 1' # (Optional) label that will appear in the UI for this text box. - type: text - options: - default_value: 'default' # (Optional) default value. -``` - -## `custom` variable type - -WARNING: -This variable type is an [Alpha](../../../policy/alpha-beta-support.md#alpha-features) feature, and is subject to change at any time -without prior notice! - -Each `custom` variable defined in the dashboard YAML creates a dropdown list -selector on the dashboard UI, allowing you to select a value for each variable. - -The `custom` variable type supports a simple and a full syntax. - -### Simple syntax - -This example creates a variable called `variable1`, with a default value of `value1`. -The dashboard UI displays a dropdown list with `value1`, `value2` and `value3` -as the choices. - -```yaml -templating: - variables: - variable1: ['value1', 'value2', 'value3'] -``` - -### Full syntax - -This example creates a variable called `variable1`, with a default value of `value_option_2`. -The label for the text box on the UI is the value of the `label` key. -The dashboard UI displays a dropdown list with `Option 1` and `Option 2` -as the choices. - -If you select `Option 1` from the dropdown list, the variable is replaced with `value option 1`. -Similarly, if you select `Option 2`, the variable is replaced with `value_option_2`: - -```yaml -templating: - variables: - variable1: # The variable name that can be used in queries. - label: 'Variable 1' # (Optional) label that will appear in the UI for this dropdown. - type: custom - options: - values: - - value: 'value option 1' # The value that will replace the variable in queries. - text: 'Option 1' # (Optional) Text that will appear in the UI dropdown. - - value: 'value_option_2' - text: 'Option 2' - default: true # (Optional) This option should be the default value of this variable. -``` - -## `metric_label_values` variable type - -WARNING: -This variable type is an [Alpha](../../../policy/alpha-beta-support.md#alpha-features) feature, and is subject to change at any time -without prior notice! - -### Full syntax - -This example creates a variable called `variable2`. The values of the dropdown list are -all the different values of the `backend` label in the Prometheus series described by -`up{env="production"}`. - -```yaml -templating: - variables: - variable2: # The variable name that can be interpolated in queries. - label: 'Variable 2' # (Optional) label that will appear in the UI for this dropdown. - type: metric_label_values - options: - series_selector: 'up{env="production"}' - label: 'backend' -``` +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/operations/metrics/dashboards/variables.md b/doc/operations/metrics/dashboards/variables.md index 2881c084115..45e13aa731a 100644 --- a/doc/operations/metrics/dashboards/variables.md +++ b/doc/operations/metrics/dashboards/variables.md @@ -2,77 +2,11 @@ stage: Monitor group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +remove_date: '2023-08-22' +redirect_to: '../../index.md' --- -# Using variables (DEPRECATED) **(FREE)** +# Using variables (removed) **(FREE)** -> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. - -WARNING: -This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -in GitLab 14.7, and is planned for removal in GitLab 16.0. - -## Query variables - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20793) in GitLab 12.7. - -Variables can be specified using double curly braces, such as `"{{ci_environment_slug}}"`. - -Support for the `"%{ci_environment_slug}"` format was -[removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31581) in GitLab 13.0. -Queries that continue to use the old format display no data. - -## Predefined variables - -GitLab supports a limited set of [CI/CD variables](../../../ci/variables/index.md) -in the Prometheus query. This is particularly useful for identifying a specific -environment, for example with `ci_environment_slug`. Variables for Prometheus queries -must be lowercase. The supported variables are: - -- `environment_filter` -- `ci_environment_slug` -- `kube_namespace` -- `ci_project_name` -- `ci_project_namespace` -- `ci_project_path` -- `ci_environment_name` -- `__range` - -### `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 -[range vector selectors](https://prometheus.io/docs/prometheus/latest/querying/basics/#range-vector-selectors). -Its value is the total number of seconds in the dashboard's time range. -For example, if the dashboard time range is set to 8 hours, the value of -`__range` is `28800s`. - -## User-defined variables - -[Variables can be defined](../../../operations/metrics/dashboards/yaml.md#templating-templating-properties) in a custom dashboard YAML file. - -Variable names are case-sensitive. - -## Query variables from URL - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214500) in GitLab 13.0. - -GitLab supports setting custom variables through URL parameters. Surround the variable -name with double curly braces (`{{example}}`) to interpolate the variable in a query: - -```plaintext -avg(sum(container_memory_usage_bytes{container_name!="{{pod}}"}) by (job)) without (job) /1024/1024/1024' -``` - -The URL for this query would be: - -```plaintext -https://gitlab.com/<user>/<project>/-/environments/<environment_id>/metrics?dashboard=.gitlab%2Fdashboards%2Fcustom.yml&pod=POD -``` +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/operations/metrics/dashboards/yaml.md b/doc/operations/metrics/dashboards/yaml.md index 7b0a91dd18a..7807f713773 100644 --- a/doc/operations/metrics/dashboards/yaml.md +++ b/doc/operations/metrics/dashboards/yaml.md @@ -2,179 +2,11 @@ stage: Monitor group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +remove_date: '2023-08-22' +redirect_to: '../../index.md' --- -# Dashboard YAML properties (DEPRECATED) **(FREE)** +# Dashboard YAML properties (removed) **(FREE)** -> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. - -WARNING: -This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -in GitLab 14.7, and is planned for removal in GitLab 16.0. - -Dashboards have several components: - -- Templating variables. -- Panel groups, which consist of panels. -- Panels, which support one or more metrics. - -The following tables outline the details of expected properties. - -## Dashboard (top-level) properties - -| Property | Type | Required | Description | -| ------ | ------ | ------ | ------ | -| `dashboard` | string | yes | Heading for the dashboard. Only one dashboard should be defined per file. | -| `panel_groups` | array | yes | The panel groups which should be on the dashboard. | -| `templating` | hash | no | Top level key under which templating related options can be added. | -| `links` | array | no | Add links to display on the dashboard. | - -## Templating (`templating`) properties - -| Property | Type | Required | Description | -| -------- | ---- | -------- | ----------- | -| `variables` | hash | yes | Variables can be defined here. | - -Read the documentation on [templating](templating_variables.md). - -## Links (`links`) properties - -| Property | Type | Required | Description | -| -------- | ---- | -------- | ----------- | -| `url` | string | yes | The address of the link. | -| `title` | string | no | Display title for the link. | -| `type` | string | no | Type of the link. Specifies the link type, can be: `grafana` | - -Read the documentation on [links](index.md#add-related-links-to-custom-dashboards). - -## Panel group (`panel_groups`) properties - -Dashboards display panel groups in the order they are listed in the dashboard YAML file. - -In GitLab versions 13.3 and below, panel groups were ordered by a `priority` key, which -is no longer used. - -| Property | Type | Required | Description | -| ------ | ------ | ------ | ------ | -| `group` | string | required | Heading for the panel group. | -| `panels` | array | required | The panels which should be in the panel group. | - -Panels in a panel group are laid out in rows consisting of two panels per row. An exception to this rule are single panels on a row: these panels take the full width of their containing row. - -## Panel (`panels`) properties - -Dashboards display panels in the order they are listed in the dashboard YAML file. - -In GitLab versions 13.3 and below, panels were ordered by a `weight` key, which -is no longer used. - -| Property | Type | Required | Description | -| ------ | ------ | ------ | ------- | -| `type` | string | no, defaults to `area-chart` | Specifies the panel type to use, for example `area-chart`, `line-chart` or `anomaly-chart`. Only types listed among [all panel types](panel_types.md) are allowed. | -| `title` | string | yes | Heading for the panel. | -| `y_label` | string | no, but highly encouraged | Y-Axis label for the panel. | -| `y_axis` | string | no | Y-Axis configuration for the panel. | -| `max_value` | number | no | Denominator value used for calculating [percentile based results](panel_types.md#percentile-based-results) | -| `metrics` | array | yes | The metrics which should be displayed in the panel. Any number of metrics can be displayed when `type` is `area-chart` or `line-chart`, whereas only 3 can be displayed when `type` is `anomaly-chart`. | -| `links` | array | no | Add links to display on the chart's [context menu](index.md#chart-context-menu). | - -## Axis (`panels[].y_axis`) properties - -| Property | Type | Required | Description | -| ----------- | ------ | ----------------------------- | -------------------------------------------------------------------- | -| `name` | string | no, but highly encouraged | Y-Axis label for the panel. Replaces `y_label` if set. | -| `format` | string | no, defaults to `engineering` | Unit format used. See the [full list of units](yaml_number_format.md). | -| `precision` | number | no, defaults to `2` | Number of decimal places to display in the number. | | - -## Metrics (`metrics`) properties - -| Property | Type | Required | Description | -| ------ | ------ | ------ | ------ | -| `id` | string | no | Used for associating dashboard metrics with database records. Must be unique across dashboard configuration files. Required for [alerting](../alerts.md) (support not yet enabled, see [relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/27980)). | -| `unit` | string | yes | Defines the unit of the query's return data. | -| `label` | string | no, but highly encouraged | Defines the legend-label for the query. Should be unique within the panel's metrics. Can contain time series labels as interpolated variables. | -| `query` | string/number | yes if `query_range` is not defined | Defines the Prometheus query to be used to populate the chart/panel. If defined, the `query` endpoint of the [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/) is used. | -| `query_range` | string/number | yes if `query` is not defined | Defines the Prometheus query to be used to populate the chart/panel. If defined, the `query_range` endpoint of the [Prometheus API](https://prometheus.io/docs/prometheus/latest/querying/api/) is used. | -| `step` | number | no, value is calculated if not defined | Defines query resolution step width in float number of seconds. Metrics on the same panel should use the same `step` value. | - -## Dynamic labels - -Dynamic labels are useful when multiple time series are returned from a Prometheus query. - -When a static label is used and a query returns multiple time series, then all the legend items are labeled the same, which makes identifying each time series difficult: - -```yaml -metrics: - - id: my_metric_id - query_range: 'http_requests_total' - label: 'Time Series' - unit: 'count' -``` - -This may render a legend like this: - - - -For labels to be more explicit, using variables that reflect time series labels is a good practice. The variables are replaced by the values of the time series labels when the legend is rendered: - -```yaml -metrics: - - id: my_metric_id - query_range: 'http_requests_total' - label: 'Instance: {{instance}}, method: {{method}}' - unit: 'count' -``` - -The resulting rendered legend looks like this: - - - -There is also a shorthand value for dynamic dashboard labels that make use of only one time series label: - -```yaml -metrics: - - id: my_metric_id - query_range: 'http_requests_total' - label: 'Method' - unit: 'count' -``` - -This works by converting the value of `label` to lower-case and, if there are more words separated by spaces, replacing those spaces with an underscore (`_`). The transformed value is then checked against the labels of the time series returned by the Prometheus query. If a time series label is found that is equal to the transformed value, then the label value renders in the legend like this: - - - -## Dashboard YAML syntax validation - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/33202) in GitLab 13.1. - -To confirm your dashboard definition contains valid YAML syntax: - -1. Go to **Repository > Files**. -1. Go to your dashboard file in your repository. -1. Review the information pane about the file, displayed above the file contents. - -Files with valid syntax display **Metrics Dashboard YAML definition is valid**, -and files with invalid syntax display **Metrics Dashboard YAML definition is invalid**. - - - -When **Metrics Dashboard YAML definition is invalid** at least one of the following messages is displayed: - -1. `dashboard: can't be blank` [learn more](#dashboard-top-level-properties) -1. `panel_groups: should be an array of panel_groups objects` [learn more](#dashboard-top-level-properties) -1. `group: can't be blank` [learn more](#panel-group-panel_groups-properties) -1. `panels: should be an array of panels objects` [learn more](#panel-group-panel_groups-properties) -1. `title: can't be blank` [learn more](#panel-panels-properties) -1. `metrics: should be an array of metrics objects` [learn more](#panel-panels-properties) -1. `query: can't be blank` [learn more](#metrics-metrics-properties) -1. `query_range: can't be blank` [learn more](#metrics-metrics-properties) -1. `unit: can't be blank` [learn more](#metrics-metrics-properties) -1. `YAML syntax: The parsed YAML is too big` - - This is displayed when the YAML file is larger than 1 MB. - -1. `YAML syntax: Invalid configuration format` - - This is displayed when the YAML file is empty or does not contain valid YAML. - -Metrics Dashboard YAML definition validation information is also available as a [GraphQL API field](../../../api/graphql/reference/index.md#metricsdashboard) +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/operations/metrics/dashboards/yaml_number_format.md b/doc/operations/metrics/dashboards/yaml_number_format.md index 99e6be96a3c..90e7f67b153 100644 --- a/doc/operations/metrics/dashboards/yaml_number_format.md +++ b/doc/operations/metrics/dashboards/yaml_number_format.md @@ -2,176 +2,11 @@ stage: Monitor group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +remove_date: '2023-08-22' +redirect_to: '../../index.md' --- -# Unit formats reference **(FREE)** +# Unit formats reference (removed) **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/201999) in GitLab 12.9. - -Format the data in your dashboard panels. - -You can select units to format your charts by adding `format` to your -[axis configuration](yaml.md). - -## Internationalization and localization - -Currently, your [internationalization and localization options](https://en.wikipedia.org/wiki/Internationalization_and_localization) for number formatting are dependent on the system you are using (that is, your OS or browser). - -## Engineering Notation - -For generic or default data, numbers are formatted according to the current locale in [engineering notation](https://en.wikipedia.org/wiki/Engineering_notation). - -While an [engineering notation exists for the web](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat), GitLab uses a version based off the [scientific notation](https://en.wikipedia.org/wiki/Scientific_notation). GitLab formatting acts in accordance with SI prefixes. For example, using GitLab notation, `1500.00` becomes `1.5k` instead of `1.5E3`. Keep this distinction in mind when using the engineering notation for your metrics. - -Formats: `engineering` - -SI prefixes: - -| Name | Symbol | Value | -| ---------- | ------- | -------------------------- | -| `yotta` | Y | 1000000000000000000000000 | -| `zetta` | Z | 1000000000000000000000 | -| `exa` | E | 1000000000000000000 | -| `peta` | P | 1000000000000000 | -| `tera` | T | 1000000000000 | -| `giga` | G | 1000000000 | -| `mega` | M | 1000000 | -| `kilo` | k | 1000 | -| `milli` | m | 0.001 | -| `micro` | μ | 0.000001 | -| `nano` | n | 0.000000001 | -| `pico` | p | 0.000000000001 | -| `femto` | f | 0.000000000000001 | -| `atto` | a | 0.000000000000000001 | -| `zepto` | z | 0.000000000000000000001 | -| `yocto` | y | 0.000000000000000000000001 | - -**Examples:** - -| Data | Displayed | -| --------------------------------- | --------- | -| `0.000000000000000000000008` | 8y | -| `0.000000000000000000008` | 8z | -| `0.000000000000000008` | 8a | -| `0.000000000000008` | 8f | -| `0.000000000008` | 8p | -| `0.000000008` | 8n | -| `0.000008` | 8μ | -| `0.008` | 8m | -| `10` | 10 | -| `1080` | 1.08k | -| `18000` | 18k | -| `18888` | 18.9k | -| `188888` | 189k | -| `18888888` | 18.9M | -| `1888888888` | 1.89G | -| `1888888888888` | 1.89T | -| `1888888888888888` | 1.89P | -| `1888888888888888888` | 1.89E | -| `1888888888888888888888` | 1.89Z | -| `1888888888888888888888888` | 1.89Y | -| `1888888888888888888888888888` | 1.89e+27 | - -## Numbers - -For number data, numbers are formatted according to the current locale. - -Formats: `number` - -**Examples:** - -| Data | Displayed | -| ---------- | --------- | -| `10` | 1 | -| `1000` | 1,000 | -| `1000000` | 1,000,000 | - -## Percentage - -For percentage data, format numbers in the chart with a `%` symbol. - -Formats supported: `percent`, `percentHundred` - -**Examples:** - -| Format | Data | Displayed | -| ---------------- | ----- | --------- | -| `percent` | `0.5` | 50% | -| `percent` | `1` | 100% | -| `percent` | `2` | 200% | -| `percentHundred` | `50` | 50% | -| `percentHundred` | `100` | 100% | -| `percentHundred` | `200` | 200% | - -## Duration - -For time durations, format numbers in the chart with a time unit symbol. - -Formats supported: `milliseconds`, `seconds` - -**Examples:** - -| Format | Data | Displayed | -| -------------- | ------ | --------- | -| `milliseconds` | `10` | 10 ms | -| `milliseconds` | `500` | 100 ms | -| `milliseconds` | `1000` | 1000 ms | -| `seconds` | `10` | 10 s | -| `seconds` | `500` | 500 s | -| `seconds` | `1000` | 1000 s | - -## Digital (Metric) - -Converts a number of bytes using metric prefixes. It scales to -use the unit that's the best fit. - -Formats supported: - -- `decimalBytes` -- `kilobytes` -- `megabytes` -- `gigabytes` -- `terabytes` -- `petabytes` - -**Examples:** - -| Format | Data | Displayed | -| -------------- | --------- | --------- | -| `decimalBytes` | `1` | 1 B | -| `decimalBytes` | `1000` | 1 kB | -| `decimalBytes` | `1000000` | 1 MB | -| `kilobytes` | `1` | 1 kB | -| `kilobytes` | `1000` | 1 MB | -| `kilobytes` | `1000000` | 1 GB | -| `megabytes` | `1` | 1 MB | -| `megabytes` | `1000` | 1 GB | -| `megabytes` | `1000000` | 1 TB | - -## Digital (IEC) - -Converts a number of bytes using binary prefixes. It scales to -use the unit that's the best fit. - -Formats supported: - -- `bytes` -- `kibibytes` -- `mebibytes` -- `gibibytes` -- `tebibytes` -- `pebibytes` - -**Examples:** - -| Format | Data | Displayed | -| ----------- | ------------- | --------- | -| `bytes` | `1` | 1 B | -| `bytes` | `1024` | 1 KiB | -| `bytes` | `1024 * 1024` | 1 MiB | -| `kibibytes` | `1` | 1 KiB | -| `kibibytes` | `1024` | 1 MiB | -| `kibibytes` | `1024 * 1024` | 1 GiB | -| `mebibytes` | `1` | 1 MiB | -| `mebibytes` | `1024` | 1 GiB | -| `mebibytes` | `1024 * 1024` | 1 TiB | +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/operations/metrics/embed.md b/doc/operations/metrics/embed.md index f622780530a..00c145adee3 100644 --- a/doc/operations/metrics/embed.md +++ b/doc/operations/metrics/embed.md @@ -2,126 +2,11 @@ stage: Monitor group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +remove_date: '2023-08-22' +redirect_to: '../index.md' --- -# Embedding metric charts within GitLab Flavored Markdown **(FREE)** +# Embedding metric charts within GitLab Flavored Markdown (removed) **(FREE)** -> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. - -WARNING: -This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -for use in GitLab 14.7, and is planned for removal in GitLab 16.0. - -You can display metrics charts within -[GitLab Flavored Markdown (GLFM)](../../user/markdown.md) -fields such as issue or merge request descriptions. The maximum number of embedded -charts allowed in a GitLab Flavored Markdown field is 100. -Embedding charts is useful when sharing an application incident or performance -metrics to others, and you want to have relevant information directly available. - -## Embedding GitLab-managed Kubernetes metrics - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29691) in GitLab 12.2. - -This feature requires [Kubernetes](../../user/project/integrations/prometheus_library/kubernetes.md) metrics. - -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>/-/metrics?environment=<environment_id>` in a field -that supports GitLab Flavored Markdown: - -```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: - - - -You can also embed a single chart. To get a link to a chart, select -**{ellipsis_v}** **More actions** in the upper right corner of the chart, -and select **Copy link to chart**, as shown in this example: - - - -The following requirements must be met for the metric to unfurl: - -- The `<environment_id>` must correspond to a real environment. -- Prometheus must be monitoring the environment. -- The GitLab instance must be configured to receive data from the environment. -- The user must have at least the Reporter role for the monitoring dashboard for the environment. -- The dashboard must have data within the last 8 hours. - - If all of the above are true, then the metric unfurls as seen below: - - - -Metric charts may also be hidden: - - - -You can open the link directly into your browser for a -[detailed view of the data](dashboards/index.md#chart-context-menu). - -## Embedding metrics in issue templates - -You can also embed either the overview dashboard metrics or individual metrics in -issue templates. For charts to render side-by-side, separate links to the entire metrics -dashboard or individual metrics by either a comma or a space. - - - -## Embedding metrics based on alerts in incident issues - -For [GitLab-managed alerting rules](alerts.md), the issue includes an embedded -chart for the query corresponding to the alert. The chart displays an hour of data -surrounding the starting point of the incident, 30 minutes before and after. - -For [manually configured Prometheus instances](../../user/project/integrations/prometheus.md#manual-configuration-of-prometheus), -a chart corresponding to the query can be included if these requirements are met: - -- The alert corresponds to an environment managed through GitLab. -- The alert corresponds to a [range query](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries). -- The alert contains the required attributes listed in the chart below. - -| Attributes | Required | Description | -| ---------- | -------- | ----------- | -| `annotations/gitlab_environment_name` | Yes | Name of the GitLab-managed environment corresponding to the alert | -| One of `annotations/title`, `annotations/summary`, `labels/alertname` | Yes | Used as the chart title | -| `annotations/gitlab_y_label` | No | Used as the chart's y-axis label | - -## Embedding cluster health charts - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/40997) in GitLab 12.9. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/208224) from GitLab Ultimate to GitLab Free in 13.2. - -[Cluster Health Metrics](../../user/infrastructure/clusters/manage/clusters_health.md) -can also be embedded in [GitLab Flavored Markdown](../../user/markdown.md). - -To embed a metric chart, include a link to that chart in the form -`https://<root_url>/<project>/-/cluster/<cluster_id>?<query_params>` anywhere that -GitLab Flavored Markdown is supported. To generate and copy a link to the chart, -follow the instructions in the -[Cluster Health Metric documentation](../../user/infrastructure/clusters/manage/clusters_health.md). - -The following requirements must be met for the metric to unfurl: - -- The `<cluster_id>` must correspond to a real cluster. -- Prometheus must be monitoring the cluster. -- The user must be allowed access to the project cluster metrics. -- The dashboards must be reporting data on the - [Cluster Health Page](../../user/infrastructure/clusters/manage/clusters_health.md) - - If the above requirements are met, then the metric unfurls as seen below. - - +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/operations/metrics/embed_grafana.md b/doc/operations/metrics/embed_grafana.md index 7bc88165b95..e14b4b5a893 100644 --- a/doc/operations/metrics/embed_grafana.md +++ b/doc/operations/metrics/embed_grafana.md @@ -2,90 +2,11 @@ stage: Monitor group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +remove_date: '2023-08-22' +redirect_to: '../index.md' --- -<!--- start_remove The following content will be removed on remove_date: '2023-08-22' --> -# Embed Grafana panels in Markdown (deprecated) **(FREE)** +# Embed Grafana panels in Markdown (removed) **(FREE)** -WARNING: -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/110290) in GitLab 15.9 -and is planned for removal in 16.0. We intend to replace this feature with the ability to [embed charts](https://gitlab.com/groups/gitlab-org/opstrace/-/epics/33) with the [GitLab Observability UI](https://gitlab.com/gitlab-org/opstrace/opstrace-ui). -This change is a breaking change. - -Grafana panels can be embedded in [GitLab Flavored Markdown](../../user/markdown.md). You can -embed Grafana panels using either: - -- [Grafana-rendered images](#use-grafana-rendered-images). -- [Grafana API](#use-integration-with-grafana-api). - -## Use Grafana-rendered images - -You can embed live [Grafana](https://docs.gitlab.com/omnibus/settings/grafana.html) panels as -[a direct link](https://grafana.com/docs/grafana/v7.5/sharing/share-panel/#use-direct-link). -Your Grafana instance must: - -- Be available to the target user, either as a public dashboard or on the same network. -- Have [Grafana Image Renderer](https://grafana.com/grafana/plugins/grafana-image-renderer/) installed. - -To use Grafana-rendered images: - -1. Go to the dashboard containing the panel in Grafana. -1. From the panel's menu, select **Share**. -1. Select **Direct link rendered image**, which provides the link. -1. Copy the link and add an image tag as [inline HTML](../../user/markdown.md#inline-html) in your - Markdown in the format `<img src="your_link"/>`. You can tweak the query parameters to meet your needs, such as removing the `&from=` - and `&to=` parameters to display a live panel. - -## Use integration with Grafana API - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31376) in GitLab 12.5. - -Each project can support integration with one Grafana instance. This enables you to copy a link to a -panel in Grafana, then paste it into a GitLab Markdown field. The panel renders in the GitLab panel -format. To embed panels from a Grafana instance, the data source must be: - -- A Prometheus instance. -- Proxyable, so the **HTTP > Access** setting for the Grafana data source should be set to - **Server (default)**. - -### Set up Grafana integration - -To set up the Grafana API in Grafana: - -1. In Grafana, [generate an Admin-level API Token](https://grafana.com/docs/grafana/next/developers/http_api/auth/#create-api-token). -1. In your GitLab project, go to **Settings > Monitor** and expand the **Grafana authentication** - section. -1. To enable the integration, check the **Active** checkbox. -1. For **Grafana URL**, enter the base URL of the Grafana instance. -1. For **API Token**, enter the Administrator API token you just generated. -1. Select **Save Changes**. - -NOTE: -If the Grafana integration is enabled, users with the Reporter role on public -projects and the Guest role on non-public projects can query metrics from the -Prometheus instance. All requests proxied through GitLab are authenticated with -the same Grafana Administrator API token. - -### Generate a link to a panel - -To generate a link to a panel: - -1. In Grafana, go to the dashboard you wish to embed a panel from. -1. In the upper-left corner of the page, select a specific value for each variable required for the - queries in the dashboard. -1. In Grafana select a panel's title, then select **Share** to open the panel's sharing dialog to - the **Link** tab. - - If you select the dashboard's share button instead, GitLab attempts to embed the first supported - panel on the dashboard (if available). -1. If your Prometheus queries use the Grafana custom template variables, ensure the - **Template variables** option is set to on. Only the Grafana global template variables - `$__interval`, `$__from`, and `$__to` are supported. -1. Set the **Current time range** option to on, to specify the time range of the panel. Otherwise, - the default range is the last 8 hours. -1. Select **Copy** to copy the URL to the clipboard. -1. In GitLab, paste the URL into a Markdown field and save. The panel takes a few moments to render. - -See the following example of a rendered panel. - - -<!--- end_remove --> +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. +Use [embed charts](https://gitlab.com/groups/gitlab-org/opstrace/-/epics/33) instead. diff --git a/doc/operations/metrics/img/copy_link_to_chart_v12_10.png b/doc/operations/metrics/img/copy_link_to_chart_v12_10.png Binary files differdeleted file mode 100644 index fc205240ea5..00000000000 --- a/doc/operations/metrics/img/copy_link_to_chart_v12_10.png +++ /dev/null diff --git a/doc/operations/metrics/img/embed_metrics_issue_template.png b/doc/operations/metrics/img/embed_metrics_issue_template.png Binary files differdeleted file mode 100644 index ca39a738d5f..00000000000 --- a/doc/operations/metrics/img/embed_metrics_issue_template.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 differdeleted file mode 100644 index 876972dc721..00000000000 --- a/doc/operations/metrics/img/embedded_metrics_rendered_v13_4.png +++ /dev/null diff --git a/doc/operations/metrics/img/example-dashboard_v13_3.png b/doc/operations/metrics/img/example-dashboard_v13_3.png Binary files differdeleted file mode 100644 index 1178b4a9be7..00000000000 --- a/doc/operations/metrics/img/example-dashboard_v13_3.png +++ /dev/null diff --git a/doc/operations/metrics/img/hide_embedded_metrics_v12_10.png b/doc/operations/metrics/img/hide_embedded_metrics_v12_10.png Binary files differdeleted file mode 100644 index 1213029d1d1..00000000000 --- a/doc/operations/metrics/img/hide_embedded_metrics_v12_10.png +++ /dev/null diff --git a/doc/operations/metrics/img/prometheus_add_metric.png b/doc/operations/metrics/img/prometheus_add_metric.png Binary files differdeleted file mode 100644 index 32a7cbf3a73..00000000000 --- a/doc/operations/metrics/img/prometheus_add_metric.png +++ /dev/null diff --git a/doc/operations/metrics/img/prometheus_cluster_health_embed_v12_9.png b/doc/operations/metrics/img/prometheus_cluster_health_embed_v12_9.png Binary files differdeleted file mode 100644 index c669467757f..00000000000 --- a/doc/operations/metrics/img/prometheus_cluster_health_embed_v12_9.png +++ /dev/null diff --git a/doc/operations/metrics/img/prometheus_dashboard_edit_metric_link_v_12_9.png b/doc/operations/metrics/img/prometheus_dashboard_edit_metric_link_v_12_9.png Binary files differdeleted file mode 100644 index b66b1a9f39b..00000000000 --- a/doc/operations/metrics/img/prometheus_dashboard_edit_metric_link_v_12_9.png +++ /dev/null diff --git a/doc/operations/metrics/img/prometheus_monitoring_dashboard_v13_3.png b/doc/operations/metrics/img/prometheus_monitoring_dashboard_v13_3.png Binary files differdeleted file mode 100644 index 1178b4a9be7..00000000000 --- a/doc/operations/metrics/img/prometheus_monitoring_dashboard_v13_3.png +++ /dev/null diff --git a/doc/operations/metrics/img/rendered_grafana_embed_v12_5.png b/doc/operations/metrics/img/rendered_grafana_embed_v12_5.png Binary files differdeleted file mode 100644 index 6cabe4193bd..00000000000 --- a/doc/operations/metrics/img/rendered_grafana_embed_v12_5.png +++ /dev/null diff --git a/doc/operations/metrics/img/view_embedded_metrics_v12_10.png b/doc/operations/metrics/img/view_embedded_metrics_v12_10.png Binary files differdeleted file mode 100644 index 95bb148ba71..00000000000 --- a/doc/operations/metrics/img/view_embedded_metrics_v12_10.png +++ /dev/null diff --git a/doc/operations/metrics/index.md b/doc/operations/metrics/index.md index 11350d65237..98ed9aba0da 100644 --- a/doc/operations/metrics/index.md +++ b/doc/operations/metrics/index.md @@ -2,167 +2,11 @@ stage: Monitor group: Respond info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +remove_date: '2023-08-22' +redirect_to: '../index.md' --- -# Monitor your environment's metrics **(FREE)** +# Monitor your environment's metrics (removed) **(FREE)** -> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7. - -WARNING: -This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) -for use in GitLab 14.7, and is planned for removal in GitLab 16.0. - -GitLab helps your team monitor the health and performance of your applications -and infrastructure by turning statistics and log files into charts and graphs -that are easy to understand, especially when time is short and decisions are -critical. For GitLab to display your information in charts, you must: - -1. **Instrument your application** - Collect accurate and complete measurements. - <I class="fa fa-youtube-play youtube" aria-hidden="true"></I> - For an overview, see [How to instrument Prometheus metrics in GitLab](https://www.youtube.com/watch?v=tuI2oJ3TTB4). -1. **Expose metrics for capture** - Make logs, metrics, and traces available for capture. -1. [**Configure Prometheus to gather metrics**](#configure-prometheus-to-gather-metrics) - - Use applications like Elasticsearch, Prometheus, and Jaeger to gather - the data you've exposed. -1. **GitLab collects metrics** - GitLab uses Prometheus to scrape the data you've - captured in your applications, and prepares the data for display. For more information, see - [Collect and process metrics](#collect-and-process-metrics). -1. **Display charts in the GitLab user interface** - GitLab converts your metrics - into easy-to-read charts on a default dashboard. You can create as many custom charts - and custom dashboards as needed so your team has full insight into your - application's health. - -## Configure Prometheus to gather metrics - -You must connect a Prometheus instance to GitLab to collect metrics. How you configure -your Prometheus integration depends on where your apps are running: - -- **For manually-configured Prometheus** - - [Specify your Prometheus server](../../user/project/integrations/prometheus.md#manual-configuration-of-prometheus), - and define at least one environment. -- **For a cluster integrated Prometheus** - GitLab can query - [an in-cluster Prometheus](../../user/clusters/integrations.md#prometheus-cluster-integration). - You must also complete a code deployment to your cluster for the **Monitor > Metrics** - page to contain data. You can do this using [Auto DevOps](../../topics/autodevops/cloud_deployments/auto_devops_with_gke.md). - - - -## Collect and process metrics - -After [configuring Prometheus for a cluster](../../user/project/integrations/prometheus.md), -GitLab attempts to retrieve performance metrics for any [environment](../../ci/environments/index.md) with -a successful deployment. - -GitLab scans the Prometheus server for metrics from known servers like Kubernetes -and NGINX, and attempts to identify individual environments. For more information about -the supported metrics and scan processes, see -[Prometheus Metrics library](../../user/project/integrations/prometheus_library/index.md). - -To view the [default metrics dashboard](dashboards/default.md) for an environment that is -[configured to gather metrics](#configure-prometheus-to-gather-metrics): - -1. *If the metrics dashboard is only visible to project members,* sign in to - GitLab as a member of a project. Learn more about [metrics dashboard visibility](#metrics-dashboard-visibility). -1. In your project, navigate to **Monitor > Metrics**. - -GitLab displays the [default metrics dashboard](dashboards/default.md) for the environment, -like the following example: - - - -The top of the dashboard contains a navigation bar. From left to right, the -navigation bar contains: - -- **Dashboard** - A dropdown list of all dashboards available for the project, - with starred dashboards listed first. -- **Environment** - A dropdown list of all [environments](../index.md) that searches - through all environments as you type. -- **Range** - The time period of data to display. -- **Refresh dashboard** **{retry}** - Reload the dashboard with current data. -- **Set refresh rate** - Set a time frame for refreshing the data displayed. -- **More actions** **{ellipsis_v}** - More dashboard actions - - **Add metric** - Adds a [custom metric](#adding-custom-metrics). Only available on GitLab-defined dashboards. - ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34779) in GitLab 12.5.) - - **Edit dashboard YAML** - Edit the source YAML file of a custom dashboard. Only available on - [custom dashboards](dashboards/index.md). - ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34779) in GitLab 12.5.) - - **Duplicate current dashboard** - Save a [complete copy of a dashboard](dashboards/index.md#duplicate-a-gitlab-defined-dashboard). Only available on GitLab-defined dashboards. - - **Star dashboard** **{star-o}** - Mark a dashboard as a favorite. - Starred dashboards display a solid star **{star}** button, and display first - in the **Dashboard** dropdown list. - ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214582) in GitLab 13.0.) - - **Create new dashboard** - Create a [new custom dashboard for your project](dashboards/index.md#add-a-new-dashboard-to-your-project). - ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/228856) in GitLab 13.3.) -- **Metrics settings** - Configure the - [settings for this dashboard](dashboards/index.md#manage-the-metrics-dashboard-settings). - -## Customize your metrics dashboard - -After creating your dashboard, you can customize it to meet your needs: - -- **Add custom metrics**: In addition to the GitLab default metrics, you can - [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)** - when environment performance falls outside of the boundaries you set. - -## Metrics dashboard visibility - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/201924) in GitLab 13.0. - -You can set the visibility of the metrics dashboard to **Only Project Members** -or **Everyone With Access**. When set to **Everyone with Access**, the metrics -dashboard is visible to authenticated and non-authenticated users. - -## Adding custom metrics - -> [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28527) from GitLab Premium to GitLab Free in 12.10. - -Custom metrics can be monitored by adding them on the monitoring dashboard page. -After saving them, they display on the environment metrics dashboard provided that either: - -- A [connected Kubernetes cluster](../../user/clusters/agent/index.md) - with the matching [environment scope](../../ci/environments/index.md#limit-the-environment-scope-of-a-cicd-variable) is used and - [Prometheus installed on the cluster](../../user/project/integrations/prometheus.md#enabling-prometheus-integration). -- Prometheus is [manually configured](../../user/project/integrations/prometheus.md#manual-configuration-of-prometheus). - - - -A few fields are required: - -- **Name**: Chart title -- **Type**: Type of metric. Metrics of the same type are shown together. -- **Query**: Valid [PromQL query](https://prometheus.io/docs/prometheus/latest/querying/basics/). -- **Y-axis label**: Y axis title to display on the dashboard. -- **Unit label**: Query units, for example `req / sec`. Shown next to the value. - -Multiple metrics can be displayed on the same chart if the fields **Name**, **Type**, -and **Y-axis label** match between metrics. For example, a metric with **Name** -`Requests Rate`, **Type** `Business`, and **Y-axis label** `rec / sec` would display -on the same chart as a second metric with the same values. A **Legend label** is -suggested if this feature is used. - -## Editing additional metrics from the dashboard - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208976) in GitLab 12.9. - -You can edit existing additional custom metrics for your dashboard by selecting the -**{ellipsis_v}** **More actions** dropdown list and selecting **Edit metric**. - - - -## Keyboard shortcuts for charts - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202146) in GitLab 13.2. - -You can use keyboard shortcuts to interact more quickly with your currently-focused -chart panel. To activate keyboard shortcuts, use keyboard tabs to highlight the -**{ellipsis_v}** **More actions** dropdown list, or hover over the dropdown list -with your mouse, then press the key corresponding to your desired action: - -- **Expand panel** - <kbd>e</kbd> -- **View logs** - <kbd>l</kbd> (lowercase 'L') -- **Download CSV** - <kbd>d</kbd> -- **Copy link to chart** - <kbd>c</kbd> -- **Alerts** - <kbd>a</kbd> +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7 +and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0. diff --git a/doc/operations/quickstart-guide.md b/doc/operations/quickstart-guide.md deleted file mode 100644 index 91c5f25405c..00000000000 --- a/doc/operations/quickstart-guide.md +++ /dev/null @@ -1,229 +0,0 @@ ---- -stage: Monitor -group: Observability -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments ---- - -# GitLab Observability Quickstart - -You can try GitLab Observability by [cloning or forking the project](https://gitlab.com/gitlab-org/opstrace/opstrace.git) and creating a local installation. - -## Prerequisites and dependencies - -To install GitLab Observability Platform (GOP), install and configure the following third-party dependencies. You can do this manually, or [automatically by using asdf](#install-dependencies-using-asdf): - -- [kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) for creating a local Kubernetes cluster. -- [Docker](https://docs.docker.com/install) - - [Docker Compose](https://docs.docker.com/compose/compose-v2/) is now part of the `docker` distribution. -- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) for interacting with GitLab Observability. -- [Telepresence](https://www.telepresence.io/) allows you to code and test microservices locally against a remote Kubernetes cluster. -- [jq](https://stedolan.github.io/jq/download/) for some Makefile utilities. -- [Go 1.19](https://go.dev/doc/install). - -The current versions of these dependencies are pinned in the `.tool-versions` file in the project. - -You can run the following commands to check the availability and versions of these dependencies on your machine: - -```shell -kind --version -docker --version -kubectl version -telepresence version -jq --version -go version -``` - -### Run GOP on macOS - -If you're running GOP on macOS, ensure you have enough resources dedicated to Docker Desktop. The recommended minimum is: - -- CPUs: 4+ -- Memory: 8 GB+ -- Swap: 1 GB+ - -It's possible to run GOP with fewer resources, but this specification works. - -### Install dependencies using asdf - -If you install dependencies using [`asdf`](https://asdf-vm.com/#/core-manage-asdf), GOP manages them for you automatically. - -1. If you have not already done so, clone the `opstrace` repository into your preferred location: - - ```shell - git clone https://gitlab.com/gitlab-org/opstrace/opstrace.git - ``` - -1. Change into the project directory: - - ```shell - cd opstrace - ``` - -1. Optional. If you need to install `asdf`, run: - - ```shell - make install-asdf - ``` - -1. Install dependencies using `asdf`: - - ```shell - make bootstrap - ``` - -## Step 1: Create a local Kubernetes cluster with kind - -Make sure Docker Desktop is running. In the `opstrace` project you cloned, run the following command: - -```shell -make kind -``` - -Wait a few minutes while kind creates your Kubernetes cluster. When it's finished, you should see the following message: - -```plaintext -Traffic Manager installed successfully -``` - -Now deploy the scheduler by running the following command in the `opstrace` project: - -```shell -make deploy -``` - -This takes around 1 minute. - -## Step 2: Create a GitLab application for authentication - -You must create a GitLab application to use for authentication. - -In the GitLab instance you'd like to connect with GOP, [create an OAuth application](../integration/oauth_provider.md). -This application can be a user-owned, group-owned or instance-wide application. -In production, you would create a trusted instance-wide application so that users are explicitly authorized without the consent screen. -The following example shows how to configure the application. - -1. Select the API scope and enter `http://localhost/v1/auth/callback` as the redirect URI. - -1. Run the following command to create the secret that holds the authentication data: - - ```shell - kubectl create secret generic \ - --from-literal=gitlab_oauth_client_id=<gitlab_application_client_id> \ - --from-literal=gitlab_oauth_client_secret=<gitlab_application_client_secret> \ - --from-literal=internal_endpoint_token=<error_tracking_internal_endpoint_token> \ - dev-secret - ``` - -1. Replace `<gitlab_application_client_id>` and `<gitlab_application_client_secret>` with the values from the GitLab application you just created. -Replace `<error_tracking_internal_endpoint_token>` with any string if you do not plan to use error tracking. - -You can also view [this MR on how to get the token to test error tracking](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91928). -You must specify all the parameters when creating the secret. - -## Step 3: Create the cluster definition - -1. In your `opstrace` project, run the following command to create a `Cluster.yaml` manifest file: - - ```shell - cat <<EOF > Cluster.yaml - apiVersion: opstrace.com/v1alpha1 - kind: Cluster - metadata: - name: dev-cluster - spec: - target: kind - goui: - image: "registry.gitlab.com/gitlab-org/opstrace/opstrace-ui/ gitlab-observability-ui:c9fb6e70" - dns: - acmeEmail: "" - dns01Challenge: {} - externalDNSProvider: {} - gitlab: - groupAllowedAccess: '*' - groupAllowedSystemAccess: "6543" - instanceUrl: https://gitlab.com - authSecret: - name: dev-secret - EOF - ``` - -1. Apply the file you just created with the following command: - - ```shell - kubectl apply -f Cluster.yaml - ``` - -1. Run the following command to wait for the cluster to be ready: - - ```shell - kubectl wait --for=condition=ready cluster/dev-cluster --timeout=600s - ``` - -After the previous command exits, the cluster is ready. - -## Step 4: Enable Observability on a GitLab namespace you own - -Go to a namespace you own in the connected GitLab instance and copy the Group ID below the group name. - -GOP can only be enabled for groups you own. -To list all the groups that your user owns, go to the menu in upper left corner and select `Groups`->`View all Groups`. You then see the **Your groups** tab. - -In your browser, go to `http://localhost/-/{GroupID}`. For example, `http://localhost/-/14485840`. - -Follow the on-screen instructions to enable observability for the namespace. -This can take a couple of minutes if it's the first time observability has been enabled for the root level namespace (GitLab.org in the previous example.) - -Once your namespace has been enabled and is ready, the page automatically redirects you to the GitLab Observability UI. - -## Step 5: Send traces to GOP - -[Follow this guide to send traces to your namespace and monitor them in the UI](https://gitlab.com/gitlab-org/opstrace/opstrace/-/blob/main/docs/guides/user/sending-traces-locally.md). - -## Step 6: Clean up your local GOP - -To tear down your locally running GOP instance, run the following command: - -```shell -make destroy -``` - -## Known issues - -### Incorrect architecture for `kind/node` image - -If your machine has an Apple silicon (M1/M2) chip, you might encounter an architecture problem with the `kind/node` image when running the `make kind` command. For more details, see [issue 1802](https://gitlab.com/gitlab-org/opstrace/opstrace/-/issues/1802). - -To fix this problem, you first need to create a Dockerfile. Then build and deploy the image: - -1. Create a new Dockerfile (without a file extension) and paste the following commands: - - ```Dockerfile - FROM --platform=arm64 kindest/node:v1.23.13 - RUN arch - ``` - -1. Save your Dockerfile, then build the image with the following command: - - ```shell - docker build -t tempkind . - ``` - - Do not forget the period at the end. - -1. Create a cluster using your new image with the following command: - - ```shell - kind create cluster --image tempkind - ``` - -### scheduler-controller-manager pod cannot start due to ImagePullBackOff - -If while executing `make deploy` in step 1, the `scheduler-controller-manager` pod cannot start due to `ImagePullBackOff`, you must set the `CI_COMMIT_TAG` to a non-dirty state. By setting the commit tag to the latest commit, you ensure the Docker image can be pulled from the container registry. - -Run the following command to set the commit tag: - -```shell -make kind -export CI_COMMIT_TAG=0.2.0-e1206acf -make deploy -``` |
