Menu

Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

GitLab data source for Grafana
Enterprise

GitLab data source for Grafana

The GitLab data source plugin allows you to keep track of detailed GitLab statistics, such as top contributors, commits per day, or deployments per day. You can also use template variables, such as projects, to set up filters for your dashboards. You can combine data from the GitLab API with data from other sources.

Requirements

This plugin has the following requirements:

  • A GitLab account
  • One of the following account types:
    • Grafana Cloud: Pro customers, Advanced customers, or Pro trial users with the Enterprise plugin add-on enabled
    • Grafana Enterprise: Customers with an activated license and a user with Grafana server or organization administration permissions
  • The Enterprise plugin add-on enabled

Known limitations

Alerting is not supported yet on this plugin because transformations are not supported in alert queries and transformations is the only way to obtain meaningful aggregate metrics from GitLab API raw data.

Install the GitLab data source plugin

To install the data source, refer to Installation

Configure GitLab

Create a personal access token with permissions for the read_api scope:

  1. Go to your Personal Access Tokens.
  2. Fill in the Name and Expires at fields.
  3. From Scopes, select read_api.
  4. Click the Create personal access token button, and copy your personal access token.

Configure the data source in Grafana

Add a data source by filling in the following fields:

Name
A name for this particular GitLab data source
URL
The root URL for your GitLab instance, e.g. https://gitlab.com/api/v4.
Access token
our GitLab personal access token.

Configure the data source with provisioning

It is possible to configure data sources using config files with Grafana’s provisioning system. You can read more about how it works and all the settings you can set for data sources on the provisioning docs page

YAML
apiVersion: 1

datasources:
  - name: GitLab
    type: grafana-gitlab-datasource
    access: proxy
    basicAuth: false
    editable: true
    enabled: true
    secureJsonData:
      accessToken: Access token
    url: https://gitlab.com
    version: 1

Query the data source

From the GitLab Query Editor you can select different resource types (commits, issues, releases, etc).

Filter and view projects

The GitLab data source allows you to query for projects.

  1. From the dropdown menu select the Projects resource type.
  2. (Optional) Filter by the projects that you own

Use the dropdown and select Yes or No to filter the results.

NOTE: Consider that fetching all the projects (Owned = No) may take long time.

Filter and view commits

The GitLab data source allows you to query for commits authored on a specific project.

  1. Select the resource type:

    Use the dropdown and select the Commits resource type.

  2. Add the project ID:

    Use the input field to add the project ID.

  3. (Optional) Filter by branch/tag.

    Use the input field to add a branch/tag reference.

Filter and view issues

The GitLab data source allows you to query for issues from a specific project.

  1. Select the resource type:

    Use the dropdown and select the Issues resource type.

  2. Add the project ID:

    Use the input field to add the project ID.

  3. (Optional) Filter by title/description:

    Use the input field to search issues against their title and description.

View releases

The GitLab data source allows you to query for releases from a specific project.

  1. Select the resource type:

    Use the dropdown and select the Releases resource type.

  2. Add the project ID:

    Use the input field to add the project ID.

Filter and view deployments

The GitLab data source allows you to query for deployments from a specific project.

  1. Select the resource type:

    Use the dropdown and select the Deployments resource type.

  2. Add the project ID:

    Use the input field to add the project ID:

  3. (Optional) Filter by environment/status

    Use the input fields to filter by environment and/or status.

    The status attribute can be one of the following values: created,running,success,failed, and canceled.

View labels

The GitLab data source allows you to query for labels from a specific project.

  1. Select the resource type:

    Use the dropdown and select the Labels resource type.

  2. Add the project ID:

    Use the input field to add the project ID.

Templates and variables

To add a new GitLab query variable, refer to Add a query variable. Use your GitLab data source as your data source. Choose a resource type: Releases, Projects, or Labels.

To get a dynamic list of Projects, Labels, etc to choose from, create a Query type variable.
Query type variables use the GitLab Query Editor to query and return Projects, Labels, etc.

Example: Create a Project variable to parameterize your queries.

  1. Add a variable of type Query named project
  2. Select your GitLab data source and refresh On Dashboard Load.
  3. Select resource type: Projects, owned: Yes, display field: name and value field id.
  4. Click Update to add the variable to the dashboard.
  5. A dropdown appears on your dashboard with a list of projects.
  6. Add a new panel to the dashboard and use $project as the project ID.
  7. Now when choosing from the dropdown, you get the results that belong to that project.

After creating a variable, you can use it in your GitLab queries by using Variable syntax. For more information about variables, refer to Templates and variables.

Get the most out of the plugin

Using Transformations from Grafana to answer common questions

Now that you can perform basic GitLab queries to find commits, issues, etc, you can use Transformations to visualize, aggregate, group, and join datasets, along with many other types of transformations to transform simple results into answers for complex questions. Below are a few common questions and how to use transformations to answer them.

Question: How many commits / issues / deployments per day in my project?

  1. Add a query:

    a. Select resource type: Commits.

    b. Add the project ID.

  2. Add a new Group by transformation:

    a. Group by = created_at_date.

    b. Calculate (Count) = id.

  3. Select the Graph visualization.

Question: What is the average time to close issues in my project?

  1. Add a query:

    a. Select resource type: Issues.

    b. Add the project ID.

  2. Add a new Add field from calculation transformation:

    a. Mode = Binary Operation.

    b. Operation = closed_at - created_at.

    c. Alias = resolution_time.

  3. Add a new Add field from calculation transformation:

    a. Mode = Binary Operation.

    b. Operation = resolution_time / 86400000 (1000 * 3600 * 24) …to get days.

    c. Alias = resolution_time.

    d. Replace all fields = True.

  4. Select the Stat visualization:

    a. Show = Calculate.

    b. Calculation = Mean.

    c. Fields = resolution_time.