diff options
Diffstat (limited to 'doc/operations/metrics/dashboards/index.md')
| -rw-r--r-- | doc/operations/metrics/dashboards/index.md | 262 |
1 files changed, 129 insertions, 133 deletions
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 |