Create a support zip using the REST API in Data Center applications

Still need help?

The Atlassian Community is here for you.

Ask the community

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. 

The following REST endpoints are available:
REST APIDescriptionFor

/rest/troubleshooting/latest/support-zip/local

Create a support zip Server
/rest/troubleshooting/latest/support-zip/status/taskGet the status of all recent zip creation tasksServer
/rest/troubleshooting/latest/support-zip/status/task/<taskId>Get the status of a specific zip creation taskServer and Data Center 

/rest/troubleshooting/latest/support-zip/download/<filename>

Download support zip fileServer and Data Center
/rest/troubleshooting/latest/support-zip/clusterCreate a support zip on multiple nodes of the clusterData Center
/rest/troubleshooting/latest/support-zip/status/cluster/<clusterTaskId>Get the status of the zip creation tasks for the clusterData 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.  

tip/resting Created with Sketch.

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. 

To generate a support zip using Windows PowerShell...

This step requires Invoke-WebRequest. This was introduced in PowerShell v3.0, so is available by default in Windows 8 and from Windows Server 2012. 

# Specify your username, password and Base URL (including a context path if one is being used) below
$user = '<username>'
$pass = '<password>'
$baseurl = 'http://<base-url.example.com:8080>'

# no need to change anything below this line
$pair = "$($user):$($pass)"
$encodedCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($pair))
$basicAuthValue = "Basic $encodedCreds"

$headers = @{}
$headers.Add("Authorization", $basicAuthValue)
$headers.Add("X-Atlassian-Token", "no-check")

Invoke-WebRequest -Method POST -Uri "$baseurl/rest/troubleshooting/latest/support-zip/cluster" -UseBasicParsing -Headers $headers
Output when using Windows PowerShell...
StatusCode        : 200
StatusDescription : OK
Content           : {"clusterTaskId":"eec930c0-687c-4a07-b625-02e95022b8ad","nodeIds":["jira1","jira2"]"}

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

To generate a support zip using Windows PowerShell...
# Specify your username, password and Base URL (including a context path if one is being used) below
$user = '<username>'
$pass = '<password>'
$baseurl = 'http://<base-url.example.com:8080>'
$clustertaskid = '<clusterTaskId>'

# no need to change anything below this line
$pair = "$($user):$($pass)"
$encodedCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($pair))
$basicAuthValue = "Basic $encodedCreds"

$headers = @{}
$headers.Add("Authorization", $basicAuthValue)
$headers.Add("X-Atlassian-Token", "no-check")

(Invoke-WebRequest -Uri "$baseurl/rest/troubleshooting/latest/support-zip/status/cluster/$clustertaskid" -UseBasicParsing -Headers $headers).Content

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 

Here's a list of 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 UIField for APIIncluded 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:

ParameterDescriptionValues

fileConstraintLastModified


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.

  • Any time (unlimited): -1

  • Today: 0

  • In the past 3 days: 3

  • In the past 5 days: 5

  • In the past 10 days: 10

fileConstraintSizeThis 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.
  • No limit: -1

  • For 25 MB per file: 25

  • For 100 MB per file: 10

  • For 500 MB per file: 500

Examples of POST request’s parameters for creating support zip and expected results

If  limitFileSizes, fileConstraintSize, or fileConstraintLastModified isn’t present, assume it’s not included in the request’s parameters:

// File size constraint with default value (100MB per each file) applied
{
...,
"limitFileSizes":"true"
}

// No file size limits are applied
{
...,
"limitFileSizes":"false"
}

// File size constraint with default value (100MB per each file) applied
{
...
}

// File size constraint with value of 25MB per each file applied
{
...,
"limitFileSizes":"false",
"fileConstraintSize":"25"
}

{
...,
"limitFileSizes":"true",
"fileConstraintSize":"25"
}

{
...,
"fileConstraintSize":"25"
}

// File age constraint for files modified in current day applied
{
...,
"fileConstraintLastModified":"0"
}

/**
* File size constraint with value of 25MB per each file applied
* File age constraint for files modified in the past 5 days applied
*/
{
...,
"fileConstraintSize":"25",
"fileConstraintLastModified":"5"
}
tip/resting Created with Sketch.

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 the X-Atlassian-Token header to each request, setting the value to no-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"


Last modified on Jul 7, 2023

Was this helpful?

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