From f509742f5ef7ba89f75812879646095b9abc26c8 Mon Sep 17 00:00:00 2001 From: Justin Prieto Date: Thu, 17 Sep 2026 13:11:09 -0400 Subject: [PATCH 1/4] ZOOKEEPER-4391: Allow automatic JVM heap sizing --- bin/zkEnv.sh | 10 +++++-- conf/java.env | 30 +++++++++++++++++++ .../pages/_docs/docs/_mdx/admin-ops/tools.mdx | 24 ++++++++++++++- 3 files changed, 61 insertions(+), 3 deletions(-) create mode 100644 conf/java.env diff --git a/bin/zkEnv.sh b/bin/zkEnv.sh index 40889874818..97722d89453 100755 --- a/bin/zkEnv.sh +++ b/bin/zkEnv.sh @@ -136,8 +136,14 @@ export CLASSPATH # default heap for zookeeper server ZK_SERVER_HEAP="${ZK_SERVER_HEAP:-1000}" -export SERVER_JVMFLAGS="-Xmx${ZK_SERVER_HEAP}m $SERVER_JVMFLAGS" +if [[ $ZK_SERVER_HEAP != auto ]]; then + SERVER_JVMFLAGS="-Xmx${ZK_SERVER_HEAP}m $SERVER_JVMFLAGS" +fi +export SERVER_JVMFLAGS # default heap for zookeeper client ZK_CLIENT_HEAP="${ZK_CLIENT_HEAP:-256}" -export CLIENT_JVMFLAGS="-Xmx${ZK_CLIENT_HEAP}m $CLIENT_JVMFLAGS" +if [[ $ZK_CLIENT_HEAP != auto ]]; then + CLIENT_JVMFLAGS="-Xmx${ZK_CLIENT_HEAP}m $CLIENT_JVMFLAGS" +fi +export CLIENT_JVMFLAGS diff --git a/conf/java.env b/conf/java.env new file mode 100644 index 00000000000..ef8e997fafe --- /dev/null +++ b/conf/java.env @@ -0,0 +1,30 @@ +#!/usr/bin/env bash +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +# + +# ZooKeeper defaults to a 1000 MiB server heap and a 256 MiB client heap. +# Set either heap to a number to choose a different size in MiB. +# ZK_SERVER_HEAP=1000 +# ZK_CLIENT_HEAP=256 + +# Set a heap to "auto" to omit -Xmx and configure JVM memory sizing directly. +# ZK_SERVER_HEAP=auto +# SERVER_JVMFLAGS="-XX:InitialRAMPercentage=25 -XX:MaxRAMPercentage=75" +# ZK_CLIENT_HEAP=auto +# CLIENT_JVMFLAGS="-XX:MaxRAMPercentage=25" diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/tools.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/tools.mdx index 15ee17c2e71..d32c031126a 100644 --- a/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/tools.mdx +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/tools.mdx @@ -56,9 +56,31 @@ See [ZooKeeper CLI](/admin-ops/cli). ### zkEnv.sh -Sets environment variables for the ZooKeeper server. Key variables: +Sets environment variables for ZooKeeper scripts. Values can be provided in +the environment or in `conf/java.env`. Key variables: - `ZOO_LOG_DIR` — the directory where logs are stored. +- `ZK_SERVER_HEAP` — the server maximum heap in MiB, or `auto` to omit `-Xmx`. +- `SERVER_JVMFLAGS` — additional JVM options for the server. +- `ZK_CLIENT_HEAP` — the client maximum heap in MiB, or `auto` to omit `-Xmx`. +- `CLIENT_JVMFLAGS` — additional JVM options for clients. + +Heap settings produce the following JVM options: + +| Heap setting | Server result | Client result | +|------------------|---------------------|---------------------| +| Unset | `-Xmx1000m` | `-Xmx256m` | +| Positive integer | `-Xmxm` | `-Xmxm` | +| `auto` | No generated `-Xmx` | No generated `-Xmx` | + +Use `auto` when JVM memory sizing should be configured with other options. For +example, a containerized server can use a percentage of the available memory: + +```bash +ZK_SERVER_HEAP=auto \ +SERVER_JVMFLAGS="-XX:InitialRAMPercentage=25 -XX:MaxRAMPercentage=75" \ +./zkServer.sh start +``` ### zkCleanup.sh From 970b3b323cb24aa9237799010dbcac5230c8a435 Mon Sep 17 00:00:00 2001 From: Justin Prieto Date: Thu, 17 Sep 2026 21:02:53 -0400 Subject: [PATCH 2/4] ZOOKEEPER-4391: Rename auto heap setting to omit --- bin/zkEnv.sh | 4 ++-- conf/java.env | 6 +++--- .../app/pages/_docs/docs/_mdx/admin-ops/tools.mdx | 10 +++++----- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/bin/zkEnv.sh b/bin/zkEnv.sh index 97722d89453..bc57d874906 100755 --- a/bin/zkEnv.sh +++ b/bin/zkEnv.sh @@ -136,14 +136,14 @@ export CLASSPATH # default heap for zookeeper server ZK_SERVER_HEAP="${ZK_SERVER_HEAP:-1000}" -if [[ $ZK_SERVER_HEAP != auto ]]; then +if [[ $ZK_SERVER_HEAP != omit ]]; then SERVER_JVMFLAGS="-Xmx${ZK_SERVER_HEAP}m $SERVER_JVMFLAGS" fi export SERVER_JVMFLAGS # default heap for zookeeper client ZK_CLIENT_HEAP="${ZK_CLIENT_HEAP:-256}" -if [[ $ZK_CLIENT_HEAP != auto ]]; then +if [[ $ZK_CLIENT_HEAP != omit ]]; then CLIENT_JVMFLAGS="-Xmx${ZK_CLIENT_HEAP}m $CLIENT_JVMFLAGS" fi export CLIENT_JVMFLAGS diff --git a/conf/java.env b/conf/java.env index ef8e997fafe..b572977a33b 100644 --- a/conf/java.env +++ b/conf/java.env @@ -23,8 +23,8 @@ # ZK_SERVER_HEAP=1000 # ZK_CLIENT_HEAP=256 -# Set a heap to "auto" to omit -Xmx and configure JVM memory sizing directly. -# ZK_SERVER_HEAP=auto +# Set a heap to "omit" to suppress -Xmx and configure JVM memory sizing directly. +# ZK_SERVER_HEAP=omit # SERVER_JVMFLAGS="-XX:InitialRAMPercentage=25 -XX:MaxRAMPercentage=75" -# ZK_CLIENT_HEAP=auto +# ZK_CLIENT_HEAP=omit # CLIENT_JVMFLAGS="-XX:MaxRAMPercentage=25" diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/tools.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/tools.mdx index d32c031126a..bbbb5b9b2c0 100644 --- a/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/tools.mdx +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/tools.mdx @@ -60,9 +60,9 @@ Sets environment variables for ZooKeeper scripts. Values can be provided in the environment or in `conf/java.env`. Key variables: - `ZOO_LOG_DIR` — the directory where logs are stored. -- `ZK_SERVER_HEAP` — the server maximum heap in MiB, or `auto` to omit `-Xmx`. +- `ZK_SERVER_HEAP` — the server maximum heap in MiB, or `omit` to omit `-Xmx`. - `SERVER_JVMFLAGS` — additional JVM options for the server. -- `ZK_CLIENT_HEAP` — the client maximum heap in MiB, or `auto` to omit `-Xmx`. +- `ZK_CLIENT_HEAP` — the client maximum heap in MiB, or `omit` to omit `-Xmx`. - `CLIENT_JVMFLAGS` — additional JVM options for clients. Heap settings produce the following JVM options: @@ -71,13 +71,13 @@ Heap settings produce the following JVM options: |------------------|---------------------|---------------------| | Unset | `-Xmx1000m` | `-Xmx256m` | | Positive integer | `-Xmxm` | `-Xmxm` | -| `auto` | No generated `-Xmx` | No generated `-Xmx` | +| `omit` | No generated `-Xmx` | No generated `-Xmx` | -Use `auto` when JVM memory sizing should be configured with other options. For +Use `omit` when JVM memory sizing should be configured with other options. For example, a containerized server can use a percentage of the available memory: ```bash -ZK_SERVER_HEAP=auto \ +ZK_SERVER_HEAP=omit \ SERVER_JVMFLAGS="-XX:InitialRAMPercentage=25 -XX:MaxRAMPercentage=75" \ ./zkServer.sh start ``` From 875980791442709274130fa97db37cb775d581d1 Mon Sep 17 00:00:00 2001 From: Justin Prieto Date: Thu, 17 Sep 2026 21:07:01 -0400 Subject: [PATCH 3/4] ZOOKEEPER-4391: Add example with custom Xmx configuration --- .../app/pages/_docs/docs/_mdx/admin-ops/tools.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/tools.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/tools.mdx index bbbb5b9b2c0..ae86b6d1342 100644 --- a/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/tools.mdx +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/tools.mdx @@ -82,6 +82,14 @@ SERVER_JVMFLAGS="-XX:InitialRAMPercentage=25 -XX:MaxRAMPercentage=75" \ ./zkServer.sh start ``` +It can also be used to provide an `-Xmx` value directly: + +```bash +ZK_SERVER_HEAP=omit \ +SERVER_JVMFLAGS="-Xmx2g" \ +./zkServer.sh start +``` + ### zkCleanup.sh Clean up old snapshots and transaction logs. From 5d1ebb3fc3ef92ffad2a97e8be38a593ec51d34b Mon Sep 17 00:00:00 2001 From: Justin Prieto Date: Fri, 18 Sep 2026 08:03:40 -0400 Subject: [PATCH 4/4] ZOOKEEPER-4391: Update documentation --- conf/java.env | 5 ++-- .../pages/_docs/docs/_mdx/admin-ops/tools.mdx | 27 ++++++++++++------- 2 files changed, 21 insertions(+), 11 deletions(-) diff --git a/conf/java.env b/conf/java.env index b572977a33b..62c005e3b51 100644 --- a/conf/java.env +++ b/conf/java.env @@ -19,11 +19,12 @@ # # ZooKeeper defaults to a 1000 MiB server heap and a 256 MiB client heap. -# Set either heap to a number to choose a different size in MiB. +# Set either heap to a positive integer to choose a different size in MiB. # ZK_SERVER_HEAP=1000 # ZK_CLIENT_HEAP=256 -# Set a heap to "omit" to suppress -Xmx and configure JVM memory sizing directly. +# Set a heap to "omit" to skip ZooKeeper's generated -Xmx option. The matching +# JVMFLAGS variable can still provide -Xmx or any other heap-related JVM options. # ZK_SERVER_HEAP=omit # SERVER_JVMFLAGS="-XX:InitialRAMPercentage=25 -XX:MaxRAMPercentage=75" # ZK_CLIENT_HEAP=omit diff --git a/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/tools.mdx b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/tools.mdx index ae86b6d1342..488286618ec 100644 --- a/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/tools.mdx +++ b/zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/tools.mdx @@ -57,23 +57,32 @@ See [ZooKeeper CLI](/admin-ops/cli). ### zkEnv.sh Sets environment variables for ZooKeeper scripts. Values can be provided in -the environment or in `conf/java.env`. Key variables: +the environment or in `conf/java.env`, whose values take precedence. Key +variables: - `ZOO_LOG_DIR` — the directory where logs are stored. -- `ZK_SERVER_HEAP` — the server maximum heap in MiB, or `omit` to omit `-Xmx`. +- `ZK_SERVER_HEAP` — configures the server maximum heap in MiB. - `SERVER_JVMFLAGS` — additional JVM options for the server. -- `ZK_CLIENT_HEAP` — the client maximum heap in MiB, or `omit` to omit `-Xmx`. +- `ZK_CLIENT_HEAP` — configures the client maximum heap in MiB. - `CLIENT_JVMFLAGS` — additional JVM options for clients. Heap settings produce the following JVM options: -| Heap setting | Server result | Client result | -|------------------|---------------------|---------------------| -| Unset | `-Xmx1000m` | `-Xmx256m` | -| Positive integer | `-Xmxm` | `-Xmxm` | -| `omit` | No generated `-Xmx` | No generated `-Xmx` | +| Heap setting | Server result | Client result | +| ---------------- | -------------------------------- | -------------------------------- | +| Unset | `-Xmx1000m` | `-Xmx256m` | +| Positive integer | `-Xmxm` | `-Xmxm` | +| `omit` | No `-Xmx` generated by ZooKeeper | No `-Xmx` generated by ZooKeeper | -Use `omit` when JVM memory sizing should be configured with other options. For +Unless the heap setting is `omit`, ZooKeeper prepends the generated `-Xmx` +option to any options provided in the corresponding `*_JVMFLAGS` variable. + +The server and client settings are independent. Setting either heap variable to +`omit` skips only the `-Xmx` option ZooKeeper would otherwise generate from the +corresponding heap setting. It does not remove or override options in the corresponding +`*_JVMFLAGS` variable, including an explicitly supplied `-Xmx` option. + +Use `omit` when heap-related JVM options should be configured manually. For example, a containerized server can use a percentage of the available memory: ```bash