New database connectivity metrics for in-product diagnostics

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

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

IPD provides additional metrics handling Jira’s interactions with its database. Using database connectivity metrics, you’ll efficiently identify what in your environment or infrastructure might cause the performance issues. Early discovery of a problem guarantees that it can be fixed before its consequences have a bigger impact on instance operation.

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

  • as new JMX MBeans
  • as a history of snapshots of the JMX values in the new IPD log file atlassian-jira-ipd-monitoring.log

The log file is available in the {jira_home}\log folder where you can find all the existing log files. The log file is also included in the Support Zip file, created in the ATST plugin. If needed, you can generate the Support Zip file in the Atlassian troubleshooting & support tools plugin and send the file to Atlassian Support, where we have internal tools to interpret it. Learn more about the plugin

Communication

The feature communicates in the following ways:

  • JMX: JMX MBeans are updated periodically based on an internal schedule.
  • The log file atlassian-jira-ipd-monitoring.log: JMX values are snapshotted and recorded to the log file on a configurable schedule. By default, the JMX values are polled and written to the log file every 60 seconds. (This parameter is up to date since the EAP 02.) This polling interval can be changed by using the system property jira.diagnostics.ipdlog.poll.seconds.

Database connectivity metrics

See the metrics provided by the IPD and their descriptions in the following table.

To use the metrics, make sure you’ve enabled JMX. Read more about JMX in Jira

MBean ObjectNameMetric description
com.atlassian.jira:type=metrics,
category00=db,category01=connection,
category02=failures,name=statistics

db.connection.failures.counter

  • The count of database connection failures since the last restart
com.atlassian.jira:type=metrics,
category00=db,category01=connection,
category02=latency,name=statistics

db.connection.latency.statistics

  • Aggregated statistics of latency since the last restart

com.atlassian.jira:type=metrics,
category00=db,category01=connection,
category02=latency,name=value

db.connection.latency.value

  • The latest measure of latency when querying the database

com.atlassian.jira:type=metrics,
category00=db,category01=connection,
category02=pool,category02=numActive,
name=statistics

db.connection.pool.numActive.statistics

  • Aggregated statistics of the number of active connections in the database connection pool since the last restart

com.atlassian.jira:type=metrics,
category00=db,category01=connection,
category02=pool,category02=numActive,
name=value

db.connection.pool.numActive.value

  • The latest measure of the number of active connections in the database connection pool

com.atlassian.jira:type=metrics,
category00=db,category01=connection,
category02=pool,category02=numIdle,
name=statistics

db.connection.pool.numIdle.statistics

  • Agregated statistics of the number of idle connections in the database connection pool since the last restart

com.atlassian.jira:type=metrics,
category00=db,category01=connection,
category02=pool,category02=numIdle,
name=value

db.connection.pool.numIdle.value

  • The latest measure of the number of idle connections in the database connection pool

com.atlassian.jira:type=metrics,
category00=db,category01=connection,
category02=state,name=value

db.connection.state.value

  • The latest indicator of the state of the connection to the database

Disabling the IPD

The IPD is enabled by default since the EAP 02. To disable it:

  1. Go to <JIRA_URL>/secure/admin/SiteDarkFeatures!default.jspa, where <JIRA_URL> is the base URL of your Jira instance.
  2. In the Enable dark feature text area, enter com.atlassian.jira.in.product.diagnostics.disabled. Select Add. Learn how to manage dark features
    1. To re-enable the IPD, in the Site Wide Dark Features panel, find com.atlassian.jira.in.product.diagnostics.disabled and select Disable.

Log formatting

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

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

log4j.appender.ipd=com.atlassian.jira.logging.JiraHomeAppender
log4j.appender.ipd.File=atlassian-jira-ipd-monitoring.log
log4j.appender.ipd.MaxFileSize=20480KB
log4j.appender.ipd.MaxBackupIndex=5
log4j.appender.ipd.layout=com.atlassian.logging.log4j.NewLineIndentingFilteringPatternLayout
log4j.appender.ipd.layout.ConversionPattern=%d %m%n

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

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

To enable the extended data:

  1. Go to <JIRA_URL>/secure/admin/SiteDarkFeatures!default.jspa, where <JIRA_URL> is the base URL of your Jira instance.
  2. In the Enable dark feature text area, enter com.atlassian.jira.in.product.diagnostics.extended.logging.enabled. Select Add. Learn how to manage dark features
    1. To disable the extended data, in the Site Wide Dark Features panel, find com.atlassian.jira.in.product.diagnostics.extended.logging.enabled and select Disable.


Last modified on Sep 27, 2022

Was this helpful?

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