Jira data source with Grafana
Get the whole picture of your development process by combining issue data from Jira with application performance data from other sources.
- Create annotations based on issue creation or resolution, to see the relationship between issues and metrics
- Track detailed Jira stats, like mean time to resolution and issue throughput
The following instructions assume that you’re configuring the Jira data source on-premises. To view a video on Cloud configuration, see visualizing Jira with Grafana Cloud.
Requirements
This plugin has the following requirements:
- An Atlassian account with access to a Jira project
- One of the following account types:
- Available for users with a Grafana Cloud Free, Advanced or Trial account or with an activated Grafana Enterprise license.
Known limitations
Custom field types from Jira addons might not be supported.
Install the Jira data source plugin
To install the data source, refer to Installation
Configure Jira with your Atlassian API key
Follow these instructions to create an API Token: Atlassian manage API tokens
Configure the data source
Follow these instructions to add a new Jira data source, and choose from three datasource configuration options:
Fields | Descriptions |
---|---|
Name | Enter a name for this particular Jira data source. |
Provider | Select Jira Cloud if your Jira is being hosted on Atlassian Cloud. Select Jira Data Center / Jira Server if your Jira is being hosted elsewhere. |
URL | Enter a root URL for your Atlassian instance, for example https://bletchleypark.atlassian.net |
User | Enter an email address for the user/service account, for example joan.clarke@bletchleypark.com |
API Token | Enter an API token generated for the user. You can create on here. |
Configure the data source with provisioning
Data sources can be configured 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: Jira
type: grafana-jira-datasource
access: proxy
basicAuth: false
editable: true
enabled: true
jsonData:
url: root URL of Atlassian instance
user: email address for user
hosting: server OR cloud
secureJsonData:
token: API token
Query the data source
From the Jira Query Editor you can select fields and query issues.
Filter and view issues
The Jira data source queries Jira for issues, which can represent bugs, user stories, support tickets, or other tasks in Jira. First select a field that you wish to view and then use JQL to filter and/or sort your issues.
- Select Fields
Click the dropdown and use type-ahead to select from any of the fields in your Jira instance, including custom fields. Some fields to try:
Summary
: the name of the issueEpic Name
: the Epic that an issue belongs toStory Point Estimate
: The number of Story Points the team has estimated for an issue
- Filter and/or Sort Issues
Enter any valid JQL expression to filter and/or sort your issues based on any of their fields like Project, Assignee, or Sprint with the Atlassian query language JQL. For more information, refer to Search Jira like a boss with JQL.
From here, you can display your data in a table or use Grafana transformations to manipulate that issue data, run calculations, or turn the data into a time series graph. For more information, refer to Apply Transformations
Time series query
To show time series data, choose a Date field along with a numeric field, then switch to graph visualization.
For example: Sprint Start Date, Story point estimate
The above example, on its own, is not very useful. The numeric field can be (and will most likely be) calculated from Transformations.
Using the Group By Transformation would allow grouping by Sprint Start Date and summarizing the Story point estimate allowing a visualization of Story Points over time per Sprint. Learn more about transformations here
Templates and variables
To add a new Jira query variable, refer to Add a query variable. Use your Jira data source as your data source
You can define variables on your dashboards and reference them in JQL expressions.
For example, you can create a project status dashboard and choose between projects, or an epic status dashboard and choose different epics, or a task status dashboard and choose different assignees.
To get a dynamic list of Projects, Epics, Assignees, etc to choose from, create a Query type variable. Query type variables use JQL to query issues and return Projects, Epics, Assignees or anything related to issues.
Example: Create an Assignee variable to get the status of issues by Assignee.
- Add a variable of type Query called assignee
- Select Field: Assignee
- Add JQL Filter (optional):
project = 'your project'
. - Click the Run button to see the list of Assignees at the bottom.
- Click Update to add the variable to the Dashboard.
- Add drop down appears on your dashboard with a list of assignees.
- Add a panel to the Dashboard, and edit the JQL to filter using your new variable
assignee = $assignee
. - Now when choosing from the drop down, you only see issues assigned to that user.
Multi-value variables allow selecting multiple options and can be used as part of the IN clause.
assignee IN ($assignee)
After creating a variable it can be used in your Jira queries by using this syntax.
For more information on variables to refer this.
Import a dashboard for Jira
Follow these instructions for importing a dashboard.
Imported dashboards can be found in Configuration > Data Sources > select your Jira data source > select the Dashboards tab to see available pre-made dashboards.
Macros
Macros are variables that reference the Dashboard time window so you can filter issues only within the range of the Dashboard window.
There are 2 macros: $__timeFrom and $__timeTo.
Example: JQL to filter issues created within the Dashboard time window.
createdDate >= $__from AND createdDate <= $__to
Get the most out of the plugin
Utilizing Grafana’s transformations and other built in features can help you meaningly view your Jira data.
Transformations to augment JQL
While there are many Transformations in Grafana to choose from, the following provide a powerful augmentation to give JQL some of the features/power of SQL. For more information on types of transformations refer this.
Group By This transformation provides a key feature that is not part of the standard Jira JQL syntax: Grouping. Using the Group By transformation, you can group by Sprints or other Issue fields, and aggregate by group to get metrics like velocity and story point estimates vs actual completed in a Sprint.
Outer Join Similar to SQL joins, you can join 2 or more queries together by common fields. This provides a way to combine datasets from queries and use other transformations to calculate values from multiple queries/datasets.
Add Field from Calculation Similar to SQL expressions, this transformation allows adding new fields to your dataset based on calculations of other fields. The fields used in the calculation can be from a single query or from queries you’ve joined together. You can also chain together calculations and perform calculations from calculated fields.
Extract fields As some fields are returned in stringified JSON format, this transformation allows to parse those JSON fields and create new fields by providing JSON path to the data you need.
Providing path is available in Grafana v9.4+. On earlier versions Extract fields is in Alpha.
You can also find the example of working with JSON data in the “Jira JSON fields demo” dashboard that you can import from the datasource page (requires Grafana v9.4+).
Using Transformations from Grafana to answer common questions
Now that you can perform basic Jira queries to find Issues, 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.
Question: How do I show Velocity per Sprint?
- Select Fields: Sprint Name, Story point estimate
- Add JQL Filter
project = "Your Project" AND type != epic AND status = done order by created ASC
- Add Group By Transformation
- Sprint Name | Group By
- Story Point Estimate | Calculate | Total
- Select the Bar Gauge Visualization
Question: How do I show what was Completed vs Estimated in a Sprint?
- Add a Query
- Select Fields: Sprint Name, Sprint Start Date, Story point estimate
- Add JQL Filter:
project = 'Your Project' AND type != epic
- Add a second Query
- Select Fields: Sprint Name, Sprint Start Date, Story point estimate
- Add JQL Filter:
project = 'Your Project' AND type != epic AND status = done
- Add Group By Transformation
- Sprint Name | Group By
- Sprint Start Date | Group By
- Story point estimate | Calculate | Total
- Select Graph visualization
Question: What is the Average time to complete issues in my project?
- Add a Query
- Select Fields: Created, Status Category Changed
- Add JQL Filter:
project = 'Your Project' AND type != epic AND status = done
- Add Transformation: Add field from calculation
- Mode = Reduce Row
- Calculation = Difference
- Add Transformation: Add field from calculation
- Mode = Binary Operation
- Operation = Difference / 86000000 (1000 * 3600 * 24 to get days
- Alias = Days
- Add Transformation: Organize fields
- Hide Difference field
- Add Transformation: Filter data by values
- Filter Type = Include
- Conditions = Match any
- Field = Days | Match = Is Greater | Value = 1
- Add Transformation: Reduce
- Mode = Series to Rows
- Calculations = mean
- Select Visualization: Stat
Question: How do I show linked issues for the issues I queried?
“Linked issues” field is returned as a stringified JSON. You will need to apply Extract fields transformation to get the data you need. Also, since Jira returns linked issues in 2 different paths (depending on the issue relation, e.g. “blocks” or “is blocked by”), you will need to duplicate the query to handle each of the paths separately and then merge 2 results into single table.
You can find this example in the “Jira JSON fields demo” dashboard that you can import from the datasource page.
- Add a Query
- Select Fields: Key, Linked Issues
- Add JQL Filter:
project = 'YOUR_PROJECT'
- Add the same query as above one more time
- Add transformation Extract fields
- Source = Linked issues
- Format = JSON
- Add path
- Field =
inwardIssue.key
- Alias = Linked issue key
- Field =
- Add transformation filter so that transformation only applies to query A
- Add another transformation Extract fields
- Repeat everything from step 3, but use path
outwardIssue.key
and apply transformation to query B.
- Repeat everything from step 3, but use path
- Add transformation Filter data by values
- Filter type = Include
- Conditions = Match any
- Add condition:
- Field = Linked issues
- Match = Is equal
- Value = Leave the field empty
- Add another condition:
- Field = Linked issues
- Match = Regex
- Value =
inwardIssue
- Add transformation filter so that transformation only applies to query A
- Add another transformation Filter data by values
- Repeat everything from step 5, but use
outwardIssue
in the condition and apply transformation to query B.
- Repeat everything from step 5, but use
- Add transformation Merge
- Add transformation Organize fields
- Hide field “Linked issues” with JSON data
- As Merge transformation might have had an impact on the field names, rename other fields if necessary
Additional links
Related resources from Grafana Labs


