GitLab

Data SourceENTERPRISE

GitLab backend data source plugin for Grafana
Enterprise

Enterprise plugins, along with support and assistance from the core team behind Grafana, are available with Grafana Enterprise.

Upgrade Now

    Grafana GitLab data source [beta]

    This is a beta release available for early adopters. You might encounter issues and breaking changes might be introduced prior to the 1.x release.

    Overview

    With this plugin, you can 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.

    For example, you can create an annotation for an event, such as a deployment. Next, you can correlate the annotation with another metric from GitLab or another source such as Prometheus. This could allow you to determine if your latest deployment caused a memory spike. Other annotations include events such as release publications, issue creation, or issue resolution.

    Set up your GitLab account

    1. Create a GitLab account.

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

      a. Go to your Personal Access Tokens.

      b. Fill in the Name and Expires at fields.

      c. From Scopes, select read_api.

      d. Click the Create personal access token button, and copy your personal access token.

    Set up the GitLab data source in Grafana

    1. From the browser, go to the home page of your Grafana instance.

    2. From the left-hand menu, go to Configuration > Data sources.

    3. Click the Add data source button.

    4. Search for GitLab and click the Select button.

    5. From the Settings tab, fill in the following fields:

      Field namesDescriptions
      NameThe data source name, which appears in panels and queries.
      URLThe root URL for your GitLab instance, for example https://gitlab.com/api/v4.
      Access tokenYour GitLab personal access token.

      If you set the data source as the default, it will be Grafana's default data source for panels and Explore mode.

    Querying GitLab

    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.

    Transformations to filter and aggregate raw data

    While there are many Transformations in Grafana to choose from, the following are especially relevant to create metrics from GitLab API data.

    Organize Fields This transformation provides a key feature that is not part of the standard GitLab API: show / hide fields. By using the Organize Fields transformation, you can select which fields you want to display and / or rename them.

    Group By This transformation provides a key feature that is not part of the standard GitLab API: grouping. Using the Group By transformation, you can group by date and aggregate by group to get metrics like commits per day.

    Filter Data By Values This transformation provides a key feature that is not part of this plugin yet: filter by values. Using the Filter Data By Values transformation, you can filter results by its attributes, like "only closed" issues.

    Add Field from Calculation Similar to SQL expressions, this transformation allows adding new fields to your dataset based on calculations of other fields. You can also chain together calculations and perform calculations from calculated fields.

    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.

    Template variables

    You can define variables on your dashboards and reference them in queries.

    For example, you can create a project dashboard and choose between projects.

    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.

    Annotations

    You can create annotations on your dashboards to see their relationship with other metrics.

    For example, you can create annotations based on release publication, deployment and issue creation or resolution.

    Example: Create an annotation for each release.

    1. Add an annotation named Releases from your GitLab data source.
    2. Select resource type: Releases, your project ID, display field: name and time field created_at.
    3. Click Update to add the annotations to the dashboard.
    4. A switch appears on your dashboard to hide / show release-based annotations.
    5. Now when creating Graph panels, you see an annotation for each release.

    Alerting

    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.

    Sign up Now

    Version

    Dependencies:
    • Grafana 7.x.x