Plugins 〉Jira
Jira
Grafana Jira Data Source
Overview
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
Connecting to Jira
Prerequisites
In order to use the plugin, you need an Atlassian account with access to a Jira project.
Configuration
Name | Description |
---|---|
Name | The data source name; this is how you refer to the data source in panels and queries |
Default | When toggled on, this will become Grafana's default data source for panels and Explore mode |
URL | The root URL for your Atlassian instance, for example https://bletchleypark.atlassian.net |
User | The email address for the user/service account for example joan.clarke@bletchleypark.com |
API Token | An API token generated for the user |
Follow these instructions to create an API Token: https://confluence.atlassian.com/cloud/api-tokens-938839638.html
- Log in to https://id.atlassian.com/manage/api-tokens.
- Click Create API token.
- From the dialog that appears, enter a memorable and concise Label for your token and click Create.
- Click Copy to clipboard, then paste the token to your script, or elsewhere to save:
Querying Jira
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. Using the query editor, you can choose the issue fields you'd like to display in Grafana (like Summary, Epic Name, and Created Date/Time), filter issues based on any of their fields like Project, Assignee, or Sprint with the Atlassian query language JQL. From there, 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.
Step 1. 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
Step 2. Filter and/or Sort Issues
Enter any valid JQL expression to filter or sort your issues.
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.
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.
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. Below are a few common questions and how to use transformations to answer them.
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
Template Variables
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)
Ad Hoc Filters
Ad Hoc filters are global filters. When added to your Dashboard, the values selected are automatically applied as filters to the JQL on all of the panels on our dashboard.
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 Dasbboard time window.
createdDate >= $__timeFrom AND createdDate <= $__timeTo
Time Series
To show time series data, choose a Date field along with a numeric field, then switch to the 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.
Alerting
Alerting allows you to set up notifications based on thresholds you define. For example, you may want to receive a notification if a Project is not on track or past due, or if Sprint estimates are outside the average velocity, or a change was made that will impact a team's ability to deliver on time.
Enterprise plugins, along with support and assistance from the core team behind Grafana, are available with Grafana Enterprise.
Installing Jira on Grafana Cloud:
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
For more information, visit the docs on plugin installation.
Installing on a local Grafana:
For local instances, plugins are installed and updated via a simple CLI command. Plugins are not updated automatically, however you will be notified when updates are available right within your Grafana.
1. Install the Data Source
Use the grafana-cli tool to install Jira from the commandline:
grafana-cli plugins install
The plugin will be installed into your grafana plugins directory; the default is /var/lib/grafana/plugins. More information on the cli tool.
Alternatively, you can manually download the .zip file for your architecture below and unpack it into your grafana plugins directory.
Alternatively, you can manually download the .zip file and unpack it into your grafana plugins directory.
2. Configure the Data Source
Accessed from the Grafana main menu, newly installed data sources can be added immediately within the Data Sources section.
Next, click the Add data source button in the upper right. The data source will be available for selection in the Type select box.
To see a list of installed data sources, click the Plugins item in the main menu. Both core data sources and installed data sources will appear.
Change Log
Entries
[1.0.1] 2021-4-7
- Update grafana-enterprise-sdk
[1.0.0] 2021-3-32
- Official plugin release
[0.9.7] 2021-3-11
- Query type is now being set when selecting the Jira data source
[0.9.6] 2021-2-26
- Feature: Add Jira Server support
- Feature: Add Limit setting for Issues query
[0.9.5] 2021-1-15
- <nil> and [] are no longer displayed when there is no data to display in a field
- Fields that do not have a converter no longer show up in list of selectable fields
- Added tooltips
- User Display Name will not just be User Name
- Added support for more fields
- Status
- Labels
- Components
- Resolution
- Priority
- Due Date
- Votes
- User (not in arrays)
- Version
- Parent
- Sub Tasks
- All options fields
- Any
- FixVersions
- AffectsVersions
- Rank
- Epic Link
- Epic Status
[0.9.4] 2021-1-11
- Added supported Jira types
- Any
- Approval
- Array
- Date
- Feed Back
- Number
- Option
- Project
- Sprint
- String
- User
- Added support for expanding Jira types so they can be selected in the field selector, for example Sprint object becomes Sprint Name, Sprint Start Date and so on
[0.9.0] 2021-1-6
- Beta release