Create a support zip using the REST API in Data Center applications
Support zips help Atlassian support understand how your application has been configured and troubleshoot your problem.
The most common way to generate a support zip is from the administration menu of your application. However, for Data Center applications it can be more convenient to use the REST API to create the zip. If your application is clustered, this allows you to generate zips from every node, not just the one you're currently accessing. Learn more about creating a support zip
The option to use REST to generate a support zip from multiple nodes is only available for Data Center applications running Atlassian Troubleshooting and Support Tools 1.11.0 or later.
You can upgrade this app at any time: in the Administration menu, go to Manage apps, and search for Atlassian Troubleshooting and Support Tools (ATST). If you're running an older version, it may be called Atlassian Support Tools. Learn more about upgrading apps
REST API reference
We’ve added new API parameters in Atlassian Troubleshooting and Support Tools 1.49.0. Learn more about the introduced changes
This page contains examples of using this REST API in Data Center applications using curl and Windows PowerShell. You can use the scripting language of your choice.
REST API | Description | For |
---|---|---|
/rest/troubleshooting/latest/support-zip/local | Create a support zip | Server |
/rest/troubleshooting/latest/support-zip/status/task | Get the status of all recent zip creation tasks | Server |
/rest/troubleshooting/latest/support-zip/status/task/<taskId> | Get the status of a specific zip creation task | Server and Data Center |
/rest/troubleshooting/latest/support-zip/download/<filename> | Download support zip file | Server and Data Center |
/rest/troubleshooting/latest/support-zip/cluster | Create a support zip on multiple nodes of the cluster | Data Center |
/rest/troubleshooting/latest/support-zip/status/cluster/<clusterTaskId> | Get the status of the zip creation tasks for the cluster | Data Center |
Generate a support zip on all nodes
To access the Troubleshooting and Support Tools app, you must have the System administrator global permission.
To generate a support zip on all nodes in a Data Center instance from the command line:
curl -s -X POST -H 'Content-Type: application/json' -u <username>:<password> http://<base-url.example.com:8080>/rest/troubleshooting/latest/support-zip/cluster
This returns the Cluster Task ID and node information, for example:
{
"clusterTaskId":"eec930c0-687c-4a07-b625-02e95022b8ad",
"nodeIds":["jira1","jira2"]
}
The Cluster Task ID groups all the individual support zip tasks for each node, and allows you to check their progress.
Including the Content-Type header will allow you to include a json payload, which is used to specify particular nodes or items to include in the zip.
Generate a support zip on particular nodes
To specify particular nodes, include the nodeIds
in your request as follows:
curl -s -X POST -H 'Content-Type: application/json' -u <username>:<password> http://<base-url.example.com:8080>/rest/troubleshooting/latest/support-zip/cluster -d '{"nodeIds":["jira1","jira2"]}'
In this example the node IDs are Jira1
and Jira2
. Your nodes may be named differently.
Check the progress of the requests
Often it can take some time to generate the zips, especially on large instances. To check the progress of the tasks:
curl -s -X GET -u <username>:<password> http://<base-url.example.com:8080>/rest/troubleshooting/latest/support-zip/status/cluster/<clusterTaskId>
The Cluster Task ID in this example would be eec930c0-687c-4a07-b625-02e95022b8ad
.
This returns the current progress of the zip generation on each node. In this example, the zips are complete and ready to be downloaded or transferred from the shared home directory.
{
"clusterTaskId": "eec930c0-687c-4a07-b625-02e95022b8ad",
"tasks": [
{
"taskId": "aaa192c8-f033-4df4-8530-95bcf328c646",
"progressPercentage": 100,
"progressMessage": "Your support ZIP can be found in your home directory at: /<shared-home>/export/JIRA_jira2_support_2018-06-11-23-35-12.zip or you can download a copy.",
"nodeId": "jira2",
"fileName": "JIRA_jira2_support_2018-06-11-23-35-12.zip"
},
{
"taskId": "d7086507-2d2d-464b-9a7f-9b580ed85956",
"progressPercentage": 100,
"progressMessage": "Your support ZIP can be found in your home directory at: /<shared-home>/export/JIRA_jira1_support_2018-06-11-23-35-09.zip or you can download a copy.",
"nodeId": "jira1"
}
]
}
If /status/clustertaskID
doesn't return all the nodes this may be because a node is not responding, or the zip generation may not have started on that node yet. Give it a few minutes to broadcast the request to all nodes, and start processing, then try again.
Generate a support zip with particular parameters
hen you generate a support zip via the admin console, you're able to select which items to include, limit file sizes if needed, and export log files for the selected timeframe. This is also possible when generating the zip using the REST API.
For example, if you wanted the log files and health check results from nodes 1 and 2, and didn't want to limit file sizes you could use the following:
curl -s -X POST -H 'Content-Type: application/json' -u <username>:<password> http://<base-url.example.com:8080>/rest/troubleshooting/latest/support-zip/cluster -d '{"nodeIds":["jira1","jira2"], "items":["application-logs", "tomcat-logs", "healthchecks"], "limitFileSizes": false}'
REST API values accepted before 1.33
items
you can include in your support zip, and what they're called in the UI, for reference. See Create a Support Zip for a full description of each item. Description in UI | Field for API | Included by default |
---|---|---|
Authentication Configuration | auth-cfg | Yes |
Application Configuration Files | application-config | Yes |
Application properties | application-properties | Yes |
Application Customization | confluence-customisations | Yes (Confluence) |
Health checks | healthchecks | Yes |
Application Logs | application-logs | Yes |
Cache Configuration | cache-cfg | Yes |
Fisheye/Crucible.out log | fecru-out | Yes (Fisheye/Crucible) |
Fisheye/Crucible plugin configuration | fecru-pluginstate-properties | Yes (Fisheye/Crucible) |
Locally modified files | modz | Yes (Fisheye/Crucible) |
Fisheye/Crucible plugin configuration files | fecru-plugin-cfg | Yes (Fisheye/Crucible) |
Thread dumps | thread-dump | No |
Tomcat Configuration Files | tomcat-config | Yes |
Tomcat Logs | tomcat-logs | Yes |
Tomcat access logs | tomcat-access-logs | No |
Jira cluster nodes | cluster-nodes | Yes (Jira) |
Cloud Migration Logs | cloud-migration-logs | Yes |
Include runtime diagnostics data | jfr-bundle | Yes (If Java Flight Recorder has been enabled) |
Synchrony configuration | synchrony-config | Yes (Confluence) |
REST API parameters added in 1.49.0
We’ve added new API parameters in the 1.49.0 version of the app. These parameters allow you to define the Modification date of log files and select the Maximum file size for each exported file. Learn more about the introduced options
If you upgrade your ATST app to the 1.49.0 version or later but continue using the old API only with the limitFileSizes:true
parameter to fetch Tomcat access logs, all Tomcat access logs will be added to the zip. This might significantly affect your zip size because these logs aren’t affected by the Maximum file size option.
To limit the number of Tomcat access logs added to your zip, use the new fileConstraintAge
parameter.
New API parameters are available in Troubleshooting and Support Tools 1.49.0 and later:
Parameter | Description | Values |
---|---|---|
| Export log files that were last modified within the selected period. If you don’t want to change the behavior of past API calls, don’t add this parameter and the time limit won’t be applied. |
|
fileConstraintSize | This parameter always takes precedence over the old limitFileSizes . This means that if the request provides limitFileSizes: false and fileConstraintSize: 25 , the 25 MB per file limitation will be applied while creating a support zip. |
|
The API for creating support zip is backward compatible. However, the default value for file size limit changes from 25 MB to 100 MB per file in the support zip.
Download support zip files
The support zip will be saved to a location in your shared home directory. If you're not able to easily access that directory, or you want to automate the process, you can use the REST API to download it as follows:
curl -u <username>:<password> http://<base-url.example.com:8080>/rest/troubleshooting/latest/support-zip/download/<filename> -o support.zip
In this example <filename>
would be JIRA_jira2_support_2018-06-11-23-35-12.zip
and support.zip
the output file name. Note that you don't have to specify the node, just the filename (which is returned when you check the status of the request).
Troubleshooting
- You need System administrator permissions to generate the support zip. The request will fail with a permission error if you don't have the proper permissions.
- If
/status/clustertaskID
doesn't return all the nodes this may be because a node is not responding, or the zip generation may not have started on that node yet. Give it a few minutes to broadcast the request to all nodes and start processing, then try again. - If you see a 404 error, make sure that your Atlassian application is running and has version 1.10.5 or later of the Atlassian Troubleshooting and Support Tools app. You can update the app at any time. Learn more about updating apps
If an '
XSRF check failed'
error is returned, you can add theX-Atlassian-Token
header to each request, setting the value tono-check
. Adding this header to a request bypasses the server-side XSRF check and allows the request to be fulfilled. This is required for Confluence. For example:curl -u <username>:<password> -X POST http://<app-node1.example.com:8080>/rest/troubleshooting/latest/support-zip/local -H "X-Atlassian-Token: no-check"