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
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:
- Go to your Personal Access Tokens.
- Fill in the Name and Expires at fields.
- From Scopes, select read_api.
- 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
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.
- From the dropdown menu select the Projects resource type.
- (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.
Select the resource type:
Use the dropdown and select the
Commits
resource type.Add the project ID:
Use the input field to add the project ID.
(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.
Select the resource type:
Use the dropdown and select the
Issues
resource type.Add the project ID:
Use the input field to add the project ID.
(Optional) Filter by title/description:
Use the input field to search issues against their
title
anddescription
.
View releases
The GitLab data source allows you to query for releases from a specific project.
Select the resource type:
Use the dropdown and select the
Releases
resource type.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.
Select the resource type:
Use the dropdown and select the
Deployments
resource type.Add the project ID:
Use the input field to add the project ID:
(Optional) Filter by environment/status
Use the input fields to filter by
environment
and/orstatus
.The status attribute can be one of the following values:
created
,running
,success
,failed
, andcanceled
.
View labels
The GitLab data source allows you to query for labels from a specific project.
Select the resource type:
Use the dropdown and select the
Labels
resource type.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.
- Add a variable of type Query named project
- Select your GitLab data source and refresh
On Dashboard Load
. - Select resource type:
Projects
, owned:Yes
, display field:name
and value fieldid
. - Click Update to add the variable to the dashboard.
- A dropdown appears on your dashboard with a list of projects.
- Add a new panel to the dashboard and use
$project
as the project ID. - 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
- Add Annotations.
- Configure and use Templates and variables.
- Add Transformations.
- Set up alerting; refer to Alerts overview.
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?
Add a query:
a. Select resource type: Commits.
b. Add the project ID.
Add a new Group by transformation:
a. Group by =
created_at_date
.b. Calculate (
Count
) =id
.Select the Graph visualization.
Question: What is the average time to close issues in my project?
Add a query:
a. Select resource type: Issues.
b. Add the project ID.
Add a new Add field from calculation transformation:
a. Mode = Binary Operation.
b. Operation =
closed_at
-created_at
.c. Alias =
resolution_time
.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.
Select the Stat visualization:
a. Show = Calculate.
b. Calculation = Mean.
c. Fields =
resolution_time
.