Commit 245a14a5 authored by Amy Qualls's avatar Amy Qualls

Shift information on the dashboard page

Move the info on the dashboard page to the top of the page, in
prep for changing subheadings.
parent e58a2eea
......@@ -8,4 +8,4 @@
- viewer.errors.messages.each do |error|
%li= error.join(': ')
= link_to _('Learn more'), help_page_path('operations/metrics/dashboards/index.md', anchor: 'defining-custom-dashboards-per-project')
= link_to _('Learn more'), help_page_path('operations/metrics/dashboards/index.md')
......@@ -58,7 +58,7 @@ The dashboard uses metrics available in
![GitLab self monitoring default dashboard](img/self_monitoring_default_dashboard.png)
You can also
[create your own dashboards](../../../operations/metrics/dashboards/index.md#defining-custom-dashboards-per-project).
[create your own dashboards](../../../operations/metrics/dashboards/index.md).
## Connection to Prometheus
......@@ -83,8 +83,8 @@ Once the webhook is setup, you can
You can add custom metrics in the self monitoring project by:
1. [Duplicating](../../../operations/metrics/dashboards/index.md#duplicating-a-gitlab-defined-dashboard) the default dashboard.
1. [Editing](../../../operations/metrics/dashboards/index.md#view-and-edit-the-source-file-of-a-custom-dashboard) the newly created dashboard file and configuring it with [dashboard YAML properties](../../../operations/metrics/dashboards/yaml.md).
1. [Duplicating](../../../operations/metrics/dashboards/index.md#duplicate-a-gitlab-defined-dashboard) the default dashboard.
1. [Editing](../../../operations/metrics/index.md) the newly created dashboard file and configuring it with [dashboard YAML properties](../../../operations/metrics/dashboards/yaml.md).
## Troubleshooting
......
......@@ -4,61 +4,129 @@ 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
## 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, 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).
1. Sign in as a user with project Maintainer or Admin
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
> 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. For the dashboard to display on your project's
**{cloud-gear}** **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. In the top-right corner of your dashboard, click the **{file-addition-solid}** **Actions** menu,
and select **Create new**:
![Monitoring Dashboard actions menu with create new item](../../../user/project/integrations/img/actions_menu_create_new_dashboard_v13_2.png)
1. In the modal window, click **Open Repository**, then follow the instructions
for creating a new dashboard from the command line.
![Monitoring Dashboard actions menu with create new item](../../../user/project/integrations/img/metrics_settings_button_v13_2.png)
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:
```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"
```
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.
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.
![Context Menu](../../../user/project/integrations/img/panel_context_menu_v13_0.png)
Your custom dashboard is available at `https://example.com/project/-/metrics/custom_dashboard_name.yml`.
The options are:
NOTE: **Note:**
Configuration files nested under subdirectories of `.gitlab/dashboards` are not
supported and won't be available in the UI.
- [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)
## Duplicate a GitLab-defined dashboard
### View and edit the source file of a custom 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.
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34779) in GitLab 12.5.
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 dashboard** in the dashboard dropdown or in the 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.
When viewing a custom dashboard of a project, you can view the original
`.yml` file by clicking on the **Edit dashboard** button.
Your custom dashboard is available at `https://example.com/project/-/metrics/custom_dashboard_name.yml`.
## Manage the metrics dashboard settings
### Expand panel
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223204) in GitLab 13.2.
> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3100) in GitLab 13.0.
To manage the settings for your metrics dashboard:
To view a larger version of a visualization, expand the panel by clicking the
**{ellipsis_v}** **More actions** icon and selecting **Expand panel**.
1. Sign in as a user with project Maintainer or Admin
[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**:
To return to the metrics dashboard, click the **Back** button in your
browser, or pressing the <kbd>Esc</kbd> key.
![Monitoring Dashboard actions menu with create new item](../../../user/project/integrations/img/metrics_settings_button_v13_2.png)
### View Logs **(ULTIMATE)**
## Chart Context Menu
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/122013) in GitLab 12.8.
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:
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.
![Context Menu](../../../user/project/integrations/img/panel_context_menu_v13_0.png)
If you use the **Timeline zoom** function at the bottom of the chart, logs will narrow down to the time range you selected.
The options are:
- **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](../alerts.md)
### Timeline zoom and URL sharing
......@@ -69,10 +137,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`).
......@@ -90,7 +154,7 @@ You can create annotations by making requests to the
![Annotations UI](../../../user/project/integrations/img/metrics_dashboard_annotations_ui_v13.0.png)
### Retention policy
### Annotation retention policy
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211433) in GitLab 13.01.
......@@ -139,99 +203,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**:
![Monitoring Dashboard actions menu with create new item](../../../user/project/integrations/img/actions_menu_create_new_dashboard_v13_2.png)
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
......
......@@ -53,7 +53,7 @@ Metric charts may also be hidden:
![Show Hide](../../user/project/integrations/img/hide_embedded_metrics_v12_10.png)
You can open the link directly into your browser for a
[detailed view of the data](dashboards/index.md#expand-panel).
[detailed view of the data](dashboards/index.md#chart-context-menu).
## Embedding metrics in issue templates
......
......@@ -41,8 +41,11 @@ navigation bar contains:
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.)
- **Edit dashboard** - 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.)
- **Create dashboard** **{file-addition-solid}** - Create a
[new custom dashboard for your project](dashboards/index.md#adding-a-new-dashboard-to-your-project).
[new custom dashboard for your project](dashboards/index.md#add-a-new-dashboard-to-your-project).
- **Metrics settings** **{settings}** - Configure the
[settings for this dashboard](dashboards/index.md#manage-the-metrics-dashboard-settings).
......
......@@ -105,11 +105,8 @@ in incidents and issue templates.
You can view more details about an embedded metrics panel from the context menu.
To access the context menu, click the **{ellipsis_v}** **More actions** dropdown box
above the upper right corner of the panel. The options are:
- [View logs](#view-logs-from-metrics-panel).
- **Download CSV** - Data from embedded charts can be
[downloaded as CSV](../../operations/metrics/dashboards/index.md#downloading-data-as-csv).
above the upper right corner of the panel. For a list of options, see
[Chart context menu](../../operations/metrics/dashboards/index.md#chart-context-menu).
#### View logs from metrics panel
......@@ -117,7 +114,7 @@ above the upper right corner of the panel. The options are:
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25455) to [GitLab Core](https://about.gitlab.com/pricing/) 12.9.
Viewing logs from a metrics panel can be useful if you're triaging an application
incident and need to [explore logs](../../operations/metrics/dashboards/index.md#view-logs-ultimate)
incident and need to [explore logs](../../operations/metrics/dashboards/index.md#chart-context-menu)
from across your application. These logs help you understand what is affecting
your application's performance and resolve any problems.
......
......@@ -121,7 +121,8 @@ one of them will be used:
[Prometheus manual configuration](#manual-configuration-of-prometheus)
and a [managed Prometheus on Kubernetes](#managed-prometheus-on-kubernetes),
the manual configuration takes precedence and is used to run queries from
[dashboards](../../../operations/metrics/dashboards/index.md#defining-custom-dashboards-per-project) and [custom metrics](../../../operations/metrics/index.md#adding-custom-metrics).
[custom dashboards](../../../operations/metrics/dashboards/index.md) and
[custom metrics](../../../operations/metrics/index.md#adding-custom-metrics).
- If you have managed Prometheus applications installed on Kubernetes clusters
at **different** levels (project, group, instance), the order of precedence is described in
[Cluster precedence](../../instance/clusters/index.md#cluster-precedence).
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment