How to use the Performance Data Collector

Overview

This page explains how you can collect performance data, such as thread dumps, disk speed and cpu usage information, with the Performance Data Collection tool.

The collector is made up of two parts, the toolkit and the graphical user interface (GUI). The toolkit needs to be installed on the same server as your Atlassian product, and the GUI can be used on a local machine to connect remotely, provided the toolkit is accessible externally.

Toolkit installation instructions for Windows

1. Install Java 8 JDK (unless already present).
2. Add the JDK 8 directory to the windows %PATH% at the beginning (e.g.: C:\Program Files\Java\jdk1.8.0_181\bin) as per the How do I set or change the PATH system variable? Oracle documentation. For example:
   
   
   This is required, due to a limit in the installer.
3. Using the download section of the Bitbucket repository, download the archive and expand it to where you want it to be installed, e.g.: C:\Program Files\Atlassian.

4. Install it with InstallAsService.bat - this must be run as an Administrator user. It will put it into the standard Windows services along with the other Atlassian products, for example:
   
   It must be run by the same user that the Atlassian products are run by, otherwise it won't be able to connect to them - this is due to restrictions in the Java JDK. For all products except Bitbucket Server, this will work with the defaults.

   Account utilization caveat (Windows)

   In order to be able to properly utilize the Data Collector Tool, Jira must not be running with the 'Network Service' account (which is the default 'Log On As' when Jira is installed on Windows), due to its iterative login not allowing the data collector to correctly bind to the Jira service.

   If this is your case, you can change the account that Jira is using to the Local System Account, with the below steps:
   - Open the Windows Services.
   - Right-click the Atlassian Jira service and select properties.
   - Select the Log On tab
   - Mark the Local System Account option and Apply.
   

   - Hit Ok to close the service Properties windows.
   - Restart the Jira service so that the changes can be picked up.

   Ensure that the Data Collector is also running with the same 'Log On As', if it is not, you can use the same steps to adjust its service.

5. If you need to change the user (say the Atlassian product is run as a specific user, such as in BitBucket Server), uncommenting below in <INSTALL_DIR>\windows-service\service.xml and uninstalling / reinstalling will set it as that user:

   <!-- If you need the service to be run as a particular user, add the details in below. Otherwise it will use the default account.
   <serviceaccount>
       <domain>YOURDOMAIN</domain>
       <user>useraccount</user>
       <password>Pa55w0rd</password>
       <allowservicelogon>true</allowservicelogon>
   </serviceaccount>
   -->

6. It can now be accessed on http://localhost:4242, or the relevant domain name. We recommend using the GUI for this, as detailed below.

Toolkit installation instructions for Linux

1. Install Oracle Java 8 JDK (unless already present). There is a third-party Oracle Java (JDK) 8 Installer PPA that can be used for this in Ubuntu.
2. Due to restrictions in the Oracle Java JDK APIs that are used, the app must be run by the same user that is used to run the application (e.g.: jira).
3. Using the download section of the Bitbucket repository, locate the appropriate file and download it to the product home directory to install it, e.g.: /var/atlassian/application-data/jira.

4. If using Linux, the jar is executable, so run with the below (or the appropriately named file, depending on the version).

   ./data-collector-1.0.jar

   It can also be run in the background with

   ./data-collector-1.0.jar &

5. It can now be accessed on http://localhost:4242, or the relevant domain name. We recommend using the GUI for this, as detailed below.
6. If you want to set it up as a init.d or systemd service it can be done as per the Installing Spring Boot Applications documentation.

GUI installation instructions

Download the platform-specific app from the download section of the Bitbucket repository, and use that by running the downloaded file.

Collecting data with the GUI

1. Start it up and point it to the appropriate instance URL. For example, we're going to connect to http://jira.atlassian.com:4242 and use the default user / pass of collector / changeit



2. Press Continue
3. Select the appropriate product, in this case Jira, then press Run Data Collection at the time the product is experiencing performance problems
   
   The frequency indicates how often it will collect. For example, 6 snaps in a minute means every 10 seconds it will collect a snapshot of data.
   
   
4. Wait for the collection to complete. With the default settings this should take approximately 1 minute - it's periodically collecting data at set intervals
   
5. When the results are finished, it will give the results of your disk speed and also a link to download the collected data
   
6. Download the zip and attach it to your support case

Collecting data with the Toolkit

There are a series of REST APIs that can be accessed for various collections. There is a Swagger spec that can be downloaded from http://<app_url>:4242/v2/api-docs (e.g.: http://localhost:4242/v2/api-docs). Or you can access the collector directly on http://<app_url>:4242/ (e.g.: http://localhost:4242) and it'll show the Swagger UI.

Using a client such as Postman will allow you to import the API spec to easily make calls to the toolkit. For example:

How to configure the Toolkit

All settings are located in the <INSTALL_DIR>/config/application.properties file.

Changing the credentials

The default login / pass is collector / changeit. These can be changed by modifying the application.properties file as per the example below:

# Basic auth for application. Changing this requires a restart.
security.user.name=collector
security.user.password=securepassword!

Changing the port

In the above example, the login / pass will now be collector / securepassword! next time it is started.

This can be done by modifying server.port in the application.properties file as per the example below:

# Tomcat config.
server.port=8962
server.context-path=/

In the above example, the toolkit will now run on port 8962 next time it is started.

How to troubleshoot the Toolkit

There are logs written to <INSTALL_DIR>/logs/atlassian-perftools.log which can be used to review what the toolkit is doing. If the collector isn't working, please provide the log on the support case and we can take a look to see what's going on.

It can't find my product

The most common issue here is the product is being run as a different user. Due to limitations in the Java JDK API the toolkit must be installed as the user that is running the service. E.g.: JIRA by default, on Linux, runs as user jira. This means the toolkit must run as user jira too.

Bugs and/or new features

If you'd like to raise a bug or request a new feature, please do so on the Bitbucket issue tracker.