This is an automated email from the ASF dual-hosted git repository.
jshao pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/gravitino.git
The following commit(s) were added to refs/heads/main by this push:
new 109792fe6b [#8587] docs: Document GRAVITINO_MEM usage across servers
(#9379)
109792fe6b is described below
commit 109792fe6b56593a966946605472fb6118ef1e95
Author: FANNG <[email protected]>
AuthorDate: Fri Dec 5 16:41:20 2025 +0900
[#8587] docs: Document GRAVITINO_MEM usage across servers (#9379)
### What changes were proposed in this pull request?
Document GRAVITINO_MEM usage across servers
### Why are the changes needed?
Fix: #8587
### Does this PR introduce _any_ user-facing change?
no
### How was this patch tested?
just document
---------
Co-authored-by: Copilot <[email protected]>
---
conf/gravitino-env.sh.template | 4 +++-
docs/docker-image-details.md | 12 ++++++++++++
docs/gravitino-server-config.md | 11 +++++++++++
docs/iceberg-rest-service.md | 9 ++++++++-
4 files changed, 34 insertions(+), 2 deletions(-)
diff --git a/conf/gravitino-env.sh.template b/conf/gravitino-env.sh.template
index 1d39e2e8ff..16f4ae84ae 100644
--- a/conf/gravitino-env.sh.template
+++ b/conf/gravitino-env.sh.template
@@ -28,4 +28,6 @@ GRAVITINO_VERSION=GRAVITINO_VERSION_PLACEHOLDER
# export GRAVITINO_HOME
# export GRAVITINO_CONF_DIR
# export GRAVITINO_LOG_DIR # Where log files are stored. PWD by default.
-# export GRAVITINO_MEM # Gravitino jvm mem options Default -Xms1024m
-Xmx1024m -XX:MaxMetaspaceSize=512m
\ No newline at end of file
+# export GRAVITINO_MEM # JVM memory options for the Gravitino server,
Iceberg REST server, and Lance REST server.
+# # Default: -Xms1024m -Xmx1024m
-XX:MaxMetaspaceSize=512m
+# # Appended to JAVA_OPTS by launch scripts; set
GRAVITINO_MEM to change heap/metaspace sizes.
diff --git a/docs/docker-image-details.md b/docs/docker-image-details.md
index a870886cb2..9f67aff561 100644
--- a/docs/docker-image-details.md
+++ b/docs/docker-image-details.md
@@ -17,6 +17,10 @@ Container startup commands
docker run --rm -d -p 8090:8090 -p 9001:9001 apache/gravitino:0.7.0-incubating
```
+Memory settings
+
+JVM heap and metaspace are controlled by `GRAVITINO_MEM` (default `-Xms1024m
-Xmx1024m -XX:MaxMetaspaceSize=512m`). Override with `-e GRAVITINO_MEM="-Xms4g
-Xmx4g -XX:MaxMetaspaceSize=1g"` to tune sizes. Launch scripts append
`GRAVITINO_MEM` to `JAVA_OPTS`, so set it whenever you need different
heap/metaspace sizes.
+
Changelog
@@ -71,6 +75,10 @@ Container startup commands
docker run --rm -d -p 9001:9001 apache/gravitino-iceberg-rest:0.7.0-incubating
```
+Memory settings
+
+Use `GRAVITINO_MEM` to size the JVM (default `-Xms1024m -Xmx1024m
-XX:MaxMetaspaceSize=512m`). Override with `-e GRAVITINO_MEM="-Xms4g -Xmx4g
-XX:MaxMetaspaceSize=1g"` when you need different sizes. Launch scripts append
`GRAVITINO_MEM` to `JAVA_OPTS`, so set it to change heap/metaspace settings.
+
Changelog
- apache/gravitino-iceberg-rest:1.0.0
- Upgrade Iceberg version to 1.9
@@ -129,6 +137,10 @@ You can deploy the standalone Gravitino Lance REST server
with the Docker image.
docker run --rm -d -p 9102:9102 -e LANCE_REST_GRAVITINO_METALAKE_NAME=test -e
LANCE_REST_PORT=9102 apache/gravitino-lance-rest:latest
```
+Memory settings
+
+Use `GRAVITINO_MEM` to size the JVM (default `-Xms1024m -Xmx1024m
-XX:MaxMetaspaceSize=512m`). Example: `-e GRAVITINO_MEM="-Xms2g -Xmx2g
-XX:MaxMetaspaceSize=512m"`. Launch scripts append `GRAVITINO_MEM` to
`JAVA_OPTS`, so set it whenever you need different heap/metaspace sizes.
+
Currently, Gravitino Lance REST server supports setting the following
environment variables
- LANCE_REST_GRAVITINO_METALAKE_NAME: It will overwrite the configuration
"gravitino.lance-rest.gravitino.metalake-name" in configuration file
`conf/gravitino-lance-rest-server.conf`. **You should set it to your Gravitino
metalake name.**
- LANCE_REST_NAMESPACE_BACKEND: It will overwrite the configuration
"gravitino.lance-rest.namespace-backend" in configuration file
`conf/gravitino-lance-rest-server.conf`. The default value is "gravitino" and
you should not change it as of now.
diff --git a/docs/gravitino-server-config.md b/docs/gravitino-server-config.md
index cf498b8b20..52b430db2c 100644
--- a/docs/gravitino-server-config.md
+++ b/docs/gravitino-server-config.md
@@ -266,6 +266,17 @@ Refer to [security](security/security.md) for HTTPS and
authentication configura
|-------------------------------------------|------------------------------------------------------|---------------|----------|---------------|
| `gravitino.metrics.timeSlidingWindowSecs` | The seconds of Gravitino metrics
time sliding window | 60 | No | 0.5.1 |
+### Memory settings
+
+`GRAVITINO_MEM` sets JVM heap/metaspace flags for the Gravitino server and is
also read by the Iceberg REST server and Lance REST server launchers.
+
+Default: `-Xms1024m -Xmx1024m -XX:MaxMetaspaceSize=512m` (see
`bin/common.sh`). Launch scripts append this to `JAVA_OPTS`; override
`GRAVITINO_MEM` when you need different heap/metaspace sizes.
+
+Typical values:
+- Development: `-Xms1g -Xmx1g -XX:MaxMetaspaceSize=512m`
+- Moderate production: `-Xms4g -Xmx4g -XX:MaxMetaspaceSize=1g`
+- Larger deployments: `-Xms8g -Xmx8g -XX:MaxMetaspaceSize=1g` or higher
depending on catalog count, plugins, and query concurrency
+
## Apache Gravitino catalog properties configuration
There are three types of catalog properties:
diff --git a/docs/iceberg-rest-service.md b/docs/iceberg-rest-service.md
index 7acb4ada26..4ee4976658 100644
--- a/docs/iceberg-rest-service.md
+++ b/docs/iceberg-rest-service.md
@@ -447,6 +447,14 @@ Gravitino provides the build-in
`org.apache.gravitino.iceberg.common.cache.Local
|---------------------------------------------|--------------------------------------------------------------|---------------|----------|------------------|
| `gravitino.iceberg-rest.extension-packages` | Comma-separated list of
Iceberg REST API packages to expand. | (none) | No |
0.7.0-incubating |
+### Memory settings
+
+The Iceberg REST server uses `GRAVITINO_MEM` for JVM heap/metaspace flags.
Default: `-Xms1024m -Xmx1024m -XX:MaxMetaspaceSize=512m`. Launch scripts append
`GRAVITINO_MEM` to `JAVA_OPTS`; set it to adjust heap/metaspace sizes.
+Example tuning:
+- Development: `GRAVITINO_MEM="-Xms1g -Xmx1g -XX:MaxMetaspaceSize=512m"`
+- Medium workloads: `GRAVITINO_MEM="-Xms4g -Xmx4g -XX:MaxMetaspaceSize=1g"`
+- Higher concurrency or catalog counts: increase heap and metaspace
accordingly.
+
## Starting the Iceberg REST server
To start as an auxiliary service with Gravitino server:
@@ -668,4 +676,3 @@ sh ./dev/docker/build-docker.sh --platform linux/arm64
--type iceberg-rest-serve
```
You could try Spark with Gravitino REST catalog service in our
[playground](./how-to-use-the-playground.md#using-apache-iceberg-rest-service).
-
