diff options
Diffstat (limited to 'doc/operations/metrics/dashboards')
35 files changed, 346 insertions, 166 deletions
diff --git a/doc/operations/metrics/dashboards/default.md b/doc/operations/metrics/dashboards/default.md new file mode 100644 index 00000000000..f086d7737bd --- /dev/null +++ b/doc/operations/metrics/dashboards/default.md @@ -0,0 +1,38 @@ +--- +stage: Monitor +group: APM +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# GitLab-defined metrics dashboards **(CORE)** + +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 + +NOTE: **Note:** +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 K8s cluster](../../../user/project/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. + + diff --git a/doc/operations/metrics/dashboards/develop.md b/doc/operations/metrics/dashboards/develop.md new file mode 100644 index 00000000000..b621f5fd727 --- /dev/null +++ b/doc/operations/metrics/dashboards/develop.md @@ -0,0 +1,33 @@ +--- +stage: Monitor +group: APM +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Developing templates for custom dashboards **(CORE)** + +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 + +Navigate to the browser-based editor of your choice: + +- In the **Repository view**: + + 1. Navigate to **{doc-text}** **Repository > Files**. + 1. Click **{plus}** **Add to tree** and select **New file**, + then click **Select a template type** to see a list of available templates: +  + +- In the **[Web IDE](../../../user/project/web_ide/index.md)**: + + 1. Click **Web IDE** when viewing your repository. + 1. Click **{doc-new}** **New file**, then click **Choose a template** to see a list of available templates: +  + +## Custom dashboard templates **(PREMIUM ONLY)** + +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). 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 differnew file mode 100644 index 00000000000..e03fbef3b35 --- /dev/null +++ b/doc/operations/metrics/dashboards/img/actions_menu_create_add_panel_v13_3.png 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 differnew file mode 100644 index 00000000000..ba4780b730b --- /dev/null +++ b/doc/operations/metrics/dashboards/img/actions_menu_create_new_dashboard_v13_3.png 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 differnew file mode 100644 index 00000000000..3e8d792c53e --- /dev/null +++ b/doc/operations/metrics/dashboards/img/dashboard_external_link_v13_1.png 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 differnew file mode 100644 index 00000000000..8d45607a940 --- /dev/null +++ b/doc/operations/metrics/dashboards/img/dashboard_local_timezone_v13_1.png diff --git a/doc/operations/metrics/dashboards/img/external_dashboard_link.png b/doc/operations/metrics/dashboards/img/external_dashboard_link.png Binary files differnew file mode 100644 index 00000000000..82c5e05e467 --- /dev/null +++ b/doc/operations/metrics/dashboards/img/external_dashboard_link.png 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 differnew file mode 100644 index 00000000000..c3a391b06c7 --- /dev/null +++ b/doc/operations/metrics/dashboards/img/heatmap_chart_too_much_data_v_13_2.png diff --git a/doc/operations/metrics/dashboards/img/heatmap_panel_type.png b/doc/operations/metrics/dashboards/img/heatmap_panel_type.png Binary files differnew file mode 100644 index 00000000000..a2b3911ec68 --- /dev/null +++ b/doc/operations/metrics/dashboards/img/heatmap_panel_type.png 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 differnew file mode 100644 index 00000000000..dc0bc951500 --- /dev/null +++ b/doc/operations/metrics/dashboards/img/k8s_pod_health_dashboard_v13_3.png 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 differnew file mode 100644 index 00000000000..a042fbbcf4e --- /dev/null +++ b/doc/operations/metrics/dashboards/img/metrics_dashboard_annotations_ui_v13.0.png 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 differnew file mode 100644 index 00000000000..4f6d3b3dfa4 --- /dev/null +++ b/doc/operations/metrics/dashboards/img/metrics_dashboard_panel_preview_v13_3.png 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 differnew file mode 100644 index 00000000000..bd8401a1747 --- /dev/null +++ b/doc/operations/metrics/dashboards/img/metrics_dashboard_template_selection_v13_3.png 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 differnew file mode 100644 index 00000000000..650f66e9a30 --- /dev/null +++ b/doc/operations/metrics/dashboards/img/metrics_dashboard_template_selection_web_ide_v13_3.png diff --git a/doc/operations/metrics/dashboards/img/metrics_settings_button_v13_3.png b/doc/operations/metrics/dashboards/img/metrics_settings_button_v13_3.png Binary files differnew file mode 100644 index 00000000000..9c0eac12a3f --- /dev/null +++ b/doc/operations/metrics/dashboards/img/metrics_settings_button_v13_3.png diff --git a/doc/operations/metrics/dashboards/img/panel_context_menu_v13_3.png b/doc/operations/metrics/dashboards/img/panel_context_menu_v13_3.png Binary files differnew file mode 100644 index 00000000000..1259917608b --- /dev/null +++ b/doc/operations/metrics/dashboards/img/panel_context_menu_v13_3.png 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 differnew file mode 100644 index 00000000000..5cba6fa9038 --- /dev/null +++ b/doc/operations/metrics/dashboards/img/prometheus_dashboard_anomaly_panel_type.png 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 differnew file mode 100644 index 00000000000..8c5663fef12 --- /dev/null +++ b/doc/operations/metrics/dashboards/img/prometheus_dashboard_area_panel_type_v12_8.png 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 differnew file mode 100644 index 00000000000..593e31477f4 --- /dev/null +++ b/doc/operations/metrics/dashboards/img/prometheus_dashboard_bar_chart_panel_type_v12.10.png 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 differnew file mode 100644 index 00000000000..985f2b04ef3 --- /dev/null +++ b/doc/operations/metrics/dashboards/img/prometheus_dashboard_column_panel_type.png 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 differnew file mode 100644 index 00000000000..547c565c6f9 --- /dev/null +++ b/doc/operations/metrics/dashboards/img/prometheus_dashboard_gauge_panel_type_v13_3.png 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 differnew file mode 100644 index 00000000000..15111a97464 --- /dev/null +++ b/doc/operations/metrics/dashboards/img/prometheus_dashboard_label_variable_shorthand.png 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 differnew file mode 100644 index 00000000000..9b94d0c6afa --- /dev/null +++ b/doc/operations/metrics/dashboards/img/prometheus_dashboard_label_variables.png 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 differnew file mode 100644 index 00000000000..d43a890f0fa --- /dev/null +++ b/doc/operations/metrics/dashboards/img/prometheus_dashboard_repeated_label.png 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 differnew file mode 100644 index 00000000000..2d7dfb27b49 --- /dev/null +++ b/doc/operations/metrics/dashboards/img/prometheus_dashboard_single_stat_panel_type.png 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 differnew file mode 100644 index 00000000000..ba67509bcf3 --- /dev/null +++ b/doc/operations/metrics/dashboards/img/prometheus_dashboard_stacked_column_panel_type_v12_8.png 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 differnew file mode 100644 index 00000000000..08d7d6603d2 --- /dev/null +++ b/doc/operations/metrics/dashboards/img/prometheus_dashboard_yaml_validation_v13_1.png 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 differnew file mode 100644 index 00000000000..4dc141f0e7f --- /dev/null +++ b/doc/operations/metrics/dashboards/img/related_links_v13_1.png diff --git a/doc/operations/metrics/dashboards/index.md b/doc/operations/metrics/dashboards/index.md index a46abdee2dc..ffcb7dc92c6 100644 --- a/doc/operations/metrics/dashboards/index.md +++ b/doc/operations/metrics/dashboards/index.md @@ -4,61 +4,154 @@ group: APM info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Using the Metrics Dashboard +# Custom dashboards **(CORE)** -## Manage the metrics dashboard settings +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/59974) in GitLab 12.1. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223204) in GitLab 13.2. +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. -To manage the settings for your metrics dashboard: +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). + +NOTE: **Note:** +The metrics as defined below do not support alerts, unlike +[custom metrics](../index.md#adding-custom-metrics). + +## Add a new dashboard to your project -1. Sign in as a user with project Maintainer or Admin +> 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 +**Operations > 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 **{cloud-gear}** **Operations > Metrics**. -1. In the top-right corner of your dashboard, click **{settings}** **Metrics Settings**: +1. Navigate to your dashboard at **Operations > Metrics**. +1. In the top-right corner of your dashboard, click the **{ellipsis_v}** **More actions** menu, + and select **Create new**: +  +1. In the modal window, click **Open Repository**, then follow the instructions + for creating a new dashboard from the command line. -  +To create a new dashboard from the command line: -## Chart Context Menu +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: -From each of the panels in the dashboard, you can access the context menu by clicking the **{ellipsis_v}** **More actions** dropdown box above the upper right corner of the panel to take actions related to the chart's data. + ```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 **Operations > Metrics** and choose the custom + dashboard from the dropdown. -The options are: +Your custom dashboard is available at `https://example.com/project/-/metrics/custom_dashboard_name.yml`. -- [Expand panel](#expand-panel) -- [View logs](#view-logs-ultimate) -- [Download CSV](#downloading-data-as-csv) -- [Copy link to chart](../embed.md#embedding-gitlab-managed-kubernetes-metrics) -- [Alerts](../alerts.md) +NOTE: **Note:** +Configuration files nested under subdirectories of `.gitlab/dashboards` are not +supported and won't be available in the UI. -### View and edit the source file of a custom dashboard +## Add a new metrics panel to a dashboard -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34779) in GitLab 12.5. +> UI option [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/228761) in GitLab 13.3. -When viewing a custom dashboard of a project, you can view the original -`.yml` file by clicking on the **Edit dashboard** button. +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: -### Expand panel +1. Sign in to GitLab as a user with Maintainer or Owner + [permissions](../../../user/permissions.md#project-members-permissions). +1. Click **Add panel** in the **{ellipsis_v}** **More actions** menu. + + NOTE: **Note:** + You can add panel only to custom dashboards. -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3100) in GitLab 13.0. +  +1. In the **Define and preview panel** section, paste in the YAML you want to + preview in the **Panel YAML** field. +1. Click **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. +> - From [GitLab 12.8 onwards](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. + +1. Click **Duplicate current dashboard** in the **{ellipsis_v}** **More actions** menu. + + NOTE: **Note:** + You can duplicate only GitLab-defined dashboards. + +1. Enter the filename and other information, such as the new commit's message, and click **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. + +To manage the settings for your metrics dashboard: + +1. Sign in as a user with project Maintainer or Administrator + [permissions](../../../user/permissions.md#project-members-permissions). +1. Navigate to your dashboard at **Operations > Metrics**. +1. In the top-right corner of your dashboard, click **Metrics Settings**: -To view a larger version of a visualization, expand the panel by clicking the -**{ellipsis_v}** **More actions** icon and selecting **Expand panel**. +  -To return to the metrics dashboard, click the **Back** button in your -browser, or pressing the <kbd>Esc</kbd> key. +## Chart Context Menu -### View Logs **(ULTIMATE)** +You can take action related to a chart's data by clicking the +**{ellipsis_v}** **More actions** dropdown box above the upper right corner of +any chart on a dashboard: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/122013) in GitLab 12.8. + -If you have [Logs](../../../user/project/clusters/kubernetes_pod_logs.md) enabled, -you can navigate from the charts in the dashboard to view Logs by -clicking on the context menu in the upper-right corner. +The options are: -If you use the **Timeline zoom** function at the bottom of the chart, logs will narrow down to the time range you selected. +- **Expand panel** - Displays a larger version of a visualization. To return to + the dashboard, click the **Back** button in your browser, or press the <kbd>Esc</kbd> key. + ([Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3100) in GitLab 13.0.) +- **View logs** **(ULTIMATE)** - Displays [Logs](../../../user/project/clusters/kubernetes_pod_logs.md), + if they are enabled. If used in conjunction with the [timeline zoom](#timeline-zoom-and-url-sharing) + feature, logs narrow down to the selected time range. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/122013) in GitLab 12.8.) +- **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) +- **Alerts** - Display any [alerts](../alerts.md) configured for this metric. +- **View Runbook** - Displays the runbook for an alert. For information about configuring + runbooks, read [Set up alerts for Prometheus metrics](../alerts.md). + ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211844) in GitLab 13.3.) ### Timeline zoom and URL sharing @@ -69,10 +162,6 @@ on a date and time of your choice. When you click 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 timeframes more easily. -### Downloading data as CSV - -Data from Prometheus charts on the metrics dashboard can be downloaded as CSV. - ## Dashboard Annotations > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211330) in GitLab 12.10 (enabled by feature flag `metrics_dashboard_annotations`). @@ -88,9 +177,9 @@ its description. You can create annotations by making requests to the [Metrics dashboard annotations API](../../../api/metrics_dashboard_annotations.md) - + -### Retention policy +### Annotation retention policy > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211433) in GitLab 13.01. @@ -124,7 +213,7 @@ 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 @@ -139,99 +228,6 @@ links: type: grafana ``` -## Defining custom dashboards per project - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/59974) in GitLab 12.1. - -By default, all projects include a GitLab-defined Prometheus dashboard, which -includes a few key metrics, but you can also define your own custom dashboards. - -You may create a new file from scratch or duplicate a GitLab-defined Prometheus -dashboard. - -NOTE: **Note:** -The metrics as defined below do not support alerts, unlike -[custom metrics](../index.md#adding-custom-metrics). - -### Adding a new dashboard to your project - -> UI option [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223204) in GitLab 13.2. - -You can configure a custom dashboard by adding a new YAML file into your project's -`.gitlab/dashboards/` directory. In order for the dashboards to be displayed on -the project's **{cloud-gear}** **Operations > Metrics** page, the files must have a `.yml` -extension and should be present in the 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 **{cloud-gear}** **Operations > Metrics**. -1. In the top-right corner of your dashboard, click the **{file-addition-solid}** **Actions** menu, - and select **Create new**: -  -1. In the modal window, click **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 **Operations > Metrics** and choose the custom - dashboard from the dropdown. - -NOTE: **Note:** -Configuration files nested under subdirectories of `.gitlab/dashboards` are not -supported and will not be available in the UI. - -### Navigating to a custom dashboard - -Custom dashboards are uniquely identified by their filenames. In order to quickly view the custom dashboard, -just use the dashboard filename in the URL this way: -`https://gitlab-instance.example.com/project/-/metrics/custom_dashboard_name.yml`. - -### Duplicating a GitLab-defined dashboard - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/37238) in GitLab 12.7. -> - From [GitLab 12.8 onwards](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. -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. - -1. Click **Duplicate dashboard** in the dashboard dropdown or in the actions menu. - - NOTE: **Note:** - You can duplicate only GitLab-defined dashboards. - -1. Enter the file name and other information, such as the new commit's message, and click **Duplicate**. - -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. - ## Troubleshooting When troubleshooting issues with a managed Prometheus app, it is often useful to diff --git a/doc/operations/metrics/dashboards/panel_types.md b/doc/operations/metrics/dashboards/panel_types.md index 0397218fe0e..b2cbdcb88d9 100644 --- a/doc/operations/metrics/dashboards/panel_types.md +++ b/doc/operations/metrics/dashboards/panel_types.md @@ -4,7 +4,7 @@ group: APM info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Panel types for dashboards +# Panel types for dashboards **(CORE)** The below panel types are supported in monitoring dashboards. @@ -37,7 +37,7 @@ Note the following properties: | 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 will automatically scale according to the data. Previously, it always started from 0. @@ -81,7 +81,7 @@ Note the following properties: | 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 @@ -110,7 +110,7 @@ Note the following properties: | `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 @@ -137,7 +137,7 @@ Note the following properties: | 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 @@ -169,7 +169,7 @@ panel_groups: series_name: 'group 2' ``` - + | Property | Type | Required | Description | | ------ | ------ | ------ | ------ | @@ -202,7 +202,7 @@ Note the following properties: | 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 @@ -227,6 +227,57 @@ panel_groups: 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 + +CAUTION: **Warning:** +This panel type is an _alpha_ 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. @@ -254,9 +305,9 @@ Note the following properties: | 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) | - + CAUTION: **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. - + diff --git a/doc/operations/metrics/dashboards/settings.md b/doc/operations/metrics/dashboards/settings.md new file mode 100644 index 00000000000..a4aef6b1674 --- /dev/null +++ b/doc/operations/metrics/dashboards/settings.md @@ -0,0 +1,52 @@ +--- +stage: Monitor +group: APM +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Dashboard settings + +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 > Operations**, and scroll to + **Metrics Dashboard**. +1. In the **Dashboard timezone** select box, select *User's local timezone* + or *UTC*: + +  +1. Click **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 > Operations**, and scroll to + **Metrics Dashboard**. +1. In **External dashboard URL**, provide the URL to your external dashboard: + +  + +1. Click **Save changes**. + +GitLab displays a **View full dashboard** button in the top right corner of your +[monitoring dashboard](../../../ci/environments/index.md#monitoring-environments) +which opens the URL you provided: + + diff --git a/doc/operations/metrics/dashboards/templating_variables.md b/doc/operations/metrics/dashboards/templating_variables.md index a515742ea92..71025d41281 100644 --- a/doc/operations/metrics/dashboards/templating_variables.md +++ b/doc/operations/metrics/dashboards/templating_variables.md @@ -4,7 +4,7 @@ group: APM info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Templating variables for metrics dashboards +# Templating variables for metrics dashboards **(CORE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214539) in GitLab 13.0. diff --git a/doc/operations/metrics/dashboards/variables.md b/doc/operations/metrics/dashboards/variables.md index 19b77a1ed87..8b0d7f37052 100644 --- a/doc/operations/metrics/dashboards/variables.md +++ b/doc/operations/metrics/dashboards/variables.md @@ -4,9 +4,9 @@ group: APM info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Using Variables +# Using variables **(CORE)** -## Query Variables +## Query variables Variables can be specified using double curly braces, such as `"{{ci_environment_slug}}"` ([added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20793) in GitLab 12.7). @@ -41,7 +41,7 @@ For example, if the dashboard time range is set to 8 hours, the value of [Variables can be defined](../../../operations/metrics/dashboards/yaml.md#templating-templating-properties) in a custom dashboard YAML file. -## Query Variables from URL +## Query variables from URL > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214500) in GitLab 13.0. diff --git a/doc/operations/metrics/dashboards/yaml.md b/doc/operations/metrics/dashboards/yaml.md index 6a4158798bc..f92ba4079e9 100644 --- a/doc/operations/metrics/dashboards/yaml.md +++ b/doc/operations/metrics/dashboards/yaml.md @@ -4,7 +4,7 @@ group: APM info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Dashboard YAML properties +# Dashboard YAML properties **(CORE)** Dashboards have several components: @@ -43,24 +43,34 @@ Read the documentation on [links](index.md#add-related-links-to-custom-dashboard ## **Panel group (`panel_groups`) properties** +Dashboards display panel groups in the order they are listed in the dashboard YAML file. + +NOTE: **Note:** +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. | -| `priority` | number | optional, defaults to order in file | Order to appear on the dashboard. Higher number means higher priority, which will be higher on the page. Numbers do not need to be consecutive. | | `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 will 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. + +NOTE: **Note:** +In GitLab versions 13.3 and below, panels were ordered by a `weight` key, which +is no longer used. + | Property | Type | Required | Description | | ------ | ------ | ------ | ------- | -| `type` | enum | no, defaults to `area-chart` | Specifies the panel type to use, for example `area-chart`, `line-chart` or `anomaly-chart`. [View documentation on all panel types.](panel_types.md) | +| `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) | -| `weight` | number | no, defaults to order in file | Order to appear within the grouping. Lower number means higher priority, which will be higher on the page. Numbers do not need to be consecutive. | | `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). | @@ -79,8 +89,8 @@ Panels in a panel group are laid out in rows consisting of two panels per row. A | `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 | 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/) will be utilized. | -| `query_range` | string | 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/) will be utilized. | +| `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/) will be utilized. | +| `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/) will be utilized. | | `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 @@ -99,7 +109,7 @@ metrics: 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 will be replaced by the values of the time series labels when the legend is rendered: @@ -113,7 +123,7 @@ metrics: The resulting rendered legend will look like this: - + There is also a shorthand value for dynamic dashboard labels that make use of only one time series label: @@ -127,7 +137,7 @@ metrics: This works by lowercasing the value of `label` 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 will be used and rendered in the legend like this: - + ## Dashboard YAML syntax validation @@ -142,19 +152,19 @@ To confirm your dashboard definition contains valid YAML syntax: 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](../../../operations/metrics/dashboards/yaml.md#dashboard-top-level-properties) -1. `panel_groups: should be an array of panel_groups objects` [learn more](../../../operations/metrics/dashboards/yaml.md#dashboard-top-level-properties) -1. `group: can't be blank` [learn more](../../../operations/metrics/dashboards/yaml.md#panel-group-panel_groups-properties) -1. `panels: should be an array of panels objects` [learn more](../../../operations/metrics/dashboards/yaml.md#panel-group-panel_groups-properties) -1. `title: can't be blank` [learn more](../../../operations/metrics/dashboards/yaml.md#panel-panels-properties) -1. `metrics: should be an array of metrics objects` [learn more](../../../operations/metrics/dashboards/yaml.md#panel-panels-properties) -1. `query: can't be blank` [learn more](../../../operations/metrics/dashboards/yaml.md#metrics-metrics-properties) -1. `query_range: can't be blank` [learn more](../../../operations/metrics/dashboards/yaml.md#metrics-metrics-properties) -1. `unit: can't be blank` [learn more](../../../operations/metrics/dashboards/yaml.md#metrics-metrics-properties) +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. diff --git a/doc/operations/metrics/dashboards/yaml_number_format.md b/doc/operations/metrics/dashboards/yaml_number_format.md index ae0cd9fff64..1a8bd6f4257 100644 --- a/doc/operations/metrics/dashboards/yaml_number_format.md +++ b/doc/operations/metrics/dashboards/yaml_number_format.md @@ -4,7 +4,7 @@ group: APM info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# Unit formats reference +# Unit formats reference **(CORE)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/201999) in GitLab 12.9. |
