This documentation is for an old version of Dataplane Reports.
View the latest documentation, or the list of documentation for all versions.
Tuning Performance
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.
Limiting Report Size
To block individual user reports from monopolizing system resources, Dataplane 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 |
|---|---|---|
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 property setting to JVM_SUPPORT_RECOMMENDED_ARGS in the bin/setenv.sh file in your Jira installation directory:
-Dcom.arsenalesystems.dataplane.report.maxIssues=100000
See Atlassian's Jira documentation for directions on setting JVM properties on other systems.
Analyzing the Event Log
All significant Dataplane app activity is logged to a Dataplane-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 performance, analyze app and platform resource demands such as use of Jira database pool connections, correlate any system issues with Dataplane use, and identify top Dataplane users and reports.
On multi-node Jira Data Center instances, each Dataplane node logs activity to its own, node-specific "JIRA HOME/log/dataplane-events.log.csv" file. Nodes do not share Dataplane event logs.
When the event log file grows larger than 20MB, Dataplane 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 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 |
|---|---|---|
| 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. |
Interpreting Event Log Data
Details coming soon!
- too few available database connections (under-provisioned connections pool, too many concurrently-scheduled reports, too many gadgets on a dashboard, unexpected use such as Confluence gadgets)
- slow (long-running) reports
- reports failing due to errors
- top report users
- anonymous users accessing reports
- top sources of report use (dashboards, wallboards, Confluence)
- indexing failure
- nodes becoming inactive or unresponsive
Example Event Data
Details coming soon!
- sample gadget use
- sample app report use
- sample scheduled report use
- background query
- cancel
- debug mode vs. other: begin/end vs. report.run; (same for background query)
- startup
- indexing: build index, sync index, extend index, remove index, cancel indexing
- boss node change
Example Event Data with Debug Logging Enabled
Details coming soon!
- debug mode: db connection acquire/release
Adjusting Available Database Connections
By default, Dataplane 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 will likely be using up to 8 connections.
This allows Dataplane 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 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 to use more or fewer than Dataplane's default, one-third fraction of the total Jira connection pool size, you may tune the number of database connections used by Dataplane. 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 will attempt to use at a single time:
-Dcom.arsenalesystems.dataplane.db.maxConnections=<NUMBER>
All of Dataplane's 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 has exceeded the maximum number of connections specified above, if a new connection is required, Dataplane will wait up to 60 seconds for an existing connection to become available. If no connections are made available during that time, Dataplane will abort the report and display an error message to the user.
The default value of 60 seconds should be acceptable for most environments. Should you have a need to tune the connection wait times, you can configure the following JVM parameter in bin/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 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 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, which helps to prevent HTTP thread exhaustion.
To adjust the maximum number of threads that are permitted to wait for database connections, set the following JVM system property in bin/setenv.sh:
-Dcom.arsenalesystems.dataplane.db.maxWaitQueueLength=<MAX_THREADS>
By tuning this parameter, you can control the maximum number of HTTP threads that can be consumed by Dataplane-related tasks.
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 parameters 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 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:
- all data associated with the archived projects/issues is now 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 after archiving projects/issues—archived projects/issues are automatically excluded from report results, and the size of the Dataplane index does not significantly affect reporting performance.
However archived project/issue data will continue to take up space in Dataplane's index until a full Dataplane reindex is performed. Reindex Dataplane when you wish to reclaim the database space.
Unarchiving
After unarchiving Jira projects/issues, a full reindex of Dataplane is required to ensure report results for those issues include accurate historical data.
Upon unarchiving a group of Jira projects/issues and reindexing Dataplane:
- 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
Page Contents