Live monitoring using the JMX interface

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

This article describes how to expose JMX MBeans within Jira for monitoring with a JMX client.

This guide provides a basic introduction to the JMX interface and is provided as is. Our support team can help you troubleshoot a specific Jira problem, but aren't able to help you set up your monitoring system or interpret the results.

What is JMX?

JMX (Java Management Extensions) is a technology for monitoring and managing Java applications. JMX uses objects called MBeans (Managed Beans) to expose data and resources from your application. For large instances of Jira Server or Jira Data Center, enabling JMX allows you to more easily monitor the consumption of application resources and diagnose performance issues related to indexing. This enables you to make better decisions about how to maintain and optimize machine resources. 

Details of the JMX metrics available in Jira

JMX attribute name

Description

50thPercentile

The value at the 50th percentile in the distribution of measured times (the median value).

75thPercentile

The value at the 75th percentile in the distribution of measured times.

95thPercentile

The value at the 95th percentile in the distribution of measured times.

98thPercentile

The value at the 98th percentile in the distribution of measured times.

99thPercentile

The value at the 99th percentile in the distribution of measured times.

999thPercentile

The value at the 99.9th percentile in the distribution of measured times.

Count

The number of invocations since node startup.

DurationUnit

The time unit used to report percentile values, min, max, mean and standard deviation. The default is milliseconds.

FifteenMinuteRate

The fifteen-minute moving average rate of invocations since node startup. This rate uses the same exponential decay factor as is used for the fifteen-minute load average in Unix’s top command.

FiveMinuteRate

The five-minute moving average rate of invocations since node startup. This rate uses the same exponential decay factor as is used for the five-minute load average in Unix’s top command.

Max

The highest measured time since node startup.

Mean

The mean measured time since node startup.

MeanRate

The mean rate of invocations since node startup.

Min

The lowest measured time since node startup.

OneMinuteRate

The one-minute moving average rate of invocations since node startup. This rate uses the same exponential decay factor as is used for the one-minute load average in Unix’s top command.

RateUnit

The unit in which MeanRate, OneMinuteRate, FiveMinuteRate, and FifteenMinuteRate are reported. The default is events/second.

StdDev

The standard deviation in the measured times since node startup.

Metrics collected by Jira

The following table lists metrics (MBeans) that are collected by Jira. All of them are grouped in the com.atlassian.jira property.

MetricDescriptionReset after restarting Jira
dashboard.view.count

The number of times all dashboards were viewed by users.

Yes
entity.attachments.totalThe number of attachments.-
entity.components.totalThe number of components.-
entity.customfields.totalThe number of custom fields.-
entity.filters.totalThe number of filters.-
entity.groups.totalThe number of user groups.-
entity.issues.totalThe number of issues.-
entity.users.totalThe number of users.-
entity.versions.totalThe number of versions created.-
issue.assigned.count

The number of times issues were assigned or reassigned to users (counts each action).

Yes
issue.created.count

The number of issues that you created after starting your Jira instance.

Yes
issue.link.count

The number of issue links created after starting your Jira instance.

Yes
issue.search.count

The number of times you searched for issues.

Yes
issue.updated.count

The number of times you updated issues (each update after adding or changing some information).

Yes
issue.worklogged.count

The number of times you logged work on issues.

Yes
jira.licenseThe types of licenses you have, the number of active users, and the maximum number of users available for each license type.-
quicksearch.concurrent.search

The number of concurrent searches that are being performed in real-time by using the quick search. You can use it to determine whether the limit set for concurrent searches is sufficient or should be increased.

Yes
web.requests

The number of requests (invocation.count), and the total response time (total.elapsed.time).

Yes

The following metrics have been added to Jira as of 8.1 and are exposed under under com.atlassian.jira/metrics. All the metrics mentioned below will be reset after restarting Jira. 

Metric path

Description

comment

Metrics related to comment operations

comment/Create

Comment being created

comment/Delete

Comment being deleted

comment/Update

Comment being updated

indexing

Metrics related to issue, comment, worklog, and change indexing

indexing/CreateChangeHistoryDocument

Index documents being created for Change History entities. Note that many Change History Documents can be created for every issue.

indexing/CreateCommentDocument

Index documents being created for Comment entities.

indexing/CreateIssueDocument

Index documents being created for Issue entities

indexing/IssueAddFieldIndexers

FieldIndexer modules enrich Issue documents as part of Index document creation. Plugins can register custom FieldIndexer modules. These metrics provide insight into how much time is spent in FieldIndexer, and can be used to track down indexing performance issues caused by them. The metrics describe how much time was spent in all FieldIndexers combined per Issue document created.

indexing/LuceneAddDocument

How much time was spent adding a document to the Lucene index

indexing/LuceneDeleteDocument

How much time was spent deleting one or more documents matching a term from the Lucene index

indexing/LuceneOptimize

Metrics about Lucene index optimization (triggered manually from Jira)

indeding/LuceneUpdateDocument

How much time was spent adding a created document to the Lucene index.

indexing/ReplicationLatency

Replication latency is the time between an issue, comment, or worklog being indexed on the node where the change was made and the indexing operation being replayed on the current node.

indexing/WaitForLucene

Documents are written to the Lucene index asynchronously. This metric captures how much time Jira’s indexing thread spent waiting for Lucene to complete the write.

indexing/issueAddSearchExtractors

EntitySearchExtractor enriches issue documents as part of Index document creation. Plugins can register custom EntitySearchExtractor modules. These metrics provide insight into how much time is spent in EntitySearchExtractor and can be used to track down indexing performance issues they cause. The metrics describe how much time was spent in all EntitySearchExtractors combined per issue document created.

issue

Metrics about issue operations

issue/Create

Issue being created

issue/Delete

Issue being deleted

issue/Index

Issue being added to the Lucene index. This covers issue document creation and adding the document to the index.

issue/DeIndex

Issue being removed from the Lucene index

issue/ReIndex

Issue being re-indexed (as a result of issue updates). This covers issue document creation, deleting the old document from the index and adding new documents to the index.

issue/Update

Issue being updated

Monitoring Jira

Before you can monitor Jira, you need to enable JMX monitoring and then use a JMX client to view the metrics.

Viewing the metrics will always have some performance impact on Jira. We recommend that you don't refresh them more than once a second.

Enabling JMX monitoring in Jira

All of the metrics are collected by default, but you need to enable JMX monitoring to expose them. You can do it in Jira but you must be a Jira admin.

  1. In Jira, go to Administration (> System > JMX monitoring.
  2. Toggle Enable JMX monitoring.

Monitoring with JConsole

After you enabled JMX monitoring, you can use any JMX client to view the metrics. To make it quick and easy, we've described how to view them by using JConsole. You can monitor your Jira instance either locally, or remotely:

  • Monitoring Jira locally is good if you're troubleshooting a particular issue, or only need to monitor Jira for a short time. Local monitoring can have a performance impact on your server, so it's not recommended for long-term monitoring of your production system.

    Show me how to do this...

     To monitor locally:

    1. Start JConsole. You'll find it in the bin directory of the JDK installation directory. (JConsole is only available as part of the JDK.)
    2. Select Local Process.
    3. Select the Jira process. It will be called something like org.apache.catalina.startup.Bootstrap start
    4. After connecting, expand the com.atlassian.jira property that groups all the metrics.

    See Using JConsole for more information on local monitoring.

  • Monitoring Jira remotely is recommended for production systems, as it does not consume resources on your Jira server.

    Show me how to do this...

     To monitor remotely:

    • Add the following properties to your setenv.sh / setenv.bat file. The port can be any port that is not in use.

      CATALINA_OPTS

      Windows
      SET CATALINA_OPTS="-Dcom.sun.management.jmxremote.authenticate=true ${CATALINA_OPTS}"
      SET CATALINA_OPTS="-Dcom.sun.management.jmxremote.password.file=/atlassian-jira-software-x.y.z-standalone/jmxremote.password ${CATALINA_OPTS}"
      SET CATALINA_OPTS="-Dcom.sun.management.jmxremote.access.file=/atlassian-jira-software-x.y.z-standalone/jmxremote.access ${CATALINA_OPTS}"

      (info) x.y.z stands for the Jira version you're using.

      Linux
      CATALINA_OPTS="-Dcom.sun.management.jmxremote.authenticate=true ${CATALINA_OPTS}"
      CATALINA_OPTS="-Dcom.sun.management.jmxremote.password.file=/atlassian-jira-software-x.y.z-standalone/jmxremote.password ${CATALINA_OPTS}"
      CATALINA_OPTS="-Dcom.sun.management.jmxremote.access.file=/atlassian-jira-software-x.y.z-standalone/jmxremote.access ${CATALINA_OPTS}"

      (info) x.y.z stands for the Jira version you're using.

      For more details, see the Using Password Authentication section in Monitoring and Management Using JMX Technology.

      Additionally, to access the JMX properties, you might need to configure SSL. For more details, see the SSL sections in Monitoring and Management Using JMX Technology.

      JAVA_OPT

      Using JAVA_OPTS works to expose the JMX MBeans for remote access but causes errors to be thrown during Jira shutdown.

      Windows
      JAVA_OPTS=-Dcom.sun.management.jmxremote %JAVA_OPTS%
      JAVA_OPTS=-Dcom.sun.management.jmxremote.port=8099 %JAVA_OPTS%
      JAVA_OPTS=-Dcom.sun.management.jmxremote.authenticate=false %JAVA_OPTS%
      Linux
      JAVA_OPTS="-Dcom.sun.management.jmxremote ${JAVA_OPTS}"
      JAVA_OPTS="-Dcom.sun.management.jmxremote.port=8099 ${JAVA_OPTS}"
      JAVA_OPTS="-Dcom.sun.management.jmxremote.authenticate=false ${JAVA_OPTS}"
      export JAVA_OPTS
    • Decide how you will secure your remote connection. See Remote Monitoring and Management for more information. 
      Although it is possible to disable authentication, we do not recommend doing this on a production system.
    • Start JConsole (you'll find it in the bin directory of the JDK installation directory).
    • Select Remote Process.
    • Enter your hostname and port (this is the port you specified earlier, not the Jira port).
    • Click Connect.
    • After connecting, expand the com.atlassian.jira property that groups all the metrics.

    See Using JConsole for more information on remote monitoring.

Last modified on Jan 16, 2023

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.