Issue

• Best Practice For Java Heap settings

Environment

• CloudBees Jenkins Team (CJT)
• CloudBees Jenkins Platform - Client Master (CJP-CM)
• CloudBees Jenkins Platform - Operations Center (CJP-OC)
• CloudBees Jenkins Enterprise (CJE)
• Jenkins LTS

Resolution

General

A. According to JVM ergonomic page, the maximum heap size should be be 1/4 of the physical memory. This threshold is also extended when Jenkins is running inside VM and/or Docker Containers (maximum heap size limits is aggregated when there was more than one Java application running on the same Host).

B. Set your minimum heap size (-Xms) to at least 1/2 of your maximum size (-Xmx).

C. For 64 bit JVM, set -Xmx less than 32G to benefit from -XX:+UseCompressedOops (which comes activated by default in recent JVM).

D. Jenkins should not be started with less than -Xmx2g. However, for production environment with a considerable job workload, Jenkins should run with -Xmx16g or so. In the case your instance demands more than -Xmx16g any of the following points could be happening.

• Other factors, apart from the Heap Size, are not taking into consideration for improving your performance. please review: CJP Performance Best Practices for Linux.
• Your instance is not able to support its current workload (number of jobs and configuration) so you should consider about scaling horizontally your infra (more masters) to divide this workload more efficiently.

Docker containers - Java < 8u131

D. -XX:MaxRAM taking into account the point A.

• MaxRAM is correctly detected with UseCGroupMemoryLimitForHeap in 8u131+
• Particullary for CJE 2 it is recommended XX:MaxRAM=${MEM_LIMIT}m being

...
- name: MEM_LIMIT
          valueFrom:
            resourceFieldRef:
              containerName: jenkins
              resource: limits.memory
              divisor: 1Mi
...              

Estimation

F. The Jenkins Monitoring Plugin can be installed temporally (It’s not recommendable for Production Environments) to monitor the performance of your instance, the right heap value which should be a value between 80-90% of total heap consumption when the instance is at the maximum workload. Big heap memory values might produce big GC pauses which means slowness and sometimes even side effects like agent disconnections.

E. Running Jenkins inside a Docker Container: The following points talk about how to calculate the max heap size for a Java application running in a Docker Container.

• See Running a JVM in a Container Without Getting Killed.
• The image fabric8/java-jboss-openjdk8-jdk uses a script that calculates the container restriction and uses 50% of the available memory as an upper boundary. You can also use this image to enable/disable debugging, diagnostics, and much more. See RedHat Post - Java inside docker: What you must know to not FAIL.