Configure Grafana

Version history
  • Grafana bundled with GitLab was deprecated in GitLab 16.0.
  • Grafana bundled with GitLab was removed in GitLab 16.3.

Grafana is a tool that enables you to visualize time series metrics through graphs and dashboards. GitLab writes performance data to Prometheus, and Grafana allows you to query the data to display graphs.

caution
Grafana bundled with GitLab was deprecated GitLab 16.0 and removed in GitLab 16.3. For more information, see deprecation notes.

Import GitLab dashboards

You can import a set of default dashboards to start displaying information. GitLab has published a set of default Grafana dashboards to get you started. To use them:

  1. Clone the repository, or download a ZIP file or tarball.
  2. Follow these steps to import each dashboard JSON file individually

Alternatively, you can import all the dashboards into your Grafana instance. For more information about this process, see the GitLab Grafana dashboards.

Integrate with GitLab UI

Introduced in GitLab 12.1.

After setting up Grafana, you can enable a link to access it from the GitLab sidebar:

  1. On the left sidebar, select Search or go to.
  2. Select Admin Area.
  3. On the left sidebar, select Settings > Metrics and profiling and expand Metrics - Grafana.
  4. Select the Add a link to Grafana checkbox.
  5. Configure the Grafana URL. Enter the full URL of the Grafana instance.
  6. Select Save changes.

GitLab displays your link in the Admin Area under Monitoring > Metrics Dashboard.

Required Scopes

Introduced in GitLab 13.10.

When setting up Grafana through the process above, no scope shows in the screen in the Admin Area under Applications > GitLab Grafana. However, the read_user scope is required and is provided to the application automatically. Setting any scope other than read_user without also including read_user leads to this error when you try to sign in using GitLab as the OAuth provider:

The requested scope is invalid, unknown, or malformed.

If you see this error, make sure that one of the following is true in the GitLab Grafana configuration screen:

  • No scopes appear.
  • The read_user scope is included.

Deprecation of bundled Grafana

Bundled Grafana was an optional service for Linux package installations that provided a user interface to GitLab metrics.

The version of Grafana that is bundled with Linux package installations is no longer supported. If you’re using the bundled Grafana, you should switch to a newer version from Grafana Labs.

Switch to new Grafana instance

To switch away from bundled Grafana to a newer version of Grafana from Grafana Labs:

  1. Set up a version of Grafana from Grafana Labs.
  2. Export the existing dashboards from bundled Grafana.
  3. Import the existing dashboards in the new Grafana instance.
  4. Configure GitLab to use the new Grafana instance.