/
Tuning Performance
Document toolboxDocument toolbox

Tuning Performance

Owned by David Goldstein
Last updated: May 15, 2025
9 min read

For small-to-medium size Jira installations, no special tuning is typically required.

The following sections address optional Jira performance tunings that may be relevant to customers with larger installations.

Many of these tunings are configurable with JVM property settings.

On a Linux system, JVM property settings are typically added to JVM_SUPPORT_RECOMMENDED_ARGS in the bin/setenv.sh file in your Jira installation directory.

See Atlassian's Jira documentation for directions on setting JVM properties on other systems.

Limiting Long-Running Reports

Dataplane Reports has a number of load management features to prevent individual user reports from monopolizing system resources.

Limiting Report Size

Dataplane Reports has a default limit of 75,000 Jira issues for the maximum number of Jira issues that may be included by an individual report.

Reports returning more than this number of issues are prevented from running and instead display an error message to the user explaining the issue limit:

You may choose a different limit for the maximum number of issues allowed in report results by specifying the following JVM system property:

Property

Default Value

Value

Property

Default Value

Value

com.arsenalesystems.dataplane.report.maxIssues

75000

<MAX_ISSUES>

For example, to increase this limit to 100,000 issues on a Linux system, add the following JVM property:

-Dcom.arsenalesystems.dataplane.report.maxIssues=100000

Limiting Report Database Query Time

Dataplane Reports prevents overly-complex, long-running report database queries from creating database or Jira performance issues by limiting all report database queries to 60 seconds in duration.

Database queries exceeding this time limit are automatically canceled, and the user is shown an error message explaining the limitation:

dbQueryTimeoutError.png

To use a different database query time limit for all users and reports, specify the following JVM system property:

Property

Default Value

Value

Property

Default Value

Value

com.arsenalesystems.dataplane.db.queryTimeoutSeconds

60

<SECONDS>

For example, to increase this limit to 90 seconds on a Linux system, add the following JVM property:

-Dcom.arsenalesystems.dataplane.db.queryTimeoutSeconds=90

Disabling the Database Query Timeout

When long-running reports are blocked by the database query time limit, it can be frustrating to iteratively tweak the report’s configuration to get around the query time limit.

To help users debug long-running reports, administrators can temporarily bypass the database query time limit for a report by enabling the menu option More > Disable Query Timeout on that report’s Configuration page and then re-running the report.

disableQueryTimeout.png

To prevent users from regularly or accidentally disabling the timeout, the Disable Query Timeout menu option is only visible to Jira administrators, and its setting is not saved with the report or persisted across page loads.

Analyzing the Event Log

All significant Dataplane Reports app activity is logged to an app-specific event log file—dataplane-events.log.csv—located in the <JIRA HOME>/log directory.

The data from this log helps to better understand and tune Dataplane Reports performance, analyze app and platform resource demands such as use of Jira database pool connections, correlate any system issues with app use, and identify top app users and reports.

On multi-node Jira Data Center instances, each Dataplane Reports node logs activity to its own, node-specific <JIRA HOME>/log/dataplane-events.log.csv file. Nodes do not share app event logs.

When the event log file grows larger than 20MB, Dataplane Reports automatically archives the file as dataplane-events.log.csv.1, and continues logging app events to a new, empty dataplane-events.log.csv file. Up to 10 log archives are kept (dataplane-events.log.csv.1, dataplane-events.log.csv.2, etc), storing the most recent 200MB of event data.

Event Log Format

The Dataplane Reports event log is formatted as a comma-separated value (CSV) file. It can be opened in any CSV-format compatible application such as Excel or Numbers.

Each line in the file represents one individual app event that occurred. All events share a standard set of fields/columns, with field values surrounded by double-quotes and separated from one-another by a comma character.

The event log fields are as follows: 

Field/Column

Values

Description

Field/Column

Values

Description

TIMESTAMP

<yyyy-MM-dd HH:mm:ss,SSS>, e.g. "2022-01-05 19:19:17,131"

Date and time of the event

THREAD

<text>, e.g. "http-nio-8085-exec-8"

Name of Java thread on which the event occurred

USER

<user ID> or "<anonymous>"

Jira user that caused the event to occur

IP ADDRESS

<a.b.c.d>

IP address of device that caused the event to occur

CONTEXT

<unique ID>, e.g. "b5ba8e2f-3fca-4957-94a9-3bcab675427d"

Unique identifier for the event or group of related events

This allows multiple, related events to be correlated with one another, for example, a single context ID labels the starting event for a report run, the report run's database connection acquisition event, and the completion event of that report run.

SOURCE

"App", "Dashboard", "Wallboard", "Confluence", "Scheduled", "Admin", "User", "Internal"

What app or platform feature caused the event to be run

For example, reports run from within Dataplane app pages are labeled "App"; reports run from Jira dashboard gadgets are labeled "Dashboard"; and reports run from Dataplane gadgets on Confluence pages are labeled "Confluence".

EVENT

<various>, e.g. "Report.Run", "Indexer.Build.Begin"

Identifier for the type of event, such as a reporting, indexing or admin event, or marking the beginning or ending of one of those events

SUMMARY

<text>

Text summary of the event

DETAILS

<text>, e.g. "

owner=adam24, qrs=ef17192a-dc15-43ed-8424-afd388681b5e, format=HTML_GADGET, type=pivotTableReport, rid=5"

Various event properties and other event details, such as the report owner and type of report being run, or the speed of indexing issues

RESULT

"Ok", "Delayed", "Error", "Canceled", "Unauthorized"

Result status of the event, such as successful, delayed, canceled or an error was encountered

RESULT INFO

<text>

Additional details on the event result

TOTAL ITEMS

<count>

Number of items processed by the event, for instance a full index build of 177245 Jira issues will show "177245"

WAIT TIME (MS)

<time, in milliseconds>

Within the event, time spent waiting for a resource to become available

For example, running a Dataplane report might be delayed because a database connection was not immediately available.

QUERY TIME (MS)

<time, in milliseconds>

Within the event, time spent querying the database

PROC TIME (MS)

<time, in milliseconds>

Within the event, time spent processing data

TOTAL TIME (MS)

<time, in milliseconds>

Total duration of the event

The total event duration = "WAIT TIME" + "QUERY TIME" + "PROC TIME".

AVAIL DB CONN

<count>

Number of unused database connections currently available for Dataplane use

The total number of database connections in the Jira connections pool that are reserved for Dataplane use = "AVAIL DB CONN" + "USED DB CONN".

USED DB CONN

<count>

Number of database connections currently in use by Dataplane

The total number of database connections in the Jira connections pool that are reserved for Dataplane use = "AVAIL DB CONN" + "USED DB CONN".

WAITING DB CONN

<count>

Number of Dataplane processes (e.g. reports) that are blocked waiting for an available database connection

Jira Data Center

NODE

<node name>, e.g. "jira-node1"

Name of the Jira node on which this event occurred

This value is a constant for all events and event logs on the same Jira node. It is included to allow event logs from multiple Jira nodes to be combined and sorted for analysis while still maintaining each event's node-association.

BOSS

<node name>, e.g. "jira-node2"

Name of the "Boss" Jira node currently assigned by Dataplane to perform certain Dataplane administrative tasks, such as building the Dataplane index

Across active Jira nodes, only one node is selected as the Dataplane Boss node at any given time. If the current Boss node becomes unresponsive or inactive, Dataplane selects a different node to be Boss.

Adjusting Available Database Connections

By default, Dataplane Reports will use up to 8 concurrent database connections, or one third of the total Jira database connection pool, whichever value is larger. If you have not modified Atlassian's default Jira database configuration of 20 database connections, Dataplane Reports will likely be using up to 8 connections.

This allows Dataplane Reports to use enough connections to support multiple concurrent report requests, but this limit also prevents Dataplane from starving the core Jira application of database connections for other operations.

The defaults should be sufficient for most systems, but if you see slow-loading reports when many users are accessing the system, or if you see messages similar to the following in the Jira log, you may wish to increase your connection limit:

Request for new database connection is likely to exceed maximum limit of <NUMBER> connections

Use Jira's built-in database connection pool monitor to see how many active database connections are being used by Jira and Dataplane together.

Increasing the Jira Database Connection Pool Size

All of the database connections used by Dataplane Reports are taken from the common Jira database connection pool.

To increase the number of database connections available to Jira, follow Atlassian's guide for tuning database connections.

A sufficient number of connections must also be made available in your database server configuration.

Adjusting Dataplane's Maximum Database Connection Usage

If you want Dataplane Reports to use more or fewer connections than its default, you may tune the number of database connections it uses. To do this, configure the following JVM system property in your bin/setenv.sh file, where <NUMBER> is the maximum number of database connections that Dataplane Reports will attempt to use at a single time:

-Dcom.arsenalesystems.dataplane.db.maxConnections=<NUMBER>

All of Dataplane Reports' database connections are taken from Jira's common JDBC connection pool, so the Jira connection pool size must be larger than the number you specify here.

Adjusting the Maximum Database Connection Wait Time

Once Dataplane Reports has exceeded the maximum number of allocated database connections, for any new connection requests Dataplane will wait up to 60 seconds for an existing connection to become available. If no connections are made available during that time, Dataplane Reports will abort the report and display an error message to the user.

The default 60 second wait should be reasonable for most environments, but can be customized using the following JVM property inbin/setenv.sh:

-Dcom.arsenalesystems.dataplane.db.maxConnectionWaitTime=<DELAY_IN_SECONDS>

Note that the specified value for maxConnectionWaitTime may not be smaller than 10 seconds.

Adjusting the Maximum Number of Threads Waiting for Database Connections

Dataplane Reports also allows you to set an upper limit on the maximum number of threads that are permitted to wait for a database connection to become available. By default, up to 30 threads can be waiting for a database connection at any given time, which should be sufficient for most systems.

If more than the specified number of Dataplane Reports threads are already waiting for a database connection, new requests for database connections will be immediately aborted without waiting and an error message will be shown to the user. This helps to prevent HTTP thread exhaustion.

To customize the maximum number of Dataplane Reports threads that are permitted to wait for database connections, set the following JVM property in bin/setenv.sh:

-Dcom.arsenalesystems.dataplane.db.maxWaitQueueLength=<MAX_THREADS>

In general:

Maximum Dataplane HTTP Thread Usage =  maxConnections (actively using database connections) + maxWaitQueueLength (each waiting up to maxConnectionWaitTime seconds for a connection)

For example, if you are using default Atlassian values for Jira database connection properties and have not performed any of the above tuning, the maximum Dataplane HTTP thread usage will be 8 + 30 = 38 threads.

Archiving Jira Projects and Issues

For large Jira installations, typically of 1 million Jira issues or more, Atlassian encourages administrators and project managers to archive old Jira projects and issues to improve Jira performance. Archiving can also significantly benefit Dataplane Reports performance.

See the following Atlassian documentation for details on how to archive Jira projects and archive individual Jira issues.

Archiving

Archiving a group of Jira projects/issues provides the following immediate benefits in Dataplane Reports:

  • all data associated with the archived projects/issues is excluded from report results

  • the archived projects/issues are no longer selectable in the "Search" option of report configurations

  • the speed of generating reports improves proportional to the number of archived issues no longer included in each report

You do not need to immediately reindex Dataplane Reports after archiving projects/issues—archived projects/issues are automatically excluded from report results, and the size of the Dataplane Reports index does not significantly affect reporting performance.

However archived project/issue data will continue to take up space in the Dataplane Reports index until a full app reindex is performed. Reindex Dataplane Reports when you wish to reclaim the database space.

Unarchiving

After unarchiving Jira projects/issues, a full reindex of Dataplane Reports is required to ensure report results for those issues include accurate historical data.

Upon unarchiving a group of Jira projects/issues and reindexing Dataplane Reports:

  • the unarchived projects/issues are again included in report results

  • the unarchived projects/issues are again selectable in the "Search" option of report configurations

  • the speed of generating reports decreases proportional to the number of unarchived issues now included in each report

Need support? Create a request with our support team.

Copyright © 2005 - 2025 Appfire | All rights reserved.