What is it?

In a nutshell, it’s a way to pull useful metrics out of Jira™¹.

Jira collects and maintains all kinds of useful data about your workflow. Unfortunately it does a horrible job of exposing that in any meaningful way. This project addresses that gap by giving you a way to pull that data out of Jira and either generating a HTML report or giving you the raw data in the form of CSV files.

If you just want to see something working fast, without wading through a lot of documentation on configuration, jump to the QuickStart and come back to the rest later.

JiraMetrics is an open source project, released under an Apache License. In a nutshell, that means that you can use it for free; see the license for more specifics around that. We do offer paid support for those who wish it.

JiraMetrics is a standalone tool that can connect to any Jira instance that you have. It is not a plugin that needs to be configured by an administrator. If you can access Jira through a web browser, then you can configure this tool to also get reports from that instance.

For a primer on the basic flow metrics then see this course by Mike Bowler, the primary author of JiraMetrics. While the course isn't specific to JiraMetrics, it is directly relevant to anyone using it.

How do I make it work?

At a high level, there are four steps, and we’ll walk through each.

1. Install JiraMetrics
2. Configure it to talk to your Jira instance(s).
3. Configure what kind of output you want and options you want to use. This is all in a single configuration file, which is described here.
   • HTML report using standard_project. Significantly easier to get set up but more limited in customization, as it makes a lot of assumptions about how you want things.
   • HTML report with full configuration. Highly customizable, but that means that you need to spend more time customizing it.
   • CSV files, suitable for import into other tools.
4. Run the tool and look at the output in the target directory.
   • See command line options

Other things you might want to know

• At the top of every report is a data quality section. Here’s more information on that.
• We release new versions fairly frequently. The full changelog can be found here and you can upgrade to the latest with gem update jirametrics
• Getting errors or weird behaviour when running the tool? Check out the Frequently Asked Questions
• If you find a bug or have an idea for a feature, report it here
• If you want to contribute then check out the contribution page
• Our security folks have concerns about people pulling potentially confidential information. What can I tell them?
• How do I get started with probabilistic forecasting?

Presentation: Getting Great Metrics out of Jira

This talk walks through the kinds of metrics you can pull with JiraMetrics and walks through many of the charts. The talk was given in November 2024 to the KanbanTO group, and shows off JiraMetrics v2.7.3

---

Configuration Index

There are a lot of configuration items that can be set. Here’s an index to get you to the ones you want, quickly.

• Exporter.configure
  • target_path
  • jira_config
  • timezone_offset

  • holiday_dates

  • project
    • file_prefix
    • download
    • board
      • cycletime
    • file (when exporting data in CSV)
      • file_suffix
      • only_use_row_if
      • columns
        • write_headers
        • column_entry_times
        • Type specific values
        • Accessing custom fields
    • file (when creating an HTML report)
      • file_suffix
      • discard_changes_before
      • html_report
        • board_id
        • All Charts
          • cycletime_scatterplot
          • cycletime_histogram
          • throughput_chart
          • aging_work_in_progress_chart
          • daily_wip_by_age_chart
          • daily_wip_by_blocked_stalled_chart
          • daily_wip_by_parent_chart
          • daily_wip_chart
          • daily_view
          • expedited_chart
          • sprint_burndown
          • estimate_accuracy_chart
          • dependency_chart
            • issue_rules
            • link_rules
    • status_category_mapping
    • anonymize
    • standard_project
    • aggregated_project
    • Project specific settings

---

So now we’ve got data. What’s next?

We’re always collecting data because we want to make decisions based on what’s there. If we don’t want to make decisions then any data collection is frankly a waste of time.

What decisions might we want to make?

• Perhaps we want to know how long it will take to get one or more items finished, and we could use probabilistic forecasting for that.
• Perhaps we’re setting up a Service Level Agreement (SLA) or Service Level Expectation (SLE), and need to understand the current baseline so that we can set expectations accordingly.
• Perhaps we’re trying to get a sense of how focused the team is on delivering value, rather than just being busy. While flow metrics don’t directly show use value delivered, there are many hints that we can get from this to indicate if we’re on track. If the WIP is too high then we’re distracted. If there is significant blocked or stalled work then we’re not delivering.
• Perhaps we’re looking for general improvement, and are looking for both a baseline and also a way to see how those metrics change over time. This is great information to feed into a retrospective.

Mike also has a course on improving your retrospectives, and all the information you get from JiraMetrics is great input for those. Then within the retrospective, you decide how satisfied you are with the existing system and devise some experiments to improve. Subsequently you use JiraMetrics again to measure any improvements to that system..

1. Jira is a registered trademark of Atlassian Corporation Plc ↩