Monitor application performance in Jira

Set up monitoring

Before you can connect your APM to Jira, you need to:

• configure a JMX exporter, and

• make sure that JMX and App metrics are enabled in your site. 

The instructions on this page assume you’ll be using Prometheus. You can use any Application Performance Monitoring (APM) solution, the steps will be very similar for each.

1. Configure the JMX Exporter

The exporter takes the JMX MBeans and transforms them into the right format for Prometheus. It also hosts a HTTP endpoint which Prometheus will connect to. Learn more about the Prometheus JMX exporter.

If you don't plan to use Prometheus, you'll need to check which exporter or agent is required for your APM solution. For example, this Java agent for NewRelic.

To install the exporter:

1. Download the Prometheus JMX exporter jar file from the GitHub repository.
   
   

   $ curl -L https://repo1.maven.org/maven2/io/prometheus/jmx/jmx_prometheus_javaagent/0.16.1/jmx_prometheus_javaagent-0.16.1.jar > jmx-exporter.jar

2. Create a configuration file for the exporter. You can download an example file from our repository. For more information on the configuration options see the README.md.

3. Copy the jar file and configuration file to each application node (the local home directory is a good option).

4. Stop Jira on one node.

5. Add the following system properties to tell Jira where to find the JMX exporter. See Setting properties and options on startup to check how to do this for your site.
   
   

   -javaagent:<full-path-to-jmx-exporter-jar>=<port>:<full-path-to-jmx-exporter-config.yml>

   The JMX exporter defaults to port 8080. You’ll need to specify a different port for the exporter if this port is in use by Jira or another application.
    

6. Start Jira.

7. To check that the exporter is working, go to localhost:<jmx-exporter-port>. You should see the metrics output.

Repeat these steps for all remaining nodes, if you run Jira in a cluster. You can perform a rolling restart to avoid any downtime.

You'll need to make sure the JMX exporter endpoint is not exposed outside your network, or that you've taken appropriate steps to secure it. 

2. Enable application monitoring in Jira

Application monitoring uses JMX (Java Management Extensions), so JMX monitoring must also be enabled. Both JMX and App monitoring are enabled by default, but may have been disabled by an administrator. 

To turn on application monitoring:

1. Go to  > System > Monitoring.

2. Check that JMX monitoring is enabled.

3. Check that Application monitoring is enabled.

If you have previously set up JMX monitoring for Jira, there’s nothing else you need to do. The additional application monitoring metrics will be exposed in the same way as existing application metrics. For the full list of things, you might want to monitor see Application metrics reference.

If you don’t have an existing Application Performance Monitoring (APM) solution, see our guide on getting started with Prometheus and Grafana.

JMX monitoring can have a performance impact on your site. In most cases it’s not significant. However if you do experience any problems with your instance performance or stability, you can disable both JMX and app monitoring.

Disable app monitoring

To disable app monitoring:

1. Go to  > Monitoring.

2. Disable App monitoring.

Once disabled, Jira will no longer emit app-specific metrics, or write them to logs. If you want to disable JMX altogether, you can also disable JMX monitoring. 

Identify the app name

App metrics include the plugin key rather that the app's display name. For example,  com.atlassian.troubleshooting.plugin-jira is the plugin key for the Troubleshooting and Support Tools system app for Jira. 

To find the app name:

1. Go to <base-url>/plugins/servlet/upm/osgi

2. Enter the plugin key in the Search bundled metadata field

3. The plugin details will be returned, including the name and vendor.

OSGi admin screen showing search results for a plugin key

You can also use the following REST endpoint /rest/plugins/1.0/<plugin-key>/summary which returns all the details about the app. 

Enable optional tags

App vendors can choose to include additional metadata which can help when troubleshooting a performance issues. These tags are not included by default.

You can use the atlassian.metrics.optional.tags system property to show additional tags for a metric. 

atlassian.metrics.optional.tags.<metric-name>=<tag-key1>,<tag-key2>

For example, if the full metric name is sampleApp.asset.loadtime and the app vendor included a tag to output additional information about the content type.

atlassian.metrics.optional.tags.sampleApp.asset.loadtime=sampleApp-type

The app vendor will be able to tell you the exact metric and tag names.

Troubleshooting

Out of memory errors

Because the monitoring is happening outside your application, we don’t expect there to be a significant impact on your instance performance or stability. If you do experience problems, you can disable JMX and app monitoring.

In the event of out of memory errors (OOME) caused by the monitoring agent, increase the JVM_MINIMUM_MEMORY(-xmx) in the setenv file. See Increasing Jira application memory

Application monitoring early access preview

If you participated in our early access program, you must remove the EAP monitoring agent and associated system properties before you upgrade, or Jira may fail to start or encounter problems.