Prepare Jenkins for Support


  • Best Practices to Support Jenkins



Please be aware that if Jenkins runs under control of systemd, then defining the ulimits as shown below within /etc/security/limits.conf has no effect on Jenkins. Parameters like LimitNoFile and LimitNoProc must be set within the systemd service unit file.


The following settings are known Best Practices, and should be used in your Jenkins environment to allow for easier support in the event of an issue.

A. Java Parameters

CloudBees Supported Java Version

JVM Administration and Tuning is necessary for any Enterprise Java Application Deployment. As Jenkins is an Enterprise Java Application, the following arguments are considered to be best practices, based on historical data analysis of Garbage Collection Logs, Thread Dump Analysis, and Heap Dump Analysis.

In the last several years with Java 1.8.0, fine tuning Garbage Collection settings was considered a common practice, but ultimately masks underlying problems within the JDK. Because of this, it was also common practice to allocate more RAM and CPU resources to the JVM to keep it running smoothly. While this will help in the short term, it still masks underlying problems. These methodologies are described in-depth in this article.

In today’s methodologies, it is more important to ensure you are running a current JDK version, and keep the JVM Arguments simple. There have been several years of bug fixes, memory leak fixes, threading improvements, and Garbage Collection enhancements, and therefore we recommend JDK 1.8.0_212 or newer.

Additionally, keeping your JVM Heap size below 16GB per our JVM Best Practices encourages horizontal scaling and prevents you from creating a monolithic JVM. Following this methodology will ensure you achieve a performant and stable instance of Jenkins, and will ultimately improve the experience for the end-users.

Please ensure you are using ONLY the following arguments unless directed by a Support Engineer, and if you have a question about adding an argument, please engage our Support Team.

Heap Size

Heap Size -Xmx= and -Xms= should be set to the same value, and should be determined by the current needs of the application. Per our JVM Best Practices we recommend a minimum of 2GB (4GB for Production Instances) and a maximum of 16GB (Anything larger should be scaled horizontally.) It is important, as a JVM Administrator, to plan for heap to be increased as usage increases, and scale horizontally when the recommended maximum heap size of 16GB is reached. Monitoring Garbage Collection logging is the recommended way to predict how much heap you need.

JVM Arguments

The following parameters are explained in-depth in Oracle Documentation as well as our JVM Best Practice. Please implement the following arguments ensuring ${PATH} is replaced by a valid path on your operating system in which Jenkins has permission to write:

-Xloggc:${PATH}/gc.log  *Note that the slash should be adjusted for your operating system, i.e. Windows uses* \
-XX:ErrorFile=${PATH}/hs_err_%p.log  *Note that the slash should be adjusted for your operating system, i.e. Windows uses* \
-XX:+LogVMOutput    (requires -XX:+UnlockDiagnosticVMOptions)
-XX:LogFile=${PATH} (requires -XX:+UnlockDiagnosticVMOptions)             
* *Example: `-XX:LogFile=/var/log/jenkins/jvm.log` (Linux)*
* *Example: `-XX:LogFile="C:\Program Files (x86)\Jenkins\jvm.log"` (Windows)*

Note: the arguments requiring a valid filesystem path (-Xloggc, -XX:HeapDumpPath, -XX:ErrorFile and -XX:LogFile) should be adjusted for your OS. Please consider using a path to local disk drives instead of network disk volumes for those arguments (especially Xloggc) in order to avoid I/O performance issues.

GC log note: To increase GC logs to a longest period of time, we suggest increasing the value of the arguments -XX:GCLogFileSize and -XX:NumberOfGCLogFiles and as ultimate option use -Xloggc:${PATH}/gc-%t.log instead of -Xloggc:${PATH}/gc.log. The %t will produce that each time time instance is restarted a new set of GC files will be created. It is well known that when the GC log folder gets big enough in terms of size, the support bundle might produce performance issues in the instance given that it needs to compress all of them.

If you are unsure how to add Java arguments to Jenkins, please see: How to add Java arguments to Jenkins.

Note that Jenkins will require a restart for the JVM parameters to be picked up by the JVM.

B. Ulimit Settings [just for Linux OS]

ulimit -c and ulimit -f should be set to unlimited for the user that starts Jenkins. ulimit -c set to unlimited will allow core files to be generated successfully. The core files include full thread dumps and core files generated by the JVM in the event of a JVM crash. ulimit -f should be set to unlimited to ensure that files are not truncated during their generation.

ulimit -n should be set to 4096 (soft) and 8192 (hard)

ulimit -u should be set to 30654 (soft) and 30654 (hard)

The ulimit -n and ulimit -u setting recommendations are taken from: Memory problem: ‘unable to create new native thread’

Please see this KB Article for setting ulimits in Docker: Too many open files.

To have the ulimit settings persist for the user that runs Jenkins, they will need to be added to /etc/security/limits.conf.

Your /etc/security/limits.conf file should like similar to the example below, for the user that starts jenkins in your environment:


C. Java Home Environment Variable

It is recommended to set the JAVA_HOME environment variable in both Linux and Windows environments. The Java JDK’s bin directory should also be in the PATH environment variable. This will allow for easier access to Java JDK commands, such as jstack and jmap. Please note that the jstack command is only available in the Java JDK, not the Java JRE.

Please also note that core files and heapdump files can be large and are generated in the working directory of the JVM. Thus, it is recommended that there is adequate disk space for that directory.

For example, on Windows, the PATH environment variable will include: C:\Program Files\Java\jdk1.8.0_202\bin

Running jstack in terminal window or command prompt should generate the following output:


D. Log Startup Timing Info

Per our Startup Troubleshooting Guide: it is recommended to set -Djenkins.model.Jenkins.logStartupPerformance=true in your Jenkins environment to have Jenkins output additional data to the jenkins.log, showing how much time is being spent in a specific component during startup.

E. Jenkins Admin Should Be Able To Generate A Support Bundle via jenkins-cli.jar

This will allow Jenkins admins to generate support bundles in the event the Jenkins User Interface (UI) is not available,
even though Jenkins is running.

Please note that Jenkins accounts must have the Overall/Read account permission to access the CLI.

The jenkins-cli.jar can be downloaded from JENKINS_URL/cli.

More information about the jenkins-cli.jar support command can be viewed by navigating to JENKINS_URL/cli/command/support .

Additional information about the jenkins-cli.jar can be found at jenkins-cli.jar wiki page.

Please see the screen shot below showing a support bundle generated via jenkins-cli.jar using the username and password.
The jenkins-cli.jar authentication can be setup to use SSH keys if you prefer, as documented in the jenkins-cli.jar wiki page
linked above.


Have more questions?


  • 0
    Brian Hedlund

    Looks like I want to add this in for GC


  • 0
    Carlos Rodriguez Lopez

    Please, Can you elaborate more your question?

  • 0
    Seu Support

    Please be aware that if Jenkins runs under control of systemd, then defining the ulimits as shown above within /etc/security/limits.conf has no effect on Jenkins. Parameters like LimitNoFile and LimitNoProc must be set within the systemd service unit file.

  • 0
    Tim Black

    Many of the suggested JAVA args are not supported in recent JDK versions. Would be good to update this page accordingly. I'm using:

    jenkins@jenkins:~$ java --version
    openjdk 11.0.8 2020-07-14
    OpenJDK Runtime Environment (build 11.0.8+10-post-Debian-1deb10u1)
    OpenJDK 64-Bit Server VM (build 11.0.8+10-post-Debian-1deb10u1, mixed mode, sharing)

    and getting the following errors with your suggested args:

    • Unrecognized VM option 'NumberOfGCLogFiles=2'
    • [0.001s][warning][gc] -Xloggc is deprecated. Will use -Xlog:gc:/var/log/jenkins/gc-%t.log instead.
    • Unrecognized VM option 'UseGCLogFileRotation'
    • Unrecognized VM option 'GCLogFileSize=100m'
    • Unrecognized VM option 'PrintGCDateStamps'
    • Unrecognized VM option 'PrintHeapAtGC'
    • Unrecognized VM option 'PrintGCCause'
    • Unrecognized VM option 'PrintTenuringDistribution'
    • Unrecognized VM option 'PrintReferenceGC'
    • Unrecognized VM option 'PrintAdaptiveSizePolicy'
      Did you mean '(+/-)UseAdaptiveSizePolicy'?

    After removing all these options, Jenkins service will once again start.

    See here for reference to new options for GC Logging.

    Update: I believe the new way to specify these args would be:


    Update Update: Actually, no, for my java version, I had to trim the gc logging option to this to get it to work:


    (which was what jenkins recommended in the original err)

    Edited by Tim Black
Please sign in to leave a comment.