Documentation Plugins Jira data source Query editor

Jira query editor

The Jira query editor allows you to build queries to retrieve and visualize issue data from your Jira instance. For general documentation on querying data sources in Grafana, refer to Query and transform data.

You must select at least one field before the query can run. In dashboards and panel edit, click Run query. In Explore, Grafana runs the query for you. In either place, press Cmd/Ctrl + Enter to run the query.

Query editor options

The following section describes the Jira-specific query editor options.

• Select Fields - Select one or more Jira issue fields to display, such as Summary, Sprint Name, and Story point estimate. Click the drop-down or anywhere in the field for a list of available options. Field names come from your Jira instance and can differ from the names in these docs.

• Limit - The maximum number of issues the plugin returns. The default is 50. The plugin paginates through Jira results until it reaches this count, the last page, or an empty page.

• Filter (JQL) - Enter a valid JQL query to filter issues. Press Cmd/Ctrl + Enter to run the query.

To filter by the dashboard time range, use the $__timeFrom and $__timeTo macros in JQL. For syntax and more examples, refer to Time range macros.

Grafana results vs Jira search

The same JQL can return a different row count or shape in Grafana than in Jira issue search:

• Limit defaults to 50. Raise it if you expect more issues. The plugin paginates until it reaches this count or the last page.
• Grafana returns only the fields you select. Jira issue search shows a default column set.
• Sprint isn’t a single column. The plugin lists Sprint Name, Sprint Start Date, Sprint End Date, and Sprint Complete Date (plugin 2.5.4 or later).
• Multi-value array fields expand one issue into multiple rows. Refer to Multi-value fields and extra rows.
• Time range macros insert a quoted yyyy-MM-dd HH:mm timestamp. Don’t add extra quotes around $__timeFrom or $__timeTo.

Filter and sort issues with JQL

The Jira data source uses Jira Query Language (JQL) to filter and sort issues. JQL uses field identifiers such as project, issuetype, assignee, status, and sprint. Those identifiers aren’t the same as the labels in Select Fields, which are display names from your Jira instance (for example, Sprint Name or Story point estimate).

The following example query finds all of Joe Smith’s issues in the TEST project:

jql Copy

project = TEST AND assignee = 'Joe Smith'

You can also sort results using the ORDER BY clause:

jql Copy

project = TEST AND status = 'In Progress' ORDER BY created DESC

For more information on JQL syntax, refer to:

• Use advanced search with Jira Query Language (JQL)
• Search Jira like a boss with JQL

Multi-value fields and extra rows

When you select an array field, the plugin creates one row per value. An issue with three owners, three components, or three labels appears three times if you include that field. That changes counts and joins.

To keep one row per issue:

1. Leave multi-value fields out of Select Fields when you only need a count or a unique issue list.
2. Or keep the field and add a Group by transformation on Key (or another unique field) after the query.

Use Ad hoc filters

The Jira data source supports Ad hoc filters dashboard variables, which let you add filters to a dashboard without editing each query. Grafana appends the selected filters to Jira queries on the dashboard using AND conditions.

To use Ad hoc filters:

1. Add an Ad hoc filters variable to your dashboard. For more information, refer to Add ad hoc filters.
2. Select the Jira data source for the variable.
3. Use the filter controls to select a field, operator, and value.

Jira Service Management fields

The plugin supports Jira Service Management (JSM) fields, including SLA metrics, approvals, and customer feedback. Field names vary by Jira instance. Check the Select Fields drop-down for the names in your environment.

SLA metrics

SLA fields (for example, Time to Resolution) are returned as JSON formatted as a string. Typical keys include ongoingCycle.breached, ongoingCycle.remainingTime.friendly, and completedCycles. Use the Extract fields transformation to parse the values you need. Refer to Extract fields for more information.

To show remaining SLA time for open requests:

1. Select Fields: Key, Time to Resolution (or the SLA field name in your instance)
2. Add JQL Filter: project = 'SERVICE' AND status != done
3. Add the Extract fields transformation:
   • Source: Time to Resolution
   • Format: JSON
   • Path: ongoingCycle.remainingTime.friendly
   • Alias: Remaining SLA
4. Select the Table visualization

Approvals

Approvals expand into the following sub-fields. Each appears in Select Fields as the approval field name plus the sub-field name:

• Name
• Final Decision
• Created Date
• Approvers

Customer feedback

Customer feedback fields expose a numeric rating. Feedback date fields are date and time values you can use in time series visualizations.

Organizations and request participants

Organization fields return a comma-separated list of organization names. Request participant fields return a comma-separated list of display names.

Create time series visualizations

To create time series visualizations from Jira data, select a date field along with a numeric field, then choose a time series visualization such as Time series, Bar chart, or Stat.

Common date fields include:

• Created - When the issue was created
• Updated - When the issue was last updated
• Resolution Date - When the issue was resolved
• Sprint Start Date - When the sprint started
• Sprint End Date - When the sprint ended
• Sprint Complete Date - When the sprint was completed

Common numeric fields include:

• Story point estimate - Estimated story points
• Time Spent - Time logged on the issue
• Original Estimate - Original time estimate

To aggregate data over time, use the Group By transformation. For example, to visualize story points completed per sprint:

1. Select Fields: Sprint Start Date, Story point estimate
2. Add JQL Filter: project = 'Your Project' AND status = done
3. Add the Group By transformation:
   • Sprint Start Date | Group By
   • Story point estimate | Calculate | Total
4. Select the Time series or Bar chart visualization

Work with transformations

Grafana transformations extend JQL capabilities by allowing you to manipulate, calculate, and reshape your data. For more information on transformations, refer to Transform data.

The following transformations are particularly useful when working with Jira data:

Add field from calculation

Use this transformation to add calculated columns from other fields. You can chain calculations and use calculated fields as inputs. Refer to Add field from calculation for more information.

Extract fields

Some Jira fields are returned as JSON formatted as a string. Use this transformation to parse JSON fields and extract specific values using JSON path notation. Refer to Extract fields for more information.

Group by

This transformation provides grouping capabilities not available in JQL. Use it to group by sprints or other fields and aggregate metrics like velocity or story point completion rates. Refer to Group by for more information.

Outer join

This transformation combines two or more queries on a shared field. Use it to correlate data across queries. Refer to Outer join for more information.

Work with linked issues

The Linked Issues field returns JSON as a string. Because Jira returns linked issues in different paths (for example, “blocks” or “is blocked by”), you need to use transformations to extract and display the data.

To display linked issues:

1. Add a query:
   • Select Fields: Key, Linked Issues
   • Add JQL Filter: project = 'YOUR_PROJECT'
2. Duplicate the query (you now have Query A and Query B).
3. Add the Extract fields transformation:
   • Source: Linked Issues
   • Format: JSON
   • Path: inwardIssue.key
   • Alias: Linked issue key
   • Apply transformation filter to Query A only
4. Add another Extract fields transformation:
   • Use the same settings but with path outwardIssue.key
   • Apply transformation filter to Query B only
5. Add the Filter data by value transformation:
   • Filter type: Include
   • Conditions: Match any
   • Condition 1: Field = Linked Issues, Match = Is equal, Value = (empty)
   • Condition 2: Field = Linked Issues, Match = Regex, Value = inwardIssue
   • Apply transformation filter to Query A only
6. Add another Filter data by value transformation:
   • Use the same settings but with Regex value outwardIssue
   • Apply transformation filter to Query B only
7. Add the Merge transformation.
8. Add the Organize fields transformation:
   • Hide the Linked Issues field containing raw JSON

Examples

The following examples demonstrate common use cases for the Jira data source.

List issues in a table

1. Select Fields: Key, Summary, Status, Assignee
2. Add JQL Filter: project = 'Your Project' AND status != done ORDER BY priority DESC
3. Select the Table visualization

Filter issues by the dashboard time range

1. Select Fields: Key, Summary, Created
2. Add JQL Filter: project = 'Your Project' AND created >= $__timeFrom AND created <= $__timeTo
3. Select the Table visualization

The plugin replaces $__timeFrom and $__timeTo with the dashboard time range. For more macro examples, refer to Time range macros.

Show issues in the current sprint

1. Select Fields: Key, Summary, Status, Sprint Name
2. Add JQL Filter: project = 'Your Project' AND sprint in openSprints() AND type != epic
3. Select the Table visualization

Show velocity per sprint

1. Select Fields: Sprint Name, Story point estimate
2. Add JQL Filter: project = 'Your Project' AND type != epic AND status = done ORDER BY created ASC
3. Add the Group By transformation:
   • Sprint Name | Group By
   • Story point estimate | Calculate | Total
4. Select the Bar gauge visualization

Compare completed vs. estimated story points

1. Add Query A:
   • Select Fields: Sprint Name, Sprint Start Date, Story point estimate
   • Add JQL Filter: project = 'Your Project' AND type != epic
2. Add Query B:
   • Select Fields: Sprint Name, Sprint Start Date, Story point estimate
   • Add JQL Filter: project = 'Your Project' AND type != epic AND status = done
3. Add the Group By transformation:
   • Sprint Name | Group By
   • Sprint Start Date | Group By
   • Story point estimate | Calculate | Total
4. Select the Time series visualization

Calculate average time to complete issues

1. Add a query:
   • Select Fields: Created, Status Category Changed
   • Add JQL Filter: project = 'Your Project' AND type != epic AND status = done
2. Add the Add field from calculation transformation:
   • Mode: Reduce Row
   • Calculation: Difference
3. Add another Add field from calculation transformation:
   • Mode: Binary Operation
   • Operation: Difference / 86400000 (milliseconds per day: 1000 × 3600 × 24)
   • Alias: Days
4. Add the Organize fields transformation:
   • Hide the Difference field
5. Add the Filter data by value transformation:
   • Filter Type: Include
   • Conditions: Match any
   • Condition: Field = Days, Match = Is Greater, Value = 1
6. Add the Reduce transformation:
   • Mode: Series to Rows
   • Calculations: Mean
7. Select the Stat visualization

Show issues by status

1. Select Fields: Status, Key
2. Add JQL Filter: project = 'Your Project'
3. Add the Group By transformation:
   • Status | Group By
   • Key | Calculate | Count
4. Select the Pie chart visualization

Show issues per assignee

1. Select Fields: Assignee, Key
2. Add JQL Filter: project = 'Your Project' AND status != done
3. Add the Group By transformation:
   • Assignee | Group By
   • Key | Calculate | Count
4. Select the Bar gauge visualization