JMX (Java Management Extensions API) allows you to monitor the status of your Confluence instance in real time. JMX uses objects called MBeans (Managed Beans) to expose data and resources from your application, providing useful data such as the resource usage of your instance and its database latency, allowing you to diagnose problems or performance issues.

On this page, we'll guide you through how to use JConsole to monitor Confluence locally and remotely. JConsole is included in the Java Development Kit (JDK), but you can use any JMX client.

This page also contains information about In-product diagnostics available through JMX.

Monitor Confluence using JMX

Monitor Confluence remotely using your APM

To monitor Confluence in your Application Performance Monitoring (APM) tool, you'll need to install a JMX exporter to transform theJMX MBeans into the right format for your tool. See Monitor application performance to find out how to do this. 

If you don't have an Application Performance Monitoring (APM) system, we've created a guide to get you started with Prometheus and Grafana, including some template dashboards that you can use as a jumping off point. See Monitor Confluence with Prometheus and Grafana.

Monitor Confluence remotely using JConsole

Remote monitoring is recommended for production systems, as it does not consume resources on your Confluence server.

To monitor remotely:

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

   set CATALINA_OPTS=-Dcom.sun.management.jmxremote %CATALINA_OPTS%
   set CATALINA_OPTS=-Dcom.sun.management.jmxremote.port=8099 %CATALINA_OPTS%

2. 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.

3. Start JConsole (you'll find it in the bin directory of the JDK installation directory).
4. Select Remote Process.
5. Enter your hostname and port (this is the port you specified earlier, not the Confluence port).
6. Click Connect.

See Using JConsole for more information on remote monitoring.

Monitor Confluence locally using JConsole

If you are troubleshooting a particular issue, or only need to monitor Confluence for a short time, you can use local monitoring. Local monitoring can have a performance impact on your server, so its not recommended for long-term monitoring of your production system.

To monitor locally:

1. Start JConsole (you'll find it in the bin directory of the JDK installation directory)

2. Select Local Process.

3. Select the Confluence process. It will be called something like org.apache.catalina.startup.Bootstrap start

See Using JConsole for more information on local monitoring.

Write JMX metrics to a log file

You can also choose to write the following JMX metrics to a log file. This is useful when you are troubleshooting a problem.

• CacheStatistics
• IndexingStatistics
• MailTaskQueue
• RequestMetrics
• SystemInformation
• ThreadPool
• OS
• GC
• Threading
• TomcatManager
• RequestProcessor

To write JMX metrics to a log file:

1. Go to Administration  > General Configuration > Scheduled jobs
2. Enable the Log JMX Metrics job. 

This job runs once per minute by default, and writes metrics to the <local-home/logs/atlassian-confluence-jmx.log file. See Working with Confluence Logs

Disable JMX monitoring

To diable JMX monitoring:

1. Go to Administration  > General Configuration > Monitoring.
2. Deselect JMX monitoring.

This will also disable App monitoring, as it requires JMX to be enabled. 

Confluence MBeans

You can use the following Confluence MBeans to see live information about your Confluence instance.

CacheStatistics

This MBean shows information about Confluence caches. This info can also be found on the Cache Statistics page.

IndexingStatistics

This MBean shows information related to search indexing. Here's some useful attributes.

SystemInformation

This MBean shows information such as the Confluence version and uptime. This info can also be found on the System Information page.  

RequestMetrics

This MBean shows information related to system load and error pages served.

MailServer-SMTPServer

This MBean shows information related to email dispatch attempts and failures. There will be an MBean for every SMTP Mailserver that has been configured in the Confluence instance.

MailTaskQueue

This MBean shows information related to the email workload.

SchedulingStatistics

This MBean shows information related to current jobs, scheduled tasks and the time that they were last run.

App-specific metrics

Enable app monitoring to expose additional metrics that are useful when troubleshooting issues with Marketplace and custom-built apps. 

See App metrics reference for a full list of app-specific metrics.

Additional MBeans

To also monitor Hibernate and Hazelcast (Confluence Data Center only) you will need to add the following properties to your setenv.sh / setenv.bat file first. 

set CATALINA_OPTS=-Dconfluence.hazelcast.jmx.enable=true %CATALINA_OPTS%
set CATALINA_OPTS=-Dconfluence.hibernate.jmx.enable=true %CATALINA_OPTS%

This will make the Hibernate and Hazelcast MBeans available in your JMX client. 

Monitoring high CPU consuming threads

The Top Threads Plugin for JConsole is useful for monitoring whether the CPU is spiking. Use the following command to start JConsole with this plugin:

JConsole -pluginpath /pathto/topthreads.jar

In-product diagnostics available through JMX

We've introduced a set of database connectivity and HTTP connection metrics for in-product diagnostics available through JMX.

In-product diagnostics (IPD) provide greater insights for you and Atlassian Support into how running Confluence instances are operating.

IPD uses additional metrics handling Confluence’s interactions with its database. For example, using database connectivity metrics, you can efficiently identify what in your environment or infrastructure may be responsible for performance issues. 

The feature is enabled by default. Live metrics are available in the following formats:

• as new JMX MBeans

• as a history of snapshots of the JMX values in the new IPD log file atlassian-confluence-ipd-monitoring.log. See Working with Confluence Logs

  • The log file is also included in the Support Zip file created in the Atlassian Troubleshooting and Support app. If needed, send the zip file to Atlassian Support who has the internal tools to interpret it.

In-product diagnostics metrics

Expand the following sections to learn more about the metrics available for in-product diagnostics.

Enabling in-product diagnostics monitoring

IPD monitoring is enabled by default. To manage it:

1. Go to Administration  > General Configuration

2. In the left panel, select Monitoring.

3. Use the Enable in-product diagnostics toggle to enable or disable IPD monitoring.

Screenshot: JMX monitoring settings with in-product diagnostics disabled

Log formatting

Writing to atlassian-confluence-ipd-monitoring.log is done via log4j. Its configuration is managed in log4j.properties.

#####################################################
# In-product diagnostics monitoring logging
#####################################################

log4j.appender.ipdLogAppender=com.atlassian.confluence.logging.ConfluenceHomeLogAppender
log4j.appender.ipdLogAppender.LogFileName=atlassian-confluence-ipd-monitoring.log
log4j.appender.ipdLogAppender.MaxFileSize=20480KB
log4j.appender.ipdLogAppender.MaxBackupIndex=5
log4j.appender.ipdLogAppender.layout=com.atlassian.logging.log4j.NewLineIndentingFilteringPatternLayout
log4j.appender.ipdLogAppender.layout.ConversionPattern=%d %m%n

log4j.logger.ipd-monitoring = INFO, consolelog
log4j.additivity.ipd-monitoring = false
log4j.logger.ipd-monitoring-data-logger = INFO, ipdLogAppender
log4j.additivity.ipd-monitoring-data-logger = false

Log contents

By default, a concise set of data is included in each log entry. An extended set of data can be logged by enabling the confluence.in.product.diagnostics.extended.logging feature flag.

To enable the extended data:

1. Go to <CONFLUENCE_URL>/admin/darkfeatures.action, where <CONFLUENCE_URL> is the base URL of your Confluence instance.

2. In the Enable dark feature field, enter confluence.in.product.diagnostics.extended.logging

3. Select Submit. Learn how to manage dark features

   1. To disable the extended data, in the Site Dark Features section, find confluence.in.product.diagnostics.extended.logging and select remove.

In the following tables, see the structures of the concise and extended logging formats.

Concise data

2023-01-13 11:51:13,106 IPDMONITORING {"timestamp":"1673610673","label":"DB.CONNECTION.POOL.NUMACTIVE.STATISTICS","attributes":{"_max":"2.0","_mean":"1.2436699769063984","_99thPercentile":"2.0","_count":"5","_min":"1.0"}}

Extended data

2022-09-06 18:38:48,015 IPDMONITORING {"timestamp":"1662453528","label":
"DB.CONNECTION.LATENCY.STATISTICS","objectName":
"com.atlassian.confluence:category00\u003ddb,category01\u003dconnection,category02\
u003dlatency,name\u003dstatistics,type\u003dmetrics",
"attributes":{"_oneMinuteRate":"0.02012497818617073","_50thPercentile":"0.0",
"_mean":"1.9379304604014412E-25","_max":"1.0","_stdDev":"4.40219315841711E-13",
"_98thPercentile":"0.0","_meanRate":"0.003612560785169162","_rateUnit":
"events/second","_99thPercentile":"0.0","_count":"16","_durationUnit":
"milliseconds","_75thPercentile":"0.0","_fiveMinuteRate":
"0.005912972095043379","_fifteenMinuteRate":"0.0037696657500141968",
"_999thPercentile":"0.0","_95thPercentile":"0.0","_min":"0.0"}}

Definitions of metric attributes

Expand the following sections to learn more about metric attributes.