From 4a3ebf2614d09c311c66d0ddbff4fcf0f0c617aa Mon Sep 17 00:00:00 2001 From: Ayan Alam Date: Fri, 2 Oct 2026 22:49:30 +0530 Subject: [PATCH 01/19] doc(server): describe Server crash files and HStore image stdout logs apache/hugegraph#3258 makes the Server launcher always write heap dumps and JVM crash logs to logs/, even when JAVA_OPTIONS is set, and sets STDOUT_MODE=true in the HStore hugegraph/server image. - Server quickstart: after the startup options, describe the heap dump and crash log files, how to turn dumps off, which settings override the defaults, and what 1.7.0 does instead. - Docker cluster guide: the runtime-logs note said the HStore Server image does not log to stdout. Update it, say which output stays in files, and add the /hugegraph-server/logs mount for Kubernetes. The 1.7.0 behaviour moves to a version-scope note. English and Chinese pages are updated together. --- content/cn/docs/guides/hugegraph-docker-cluster.md | 9 ++++++++- .../cn/docs/quickstart/hugegraph/hugegraph-server.md | 8 ++++++++ content/en/docs/guides/hugegraph-docker-cluster.md | 11 ++++++++++- .../en/docs/quickstart/hugegraph/hugegraph-server.md | 9 +++++++++ 4 files changed, 35 insertions(+), 2 deletions(-) diff --git a/content/cn/docs/guides/hugegraph-docker-cluster.md b/content/cn/docs/guides/hugegraph-docker-cluster.md index 15df1a8afe..611770552e 100644 --- a/content/cn/docs/guides/hugegraph-docker-cluster.md +++ b/content/cn/docs/guides/hugegraph-docker-cluster.md @@ -293,7 +293,14 @@ curl -o /dev/null -w '%{http_code}\n' -u "admin:${HUGEGRAPH_ADMIN_PASSWORD}" \ 5. **数据在意料之外地保留了下来**：`docker compose down` 会保留命名卷。要同时删除该拓扑的数据，请使用 `docker compose down -v` -**查看运行时日志**：使用 `docker logs `（如 `docker logs hg-pd0`）可直接查看日志，无需进入容器。单机镜像 `hugegraph/hugegraph` 设置了 `STDOUT_MODE=true`，其服务日志会输出到容器 stdout。`hugegraph/server`（HStore）镜像没有设置该变量，因此对 HStore 拓扑的 Server 执行 `docker logs` 只能看到入口脚本的输出，其余内容需在容器内查看 `logs/hugegraph-server.log`。 +**查看运行时日志**：使用 `docker logs `（如 `docker logs hg-pd0`）可直接查看日志，无需进入容器。PD、Store 以及两个 Server 镜像（`hugegraph/hugegraph` +和 HStore 的 `hugegraph/server`）都设置了 `STDOUT_MODE=true`，服务日志会输出到容器 stdout。对 Server 而言，Hadoop、ZooKeeper、SOFA、Netty 和 Commons 的 WARN +及以上日志也会输出到 stdout；它们的 INFO 日志以及审计日志、慢查询日志仍只写入文件。完整的 `hugegraph-server.log`、JVM 崩溃日志（`hs_err_pid*.log`）和内存溢出 +堆转储（`java_pid*.hprof`）位于 `/hugegraph-server/logs`。`docker restart` 会保留这些文件，但 Kubernetes 每次重启都会新建容器，因此需要在 +`/hugegraph-server/logs` 挂载 `emptyDir` 或 PersistentVolumeClaim 来保留它们，并按与 JVM 堆同样大小的堆转储预留空间。 + +> **版本范围**：上述 HStore `hugegraph/server` 的行为适用于当前 master（[apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)）。1.7.0 +> 及更早的 `hugegraph/server` 镜像没有设置 `STDOUT_MODE`，`docker logs` 只能看到入口脚本的输出，服务日志需在容器内查看 `logs/hugegraph-server.log`。 ## 容器监控与健康检查 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index 481d2108c5..0fc2c9ea62 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md @@ -536,6 +536,14 @@ Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)......OK `bin/stop-hugegraph.sh` 支持 `-m true|false`（默认 `true`），用于控制停止服务时是否同时移除 crontab 监控任务。 +服务脚本总会添加 `-XX:+HeapDumpOnOutOfMemoryError`、`-XX:HeapDumpPath` 和 `-XX:ErrorFile`，因此无论是否设置了 `JAVA_OPTIONS`，内存溢出时的堆转储 +（`java_pid_<启动时间>.hprof`）和 JVM 崩溃日志（`hs_err_pid_<启动时间>.log`）都会写入 `logs/`。文件名带上启动时间，是为了避免重启后复用相同 PID +时与旧文件冲突。堆转储可能和堆一样大。如需关闭，可通过 `-j` 传入 `-XX:-HeapDumpOnOutOfMemoryError`；如果设置了 `JAVA_OPTIONS`，则写在 `JAVA_OPTIONS` +中（设置 `JAVA_OPTIONS` 后 `-j` 不生效）。在这些位置为上述参数指定的值会覆盖默认值；已在 `JAVA_TOOL_OPTIONS` 或 `JDK_JAVA_OPTIONS` 中设置的参数保持不变。 + +> **版本范围**：以上行为适用于当前 master（[apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)）。1.7.0 只在未设置 `JAVA_OPTIONS` +> 时添加堆转储参数，JVM 崩溃日志写入安装目录。 + ### 5.2 使用 Docker 在 [3.1 使用 Docker 容器](#31-使用-docker-容器-便于测试) 中，我们已经介绍了如何使用 `docker` 部署 Server 服务。还可以通过切换后端存储或设置参数，在 Server 启动时加载样例图。 diff --git a/content/en/docs/guides/hugegraph-docker-cluster.md b/content/en/docs/guides/hugegraph-docker-cluster.md index 098aa946bc..ffa74b3f25 100644 --- a/content/en/docs/guides/hugegraph-docker-cluster.md +++ b/content/en/docs/guides/hugegraph-docker-cluster.md @@ -293,7 +293,16 @@ Standalone publishes only `8080` and `8088`; minimal HStore publishes `8620` (PD 5. **Unexpected retained data**: `docker compose down` keeps named volumes. To delete topology data too, use `docker compose down -v`. -**Runtime logs**: `docker logs ` (for example, `docker logs hg-pd0`) shows logs without entering containers. Standalone `hugegraph/hugegraph` sets `STDOUT_MODE=true` and sends service logs to stdout. The HStore `hugegraph/server` image does not set this variable: `docker logs` shows only entrypoint output; inspect `logs/hugegraph-server.log` inside the container for service logs. +**Runtime logs**: `docker logs ` (for example, `docker logs hg-pd0`) shows logs without entering containers. The PD, Store and both Server +images (`hugegraph/hugegraph` and the HStore `hugegraph/server`) set `STDOUT_MODE=true` and send service logs to stdout. For the Server, WARN and above from +Hadoop, ZooKeeper, SOFA, Netty and Commons also reaches stdout; their INFO output and the audit and slow-query logs stay in files. The full +`hugegraph-server.log`, JVM crash logs (`hs_err_pid*.log`) and out-of-memory heap dumps (`java_pid*.hprof`) are in `/hugegraph-server/logs`. `docker restart` +keeps them, but Kubernetes starts a new container on every restart, so mount an `emptyDir` or a PersistentVolumeClaim at `/hugegraph-server/logs` to keep +them, sized for a heap dump as large as the JVM heap. + +> **Version scope**: the HStore `hugegraph/server` behavior above applies to current master +> ([apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)). In 1.7.0 and older `hugegraph/server` images `STDOUT_MODE` is unset, so +> `docker logs` shows only entrypoint output; inspect `logs/hugegraph-server.log` inside the container for service logs. ## Container Monitoring and Health Checks diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index fc62026772..486c40d72f 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -535,6 +535,15 @@ This indicates the successful creation of the sample graph. `bin/stop-hugegraph.sh` accepts `-m true|false` (default `true`), which controls whether the cron monitor task is removed along with the service. +The server script always adds `-XX:+HeapDumpOnOutOfMemoryError`, `-XX:HeapDumpPath` and `-XX:ErrorFile`, so an out-of-memory heap dump +(`java_pid_.hprof`) and a JVM crash log (`hs_err_pid_.log`) land in `logs/` whether or not `JAVA_OPTIONS` is set. The +launch time keeps a restart that reuses the PID from colliding with an earlier file. A heap dump can be as large as the heap. To turn dumps off, pass +`-XX:-HeapDumpOnOutOfMemoryError` with `-j`, or in `JAVA_OPTIONS` if you set it (`-j` is ignored when `JAVA_OPTIONS` is set). A value given there for any of +these flags overrides the default, and a flag already set in `JAVA_TOOL_OPTIONS` or `JDK_JAVA_OPTIONS` is left as is. + +> **Version scope**: this applies to current master ([apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)). In 1.7.0 the heap dump +> flags are added only when `JAVA_OPTIONS` is unset, and JVM crash logs go to the install directory. + ### 5.2 Use Docker to startup In [3.1 Use Docker container](#31-use-docker-container-convenient-for-testdev), we introduced how to deploy `hugegraph-server` with Docker. You can also switch storage backends or preload a sample graph by setting the corresponding parameters. From 93e41d4f20a574b793787dfaaf29745bafe9836d Mon Sep 17 00:00:00 2001 From: Ayan Alam Date: Sun, 4 Oct 2026 09:47:52 +0530 Subject: [PATCH 02/19] doc(server): scope stdout logging to master images and update crash files Review follow-ups: - Docker cluster guide: no 1.7.0 image sets STDOUT_MODE, the standalone hugegraph/hugegraph:1.7.0 used on the page included. Describe stdout logging as current master behaviour for all images, and widen the version note to every 1.7.0 and older image, linking #2980 and #3258. - Server quickstart: the defaults now go first in JAVA_TOOL_OPTIONS (apache/hugegraph#3258), so list every source that overrides them, _JAVA_OPTIONS included, describe the counter added to a taken file name, and mention the "Picked up JAVA_TOOL_OPTIONS" startup line. - Chinese pages: wrap only at existing spaces, so a soft break no longer renders as a space between two Chinese characters. --- .../docs/guides/hugegraph-docker-cluster.md | 16 +++++++------- .../quickstart/hugegraph/hugegraph-server.md | 8 +++---- .../docs/guides/hugegraph-docker-cluster.md | 21 ++++++++++--------- .../quickstart/hugegraph/hugegraph-server.md | 11 +++++----- 4 files changed, 29 insertions(+), 27 deletions(-) diff --git a/content/cn/docs/guides/hugegraph-docker-cluster.md b/content/cn/docs/guides/hugegraph-docker-cluster.md index 611770552e..6793870a99 100644 --- a/content/cn/docs/guides/hugegraph-docker-cluster.md +++ b/content/cn/docs/guides/hugegraph-docker-cluster.md @@ -293,14 +293,14 @@ curl -o /dev/null -w '%{http_code}\n' -u "admin:${HUGEGRAPH_ADMIN_PASSWORD}" \ 5. **数据在意料之外地保留了下来**：`docker compose down` 会保留命名卷。要同时删除该拓扑的数据，请使用 `docker compose down -v` -**查看运行时日志**：使用 `docker logs `（如 `docker logs hg-pd0`）可直接查看日志，无需进入容器。PD、Store 以及两个 Server 镜像（`hugegraph/hugegraph` -和 HStore 的 `hugegraph/server`）都设置了 `STDOUT_MODE=true`，服务日志会输出到容器 stdout。对 Server 而言，Hadoop、ZooKeeper、SOFA、Netty 和 Commons 的 WARN -及以上日志也会输出到 stdout；它们的 INFO 日志以及审计日志、慢查询日志仍只写入文件。完整的 `hugegraph-server.log`、JVM 崩溃日志（`hs_err_pid*.log`）和内存溢出 -堆转储（`java_pid*.hprof`）位于 `/hugegraph-server/logs`。`docker restart` 会保留这些文件，但 Kubernetes 每次重启都会新建容器，因此需要在 -`/hugegraph-server/logs` 挂载 `emptyDir` 或 PersistentVolumeClaim 来保留它们，并按与 JVM 堆同样大小的堆转储预留空间。 - -> **版本范围**：上述 HStore `hugegraph/server` 的行为适用于当前 master（[apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)）。1.7.0 -> 及更早的 `hugegraph/server` 镜像没有设置 `STDOUT_MODE`，`docker logs` 只能看到入口脚本的输出，服务日志需在容器内查看 `logs/hugegraph-server.log`。 +**查看运行时日志**：使用 `docker logs `（如 `docker logs hg-pd0`）可直接查看日志，无需进入容器。基于当前 master 构建的 PD、Store 以及两个 Server 镜像（`hugegraph/hugegraph` 和 HStore 的 +`hugegraph/server`）都设置了 `STDOUT_MODE=true`，服务日志会输出到容器 stdout。对 Server 而言，Hadoop、ZooKeeper、SOFA、Netty 和 Commons 的 WARN 及以上日志也会输出到 stdout；它们的 INFO +日志以及审计日志、慢查询日志仍只写入文件。完整的 `hugegraph-server.log`、JVM 崩溃日志（`hs_err_pid*.log`）和内存溢出堆转储（`java_pid*.hprof`）位于 `/hugegraph-server/logs`。`docker restart` 会保留这些文件，但 +Kubernetes 每次重启都会新建容器，因此需要在 `/hugegraph-server/logs` 挂载 `emptyDir` 或 PersistentVolumeClaim 来保留它们，并按与 JVM 堆同样大小的堆转储预留空间。 + +> **版本范围**：上文描述的是基于当前 master 构建的镜像（PD、Store 和单机 Server 见 [apache/hugegraph#2980](https://github.com/apache/hugegraph/pull/2980)，HStore Server 见 +> [apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)）。1.7.0 及更早的镜像都没有设置 `STDOUT_MODE`，包括上文使用的单机镜像 `hugegraph/hugegraph:1.7.0`：`docker logs` +> 只能看到入口脚本的输出，服务日志仍在容器内的 `logs/` 中（Server 为 `logs/hugegraph-server.log`）。 ## 容器监控与健康检查 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index 0fc2c9ea62..e650bbecf7 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md @@ -536,10 +536,10 @@ Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)......OK `bin/stop-hugegraph.sh` 支持 `-m true|false`（默认 `true`），用于控制停止服务时是否同时移除 crontab 监控任务。 -服务脚本总会添加 `-XX:+HeapDumpOnOutOfMemoryError`、`-XX:HeapDumpPath` 和 `-XX:ErrorFile`，因此无论是否设置了 `JAVA_OPTIONS`，内存溢出时的堆转储 -（`java_pid_<启动时间>.hprof`）和 JVM 崩溃日志（`hs_err_pid_<启动时间>.log`）都会写入 `logs/`。文件名带上启动时间，是为了避免重启后复用相同 PID -时与旧文件冲突。堆转储可能和堆一样大。如需关闭，可通过 `-j` 传入 `-XX:-HeapDumpOnOutOfMemoryError`；如果设置了 `JAVA_OPTIONS`，则写在 `JAVA_OPTIONS` -中（设置 `JAVA_OPTIONS` 后 `-j` 不生效）。在这些位置为上述参数指定的值会覆盖默认值；已在 `JAVA_TOOL_OPTIONS` 或 `JDK_JAVA_OPTIONS` 中设置的参数保持不变。 +服务脚本会把 `-XX:+HeapDumpOnOutOfMemoryError`、`-XX:HeapDumpPath` 和 `-XX:ErrorFile` 放在 `JAVA_TOOL_OPTIONS` 的最前面，因此内存溢出时的堆转储（`java_pid_<启动时间>.hprof`）和 JVM +崩溃日志（`hs_err_pid_<启动时间>.log`）都会写入 `logs/`，与是否设置 `JAVA_OPTIONS` 无关。如果同名文件已存在（例如重启后在同一秒内复用了相同 PID），文件名会再加上计数（`<启动时间>-1`、`-2`……）。堆转储可能和堆一样大。JVM +会在这些默认值之后读取你自己的 `JAVA_TOOL_OPTIONS`、`JDK_JAVA_OPTIONS`、命令行（`JAVA_OPTIONS`，未设置 `JAVA_OPTIONS` 时为 `-j`）和 `_JAVA_OPTIONS`，因此在其中任意一处为上述参数指定的值都会覆盖默认值。例如，可通过 `-j` 传入 +`-XX:-HeapDumpOnOutOfMemoryError` 来关闭堆转储。由于这些默认值，JVM 启动时会输出 `Picked up JAVA_TOOL_OPTIONS: ...`。 > **版本范围**：以上行为适用于当前 master（[apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)）。1.7.0 只在未设置 `JAVA_OPTIONS` > 时添加堆转储参数，JVM 崩溃日志写入安装目录。 diff --git a/content/en/docs/guides/hugegraph-docker-cluster.md b/content/en/docs/guides/hugegraph-docker-cluster.md index ffa74b3f25..f070b099cd 100644 --- a/content/en/docs/guides/hugegraph-docker-cluster.md +++ b/content/en/docs/guides/hugegraph-docker-cluster.md @@ -293,16 +293,17 @@ Standalone publishes only `8080` and `8088`; minimal HStore publishes `8620` (PD 5. **Unexpected retained data**: `docker compose down` keeps named volumes. To delete topology data too, use `docker compose down -v`. -**Runtime logs**: `docker logs ` (for example, `docker logs hg-pd0`) shows logs without entering containers. The PD, Store and both Server -images (`hugegraph/hugegraph` and the HStore `hugegraph/server`) set `STDOUT_MODE=true` and send service logs to stdout. For the Server, WARN and above from -Hadoop, ZooKeeper, SOFA, Netty and Commons also reaches stdout; their INFO output and the audit and slow-query logs stay in files. The full -`hugegraph-server.log`, JVM crash logs (`hs_err_pid*.log`) and out-of-memory heap dumps (`java_pid*.hprof`) are in `/hugegraph-server/logs`. `docker restart` -keeps them, but Kubernetes starts a new container on every restart, so mount an `emptyDir` or a PersistentVolumeClaim at `/hugegraph-server/logs` to keep -them, sized for a heap dump as large as the JVM heap. - -> **Version scope**: the HStore `hugegraph/server` behavior above applies to current master -> ([apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)). In 1.7.0 and older `hugegraph/server` images `STDOUT_MODE` is unset, so -> `docker logs` shows only entrypoint output; inspect `logs/hugegraph-server.log` inside the container for service logs. +**Runtime logs**: `docker logs ` (for example, `docker logs hg-pd0`) shows logs without entering containers. In images built from current +master, the PD, Store and both Server images (`hugegraph/hugegraph` and the HStore `hugegraph/server`) set `STDOUT_MODE=true` and send service logs to stdout. +For the Server, WARN and above from Hadoop, ZooKeeper, SOFA, Netty and Commons also reaches stdout; their INFO output and the audit and slow-query logs stay in +files. The full `hugegraph-server.log`, JVM crash logs (`hs_err_pid*.log`) and out-of-memory heap dumps (`java_pid*.hprof`) are in `/hugegraph-server/logs`. +`docker restart` keeps them, but Kubernetes starts a new container on every restart, so mount an `emptyDir` or a PersistentVolumeClaim at +`/hugegraph-server/logs` to keep them, sized for a heap dump as large as the JVM heap. + +> **Version scope**: the paragraph above describes current master images ([apache/hugegraph#2980](https://github.com/apache/hugegraph/pull/2980) for PD, Store +> and the standalone Server, [apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258) for the HStore Server). No 1.7.0 or older image sets +> `STDOUT_MODE`, including the standalone `hugegraph/hugegraph:1.7.0` used above: `docker logs` shows only entrypoint output, and service logs stay in `logs/` +> inside the container (`logs/hugegraph-server.log` for the Server). ## Container Monitoring and Health Checks diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index 486c40d72f..b8277fd5e4 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -535,11 +535,12 @@ This indicates the successful creation of the sample graph. `bin/stop-hugegraph.sh` accepts `-m true|false` (default `true`), which controls whether the cron monitor task is removed along with the service. -The server script always adds `-XX:+HeapDumpOnOutOfMemoryError`, `-XX:HeapDumpPath` and `-XX:ErrorFile`, so an out-of-memory heap dump -(`java_pid_.hprof`) and a JVM crash log (`hs_err_pid_.log`) land in `logs/` whether or not `JAVA_OPTIONS` is set. The -launch time keeps a restart that reuses the PID from colliding with an earlier file. A heap dump can be as large as the heap. To turn dumps off, pass -`-XX:-HeapDumpOnOutOfMemoryError` with `-j`, or in `JAVA_OPTIONS` if you set it (`-j` is ignored when `JAVA_OPTIONS` is set). A value given there for any of -these flags overrides the default, and a flag already set in `JAVA_TOOL_OPTIONS` or `JDK_JAVA_OPTIONS` is left as is. +The server script puts `-XX:+HeapDumpOnOutOfMemoryError`, `-XX:HeapDumpPath` and `-XX:ErrorFile` first in `JAVA_TOOL_OPTIONS`, so an out-of-memory heap dump +(`java_pid_.hprof`) and a JVM crash log (`hs_err_pid_.log`) land in `logs/` whether or not `JAVA_OPTIONS` is set. If a file +with that name already exists, for example after a restart that reuses the PID within the same second, a counter is added (`-1`, `-2`, ...). A heap +dump can be as large as the heap. The JVM reads your own `JAVA_TOOL_OPTIONS`, `JDK_JAVA_OPTIONS`, the command line (`JAVA_OPTIONS`, or `-j` when `JAVA_OPTIONS` +is unset) and `_JAVA_OPTIONS` after these defaults, so a value for one of these flags in any of them overrides the default. For example, pass +`-XX:-HeapDumpOnOutOfMemoryError` with `-j` to turn dumps off. Because of the defaults, the JVM prints `Picked up JAVA_TOOL_OPTIONS: ...` at startup. > **Version scope**: this applies to current master ([apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)). In 1.7.0 the heap dump > flags are added only when `JAVA_OPTIONS` is unset, and JVM crash logs go to the install directory. From d88623e6d4f2c2284da995021a18e5cc622a6e06 Mon Sep 17 00:00:00 2001 From: Ayan Alam Date: Sun, 4 Oct 2026 20:58:59 +0530 Subject: [PATCH 03/19] doc(server): warn that repeated OOM dumps accumulate in logs/ Every launch writes its heap dump to a new file (apache/hugegraph#3258), so a server that keeps running out of memory adds a heap-sized dump per restart until the volume is full. Say that nothing removes old dumps, and how to size the volume, clean up, or turn dumps off, in the Docker guide and the Server quickstart, English and Chinese. --- content/cn/docs/guides/hugegraph-docker-cluster.md | 4 +++- content/cn/docs/quickstart/hugegraph/hugegraph-server.md | 5 +++-- content/en/docs/guides/hugegraph-docker-cluster.md | 5 ++++- content/en/docs/quickstart/hugegraph/hugegraph-server.md | 8 +++++--- 4 files changed, 15 insertions(+), 7 deletions(-) diff --git a/content/cn/docs/guides/hugegraph-docker-cluster.md b/content/cn/docs/guides/hugegraph-docker-cluster.md index 6793870a99..508a80289a 100644 --- a/content/cn/docs/guides/hugegraph-docker-cluster.md +++ b/content/cn/docs/guides/hugegraph-docker-cluster.md @@ -296,7 +296,9 @@ curl -o /dev/null -w '%{http_code}\n' -u "admin:${HUGEGRAPH_ADMIN_PASSWORD}" \ **查看运行时日志**：使用 `docker logs `（如 `docker logs hg-pd0`）可直接查看日志，无需进入容器。基于当前 master 构建的 PD、Store 以及两个 Server 镜像（`hugegraph/hugegraph` 和 HStore 的 `hugegraph/server`）都设置了 `STDOUT_MODE=true`，服务日志会输出到容器 stdout。对 Server 而言，Hadoop、ZooKeeper、SOFA、Netty 和 Commons 的 WARN 及以上日志也会输出到 stdout；它们的 INFO 日志以及审计日志、慢查询日志仍只写入文件。完整的 `hugegraph-server.log`、JVM 崩溃日志（`hs_err_pid*.log`）和内存溢出堆转储（`java_pid*.hprof`）位于 `/hugegraph-server/logs`。`docker restart` 会保留这些文件，但 -Kubernetes 每次重启都会新建容器，因此需要在 `/hugegraph-server/logs` 挂载 `emptyDir` 或 PersistentVolumeClaim 来保留它们，并按与 JVM 堆同样大小的堆转储预留空间。 +Kubernetes 每次重启都会新建容器，因此需要在 `/hugegraph-server/logs` 挂载 `emptyDir` 或 PersistentVolumeClaim 来保留它们。堆转储可能和 JVM 堆一样大，而且每次启动都会写入新文件，因此反复内存溢出的 Server +每重启一次就会多一个与堆同样大小的转储，直到卷被写满。无论使用 `emptyDir`（它在容器重启后同样保留）还是 PVC，启动脚本都不会删除旧的转储。请按需要保留的转储数量加上日志所需空间来规划卷大小，每次排查后移走或删除旧的 `java_pid*.hprof` 文件，或通过 +`-XX:-HeapDumpOnOutOfMemoryError` 关闭堆转储。 > **版本范围**：上文描述的是基于当前 master 构建的镜像（PD、Store 和单机 Server 见 [apache/hugegraph#2980](https://github.com/apache/hugegraph/pull/2980)，HStore Server 见 > [apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)）。1.7.0 及更早的镜像都没有设置 `STDOUT_MODE`，包括上文使用的单机镜像 `hugegraph/hugegraph:1.7.0`：`docker logs` diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index e650bbecf7..06e3dd3e68 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md @@ -537,8 +537,9 @@ Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)......OK `bin/stop-hugegraph.sh` 支持 `-m true|false`（默认 `true`），用于控制停止服务时是否同时移除 crontab 监控任务。 服务脚本会把 `-XX:+HeapDumpOnOutOfMemoryError`、`-XX:HeapDumpPath` 和 `-XX:ErrorFile` 放在 `JAVA_TOOL_OPTIONS` 的最前面，因此内存溢出时的堆转储（`java_pid_<启动时间>.hprof`）和 JVM -崩溃日志（`hs_err_pid_<启动时间>.log`）都会写入 `logs/`，与是否设置 `JAVA_OPTIONS` 无关。如果同名文件已存在（例如重启后在同一秒内复用了相同 PID），文件名会再加上计数（`<启动时间>-1`、`-2`……）。堆转储可能和堆一样大。JVM -会在这些默认值之后读取你自己的 `JAVA_TOOL_OPTIONS`、`JDK_JAVA_OPTIONS`、命令行（`JAVA_OPTIONS`，未设置 `JAVA_OPTIONS` 时为 `-j`）和 `_JAVA_OPTIONS`，因此在其中任意一处为上述参数指定的值都会覆盖默认值。例如，可通过 `-j` 传入 +崩溃日志（`hs_err_pid_<启动时间>.log`）都会写入 `logs/`，与是否设置 `JAVA_OPTIONS` 无关。如果同名文件已存在（例如重启后在同一秒内复用了相同 +PID），文件名会再加上计数（`<启动时间>-1`、`-2`……）。堆转储可能和堆一样大，且旧的转储不会被删除，反复内存溢出的服务每重启一次就会在 `logs/` 中多一个转储；每次排查后请移走或删除旧的 `java_pid*.hprof` 文件。JVM 会在这些默认值之后读取你自己的 +`JAVA_TOOL_OPTIONS`、`JDK_JAVA_OPTIONS`、命令行（`JAVA_OPTIONS`，未设置 `JAVA_OPTIONS` 时为 `-j`）和 `_JAVA_OPTIONS`，因此在其中任意一处为上述参数指定的值都会覆盖默认值。例如，可通过 `-j` 传入 `-XX:-HeapDumpOnOutOfMemoryError` 来关闭堆转储。由于这些默认值，JVM 启动时会输出 `Picked up JAVA_TOOL_OPTIONS: ...`。 > **版本范围**：以上行为适用于当前 master（[apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)）。1.7.0 只在未设置 `JAVA_OPTIONS` diff --git a/content/en/docs/guides/hugegraph-docker-cluster.md b/content/en/docs/guides/hugegraph-docker-cluster.md index f070b099cd..2a2107c358 100644 --- a/content/en/docs/guides/hugegraph-docker-cluster.md +++ b/content/en/docs/guides/hugegraph-docker-cluster.md @@ -298,7 +298,10 @@ master, the PD, Store and both Server images (`hugegraph/hugegraph` and the HSto For the Server, WARN and above from Hadoop, ZooKeeper, SOFA, Netty and Commons also reaches stdout; their INFO output and the audit and slow-query logs stay in files. The full `hugegraph-server.log`, JVM crash logs (`hs_err_pid*.log`) and out-of-memory heap dumps (`java_pid*.hprof`) are in `/hugegraph-server/logs`. `docker restart` keeps them, but Kubernetes starts a new container on every restart, so mount an `emptyDir` or a PersistentVolumeClaim at -`/hugegraph-server/logs` to keep them, sized for a heap dump as large as the JVM heap. +`/hugegraph-server/logs` to keep them. A heap dump can be as large as the JVM heap, and every launch writes to a new file, so a Server that keeps running out of +memory adds one heap-sized dump per restart until the volume is full. The launcher never removes old dumps, whether the volume is an `emptyDir` (which also +survives container restarts) or a PVC. Size the volume for the number of dumps you want to keep plus the logs, move or delete old `java_pid*.hprof` files after +each incident, or turn dumps off with `-XX:-HeapDumpOnOutOfMemoryError`. > **Version scope**: the paragraph above describes current master images ([apache/hugegraph#2980](https://github.com/apache/hugegraph/pull/2980) for PD, Store > and the standalone Server, [apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258) for the HStore Server). No 1.7.0 or older image sets diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index b8277fd5e4..31898270c4 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -538,9 +538,11 @@ This indicates the successful creation of the sample graph. The server script puts `-XX:+HeapDumpOnOutOfMemoryError`, `-XX:HeapDumpPath` and `-XX:ErrorFile` first in `JAVA_TOOL_OPTIONS`, so an out-of-memory heap dump (`java_pid_.hprof`) and a JVM crash log (`hs_err_pid_.log`) land in `logs/` whether or not `JAVA_OPTIONS` is set. If a file with that name already exists, for example after a restart that reuses the PID within the same second, a counter is added (`-1`, `-2`, ...). A heap -dump can be as large as the heap. The JVM reads your own `JAVA_TOOL_OPTIONS`, `JDK_JAVA_OPTIONS`, the command line (`JAVA_OPTIONS`, or `-j` when `JAVA_OPTIONS` -is unset) and `_JAVA_OPTIONS` after these defaults, so a value for one of these flags in any of them overrides the default. For example, pass -`-XX:-HeapDumpOnOutOfMemoryError` with `-j` to turn dumps off. Because of the defaults, the JVM prints `Picked up JAVA_TOOL_OPTIONS: ...` at startup. +dump can be as large as the heap, and old dumps are never removed, so a server that keeps running out of memory fills `logs/` with one dump per restart; move or +delete old `java_pid*.hprof` files after each incident. The JVM reads your own `JAVA_TOOL_OPTIONS`, `JDK_JAVA_OPTIONS`, the command line (`JAVA_OPTIONS`, or +`-j` when `JAVA_OPTIONS` is unset) and `_JAVA_OPTIONS` after these defaults, so a value for one of these flags in any of them overrides the default. For +example, pass `-XX:-HeapDumpOnOutOfMemoryError` with `-j` to turn dumps off. Because of the defaults, the JVM prints `Picked up JAVA_TOOL_OPTIONS: ...` at +startup. > **Version scope**: this applies to current master ([apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)). In 1.7.0 the heap dump > flags are added only when `JAVA_OPTIONS` is unset, and JVM crash logs go to the install directory. From 3bcb969a03bcb5bdd5ff702a44d5388ce7329124 Mon Sep 17 00:00:00 2001 From: Ayan Alam Date: Mon, 5 Oct 2026 19:48:02 +0530 Subject: [PATCH 04/19] doc(server): add the host name to the crash-file names apache/hugegraph#3258 now puts the host name, the pod name on Kubernetes, into heap dump and crash log names so servers sharing one log directory do not pick the same name. Update the Server quickstart in English and Chinese to match. --- .../docs/quickstart/hugegraph/hugegraph-server.md | 4 ++-- .../docs/quickstart/hugegraph/hugegraph-server.md | 14 +++++++------- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index 06e3dd3e68..a7dbe19f8f 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md @@ -536,8 +536,8 @@ Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)......OK `bin/stop-hugegraph.sh` 支持 `-m true|false`（默认 `true`），用于控制停止服务时是否同时移除 crontab 监控任务。 -服务脚本会把 `-XX:+HeapDumpOnOutOfMemoryError`、`-XX:HeapDumpPath` 和 `-XX:ErrorFile` 放在 `JAVA_TOOL_OPTIONS` 的最前面，因此内存溢出时的堆转储（`java_pid_<启动时间>.hprof`）和 JVM -崩溃日志（`hs_err_pid_<启动时间>.log`）都会写入 `logs/`，与是否设置 `JAVA_OPTIONS` 无关。如果同名文件已存在（例如重启后在同一秒内复用了相同 +服务脚本会把 `-XX:+HeapDumpOnOutOfMemoryError`、`-XX:HeapDumpPath` 和 `-XX:ErrorFile` 放在 `JAVA_TOOL_OPTIONS` 的最前面，因此内存溢出时的堆转储（`java_pid_<主机名>_<启动时间>.hprof`）和 JVM +崩溃日志（`hs_err_pid_<主机名>_<启动时间>.log`）都会写入 `logs/`，与是否设置 `JAVA_OPTIONS` 无关。文件名中的主机名（在 Kubernetes 上即 Pod 名）可避免共用同一日志目录的多个服务选到相同的文件名。如果同名文件已存在（例如重启后在同一秒内复用了相同 PID），文件名会再加上计数（`<启动时间>-1`、`-2`……）。堆转储可能和堆一样大，且旧的转储不会被删除，反复内存溢出的服务每重启一次就会在 `logs/` 中多一个转储；每次排查后请移走或删除旧的 `java_pid*.hprof` 文件。JVM 会在这些默认值之后读取你自己的 `JAVA_TOOL_OPTIONS`、`JDK_JAVA_OPTIONS`、命令行（`JAVA_OPTIONS`，未设置 `JAVA_OPTIONS` 时为 `-j`）和 `_JAVA_OPTIONS`，因此在其中任意一处为上述参数指定的值都会覆盖默认值。例如，可通过 `-j` 传入 `-XX:-HeapDumpOnOutOfMemoryError` 来关闭堆转储。由于这些默认值，JVM 启动时会输出 `Picked up JAVA_TOOL_OPTIONS: ...`。 diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index 31898270c4..2b5bb01724 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -536,13 +536,13 @@ This indicates the successful creation of the sample graph. `bin/stop-hugegraph.sh` accepts `-m true|false` (default `true`), which controls whether the cron monitor task is removed along with the service. The server script puts `-XX:+HeapDumpOnOutOfMemoryError`, `-XX:HeapDumpPath` and `-XX:ErrorFile` first in `JAVA_TOOL_OPTIONS`, so an out-of-memory heap dump -(`java_pid_.hprof`) and a JVM crash log (`hs_err_pid_.log`) land in `logs/` whether or not `JAVA_OPTIONS` is set. If a file -with that name already exists, for example after a restart that reuses the PID within the same second, a counter is added (`-1`, `-2`, ...). A heap -dump can be as large as the heap, and old dumps are never removed, so a server that keeps running out of memory fills `logs/` with one dump per restart; move or -delete old `java_pid*.hprof` files after each incident. The JVM reads your own `JAVA_TOOL_OPTIONS`, `JDK_JAVA_OPTIONS`, the command line (`JAVA_OPTIONS`, or -`-j` when `JAVA_OPTIONS` is unset) and `_JAVA_OPTIONS` after these defaults, so a value for one of these flags in any of them overrides the default. For -example, pass `-XX:-HeapDumpOnOutOfMemoryError` with `-j` to turn dumps off. Because of the defaults, the JVM prints `Picked up JAVA_TOOL_OPTIONS: ...` at -startup. +(`java_pid__.hprof`) and a JVM crash log (`hs_err_pid__.log`) land in `logs/` whether or not `JAVA_OPTIONS` is +set. The host name (the pod name on Kubernetes) keeps servers that share one log directory from picking the same name. If a file with that name already exists, +for example after a restart that reuses the PID within the same second, a counter is added (`-1`, `-2`, ...). A heap dump can be as large as the +heap, and old dumps are never removed, so a server that keeps running out of memory fills `logs/` with one dump per restart; move or delete old +`java_pid*.hprof` files after each incident. The JVM reads your own `JAVA_TOOL_OPTIONS`, `JDK_JAVA_OPTIONS`, the command line (`JAVA_OPTIONS`, or `-j` when +`JAVA_OPTIONS` is unset) and `_JAVA_OPTIONS` after these defaults, so a value for one of these flags in any of them overrides the default. For example, pass +`-XX:-HeapDumpOnOutOfMemoryError` with `-j` to turn dumps off. Because of the defaults, the JVM prints `Picked up JAVA_TOOL_OPTIONS: ...` at startup. > **Version scope**: this applies to current master ([apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)). In 1.7.0 the heap dump > flags are added only when `JAVA_OPTIONS` is unset, and JVM crash logs go to the install directory. From 1a82afdf67fae1a2a30e599ae3430d573796e4ec Mon Sep 17 00:00:00 2001 From: Ayan Alam Date: Tue, 6 Oct 2026 00:53:22 +0530 Subject: [PATCH 05/19] doc(server): say where container operators turn off heap dumps The Docker entrypoint passes JAVA_OPTS to the launcher with -j, so the quickstart's -j route does not apply in a container. Recommend JAVA_TOOL_OPTIONS for -XX:-HeapDumpOnOutOfMemoryError, which keeps the image's default JAVA_OPTS, and note that setting JAVA_OPTS replaces that default. English and Chinese. --- content/cn/docs/guides/hugegraph-docker-cluster.md | 5 +++-- content/en/docs/guides/hugegraph-docker-cluster.md | 3 ++- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/content/cn/docs/guides/hugegraph-docker-cluster.md b/content/cn/docs/guides/hugegraph-docker-cluster.md index 508a80289a..79cb03688f 100644 --- a/content/cn/docs/guides/hugegraph-docker-cluster.md +++ b/content/cn/docs/guides/hugegraph-docker-cluster.md @@ -297,8 +297,9 @@ curl -o /dev/null -w '%{http_code}\n' -u "admin:${HUGEGRAPH_ADMIN_PASSWORD}" \ `hugegraph/server`）都设置了 `STDOUT_MODE=true`，服务日志会输出到容器 stdout。对 Server 而言，Hadoop、ZooKeeper、SOFA、Netty 和 Commons 的 WARN 及以上日志也会输出到 stdout；它们的 INFO 日志以及审计日志、慢查询日志仍只写入文件。完整的 `hugegraph-server.log`、JVM 崩溃日志（`hs_err_pid*.log`）和内存溢出堆转储（`java_pid*.hprof`）位于 `/hugegraph-server/logs`。`docker restart` 会保留这些文件，但 Kubernetes 每次重启都会新建容器，因此需要在 `/hugegraph-server/logs` 挂载 `emptyDir` 或 PersistentVolumeClaim 来保留它们。堆转储可能和 JVM 堆一样大，而且每次启动都会写入新文件，因此反复内存溢出的 Server -每重启一次就会多一个与堆同样大小的转储，直到卷被写满。无论使用 `emptyDir`（它在容器重启后同样保留）还是 PVC，启动脚本都不会删除旧的转储。请按需要保留的转储数量加上日志所需空间来规划卷大小，每次排查后移走或删除旧的 `java_pid*.hprof` 文件，或通过 -`-XX:-HeapDumpOnOutOfMemoryError` 关闭堆转储。 +每重启一次就会多一个与堆同样大小的转储，直到卷被写满。无论使用 `emptyDir`（它在容器重启后同样保留）还是 PVC，启动脚本都不会删除旧的转储。请按需要保留的转储数量加上日志所需空间来规划卷大小，每次排查后移走或删除旧的 `java_pid*.hprof` 文件，或设置 +`JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError` 关闭堆转储，这样会保留镜像默认的 `JAVA_OPTS`。也可以把该参数加到 `JAVA_OPTS` 中，但设置 `JAVA_OPTS` +会替换镜像默认值（`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`），需要把这些参数一并写上。 > **版本范围**：上文描述的是基于当前 master 构建的镜像（PD、Store 和单机 Server 见 [apache/hugegraph#2980](https://github.com/apache/hugegraph/pull/2980)，HStore Server 见 > [apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)）。1.7.0 及更早的镜像都没有设置 `STDOUT_MODE`，包括上文使用的单机镜像 `hugegraph/hugegraph:1.7.0`：`docker logs` diff --git a/content/en/docs/guides/hugegraph-docker-cluster.md b/content/en/docs/guides/hugegraph-docker-cluster.md index 2a2107c358..c9f946e943 100644 --- a/content/en/docs/guides/hugegraph-docker-cluster.md +++ b/content/en/docs/guides/hugegraph-docker-cluster.md @@ -301,7 +301,8 @@ files. The full `hugegraph-server.log`, JVM crash logs (`hs_err_pid*.log`) and o `/hugegraph-server/logs` to keep them. A heap dump can be as large as the JVM heap, and every launch writes to a new file, so a Server that keeps running out of memory adds one heap-sized dump per restart until the volume is full. The launcher never removes old dumps, whether the volume is an `emptyDir` (which also survives container restarts) or a PVC. Size the volume for the number of dumps you want to keep plus the logs, move or delete old `java_pid*.hprof` files after -each incident, or turn dumps off with `-XX:-HeapDumpOnOutOfMemoryError`. +each incident, or turn dumps off with `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`, which keeps the image's default `JAVA_OPTS`. Adding the flag to +`JAVA_OPTS` also works, but setting `JAVA_OPTS` replaces that default (`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`), so repeat those flags. > **Version scope**: the paragraph above describes current master images ([apache/hugegraph#2980](https://github.com/apache/hugegraph/pull/2980) for PD, Store > and the standalone Server, [apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258) for the HStore Server). No 1.7.0 or older image sets From 0eb4cce4ba207eb78845d914aeda2adf8173a45a Mon Sep 17 00:00:00 2001 From: Ayan Alam Date: Tue, 6 Oct 2026 09:20:33 +0530 Subject: [PATCH 06/19] doc(server): only INFO-level library loggers keep INFO in files The ZooKeeper and SOFA loggers are set to WARN, so their INFO events are discarded, not kept in files. Limit the file-only INFO statement in the Docker guide to the Hadoop, Netty and Commons loggers, in English and Chinese. --- .../cn/docs/guides/hugegraph-docker-cluster.md | 10 +++++----- .../en/docs/guides/hugegraph-docker-cluster.md | 17 +++++++++-------- 2 files changed, 14 insertions(+), 13 deletions(-) diff --git a/content/cn/docs/guides/hugegraph-docker-cluster.md b/content/cn/docs/guides/hugegraph-docker-cluster.md index 79cb03688f..ab2d43fac4 100644 --- a/content/cn/docs/guides/hugegraph-docker-cluster.md +++ b/content/cn/docs/guides/hugegraph-docker-cluster.md @@ -294,11 +294,11 @@ curl -o /dev/null -w '%{http_code}\n' -u "admin:${HUGEGRAPH_ADMIN_PASSWORD}" \ 5. **数据在意料之外地保留了下来**：`docker compose down` 会保留命名卷。要同时删除该拓扑的数据，请使用 `docker compose down -v` **查看运行时日志**：使用 `docker logs `（如 `docker logs hg-pd0`）可直接查看日志，无需进入容器。基于当前 master 构建的 PD、Store 以及两个 Server 镜像（`hugegraph/hugegraph` 和 HStore 的 -`hugegraph/server`）都设置了 `STDOUT_MODE=true`，服务日志会输出到容器 stdout。对 Server 而言，Hadoop、ZooKeeper、SOFA、Netty 和 Commons 的 WARN 及以上日志也会输出到 stdout；它们的 INFO -日志以及审计日志、慢查询日志仍只写入文件。完整的 `hugegraph-server.log`、JVM 崩溃日志（`hs_err_pid*.log`）和内存溢出堆转储（`java_pid*.hprof`）位于 `/hugegraph-server/logs`。`docker restart` 会保留这些文件，但 -Kubernetes 每次重启都会新建容器，因此需要在 `/hugegraph-server/logs` 挂载 `emptyDir` 或 PersistentVolumeClaim 来保留它们。堆转储可能和 JVM 堆一样大，而且每次启动都会写入新文件，因此反复内存溢出的 Server -每重启一次就会多一个与堆同样大小的转储，直到卷被写满。无论使用 `emptyDir`（它在容器重启后同样保留）还是 PVC，启动脚本都不会删除旧的转储。请按需要保留的转储数量加上日志所需空间来规划卷大小，每次排查后移走或删除旧的 `java_pid*.hprof` 文件，或设置 -`JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError` 关闭堆转储，这样会保留镜像默认的 `JAVA_OPTS`。也可以把该参数加到 `JAVA_OPTS` 中，但设置 `JAVA_OPTS` +`hugegraph/server`）都设置了 `STDOUT_MODE=true`，服务日志会输出到容器 stdout。对 Server 而言，Hadoop、ZooKeeper、SOFA、Netty 和 Commons 的 WARN 及以上日志也会输出到 stdout；Hadoop、Netty 和 Commons 的 +INFO 日志以及审计日志、慢查询日志仍只写入文件，ZooKeeper 和 SOFA 不输出 WARN 以下的日志。完整的 `hugegraph-server.log`、JVM 崩溃日志（`hs_err_pid*.log`）和内存溢出堆转储（`java_pid*.hprof`）位于 +`/hugegraph-server/logs`。`docker restart` 会保留这些文件，但 Kubernetes 每次重启都会新建容器，因此需要在 `/hugegraph-server/logs` 挂载 `emptyDir` 或 PersistentVolumeClaim 来保留它们。堆转储可能和 JVM +堆一样大，而且每次启动都会写入新文件，因此反复内存溢出的 Server 每重启一次就会多一个与堆同样大小的转储，直到卷被写满。无论使用 `emptyDir`（它在容器重启后同样保留）还是 PVC，启动脚本都不会删除旧的转储。请按需要保留的转储数量加上日志所需空间来规划卷大小，每次排查后移走或删除旧的 +`java_pid*.hprof` 文件，或设置 `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError` 关闭堆转储，这样会保留镜像默认的 `JAVA_OPTS`。也可以把该参数加到 `JAVA_OPTS` 中，但设置 `JAVA_OPTS` 会替换镜像默认值（`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`），需要把这些参数一并写上。 > **版本范围**：上文描述的是基于当前 master 构建的镜像（PD、Store 和单机 Server 见 [apache/hugegraph#2980](https://github.com/apache/hugegraph/pull/2980)，HStore Server 见 diff --git a/content/en/docs/guides/hugegraph-docker-cluster.md b/content/en/docs/guides/hugegraph-docker-cluster.md index c9f946e943..352f415b7f 100644 --- a/content/en/docs/guides/hugegraph-docker-cluster.md +++ b/content/en/docs/guides/hugegraph-docker-cluster.md @@ -295,14 +295,15 @@ Standalone publishes only `8080` and `8088`; minimal HStore publishes `8620` (PD **Runtime logs**: `docker logs ` (for example, `docker logs hg-pd0`) shows logs without entering containers. In images built from current master, the PD, Store and both Server images (`hugegraph/hugegraph` and the HStore `hugegraph/server`) set `STDOUT_MODE=true` and send service logs to stdout. -For the Server, WARN and above from Hadoop, ZooKeeper, SOFA, Netty and Commons also reaches stdout; their INFO output and the audit and slow-query logs stay in -files. The full `hugegraph-server.log`, JVM crash logs (`hs_err_pid*.log`) and out-of-memory heap dumps (`java_pid*.hprof`) are in `/hugegraph-server/logs`. -`docker restart` keeps them, but Kubernetes starts a new container on every restart, so mount an `emptyDir` or a PersistentVolumeClaim at -`/hugegraph-server/logs` to keep them. A heap dump can be as large as the JVM heap, and every launch writes to a new file, so a Server that keeps running out of -memory adds one heap-sized dump per restart until the volume is full. The launcher never removes old dumps, whether the volume is an `emptyDir` (which also -survives container restarts) or a PVC. Size the volume for the number of dumps you want to keep plus the logs, move or delete old `java_pid*.hprof` files after -each incident, or turn dumps off with `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`, which keeps the image's default `JAVA_OPTS`. Adding the flag to -`JAVA_OPTS` also works, but setting `JAVA_OPTS` replaces that default (`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`), so repeat those flags. +For the Server, WARN and above from Hadoop, ZooKeeper, SOFA, Netty and Commons also reaches stdout; INFO from Hadoop, Netty and Commons and the audit and +slow-query logs stay in files, and ZooKeeper and SOFA log nothing below WARN. The full `hugegraph-server.log`, JVM crash logs (`hs_err_pid*.log`) and +out-of-memory heap dumps (`java_pid*.hprof`) are in `/hugegraph-server/logs`. `docker restart` keeps them, but Kubernetes starts a new container on every +restart, so mount an `emptyDir` or a PersistentVolumeClaim at `/hugegraph-server/logs` to keep them. A heap dump can be as large as the JVM heap, and every +launch writes to a new file, so a Server that keeps running out of memory adds one heap-sized dump per restart until the volume is full. The launcher never +removes old dumps, whether the volume is an `emptyDir` (which also survives container restarts) or a PVC. Size the volume for the number of dumps you want to +keep plus the logs, move or delete old `java_pid*.hprof` files after each incident, or turn dumps off with `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`, +which keeps the image's default `JAVA_OPTS`. Adding the flag to `JAVA_OPTS` also works, but setting `JAVA_OPTS` replaces that default +(`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`), so repeat those flags. > **Version scope**: the paragraph above describes current master images ([apache/hugegraph#2980](https://github.com/apache/hugegraph/pull/2980) for PD, Store > and the standalone Server, [apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258) for the HStore Server). No 1.7.0 or older image sets From 8199bdcaa431893bc7869e243b49f0e601f73528 Mon Sep 17 00:00:00 2001 From: Ayan Alam Date: Tue, 6 Oct 2026 23:48:02 +0530 Subject: [PATCH 07/19] doc(server): describe the per-launch heap dump directory apache/hugegraph#3258 now points HeapDumpPath at a directory per launch, logs/heapdump__/, so the Server and any JVM it starts (computer jobs inherit JAVA_TOOL_OPTIONS) each write their own java_pid.hprof. Update the names and cleanup advice, and note that startup removes only this host's empty heapdump_* directories, in the Server quickstart and the Docker guide, English and Chinese. --- .../cn/docs/guides/hugegraph-docker-cluster.md | 9 +++++---- .../quickstart/hugegraph/hugegraph-server.md | 9 +++++---- .../en/docs/guides/hugegraph-docker-cluster.md | 15 ++++++++------- .../quickstart/hugegraph/hugegraph-server.md | 16 +++++++++------- 4 files changed, 27 insertions(+), 22 deletions(-) diff --git a/content/cn/docs/guides/hugegraph-docker-cluster.md b/content/cn/docs/guides/hugegraph-docker-cluster.md index ab2d43fac4..f43e375c09 100644 --- a/content/cn/docs/guides/hugegraph-docker-cluster.md +++ b/content/cn/docs/guides/hugegraph-docker-cluster.md @@ -295,10 +295,11 @@ curl -o /dev/null -w '%{http_code}\n' -u "admin:${HUGEGRAPH_ADMIN_PASSWORD}" \ **查看运行时日志**：使用 `docker logs `（如 `docker logs hg-pd0`）可直接查看日志，无需进入容器。基于当前 master 构建的 PD、Store 以及两个 Server 镜像（`hugegraph/hugegraph` 和 HStore 的 `hugegraph/server`）都设置了 `STDOUT_MODE=true`，服务日志会输出到容器 stdout。对 Server 而言，Hadoop、ZooKeeper、SOFA、Netty 和 Commons 的 WARN 及以上日志也会输出到 stdout；Hadoop、Netty 和 Commons 的 -INFO 日志以及审计日志、慢查询日志仍只写入文件，ZooKeeper 和 SOFA 不输出 WARN 以下的日志。完整的 `hugegraph-server.log`、JVM 崩溃日志（`hs_err_pid*.log`）和内存溢出堆转储（`java_pid*.hprof`）位于 -`/hugegraph-server/logs`。`docker restart` 会保留这些文件，但 Kubernetes 每次重启都会新建容器，因此需要在 `/hugegraph-server/logs` 挂载 `emptyDir` 或 PersistentVolumeClaim 来保留它们。堆转储可能和 JVM -堆一样大，而且每次启动都会写入新文件，因此反复内存溢出的 Server 每重启一次就会多一个与堆同样大小的转储，直到卷被写满。无论使用 `emptyDir`（它在容器重启后同样保留）还是 PVC，启动脚本都不会删除旧的转储。请按需要保留的转储数量加上日志所需空间来规划卷大小，每次排查后移走或删除旧的 -`java_pid*.hprof` 文件，或设置 `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError` 关闭堆转储，这样会保留镜像默认的 `JAVA_OPTS`。也可以把该参数加到 `JAVA_OPTS` 中，但设置 `JAVA_OPTS` +INFO 日志以及审计日志、慢查询日志仍只写入文件，ZooKeeper 和 SOFA 不输出 WARN 以下的日志。完整的 `hugegraph-server.log`、JVM +崩溃日志（`hs_err_pid*.log`）和内存溢出堆转储（`heapdump_*/java_pid*.hprof`，每次启动一个目录，Server 及其启动的 JVM 各写各的文件）位于 `/hugegraph-server/logs`。`docker restart` 会保留这些文件，但 Kubernetes +每次重启都会新建容器，因此需要在 `/hugegraph-server/logs` 挂载 `emptyDir` 或 PersistentVolumeClaim 来保留它们。堆转储可能和 JVM 堆一样大，而且每次启动都会写入新文件，因此反复内存溢出的 Server +每重启一次就会多一个与堆同样大小的转储，直到卷被写满。无论使用 `emptyDir`（它在容器重启后同样保留）还是 PVC，启动脚本都不会删除旧的转储，启动时只会删除本主机空的 `heapdump_*` 目录。请按需要保留的转储数量加上日志所需空间来规划卷大小，每次排查后移走或删除旧的 `heapdump_*` +目录，或设置 `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError` 关闭堆转储，这样会保留镜像默认的 `JAVA_OPTS`。也可以把该参数加到 `JAVA_OPTS` 中，但设置 `JAVA_OPTS` 会替换镜像默认值（`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`），需要把这些参数一并写上。 > **版本范围**：上文描述的是基于当前 master 构建的镜像（PD、Store 和单机 Server 见 [apache/hugegraph#2980](https://github.com/apache/hugegraph/pull/2980)，HStore Server 见 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index a7dbe19f8f..3c68bfbb0f 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md @@ -536,10 +536,11 @@ Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)......OK `bin/stop-hugegraph.sh` 支持 `-m true|false`（默认 `true`），用于控制停止服务时是否同时移除 crontab 监控任务。 -服务脚本会把 `-XX:+HeapDumpOnOutOfMemoryError`、`-XX:HeapDumpPath` 和 `-XX:ErrorFile` 放在 `JAVA_TOOL_OPTIONS` 的最前面，因此内存溢出时的堆转储（`java_pid_<主机名>_<启动时间>.hprof`）和 JVM -崩溃日志（`hs_err_pid_<主机名>_<启动时间>.log`）都会写入 `logs/`，与是否设置 `JAVA_OPTIONS` 无关。文件名中的主机名（在 Kubernetes 上即 Pod 名）可避免共用同一日志目录的多个服务选到相同的文件名。如果同名文件已存在（例如重启后在同一秒内复用了相同 -PID），文件名会再加上计数（`<启动时间>-1`、`-2`……）。堆转储可能和堆一样大，且旧的转储不会被删除，反复内存溢出的服务每重启一次就会在 `logs/` 中多一个转储；每次排查后请移走或删除旧的 `java_pid*.hprof` 文件。JVM 会在这些默认值之后读取你自己的 -`JAVA_TOOL_OPTIONS`、`JDK_JAVA_OPTIONS`、命令行（`JAVA_OPTIONS`，未设置 `JAVA_OPTIONS` 时为 `-j`）和 `_JAVA_OPTIONS`，因此在其中任意一处为上述参数指定的值都会覆盖默认值。例如，可通过 `-j` 传入 +服务脚本会把 `-XX:+HeapDumpOnOutOfMemoryError`、`-XX:HeapDumpPath` 和 `-XX:ErrorFile` 放在 `JAVA_TOOL_OPTIONS` +的最前面，因此内存溢出时的堆转储（`heapdump_<主机名>_<启动时间>/java_pid.hprof`）和 JVM 崩溃日志（`hs_err_pid_<主机名>_<启动时间>.log`）都会写入 `logs/`，与是否设置 `JAVA_OPTIONS` 无关。每次启动都有自己的 +`heapdump_*` 目录，因此服务及其启动的 JVM（例如 computer 任务）会写入各自的转储。文件名中的主机名（在 Kubernetes 上即 Pod 名）可避免共用同一日志目录的多个服务选到相同的文件名。如果同名文件已存在（例如重启后在同一秒内复用了相同 +PID），文件名会再加上计数（`<启动时间>-1`、`-2`……）。堆转储可能和堆一样大，且旧的转储不会被删除（启动时只会删除本主机空的 `heapdump_*` 目录），反复内存溢出的服务每重启一次就会在 `logs/` 中多一个转储；每次排查后请移走或删除旧的 `heapdump_*` 目录。JVM +会在这些默认值之后读取你自己的 `JAVA_TOOL_OPTIONS`、`JDK_JAVA_OPTIONS`、命令行（`JAVA_OPTIONS`，未设置 `JAVA_OPTIONS` 时为 `-j`）和 `_JAVA_OPTIONS`，因此在其中任意一处为上述参数指定的值都会覆盖默认值。例如，可通过 `-j` 传入 `-XX:-HeapDumpOnOutOfMemoryError` 来关闭堆转储。由于这些默认值，JVM 启动时会输出 `Picked up JAVA_TOOL_OPTIONS: ...`。 > **版本范围**：以上行为适用于当前 master（[apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)）。1.7.0 只在未设置 `JAVA_OPTIONS` diff --git a/content/en/docs/guides/hugegraph-docker-cluster.md b/content/en/docs/guides/hugegraph-docker-cluster.md index 352f415b7f..db8fe84c4a 100644 --- a/content/en/docs/guides/hugegraph-docker-cluster.md +++ b/content/en/docs/guides/hugegraph-docker-cluster.md @@ -297,13 +297,14 @@ Standalone publishes only `8080` and `8088`; minimal HStore publishes `8620` (PD master, the PD, Store and both Server images (`hugegraph/hugegraph` and the HStore `hugegraph/server`) set `STDOUT_MODE=true` and send service logs to stdout. For the Server, WARN and above from Hadoop, ZooKeeper, SOFA, Netty and Commons also reaches stdout; INFO from Hadoop, Netty and Commons and the audit and slow-query logs stay in files, and ZooKeeper and SOFA log nothing below WARN. The full `hugegraph-server.log`, JVM crash logs (`hs_err_pid*.log`) and -out-of-memory heap dumps (`java_pid*.hprof`) are in `/hugegraph-server/logs`. `docker restart` keeps them, but Kubernetes starts a new container on every -restart, so mount an `emptyDir` or a PersistentVolumeClaim at `/hugegraph-server/logs` to keep them. A heap dump can be as large as the JVM heap, and every -launch writes to a new file, so a Server that keeps running out of memory adds one heap-sized dump per restart until the volume is full. The launcher never -removes old dumps, whether the volume is an `emptyDir` (which also survives container restarts) or a PVC. Size the volume for the number of dumps you want to -keep plus the logs, move or delete old `java_pid*.hprof` files after each incident, or turn dumps off with `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`, -which keeps the image's default `JAVA_OPTS`. Adding the flag to `JAVA_OPTS` also works, but setting `JAVA_OPTS` replaces that default -(`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`), so repeat those flags. +out-of-memory heap dumps (`heapdump_*/java_pid*.hprof`, one directory per launch so the Server and any JVM it starts get separate files) are in +`/hugegraph-server/logs`. `docker restart` keeps them, but Kubernetes starts a new container on every restart, so mount an `emptyDir` or a PersistentVolumeClaim +at `/hugegraph-server/logs` to keep them. A heap dump can be as large as the JVM heap, and every launch writes to a new file, so a Server that keeps running out +of memory adds one heap-sized dump per restart until the volume is full. The launcher never removes old dumps, whether the volume is an `emptyDir` (which also +survives container restarts) or a PVC; at startup it only removes this host's empty `heapdump_*` directories. Size the volume for the number of dumps you want +to keep plus the logs, move or delete old `heapdump_*` directories after each incident, or turn dumps off with +`JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`, which keeps the image's default `JAVA_OPTS`. Adding the flag to `JAVA_OPTS` also works, but setting +`JAVA_OPTS` replaces that default (`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`), so repeat those flags. > **Version scope**: the paragraph above describes current master images ([apache/hugegraph#2980](https://github.com/apache/hugegraph/pull/2980) for PD, Store > and the standalone Server, [apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258) for the HStore Server). No 1.7.0 or older image sets diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index 2b5bb01724..cff1da23c1 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -536,13 +536,15 @@ This indicates the successful creation of the sample graph. `bin/stop-hugegraph.sh` accepts `-m true|false` (default `true`), which controls whether the cron monitor task is removed along with the service. The server script puts `-XX:+HeapDumpOnOutOfMemoryError`, `-XX:HeapDumpPath` and `-XX:ErrorFile` first in `JAVA_TOOL_OPTIONS`, so an out-of-memory heap dump -(`java_pid__.hprof`) and a JVM crash log (`hs_err_pid__.log`) land in `logs/` whether or not `JAVA_OPTIONS` is -set. The host name (the pod name on Kubernetes) keeps servers that share one log directory from picking the same name. If a file with that name already exists, -for example after a restart that reuses the PID within the same second, a counter is added (`-1`, `-2`, ...). A heap dump can be as large as the -heap, and old dumps are never removed, so a server that keeps running out of memory fills `logs/` with one dump per restart; move or delete old -`java_pid*.hprof` files after each incident. The JVM reads your own `JAVA_TOOL_OPTIONS`, `JDK_JAVA_OPTIONS`, the command line (`JAVA_OPTIONS`, or `-j` when -`JAVA_OPTIONS` is unset) and `_JAVA_OPTIONS` after these defaults, so a value for one of these flags in any of them overrides the default. For example, pass -`-XX:-HeapDumpOnOutOfMemoryError` with `-j` to turn dumps off. Because of the defaults, the JVM prints `Picked up JAVA_TOOL_OPTIONS: ...` at startup. +(`heapdump__/java_pid.hprof`) and a JVM crash log (`hs_err_pid__.log`) land in `logs/` whether or not +`JAVA_OPTIONS` is set. Each launch gets its own `heapdump_*` directory, so the server and any JVM it starts, such as a computer job, write separate dumps. The +host name (the pod name on Kubernetes) keeps servers that share one log directory from picking the same name. If a file with that name already exists, for +example after a restart that reuses the PID within the same second, a counter is added (`-1`, `-2`, ...). A heap dump can be as large as the heap, +and old dumps are never removed (startup only removes this host's empty `heapdump_*` directories), so a server that keeps running out of memory fills `logs/` +with one dump per restart; move or delete old `heapdump_*` directories after each incident. The JVM reads your own `JAVA_TOOL_OPTIONS`, `JDK_JAVA_OPTIONS`, the +command line (`JAVA_OPTIONS`, or `-j` when `JAVA_OPTIONS` is unset) and `_JAVA_OPTIONS` after these defaults, so a value for one of these flags in any of them +overrides the default. For example, pass `-XX:-HeapDumpOnOutOfMemoryError` with `-j` to turn dumps off. Because of the defaults, the JVM prints +`Picked up JAVA_TOOL_OPTIONS: ...` at startup. > **Version scope**: this applies to current master ([apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)). In 1.7.0 the heap dump > flags are added only when `JAVA_OPTIONS` is unset, and JVM crash logs go to the install directory. From e8da46d3fd8cf17b348d47be7f895f42e6bc00a1 Mon Sep 17 00:00:00 2001 From: Ayan Alam Date: Wed, 7 Oct 2026 09:50:47 +0530 Subject: [PATCH 08/19] doc(server): say which heap dump directories startup removes apache/hugegraph#3258 now removes a heapdump_* directory at startup only when it holds no dump and the JVM recorded as its owner has exited, so a running Server's empty directory is kept. Update the Server quickstart and the Docker guide, English and Chinese. --- content/cn/docs/guides/hugegraph-docker-cluster.md | 4 ++-- .../cn/docs/quickstart/hugegraph/hugegraph-server.md | 6 +++--- content/en/docs/guides/hugegraph-docker-cluster.md | 4 ++-- .../en/docs/quickstart/hugegraph/hugegraph-server.md | 10 +++++----- 4 files changed, 12 insertions(+), 12 deletions(-) diff --git a/content/cn/docs/guides/hugegraph-docker-cluster.md b/content/cn/docs/guides/hugegraph-docker-cluster.md index f43e375c09..cc7ef15b98 100644 --- a/content/cn/docs/guides/hugegraph-docker-cluster.md +++ b/content/cn/docs/guides/hugegraph-docker-cluster.md @@ -298,8 +298,8 @@ curl -o /dev/null -w '%{http_code}\n' -u "admin:${HUGEGRAPH_ADMIN_PASSWORD}" \ INFO 日志以及审计日志、慢查询日志仍只写入文件，ZooKeeper 和 SOFA 不输出 WARN 以下的日志。完整的 `hugegraph-server.log`、JVM 崩溃日志（`hs_err_pid*.log`）和内存溢出堆转储（`heapdump_*/java_pid*.hprof`，每次启动一个目录，Server 及其启动的 JVM 各写各的文件）位于 `/hugegraph-server/logs`。`docker restart` 会保留这些文件，但 Kubernetes 每次重启都会新建容器，因此需要在 `/hugegraph-server/logs` 挂载 `emptyDir` 或 PersistentVolumeClaim 来保留它们。堆转储可能和 JVM 堆一样大，而且每次启动都会写入新文件，因此反复内存溢出的 Server -每重启一次就会多一个与堆同样大小的转储，直到卷被写满。无论使用 `emptyDir`（它在容器重启后同样保留）还是 PVC，启动脚本都不会删除旧的转储，启动时只会删除本主机空的 `heapdump_*` 目录。请按需要保留的转储数量加上日志所需空间来规划卷大小，每次排查后移走或删除旧的 `heapdump_*` -目录，或设置 `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError` 关闭堆转储，这样会保留镜像默认的 `JAVA_OPTS`。也可以把该参数加到 `JAVA_OPTS` 中，但设置 `JAVA_OPTS` +每重启一次就会多一个与堆同样大小的转储，直到卷被写满。无论使用 `emptyDir`（它在容器重启后同样保留）还是 PVC，启动脚本都不会删除旧的转储，启动时只会删除本主机中没有转储且所属 JVM 已退出的 `heapdump_*` 目录。请按需要保留的转储数量加上日志所需空间来规划卷大小，每次排查后移走或删除旧的 +`heapdump_*` 目录，或设置 `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError` 关闭堆转储，这样会保留镜像默认的 `JAVA_OPTS`。也可以把该参数加到 `JAVA_OPTS` 中，但设置 `JAVA_OPTS` 会替换镜像默认值（`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`），需要把这些参数一并写上。 > **版本范围**：上文描述的是基于当前 master 构建的镜像（PD、Store 和单机 Server 见 [apache/hugegraph#2980](https://github.com/apache/hugegraph/pull/2980)，HStore Server 见 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index 3c68bfbb0f..58b0d7f0ac 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md @@ -539,9 +539,9 @@ Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)......OK 服务脚本会把 `-XX:+HeapDumpOnOutOfMemoryError`、`-XX:HeapDumpPath` 和 `-XX:ErrorFile` 放在 `JAVA_TOOL_OPTIONS` 的最前面，因此内存溢出时的堆转储（`heapdump_<主机名>_<启动时间>/java_pid.hprof`）和 JVM 崩溃日志（`hs_err_pid_<主机名>_<启动时间>.log`）都会写入 `logs/`，与是否设置 `JAVA_OPTIONS` 无关。每次启动都有自己的 `heapdump_*` 目录，因此服务及其启动的 JVM（例如 computer 任务）会写入各自的转储。文件名中的主机名（在 Kubernetes 上即 Pod 名）可避免共用同一日志目录的多个服务选到相同的文件名。如果同名文件已存在（例如重启后在同一秒内复用了相同 -PID），文件名会再加上计数（`<启动时间>-1`、`-2`……）。堆转储可能和堆一样大，且旧的转储不会被删除（启动时只会删除本主机空的 `heapdump_*` 目录），反复内存溢出的服务每重启一次就会在 `logs/` 中多一个转储；每次排查后请移走或删除旧的 `heapdump_*` 目录。JVM -会在这些默认值之后读取你自己的 `JAVA_TOOL_OPTIONS`、`JDK_JAVA_OPTIONS`、命令行（`JAVA_OPTIONS`，未设置 `JAVA_OPTIONS` 时为 `-j`）和 `_JAVA_OPTIONS`，因此在其中任意一处为上述参数指定的值都会覆盖默认值。例如，可通过 `-j` 传入 -`-XX:-HeapDumpOnOutOfMemoryError` 来关闭堆转储。由于这些默认值，JVM 启动时会输出 `Picked up JAVA_TOOL_OPTIONS: ...`。 +PID），文件名会再加上计数（`<启动时间>-1`、`-2`……）。堆转储可能和堆一样大，且旧的转储不会被删除（启动时只会删除本主机中没有转储且所属 JVM 已退出的 `heapdump_*` 目录），反复内存溢出的服务每重启一次就会在 `logs/` 中多一个转储；每次排查后请移走或删除旧的 `heapdump_*` +目录。JVM 会在这些默认值之后读取你自己的 `JAVA_TOOL_OPTIONS`、`JDK_JAVA_OPTIONS`、命令行（`JAVA_OPTIONS`，未设置 `JAVA_OPTIONS` 时为 `-j`）和 `_JAVA_OPTIONS`，因此在其中任意一处为上述参数指定的值都会覆盖默认值。例如，可通过 +`-j` 传入 `-XX:-HeapDumpOnOutOfMemoryError` 来关闭堆转储。由于这些默认值，JVM 启动时会输出 `Picked up JAVA_TOOL_OPTIONS: ...`。 > **版本范围**：以上行为适用于当前 master（[apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)）。1.7.0 只在未设置 `JAVA_OPTIONS` > 时添加堆转储参数，JVM 崩溃日志写入安装目录。 diff --git a/content/en/docs/guides/hugegraph-docker-cluster.md b/content/en/docs/guides/hugegraph-docker-cluster.md index db8fe84c4a..7e556a2527 100644 --- a/content/en/docs/guides/hugegraph-docker-cluster.md +++ b/content/en/docs/guides/hugegraph-docker-cluster.md @@ -301,8 +301,8 @@ out-of-memory heap dumps (`heapdump_*/java_pid*.hprof`, one directory per launch `/hugegraph-server/logs`. `docker restart` keeps them, but Kubernetes starts a new container on every restart, so mount an `emptyDir` or a PersistentVolumeClaim at `/hugegraph-server/logs` to keep them. A heap dump can be as large as the JVM heap, and every launch writes to a new file, so a Server that keeps running out of memory adds one heap-sized dump per restart until the volume is full. The launcher never removes old dumps, whether the volume is an `emptyDir` (which also -survives container restarts) or a PVC; at startup it only removes this host's empty `heapdump_*` directories. Size the volume for the number of dumps you want -to keep plus the logs, move or delete old `heapdump_*` directories after each incident, or turn dumps off with +survives container restarts) or a PVC; at startup it only removes this host's `heapdump_*` directories that hold no dump and whose JVM has exited. Size the +volume for the number of dumps you want to keep plus the logs, move or delete old `heapdump_*` directories after each incident, or turn dumps off with `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`, which keeps the image's default `JAVA_OPTS`. Adding the flag to `JAVA_OPTS` also works, but setting `JAVA_OPTS` replaces that default (`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`), so repeat those flags. diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index cff1da23c1..0092517eef 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -540,11 +540,11 @@ The server script puts `-XX:+HeapDumpOnOutOfMemoryError`, `-XX:HeapDumpPath` and `JAVA_OPTIONS` is set. Each launch gets its own `heapdump_*` directory, so the server and any JVM it starts, such as a computer job, write separate dumps. The host name (the pod name on Kubernetes) keeps servers that share one log directory from picking the same name. If a file with that name already exists, for example after a restart that reuses the PID within the same second, a counter is added (`-1`, `-2`, ...). A heap dump can be as large as the heap, -and old dumps are never removed (startup only removes this host's empty `heapdump_*` directories), so a server that keeps running out of memory fills `logs/` -with one dump per restart; move or delete old `heapdump_*` directories after each incident. The JVM reads your own `JAVA_TOOL_OPTIONS`, `JDK_JAVA_OPTIONS`, the -command line (`JAVA_OPTIONS`, or `-j` when `JAVA_OPTIONS` is unset) and `_JAVA_OPTIONS` after these defaults, so a value for one of these flags in any of them -overrides the default. For example, pass `-XX:-HeapDumpOnOutOfMemoryError` with `-j` to turn dumps off. Because of the defaults, the JVM prints -`Picked up JAVA_TOOL_OPTIONS: ...` at startup. +and old dumps are never removed (startup only removes this host's `heapdump_*` directories that hold no dump and whose JVM has exited), so a server that keeps +running out of memory fills `logs/` with one dump per restart; move or delete old `heapdump_*` directories after each incident. The JVM reads your own +`JAVA_TOOL_OPTIONS`, `JDK_JAVA_OPTIONS`, the command line (`JAVA_OPTIONS`, or `-j` when `JAVA_OPTIONS` is unset) and `_JAVA_OPTIONS` after these defaults, so a +value for one of these flags in any of them overrides the default. For example, pass `-XX:-HeapDumpOnOutOfMemoryError` with `-j` to turn dumps off. Because of +the defaults, the JVM prints `Picked up JAVA_TOOL_OPTIONS: ...` at startup. > **Version scope**: this applies to current master ([apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)). In 1.7.0 the heap dump > flags are added only when `JAVA_OPTIONS` is unset, and JVM crash logs go to the install directory. From 3b53268259f5fd20f655c7a882b7058912050e50 Mon Sep 17 00:00:00 2001 From: Ayan Alam Date: Wed, 7 Oct 2026 15:14:25 +0530 Subject: [PATCH 09/19] doc(server): heap dump directories are no longer removed at startup apache/hugegraph#3258 dropped the startup cleanup of heapdump_* directories, since a computer-job JVM can keep using one after its Server exits. Say that each start leaves a directory, empty unless something ran out of memory, and that old ones can be deleted once no JVM from that launch is running. English and Chinese. --- content/cn/docs/guides/hugegraph-docker-cluster.md | 6 +++--- .../cn/docs/quickstart/hugegraph/hugegraph-server.md | 6 +++--- content/en/docs/guides/hugegraph-docker-cluster.md | 7 ++++--- .../en/docs/quickstart/hugegraph/hugegraph-server.md | 10 +++++----- 4 files changed, 15 insertions(+), 14 deletions(-) diff --git a/content/cn/docs/guides/hugegraph-docker-cluster.md b/content/cn/docs/guides/hugegraph-docker-cluster.md index cc7ef15b98..b4f5be9d73 100644 --- a/content/cn/docs/guides/hugegraph-docker-cluster.md +++ b/content/cn/docs/guides/hugegraph-docker-cluster.md @@ -298,9 +298,9 @@ curl -o /dev/null -w '%{http_code}\n' -u "admin:${HUGEGRAPH_ADMIN_PASSWORD}" \ INFO 日志以及审计日志、慢查询日志仍只写入文件，ZooKeeper 和 SOFA 不输出 WARN 以下的日志。完整的 `hugegraph-server.log`、JVM 崩溃日志（`hs_err_pid*.log`）和内存溢出堆转储（`heapdump_*/java_pid*.hprof`，每次启动一个目录，Server 及其启动的 JVM 各写各的文件）位于 `/hugegraph-server/logs`。`docker restart` 会保留这些文件，但 Kubernetes 每次重启都会新建容器，因此需要在 `/hugegraph-server/logs` 挂载 `emptyDir` 或 PersistentVolumeClaim 来保留它们。堆转储可能和 JVM 堆一样大，而且每次启动都会写入新文件，因此反复内存溢出的 Server -每重启一次就会多一个与堆同样大小的转储，直到卷被写满。无论使用 `emptyDir`（它在容器重启后同样保留）还是 PVC，启动脚本都不会删除旧的转储，启动时只会删除本主机中没有转储且所属 JVM 已退出的 `heapdump_*` 目录。请按需要保留的转储数量加上日志所需空间来规划卷大小，每次排查后移走或删除旧的 -`heapdump_*` 目录，或设置 `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError` 关闭堆转储，这样会保留镜像默认的 `JAVA_OPTS`。也可以把该参数加到 `JAVA_OPTS` 中，但设置 `JAVA_OPTS` -会替换镜像默认值（`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`），需要把这些参数一并写上。 +每重启一次就会多一个与堆同样大小的转储，直到卷被写满。无论使用 `emptyDir`（它在容器重启后同样保留）还是 PVC，启动脚本都不会删除旧的转储或 `heapdump_*` 目录。每次启动都会留下一个目录，除非发生内存溢出否则为空，因为 computer 任务的 JVM 可能在 Server +退出后仍在使用它；确认该次启动的 HugeGraph JVM 都已退出后，可以删除旧目录。请按需要保留的转储数量加上日志所需空间来规划卷大小，每次排查后移走或删除旧的 `heapdump_*` 目录，或设置 `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError` +关闭堆转储，这样会保留镜像默认的 `JAVA_OPTS`。也可以把该参数加到 `JAVA_OPTS` 中，但设置 `JAVA_OPTS` 会替换镜像默认值（`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`），需要把这些参数一并写上。 > **版本范围**：上文描述的是基于当前 master 构建的镜像（PD、Store 和单机 Server 见 [apache/hugegraph#2980](https://github.com/apache/hugegraph/pull/2980)，HStore Server 见 > [apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)）。1.7.0 及更早的镜像都没有设置 `STDOUT_MODE`，包括上文使用的单机镜像 `hugegraph/hugegraph:1.7.0`：`docker logs` diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index 58b0d7f0ac..7563b6d682 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md @@ -539,9 +539,9 @@ Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)......OK 服务脚本会把 `-XX:+HeapDumpOnOutOfMemoryError`、`-XX:HeapDumpPath` 和 `-XX:ErrorFile` 放在 `JAVA_TOOL_OPTIONS` 的最前面，因此内存溢出时的堆转储（`heapdump_<主机名>_<启动时间>/java_pid.hprof`）和 JVM 崩溃日志（`hs_err_pid_<主机名>_<启动时间>.log`）都会写入 `logs/`，与是否设置 `JAVA_OPTIONS` 无关。每次启动都有自己的 `heapdump_*` 目录，因此服务及其启动的 JVM（例如 computer 任务）会写入各自的转储。文件名中的主机名（在 Kubernetes 上即 Pod 名）可避免共用同一日志目录的多个服务选到相同的文件名。如果同名文件已存在（例如重启后在同一秒内复用了相同 -PID），文件名会再加上计数（`<启动时间>-1`、`-2`……）。堆转储可能和堆一样大，且旧的转储不会被删除（启动时只会删除本主机中没有转储且所属 JVM 已退出的 `heapdump_*` 目录），反复内存溢出的服务每重启一次就会在 `logs/` 中多一个转储；每次排查后请移走或删除旧的 `heapdump_*` -目录。JVM 会在这些默认值之后读取你自己的 `JAVA_TOOL_OPTIONS`、`JDK_JAVA_OPTIONS`、命令行（`JAVA_OPTIONS`，未设置 `JAVA_OPTIONS` 时为 `-j`）和 `_JAVA_OPTIONS`，因此在其中任意一处为上述参数指定的值都会覆盖默认值。例如，可通过 -`-j` 传入 `-XX:-HeapDumpOnOutOfMemoryError` 来关闭堆转储。由于这些默认值，JVM 启动时会输出 `Picked up JAVA_TOOL_OPTIONS: ...`。 +PID），文件名会再加上计数（`<启动时间>-1`、`-2`……）。堆转储可能和堆一样大，且旧的转储和 `heapdump_*` 目录都不会被删除（每次启动都会留下一个目录，除非发生内存溢出否则为空，因为 computer 任务的 JVM 可能在服务退出后仍在使用它），反复内存溢出的服务每重启一次就会在 `logs/` +中多一个转储；每次排查后请移走或删除旧的 `heapdump_*` 目录。JVM 会在这些默认值之后读取你自己的 `JAVA_TOOL_OPTIONS`、`JDK_JAVA_OPTIONS`、命令行（`JAVA_OPTIONS`，未设置 `JAVA_OPTIONS` 时为 `-j`）和 +`_JAVA_OPTIONS`，因此在其中任意一处为上述参数指定的值都会覆盖默认值。例如，可通过 `-j` 传入 `-XX:-HeapDumpOnOutOfMemoryError` 来关闭堆转储。由于这些默认值，JVM 启动时会输出 `Picked up JAVA_TOOL_OPTIONS: ...`。 > **版本范围**：以上行为适用于当前 master（[apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)）。1.7.0 只在未设置 `JAVA_OPTIONS` > 时添加堆转储参数，JVM 崩溃日志写入安装目录。 diff --git a/content/en/docs/guides/hugegraph-docker-cluster.md b/content/en/docs/guides/hugegraph-docker-cluster.md index 7e556a2527..c2930fd6be 100644 --- a/content/en/docs/guides/hugegraph-docker-cluster.md +++ b/content/en/docs/guides/hugegraph-docker-cluster.md @@ -300,9 +300,10 @@ slow-query logs stay in files, and ZooKeeper and SOFA log nothing below WARN. Th out-of-memory heap dumps (`heapdump_*/java_pid*.hprof`, one directory per launch so the Server and any JVM it starts get separate files) are in `/hugegraph-server/logs`. `docker restart` keeps them, but Kubernetes starts a new container on every restart, so mount an `emptyDir` or a PersistentVolumeClaim at `/hugegraph-server/logs` to keep them. A heap dump can be as large as the JVM heap, and every launch writes to a new file, so a Server that keeps running out -of memory adds one heap-sized dump per restart until the volume is full. The launcher never removes old dumps, whether the volume is an `emptyDir` (which also -survives container restarts) or a PVC; at startup it only removes this host's `heapdump_*` directories that hold no dump and whose JVM has exited. Size the -volume for the number of dumps you want to keep plus the logs, move or delete old `heapdump_*` directories after each incident, or turn dumps off with +of memory adds one heap-sized dump per restart until the volume is full. The launcher never removes old dumps or `heapdump_*` directories, whether the volume is +an `emptyDir` (which also survives container restarts) or a PVC. Each start leaves a directory behind, empty unless something ran out of memory, because a +computer-job JVM can keep using it after its Server exits; old ones can be deleted once no HugeGraph JVM from that launch is running. Size the volume for the +number of dumps you want to keep plus the logs, move or delete old `heapdump_*` directories after each incident, or turn dumps off with `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`, which keeps the image's default `JAVA_OPTS`. Adding the flag to `JAVA_OPTS` also works, but setting `JAVA_OPTS` replaces that default (`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`), so repeat those flags. diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index 0092517eef..ab32b99ef6 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -540,11 +540,11 @@ The server script puts `-XX:+HeapDumpOnOutOfMemoryError`, `-XX:HeapDumpPath` and `JAVA_OPTIONS` is set. Each launch gets its own `heapdump_*` directory, so the server and any JVM it starts, such as a computer job, write separate dumps. The host name (the pod name on Kubernetes) keeps servers that share one log directory from picking the same name. If a file with that name already exists, for example after a restart that reuses the PID within the same second, a counter is added (`-1`, `-2`, ...). A heap dump can be as large as the heap, -and old dumps are never removed (startup only removes this host's `heapdump_*` directories that hold no dump and whose JVM has exited), so a server that keeps -running out of memory fills `logs/` with one dump per restart; move or delete old `heapdump_*` directories after each incident. The JVM reads your own -`JAVA_TOOL_OPTIONS`, `JDK_JAVA_OPTIONS`, the command line (`JAVA_OPTIONS`, or `-j` when `JAVA_OPTIONS` is unset) and `_JAVA_OPTIONS` after these defaults, so a -value for one of these flags in any of them overrides the default. For example, pass `-XX:-HeapDumpOnOutOfMemoryError` with `-j` to turn dumps off. Because of -the defaults, the JVM prints `Picked up JAVA_TOOL_OPTIONS: ...` at startup. +and neither old dumps nor `heapdump_*` directories are ever removed (each start leaves one, empty unless something ran out of memory, because a computer-job JVM +can keep using it after the server exits), so a server that keeps running out of memory fills `logs/` with one dump per restart; move or delete old `heapdump_*` +directories after each incident. The JVM reads your own `JAVA_TOOL_OPTIONS`, `JDK_JAVA_OPTIONS`, the command line (`JAVA_OPTIONS`, or `-j` when `JAVA_OPTIONS` +is unset) and `_JAVA_OPTIONS` after these defaults, so a value for one of these flags in any of them overrides the default. For example, pass +`-XX:-HeapDumpOnOutOfMemoryError` with `-j` to turn dumps off. Because of the defaults, the JVM prints `Picked up JAVA_TOOL_OPTIONS: ...` at startup. > **Version scope**: this applies to current master ([apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)). In 1.7.0 the heap dump > flags are added only when `JAVA_OPTIONS` is unset, and JVM crash logs go to the install directory. From 1065983185df4beb76022249557f70670e461a05 Mon Sep 17 00:00:00 2001 From: Ayan Alam Date: Wed, 7 Oct 2026 16:07:04 +0530 Subject: [PATCH 10/19] doc(server): correct crash-file guidance after a full review pass Update the Server quickstart and the Docker guide, English and Chinese, to match apache/hugegraph#3258: - -j or JAVA_OPTIONS turns heap dumps off for the server JVM only; JAVA_TOOL_OPTIONS reaches the JVMs it starts. - Never move the newest heapdump_* directory of a running server. - The directory is created even when dumps are off, and the server starts anyway when it cannot be created. - One log volume per pod, ephemeral-storage and sizeLimit, no medium: Memory, and the Helm chart's missing logs volume. - The 1.7.0 note says dumps used to go straight to logs/java_pid.hprof. - Name the script, give the launch time format, fix the garbled sentence about why directories are kept, and polish the Chinese. --- .../docs/guides/hugegraph-docker-cluster.md | 14 +++++---- .../quickstart/hugegraph/hugegraph-server.md | 20 +++++++------ .../docs/guides/hugegraph-docker-cluster.md | 21 +++++++------- .../quickstart/hugegraph/hugegraph-server.md | 29 ++++++++++--------- 4 files changed, 46 insertions(+), 38 deletions(-) diff --git a/content/cn/docs/guides/hugegraph-docker-cluster.md b/content/cn/docs/guides/hugegraph-docker-cluster.md index b4f5be9d73..b6f51b45a6 100644 --- a/content/cn/docs/guides/hugegraph-docker-cluster.md +++ b/content/cn/docs/guides/hugegraph-docker-cluster.md @@ -295,12 +295,14 @@ curl -o /dev/null -w '%{http_code}\n' -u "admin:${HUGEGRAPH_ADMIN_PASSWORD}" \ **查看运行时日志**：使用 `docker logs `（如 `docker logs hg-pd0`）可直接查看日志，无需进入容器。基于当前 master 构建的 PD、Store 以及两个 Server 镜像（`hugegraph/hugegraph` 和 HStore 的 `hugegraph/server`）都设置了 `STDOUT_MODE=true`，服务日志会输出到容器 stdout。对 Server 而言，Hadoop、ZooKeeper、SOFA、Netty 和 Commons 的 WARN 及以上日志也会输出到 stdout；Hadoop、Netty 和 Commons 的 -INFO 日志以及审计日志、慢查询日志仍只写入文件，ZooKeeper 和 SOFA 不输出 WARN 以下的日志。完整的 `hugegraph-server.log`、JVM -崩溃日志（`hs_err_pid*.log`）和内存溢出堆转储（`heapdump_*/java_pid*.hprof`，每次启动一个目录，Server 及其启动的 JVM 各写各的文件）位于 `/hugegraph-server/logs`。`docker restart` 会保留这些文件，但 Kubernetes -每次重启都会新建容器，因此需要在 `/hugegraph-server/logs` 挂载 `emptyDir` 或 PersistentVolumeClaim 来保留它们。堆转储可能和 JVM 堆一样大，而且每次启动都会写入新文件，因此反复内存溢出的 Server -每重启一次就会多一个与堆同样大小的转储，直到卷被写满。无论使用 `emptyDir`（它在容器重启后同样保留）还是 PVC，启动脚本都不会删除旧的转储或 `heapdump_*` 目录。每次启动都会留下一个目录，除非发生内存溢出否则为空，因为 computer 任务的 JVM 可能在 Server -退出后仍在使用它；确认该次启动的 HugeGraph JVM 都已退出后，可以删除旧目录。请按需要保留的转储数量加上日志所需空间来规划卷大小，每次排查后移走或删除旧的 `heapdump_*` 目录，或设置 `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError` -关闭堆转储，这样会保留镜像默认的 `JAVA_OPTS`。也可以把该参数加到 `JAVA_OPTS` 中，但设置 `JAVA_OPTS` 会替换镜像默认值（`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`），需要把这些参数一并写上。 +INFO 日志以及审计日志、慢查询日志仍只写入文件，ZooKeeper 和 SOFA 不输出 WARN 以下的日志。`/hugegraph-server/logs` 中包含 `hugegraph-server.log`、JVM +崩溃日志（`hs_err_pid*.log`）和内存溢出时的堆转储（`heapdump_*/java_pid*.hprof`，每次启动一个目录，Server 及其启动的 JVM 分别写入各自的文件）。`docker restart` +会保留这些文件，但重新创建容器时，除非该路径是一个卷，否则文件会丢失；Kubernetes 每次重启都会新建容器，因此需要在 `/hugegraph-server/logs` 挂载 `emptyDir` 或 PersistentVolumeClaim。请为每个 Pod 使用单独的卷（或在共享 PVC 上使用 +`subPathExpr: $(POD_NAME)`）：崩溃文件的名字各不相同，但日志文件本身的名字是固定的。Helm Chart 目前还不会挂载日志卷。堆转储可能和 JVM 堆一样大，而且每次启动都会使用新目录，因此反复内存溢出的 Server 会把卷写满；请按需要保留的转储数量规划卷大小，并确保不超过 +`ephemeral-storage` 限制或 `emptyDir` 的 `sizeLimit`（被驱逐时 `emptyDir` 会连同转储一起删除），也不要使用 `medium: Memory`。启动脚本从不删除转储或 `heapdump_*` 目录，因为 computer 任务的 JVM 可能在 Server +退出后仍在使用它；每次启动都会留下一个目录，除非发生内存溢出否则为空。在该次启动的 HugeGraph JVM 都已退出后可以删除旧目录，但不要动正在运行的 Server 最新的那个目录。要对所有 JVM 关闭堆转储，请设置 +`JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`，这样会保留镜像默认的 `JAVA_OPTS`；把该参数加到 `JAVA_OPTS` 中只对 Server 自身的 JVM +生效，而且会替换镜像默认值（`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`），需要把这些参数一并写上。 > **版本范围**：上文描述的是基于当前 master 构建的镜像（PD、Store 和单机 Server 见 [apache/hugegraph#2980](https://github.com/apache/hugegraph/pull/2980)，HStore Server 见 > [apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)）。1.7.0 及更早的镜像都没有设置 `STDOUT_MODE`，包括上文使用的单机镜像 `hugegraph/hugegraph:1.7.0`：`docker logs` diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index 7563b6d682..378392fde3 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md @@ -536,15 +536,17 @@ Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)......OK `bin/stop-hugegraph.sh` 支持 `-m true|false`（默认 `true`），用于控制停止服务时是否同时移除 crontab 监控任务。 -服务脚本会把 `-XX:+HeapDumpOnOutOfMemoryError`、`-XX:HeapDumpPath` 和 `-XX:ErrorFile` 放在 `JAVA_TOOL_OPTIONS` -的最前面，因此内存溢出时的堆转储（`heapdump_<主机名>_<启动时间>/java_pid.hprof`）和 JVM 崩溃日志（`hs_err_pid_<主机名>_<启动时间>.log`）都会写入 `logs/`，与是否设置 `JAVA_OPTIONS` 无关。每次启动都有自己的 -`heapdump_*` 目录，因此服务及其启动的 JVM（例如 computer 任务）会写入各自的转储。文件名中的主机名（在 Kubernetes 上即 Pod 名）可避免共用同一日志目录的多个服务选到相同的文件名。如果同名文件已存在（例如重启后在同一秒内复用了相同 -PID），文件名会再加上计数（`<启动时间>-1`、`-2`……）。堆转储可能和堆一样大，且旧的转储和 `heapdump_*` 目录都不会被删除（每次启动都会留下一个目录，除非发生内存溢出否则为空，因为 computer 任务的 JVM 可能在服务退出后仍在使用它），反复内存溢出的服务每重启一次就会在 `logs/` -中多一个转储；每次排查后请移走或删除旧的 `heapdump_*` 目录。JVM 会在这些默认值之后读取你自己的 `JAVA_TOOL_OPTIONS`、`JDK_JAVA_OPTIONS`、命令行（`JAVA_OPTIONS`，未设置 `JAVA_OPTIONS` 时为 `-j`）和 -`_JAVA_OPTIONS`，因此在其中任意一处为上述参数指定的值都会覆盖默认值。例如，可通过 `-j` 传入 `-XX:-HeapDumpOnOutOfMemoryError` 来关闭堆转储。由于这些默认值，JVM 启动时会输出 `Picked up JAVA_TOOL_OPTIONS: ...`。 - -> **版本范围**：以上行为适用于当前 master（[apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)）。1.7.0 只在未设置 `JAVA_OPTIONS` -> 时添加堆转储参数，JVM 崩溃日志写入安装目录。 +`bin/hugegraph-server.sh` 会把 `-XX:+HeapDumpOnOutOfMemoryError`、`-XX:HeapDumpPath` 和 `-XX:ErrorFile` 放在 `JAVA_TOOL_OPTIONS` 的最前面。因此无论是否设置了 +`JAVA_OPTIONS`，内存溢出时的堆转储（`heapdump_<主机名>_<启动时间>/java_pid.hprof`）和 JVM 崩溃日志（`hs_err_pid_<主机名>_<启动时间>.log`）都会写入 `logs/`，其中 `<启动时间>` 为本地时间，格式是 +`YYYYMMDD-HHMMSS`。每次启动都有自己的 `heapdump_*` 目录，因此服务及其启动的 JVM（例如 computer +任务）会分别写入各自的转储。主机名可避免共用同一日志目录的多个服务选到相同的名字；如果同一主机在同一秒内已经用过该名字，会再加上计数（`<启动时间>-1`、`-2`……）。如果无法创建该目录（例如磁盘已满），服务仍会启动，堆转储改为写入 `logs/` 本身。堆转储可能和堆一样大。启动脚本从不删除转储或 +`heapdump_*` 目录：每次启动都会留下一个目录，除非发生内存溢出否则为空；启动脚本保留它，是因为 computer 任务的 JVM 可能在服务退出后仍在使用它。在该次启动的 HugeGraph JVM +都已退出后，可以移走或删除旧目录，但不要动正在运行的服务最新的那个目录；没有它，下一次转储会被写成一个同名文件。JVM 会在这些默认值之后读取你自己的 `JAVA_TOOL_OPTIONS`、`JDK_JAVA_OPTIONS`（包括 `@argfile`）、命令行（`JAVA_OPTIONS`；未设置或为空时为 +`-j`）和 `_JAVA_OPTIONS`，因此在其中任意一处为上述参数指定的值都会覆盖默认值。只有环境变量会传给服务启动的 JVM：要对所有 JVM 关闭堆转储，请设置 `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`；通过 `-j` 或 +`JAVA_OPTIONS` 关闭只对服务自身的 JVM 生效。无论哪种方式，每次启动仍会创建空的 `heapdump_*` 目录。由于设置了这些默认值，JVM 启动时会在 stderr 输出 `Picked up JAVA_TOOL_OPTIONS: ...`。 + +> **版本范围**：以上行为适用于当前 master（[apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)）。1.7.0 只在未设置 `JAVA_OPTIONS` 时添加堆转储参数，堆转储直接写入 +> `logs/java_pid.hprof`，JVM 崩溃日志写入安装目录。 ### 5.2 使用 Docker diff --git a/content/en/docs/guides/hugegraph-docker-cluster.md b/content/en/docs/guides/hugegraph-docker-cluster.md index c2930fd6be..dbeb3b5b12 100644 --- a/content/en/docs/guides/hugegraph-docker-cluster.md +++ b/content/en/docs/guides/hugegraph-docker-cluster.md @@ -296,16 +296,17 @@ Standalone publishes only `8080` and `8088`; minimal HStore publishes `8620` (PD **Runtime logs**: `docker logs ` (for example, `docker logs hg-pd0`) shows logs without entering containers. In images built from current master, the PD, Store and both Server images (`hugegraph/hugegraph` and the HStore `hugegraph/server`) set `STDOUT_MODE=true` and send service logs to stdout. For the Server, WARN and above from Hadoop, ZooKeeper, SOFA, Netty and Commons also reaches stdout; INFO from Hadoop, Netty and Commons and the audit and -slow-query logs stay in files, and ZooKeeper and SOFA log nothing below WARN. The full `hugegraph-server.log`, JVM crash logs (`hs_err_pid*.log`) and -out-of-memory heap dumps (`heapdump_*/java_pid*.hprof`, one directory per launch so the Server and any JVM it starts get separate files) are in -`/hugegraph-server/logs`. `docker restart` keeps them, but Kubernetes starts a new container on every restart, so mount an `emptyDir` or a PersistentVolumeClaim -at `/hugegraph-server/logs` to keep them. A heap dump can be as large as the JVM heap, and every launch writes to a new file, so a Server that keeps running out -of memory adds one heap-sized dump per restart until the volume is full. The launcher never removes old dumps or `heapdump_*` directories, whether the volume is -an `emptyDir` (which also survives container restarts) or a PVC. Each start leaves a directory behind, empty unless something ran out of memory, because a -computer-job JVM can keep using it after its Server exits; old ones can be deleted once no HugeGraph JVM from that launch is running. Size the volume for the -number of dumps you want to keep plus the logs, move or delete old `heapdump_*` directories after each incident, or turn dumps off with -`JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`, which keeps the image's default `JAVA_OPTS`. Adding the flag to `JAVA_OPTS` also works, but setting -`JAVA_OPTS` replaces that default (`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`), so repeat those flags. +slow-query logs stay in files, and ZooKeeper and SOFA log nothing below WARN. `/hugegraph-server/logs` holds `hugegraph-server.log`, JVM crash logs +(`hs_err_pid*.log`) and out-of-memory heap dumps (`heapdump_*/java_pid*.hprof`, one directory per start, so the Server and the JVMs it starts get separate +files). `docker restart` keeps them, but recreating the container does not unless that path is a volume, and Kubernetes starts a new container on every restart, +so mount an `emptyDir` or a PersistentVolumeClaim at `/hugegraph-server/logs`. Give each pod its own volume (or a shared PVC with `subPathExpr: $(POD_NAME)`): +crash files get distinct names, but the log files themselves have fixed names. The Helm chart does not mount a logs volume yet. A heap dump can be as large as +the JVM heap, and every start uses a new directory, so a Server that keeps running out of memory fills the volume; size it for the dumps you want to keep, keep +it within any `ephemeral-storage` limit or `emptyDir` `sizeLimit` (eviction deletes the `emptyDir` with the dump), and do not use `medium: Memory`. The launcher +never deletes dumps or `heapdump_*` directories, because a computer-job JVM can go on using one after its Server exits; each start leaves one, empty unless +something ran out of memory. Delete old ones once no HugeGraph JVM from that launch is running, never the newest one of a running Server. To turn dumps off for +every JVM, set `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`, which keeps the image's default `JAVA_OPTS`; putting the flag in `JAVA_OPTS` affects the +Server JVM only and replaces that default (`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`), so repeat those flags. > **Version scope**: the paragraph above describes current master images ([apache/hugegraph#2980](https://github.com/apache/hugegraph/pull/2980) for PD, Store > and the standalone Server, [apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258) for the HStore Server). No 1.7.0 or older image sets diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index ab32b99ef6..cf815fdbd5 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -535,19 +535,22 @@ This indicates the successful creation of the sample graph. `bin/stop-hugegraph.sh` accepts `-m true|false` (default `true`), which controls whether the cron monitor task is removed along with the service. -The server script puts `-XX:+HeapDumpOnOutOfMemoryError`, `-XX:HeapDumpPath` and `-XX:ErrorFile` first in `JAVA_TOOL_OPTIONS`, so an out-of-memory heap dump -(`heapdump__/java_pid.hprof`) and a JVM crash log (`hs_err_pid__.log`) land in `logs/` whether or not -`JAVA_OPTIONS` is set. Each launch gets its own `heapdump_*` directory, so the server and any JVM it starts, such as a computer job, write separate dumps. The -host name (the pod name on Kubernetes) keeps servers that share one log directory from picking the same name. If a file with that name already exists, for -example after a restart that reuses the PID within the same second, a counter is added (`-1`, `-2`, ...). A heap dump can be as large as the heap, -and neither old dumps nor `heapdump_*` directories are ever removed (each start leaves one, empty unless something ran out of memory, because a computer-job JVM -can keep using it after the server exits), so a server that keeps running out of memory fills `logs/` with one dump per restart; move or delete old `heapdump_*` -directories after each incident. The JVM reads your own `JAVA_TOOL_OPTIONS`, `JDK_JAVA_OPTIONS`, the command line (`JAVA_OPTIONS`, or `-j` when `JAVA_OPTIONS` -is unset) and `_JAVA_OPTIONS` after these defaults, so a value for one of these flags in any of them overrides the default. For example, pass -`-XX:-HeapDumpOnOutOfMemoryError` with `-j` to turn dumps off. Because of the defaults, the JVM prints `Picked up JAVA_TOOL_OPTIONS: ...` at startup. - -> **Version scope**: this applies to current master ([apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)). In 1.7.0 the heap dump -> flags are added only when `JAVA_OPTIONS` is unset, and JVM crash logs go to the install directory. +`bin/hugegraph-server.sh` puts `-XX:+HeapDumpOnOutOfMemoryError`, `-XX:HeapDumpPath` and `-XX:ErrorFile` first in `JAVA_TOOL_OPTIONS`, so whether or not +`JAVA_OPTIONS` is set, an out-of-memory heap dump (`heapdump__/java_pid.hprof`) and a JVM crash log +(`hs_err_pid__.log`) land in `logs/`, where `` is the local time as `YYYYMMDD-HHMMSS`. Each start gets its own `heapdump_*` +directory, so the server and the JVMs it starts, such as computer jobs, write separate dumps. The host name keeps servers that share one log directory from +picking the same name, and a counter (`-1`, `-2`, ...) is added when the same host already used that second. If the directory cannot be created, +for example on a full disk, the server still starts and dumps go to `logs/` itself. A heap dump can be as large as the heap. The launcher never deletes dumps or +`heapdump_*` directories: each start leaves one, empty unless something ran out of memory, and the launcher keeps it because a computer-job JVM can go on using +it after the server exits. Move or delete old ones once no HugeGraph JVM from that launch is running, but never the newest one of a running server; without it, +the next dump is written as a file with that name. The JVM reads your own `JAVA_TOOL_OPTIONS`, `JDK_JAVA_OPTIONS` (including `@argfiles`), the command line +(`JAVA_OPTIONS`, or `-j` when `JAVA_OPTIONS` is unset or empty) and `_JAVA_OPTIONS` after these defaults, so a value for one of these flags in any of them +overrides the default. Only the environment variables reach the JVMs the server starts: to turn dumps off for all of them, set +`JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`, while `-j` or `JAVA_OPTIONS` turns them off for the server JVM only. Either way each start still creates +its empty `heapdump_*` directory. Because of the defaults, the JVM prints `Picked up JAVA_TOOL_OPTIONS: ...` on stderr at startup. + +> **Version scope**: this applies to current master ([apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)). In 1.7.0 the heap dump flags are +> added only when `JAVA_OPTIONS` is unset, heap dumps go directly to `logs/java_pid.hprof`, and JVM crash logs go to the install directory. ### 5.2 Use Docker to startup From 607500b9f1a7579d3467df0669c9cda76e07acb3 Mon Sep 17 00:00:00 2001 From: Ayan Alam Date: Wed, 7 Oct 2026 21:38:15 +0530 Subject: [PATCH 11/19] doc(server): set JAVA_TOOL_OPTIONS in the container's environment Exporting JAVA_TOOL_OPTIONS in the host shell has no effect: it has to be set with docker run -e, a Compose environment: entry (the shipped Compose files do not pass it through) or Kubernetes env. English and Chinese Docker guide. --- content/cn/docs/guides/hugegraph-docker-cluster.md | 5 +++-- content/en/docs/guides/hugegraph-docker-cluster.md | 6 ++++-- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/content/cn/docs/guides/hugegraph-docker-cluster.md b/content/cn/docs/guides/hugegraph-docker-cluster.md index b6f51b45a6..792fde759a 100644 --- a/content/cn/docs/guides/hugegraph-docker-cluster.md +++ b/content/cn/docs/guides/hugegraph-docker-cluster.md @@ -300,8 +300,9 @@ INFO 日志以及审计日志、慢查询日志仍只写入文件，ZooKeeper 会保留这些文件，但重新创建容器时，除非该路径是一个卷，否则文件会丢失；Kubernetes 每次重启都会新建容器，因此需要在 `/hugegraph-server/logs` 挂载 `emptyDir` 或 PersistentVolumeClaim。请为每个 Pod 使用单独的卷（或在共享 PVC 上使用 `subPathExpr: $(POD_NAME)`）：崩溃文件的名字各不相同，但日志文件本身的名字是固定的。Helm Chart 目前还不会挂载日志卷。堆转储可能和 JVM 堆一样大，而且每次启动都会使用新目录，因此反复内存溢出的 Server 会把卷写满；请按需要保留的转储数量规划卷大小，并确保不超过 `ephemeral-storage` 限制或 `emptyDir` 的 `sizeLimit`（被驱逐时 `emptyDir` 会连同转储一起删除），也不要使用 `medium: Memory`。启动脚本从不删除转储或 `heapdump_*` 目录，因为 computer 任务的 JVM 可能在 Server -退出后仍在使用它；每次启动都会留下一个目录，除非发生内存溢出否则为空。在该次启动的 HugeGraph JVM 都已退出后可以删除旧目录，但不要动正在运行的 Server 最新的那个目录。要对所有 JVM 关闭堆转储，请设置 -`JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`，这样会保留镜像默认的 `JAVA_OPTS`；把该参数加到 `JAVA_OPTS` 中只对 Server 自身的 JVM +退出后仍在使用它；每次启动都会留下一个目录，除非发生内存溢出否则为空。在该次启动的 HugeGraph JVM 都已退出后可以删除旧目录，但不要动正在运行的 Server 最新的那个目录。要对所有 JVM 关闭堆转储，请在容器的环境变量中设置 +`JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`（可以使用 `docker run -e`，或在 Compose 中 Server 服务的 `environment:` 里添加，自带的 Compose 文件没有设置它，或在 Kubernetes 中使用 +`env`；只在宿主机 shell 中导出不会生效），这样会保留镜像默认的 `JAVA_OPTS`；把该参数加到 `JAVA_OPTS` 中只对 Server 自身的 JVM 生效，而且会替换镜像默认值（`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`），需要把这些参数一并写上。 > **版本范围**：上文描述的是基于当前 master 构建的镜像（PD、Store 和单机 Server 见 [apache/hugegraph#2980](https://github.com/apache/hugegraph/pull/2980)，HStore Server 见 diff --git a/content/en/docs/guides/hugegraph-docker-cluster.md b/content/en/docs/guides/hugegraph-docker-cluster.md index dbeb3b5b12..99eb0e8c31 100644 --- a/content/en/docs/guides/hugegraph-docker-cluster.md +++ b/content/en/docs/guides/hugegraph-docker-cluster.md @@ -305,8 +305,10 @@ the JVM heap, and every start uses a new directory, so a Server that keeps runni it within any `ephemeral-storage` limit or `emptyDir` `sizeLimit` (eviction deletes the `emptyDir` with the dump), and do not use `medium: Memory`. The launcher never deletes dumps or `heapdump_*` directories, because a computer-job JVM can go on using one after its Server exits; each start leaves one, empty unless something ran out of memory. Delete old ones once no HugeGraph JVM from that launch is running, never the newest one of a running Server. To turn dumps off for -every JVM, set `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`, which keeps the image's default `JAVA_OPTS`; putting the flag in `JAVA_OPTS` affects the -Server JVM only and replaces that default (`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`), so repeat those flags. +every JVM, set `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError` in the container's environment (`docker run -e`, an `environment:` entry on the Server +service in Compose, which the shipped Compose files do not set, or `env` in Kubernetes; exporting it in the host shell has no effect), which keeps the image's +default `JAVA_OPTS`; putting the flag in `JAVA_OPTS` affects the Server JVM only and replaces that default +(`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`), so repeat those flags. > **Version scope**: the paragraph above describes current master images ([apache/hugegraph#2980](https://github.com/apache/hugegraph/pull/2980) for PD, Store > and the standalone Server, [apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258) for the HStore Server). No 1.7.0 or older image sets From 96ef347bd9713e470137fa5dc74d789f7f15fbd4 Mon Sep 17 00:00:00 2001 From: Ayan Alam Date: Wed, 7 Oct 2026 22:09:23 +0530 Subject: [PATCH 12/19] doc(server): correct what Compose keeps across container recreates Both images declare VOLUME /hugegraph-server, so docker restart and a Compose recreate keep logs/, and docker compose down leaves an unattached anonymous volume until down -v. Recommend a named volume or bind mount instead of saying a recreate loses the files. English and Chinese Docker guide. --- content/cn/docs/guides/hugegraph-docker-cluster.md | 14 +++++++------- content/en/docs/guides/hugegraph-docker-cluster.md | 5 +++-- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/content/cn/docs/guides/hugegraph-docker-cluster.md b/content/cn/docs/guides/hugegraph-docker-cluster.md index 792fde759a..9e6e152662 100644 --- a/content/cn/docs/guides/hugegraph-docker-cluster.md +++ b/content/cn/docs/guides/hugegraph-docker-cluster.md @@ -296,13 +296,13 @@ curl -o /dev/null -w '%{http_code}\n' -u "admin:${HUGEGRAPH_ADMIN_PASSWORD}" \ **查看运行时日志**：使用 `docker logs `（如 `docker logs hg-pd0`）可直接查看日志，无需进入容器。基于当前 master 构建的 PD、Store 以及两个 Server 镜像（`hugegraph/hugegraph` 和 HStore 的 `hugegraph/server`）都设置了 `STDOUT_MODE=true`，服务日志会输出到容器 stdout。对 Server 而言，Hadoop、ZooKeeper、SOFA、Netty 和 Commons 的 WARN 及以上日志也会输出到 stdout；Hadoop、Netty 和 Commons 的 INFO 日志以及审计日志、慢查询日志仍只写入文件，ZooKeeper 和 SOFA 不输出 WARN 以下的日志。`/hugegraph-server/logs` 中包含 `hugegraph-server.log`、JVM -崩溃日志（`hs_err_pid*.log`）和内存溢出时的堆转储（`heapdump_*/java_pid*.hprof`，每次启动一个目录，Server 及其启动的 JVM 分别写入各自的文件）。`docker restart` -会保留这些文件，但重新创建容器时，除非该路径是一个卷，否则文件会丢失；Kubernetes 每次重启都会新建容器，因此需要在 `/hugegraph-server/logs` 挂载 `emptyDir` 或 PersistentVolumeClaim。请为每个 Pod 使用单独的卷（或在共享 PVC 上使用 -`subPathExpr: $(POD_NAME)`）：崩溃文件的名字各不相同，但日志文件本身的名字是固定的。Helm Chart 目前还不会挂载日志卷。堆转储可能和 JVM 堆一样大，而且每次启动都会使用新目录，因此反复内存溢出的 Server 会把卷写满；请按需要保留的转储数量规划卷大小，并确保不超过 -`ephemeral-storage` 限制或 `emptyDir` 的 `sizeLimit`（被驱逐时 `emptyDir` 会连同转储一起删除），也不要使用 `medium: Memory`。启动脚本从不删除转储或 `heapdump_*` 目录，因为 computer 任务的 JVM 可能在 Server -退出后仍在使用它；每次启动都会留下一个目录，除非发生内存溢出否则为空。在该次启动的 HugeGraph JVM 都已退出后可以删除旧目录，但不要动正在运行的 Server 最新的那个目录。要对所有 JVM 关闭堆转储，请在容器的环境变量中设置 -`JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`（可以使用 `docker run -e`，或在 Compose 中 Server 服务的 `environment:` 里添加，自带的 Compose 文件没有设置它，或在 Kubernetes 中使用 -`env`；只在宿主机 shell 中导出不会生效），这样会保留镜像默认的 `JAVA_OPTS`；把该参数加到 `JAVA_OPTS` 中只对 Server 自身的 JVM +崩溃日志（`hs_err_pid*.log`）和内存溢出时的堆转储（`heapdump_*/java_pid*.hprof`，每次启动一个目录，Server 及其启动的 JVM 分别写入各自的文件）。两个镜像都声明了 `VOLUME /hugegraph-server`，因此 `docker restart` 和 +Compose 重新创建容器都会保留这些文件；`docker compose down` 会留下这个匿名卷，但下一次 `up` 不会再挂载它，直到 `down -v` 将其删除，所以请使用具名卷或绑定挂载来保留这些文件。Kubernetes 每次重启都会新建容器，因此需要在 +`/hugegraph-server/logs` 挂载 `emptyDir` 或 PersistentVolumeClaim。请为每个 Pod 使用单独的卷（或在共享 PVC 上使用 `subPathExpr: $(POD_NAME)`）：崩溃文件的名字各不相同，但日志文件本身的名字是固定的。Helm Chart +目前还不会挂载日志卷。堆转储可能和 JVM 堆一样大，而且每次启动都会使用新目录，因此反复内存溢出的 Server 会把卷写满；请按需要保留的转储数量规划卷大小，并确保不超过 `ephemeral-storage` 限制或 `emptyDir` 的 `sizeLimit`（被驱逐时 `emptyDir` +会连同转储一起删除），也不要使用 `medium: Memory`。启动脚本从不删除转储或 `heapdump_*` 目录，因为 computer 任务的 JVM 可能在 Server 退出后仍在使用它；每次启动都会留下一个目录，除非发生内存溢出否则为空。在该次启动的 HugeGraph JVM +都已退出后可以删除旧目录，但不要动正在运行的 Server 最新的那个目录。要对所有 JVM 关闭堆转储，请在容器的环境变量中设置 `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`（可以使用 `docker run -e`，或在 Compose 中 Server +服务的 `environment:` 里添加，自带的 Compose 文件没有设置它，或在 Kubernetes 中使用 `env`；只在宿主机 shell 中导出不会生效），这样会保留镜像默认的 `JAVA_OPTS`；把该参数加到 `JAVA_OPTS` 中只对 Server 自身的 JVM 生效，而且会替换镜像默认值（`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`），需要把这些参数一并写上。 > **版本范围**：上文描述的是基于当前 master 构建的镜像（PD、Store 和单机 Server 见 [apache/hugegraph#2980](https://github.com/apache/hugegraph/pull/2980)，HStore Server 见 diff --git a/content/en/docs/guides/hugegraph-docker-cluster.md b/content/en/docs/guides/hugegraph-docker-cluster.md index 99eb0e8c31..30c09dff61 100644 --- a/content/en/docs/guides/hugegraph-docker-cluster.md +++ b/content/en/docs/guides/hugegraph-docker-cluster.md @@ -298,8 +298,9 @@ master, the PD, Store and both Server images (`hugegraph/hugegraph` and the HSto For the Server, WARN and above from Hadoop, ZooKeeper, SOFA, Netty and Commons also reaches stdout; INFO from Hadoop, Netty and Commons and the audit and slow-query logs stay in files, and ZooKeeper and SOFA log nothing below WARN. `/hugegraph-server/logs` holds `hugegraph-server.log`, JVM crash logs (`hs_err_pid*.log`) and out-of-memory heap dumps (`heapdump_*/java_pid*.hprof`, one directory per start, so the Server and the JVMs it starts get separate -files). `docker restart` keeps them, but recreating the container does not unless that path is a volume, and Kubernetes starts a new container on every restart, -so mount an `emptyDir` or a PersistentVolumeClaim at `/hugegraph-server/logs`. Give each pod its own volume (or a shared PVC with `subPathExpr: $(POD_NAME)`): +files). Both images declare `VOLUME /hugegraph-server`, so `docker restart` and a Compose recreate keep them; `docker compose down` leaves that anonymous volume +behind unattached until `down -v` deletes it, so use a named volume or bind mount to keep them reachable. Kubernetes starts a new container on every restart, so +mount an `emptyDir` or a PersistentVolumeClaim at `/hugegraph-server/logs`. Give each pod its own volume (or a shared PVC with `subPathExpr: $(POD_NAME)`): crash files get distinct names, but the log files themselves have fixed names. The Helm chart does not mount a logs volume yet. A heap dump can be as large as the JVM heap, and every start uses a new directory, so a Server that keeps running out of memory fills the volume; size it for the dumps you want to keep, keep it within any `ephemeral-storage` limit or `emptyDir` `sizeLimit` (eviction deletes the `emptyDir` with the dump), and do not use `medium: Memory`. The launcher From 90886abb067f2bbc50440d0525f9b4c26171f9cb Mon Sep 17 00:00:00 2001 From: Ayan Alam Date: Thu, 8 Oct 2026 08:57:51 +0530 Subject: [PATCH 13/19] doc(server): correct the subPathExpr and full-disk fallback notes - A per-pod directory on a shared PVC needs POD_NAME passed in from metadata.name through the Downward API before subPathExpr: $(POD_NAME) works; say so, and that the Helm chart sets neither. - Call the fallback to logs/ best effort: a full disk may have no room for the dump either. English and Chinese. --- .../docs/guides/hugegraph-docker-cluster.md | 11 +++++----- .../quickstart/hugegraph/hugegraph-server.md | 4 ++-- .../docs/guides/hugegraph-docker-cluster.md | 21 ++++++++++--------- .../quickstart/hugegraph/hugegraph-server.md | 17 ++++++++------- 4 files changed, 28 insertions(+), 25 deletions(-) diff --git a/content/cn/docs/guides/hugegraph-docker-cluster.md b/content/cn/docs/guides/hugegraph-docker-cluster.md index 9e6e152662..577b29a8f0 100644 --- a/content/cn/docs/guides/hugegraph-docker-cluster.md +++ b/content/cn/docs/guides/hugegraph-docker-cluster.md @@ -298,11 +298,12 @@ curl -o /dev/null -w '%{http_code}\n' -u "admin:${HUGEGRAPH_ADMIN_PASSWORD}" \ INFO 日志以及审计日志、慢查询日志仍只写入文件，ZooKeeper 和 SOFA 不输出 WARN 以下的日志。`/hugegraph-server/logs` 中包含 `hugegraph-server.log`、JVM 崩溃日志（`hs_err_pid*.log`）和内存溢出时的堆转储（`heapdump_*/java_pid*.hprof`，每次启动一个目录，Server 及其启动的 JVM 分别写入各自的文件）。两个镜像都声明了 `VOLUME /hugegraph-server`，因此 `docker restart` 和 Compose 重新创建容器都会保留这些文件；`docker compose down` 会留下这个匿名卷，但下一次 `up` 不会再挂载它，直到 `down -v` 将其删除，所以请使用具名卷或绑定挂载来保留这些文件。Kubernetes 每次重启都会新建容器，因此需要在 -`/hugegraph-server/logs` 挂载 `emptyDir` 或 PersistentVolumeClaim。请为每个 Pod 使用单独的卷（或在共享 PVC 上使用 `subPathExpr: $(POD_NAME)`）：崩溃文件的名字各不相同，但日志文件本身的名字是固定的。Helm Chart -目前还不会挂载日志卷。堆转储可能和 JVM 堆一样大，而且每次启动都会使用新目录，因此反复内存溢出的 Server 会把卷写满；请按需要保留的转储数量规划卷大小，并确保不超过 `ephemeral-storage` 限制或 `emptyDir` 的 `sizeLimit`（被驱逐时 `emptyDir` -会连同转储一起删除），也不要使用 `medium: Memory`。启动脚本从不删除转储或 `heapdump_*` 目录，因为 computer 任务的 JVM 可能在 Server 退出后仍在使用它；每次启动都会留下一个目录，除非发生内存溢出否则为空。在该次启动的 HugeGraph JVM -都已退出后可以删除旧目录，但不要动正在运行的 Server 最新的那个目录。要对所有 JVM 关闭堆转储，请在容器的环境变量中设置 `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`（可以使用 `docker run -e`，或在 Compose 中 Server -服务的 `environment:` 里添加，自带的 Compose 文件没有设置它，或在 Kubernetes 中使用 `env`；只在宿主机 shell 中导出不会生效），这样会保留镜像默认的 `JAVA_OPTS`；把该参数加到 `JAVA_OPTS` 中只对 Server 自身的 JVM +`/hugegraph-server/logs` 挂载 `emptyDir` 或 PersistentVolumeClaim。请为每个 Pod 使用单独的卷，或在共享 PVC 上为每个 Pod 使用单独的目录（`subPathExpr: $(POD_NAME)`，并通过 Downward API 从 +`metadata.name` 传入 `POD_NAME`；Helm Chart 两者都没有设置）：崩溃文件的名字各不相同，但日志文件本身的名字是固定的。Helm Chart 目前还不会挂载日志卷。堆转储可能和 JVM 堆一样大，而且每次启动都会使用新目录，因此反复内存溢出的 Server +会把卷写满；请按需要保留的转储数量规划卷大小，并确保不超过 `ephemeral-storage` 限制或 `emptyDir` 的 `sizeLimit`（被驱逐时 `emptyDir` 会连同转储一起删除），也不要使用 `medium: Memory`。启动脚本从不删除转储或 `heapdump_*` 目录，因为 +computer 任务的 JVM 可能在 Server 退出后仍在使用它；每次启动都会留下一个目录，除非发生内存溢出否则为空。在该次启动的 HugeGraph JVM 都已退出后可以删除旧目录，但不要动正在运行的 Server 最新的那个目录。要对所有 JVM 关闭堆转储，请在容器的环境变量中设置 +`JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`（可以使用 `docker run -e`，或在 Compose 中 Server 服务的 `environment:` 里添加，自带的 Compose 文件没有设置它，或在 Kubernetes 中使用 +`env`；只在宿主机 shell 中导出不会生效），这样会保留镜像默认的 `JAVA_OPTS`；把该参数加到 `JAVA_OPTS` 中只对 Server 自身的 JVM 生效，而且会替换镜像默认值（`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`），需要把这些参数一并写上。 > **版本范围**：上文描述的是基于当前 master 构建的镜像（PD、Store 和单机 Server 见 [apache/hugegraph#2980](https://github.com/apache/hugegraph/pull/2980)，HStore Server 见 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index 378392fde3..fde2f846a7 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md @@ -539,8 +539,8 @@ Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)......OK `bin/hugegraph-server.sh` 会把 `-XX:+HeapDumpOnOutOfMemoryError`、`-XX:HeapDumpPath` 和 `-XX:ErrorFile` 放在 `JAVA_TOOL_OPTIONS` 的最前面。因此无论是否设置了 `JAVA_OPTIONS`，内存溢出时的堆转储（`heapdump_<主机名>_<启动时间>/java_pid.hprof`）和 JVM 崩溃日志（`hs_err_pid_<主机名>_<启动时间>.log`）都会写入 `logs/`，其中 `<启动时间>` 为本地时间，格式是 `YYYYMMDD-HHMMSS`。每次启动都有自己的 `heapdump_*` 目录，因此服务及其启动的 JVM（例如 computer -任务）会分别写入各自的转储。主机名可避免共用同一日志目录的多个服务选到相同的名字；如果同一主机在同一秒内已经用过该名字，会再加上计数（`<启动时间>-1`、`-2`……）。如果无法创建该目录（例如磁盘已满），服务仍会启动，堆转储改为写入 `logs/` 本身。堆转储可能和堆一样大。启动脚本从不删除转储或 -`heapdump_*` 目录：每次启动都会留下一个目录，除非发生内存溢出否则为空；启动脚本保留它，是因为 computer 任务的 JVM 可能在服务退出后仍在使用它。在该次启动的 HugeGraph JVM +任务）会分别写入各自的转储。主机名可避免共用同一日志目录的多个服务选到相同的名字；如果同一主机在同一秒内已经用过该名字，会再加上计数（`<启动时间>-1`、`-2`……）。如果无法创建该目录（例如磁盘已满），服务仍会启动，堆转储改为尽力写入 `logs/` +本身；磁盘已满时可能也没有空间写入转储。堆转储可能和堆一样大。启动脚本从不删除转储或 `heapdump_*` 目录：每次启动都会留下一个目录，除非发生内存溢出否则为空；启动脚本保留它，是因为 computer 任务的 JVM 可能在服务退出后仍在使用它。在该次启动的 HugeGraph JVM 都已退出后，可以移走或删除旧目录，但不要动正在运行的服务最新的那个目录；没有它，下一次转储会被写成一个同名文件。JVM 会在这些默认值之后读取你自己的 `JAVA_TOOL_OPTIONS`、`JDK_JAVA_OPTIONS`（包括 `@argfile`）、命令行（`JAVA_OPTIONS`；未设置或为空时为 `-j`）和 `_JAVA_OPTIONS`，因此在其中任意一处为上述参数指定的值都会覆盖默认值。只有环境变量会传给服务启动的 JVM：要对所有 JVM 关闭堆转储，请设置 `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`；通过 `-j` 或 `JAVA_OPTIONS` 关闭只对服务自身的 JVM 生效。无论哪种方式，每次启动仍会创建空的 `heapdump_*` 目录。由于设置了这些默认值，JVM 启动时会在 stderr 输出 `Picked up JAVA_TOOL_OPTIONS: ...`。 diff --git a/content/en/docs/guides/hugegraph-docker-cluster.md b/content/en/docs/guides/hugegraph-docker-cluster.md index 30c09dff61..32d29d1c11 100644 --- a/content/en/docs/guides/hugegraph-docker-cluster.md +++ b/content/en/docs/guides/hugegraph-docker-cluster.md @@ -300,16 +300,17 @@ slow-query logs stay in files, and ZooKeeper and SOFA log nothing below WARN. `/ (`hs_err_pid*.log`) and out-of-memory heap dumps (`heapdump_*/java_pid*.hprof`, one directory per start, so the Server and the JVMs it starts get separate files). Both images declare `VOLUME /hugegraph-server`, so `docker restart` and a Compose recreate keep them; `docker compose down` leaves that anonymous volume behind unattached until `down -v` deletes it, so use a named volume or bind mount to keep them reachable. Kubernetes starts a new container on every restart, so -mount an `emptyDir` or a PersistentVolumeClaim at `/hugegraph-server/logs`. Give each pod its own volume (or a shared PVC with `subPathExpr: $(POD_NAME)`): -crash files get distinct names, but the log files themselves have fixed names. The Helm chart does not mount a logs volume yet. A heap dump can be as large as -the JVM heap, and every start uses a new directory, so a Server that keeps running out of memory fills the volume; size it for the dumps you want to keep, keep -it within any `ephemeral-storage` limit or `emptyDir` `sizeLimit` (eviction deletes the `emptyDir` with the dump), and do not use `medium: Memory`. The launcher -never deletes dumps or `heapdump_*` directories, because a computer-job JVM can go on using one after its Server exits; each start leaves one, empty unless -something ran out of memory. Delete old ones once no HugeGraph JVM from that launch is running, never the newest one of a running Server. To turn dumps off for -every JVM, set `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError` in the container's environment (`docker run -e`, an `environment:` entry on the Server -service in Compose, which the shipped Compose files do not set, or `env` in Kubernetes; exporting it in the host shell has no effect), which keeps the image's -default `JAVA_OPTS`; putting the flag in `JAVA_OPTS` affects the Server JVM only and replaces that default -(`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`), so repeat those flags. +mount an `emptyDir` or a PersistentVolumeClaim at `/hugegraph-server/logs`. Give each pod its own volume, or a per-pod directory on a shared PVC +(`subPathExpr: $(POD_NAME)`, with `POD_NAME` passed in from `metadata.name` through the Downward API; the Helm chart sets neither): crash files get distinct +names, but the log files themselves have fixed names. The Helm chart does not mount a logs volume yet. A heap dump can be as large as the JVM heap, and every +start uses a new directory, so a Server that keeps running out of memory fills the volume; size it for the dumps you want to keep, keep it within any +`ephemeral-storage` limit or `emptyDir` `sizeLimit` (eviction deletes the `emptyDir` with the dump), and do not use `medium: Memory`. The launcher never deletes +dumps or `heapdump_*` directories, because a computer-job JVM can go on using one after its Server exits; each start leaves one, empty unless something ran out +of memory. Delete old ones once no HugeGraph JVM from that launch is running, never the newest one of a running Server. To turn dumps off for every JVM, set +`JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError` in the container's environment (`docker run -e`, an `environment:` entry on the Server service in Compose, +which the shipped Compose files do not set, or `env` in Kubernetes; exporting it in the host shell has no effect), which keeps the image's default `JAVA_OPTS`; +putting the flag in `JAVA_OPTS` affects the Server JVM only and replaces that default (`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`), so repeat those +flags. > **Version scope**: the paragraph above describes current master images ([apache/hugegraph#2980](https://github.com/apache/hugegraph/pull/2980) for PD, Store > and the standalone Server, [apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258) for the HStore Server). No 1.7.0 or older image sets diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index cf815fdbd5..d8aa032940 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -540,14 +540,15 @@ This indicates the successful creation of the sample graph. (`hs_err_pid__.log`) land in `logs/`, where `` is the local time as `YYYYMMDD-HHMMSS`. Each start gets its own `heapdump_*` directory, so the server and the JVMs it starts, such as computer jobs, write separate dumps. The host name keeps servers that share one log directory from picking the same name, and a counter (`-1`, `-2`, ...) is added when the same host already used that second. If the directory cannot be created, -for example on a full disk, the server still starts and dumps go to `logs/` itself. A heap dump can be as large as the heap. The launcher never deletes dumps or -`heapdump_*` directories: each start leaves one, empty unless something ran out of memory, and the launcher keeps it because a computer-job JVM can go on using -it after the server exits. Move or delete old ones once no HugeGraph JVM from that launch is running, but never the newest one of a running server; without it, -the next dump is written as a file with that name. The JVM reads your own `JAVA_TOOL_OPTIONS`, `JDK_JAVA_OPTIONS` (including `@argfiles`), the command line -(`JAVA_OPTIONS`, or `-j` when `JAVA_OPTIONS` is unset or empty) and `_JAVA_OPTIONS` after these defaults, so a value for one of these flags in any of them -overrides the default. Only the environment variables reach the JVMs the server starts: to turn dumps off for all of them, set -`JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`, while `-j` or `JAVA_OPTIONS` turns them off for the server JVM only. Either way each start still creates -its empty `heapdump_*` directory. Because of the defaults, the JVM prints `Picked up JAVA_TOOL_OPTIONS: ...` on stderr at startup. +for example on a full disk, the server still starts and dumps go to `logs/` itself, as a best effort: a full disk may have no room for the dump either. A heap +dump can be as large as the heap. The launcher never deletes dumps or `heapdump_*` directories: each start leaves one, empty unless something ran out of memory, +and the launcher keeps it because a computer-job JVM can go on using it after the server exits. Move or delete old ones once no HugeGraph JVM from that launch +is running, but never the newest one of a running server; without it, the next dump is written as a file with that name. The JVM reads your own +`JAVA_TOOL_OPTIONS`, `JDK_JAVA_OPTIONS` (including `@argfiles`), the command line (`JAVA_OPTIONS`, or `-j` when `JAVA_OPTIONS` is unset or empty) and +`_JAVA_OPTIONS` after these defaults, so a value for one of these flags in any of them overrides the default. Only the environment variables reach the JVMs the +server starts: to turn dumps off for all of them, set `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`, while `-j` or `JAVA_OPTIONS` turns them off for the +server JVM only. Either way each start still creates its empty `heapdump_*` directory. Because of the defaults, the JVM prints +`Picked up JAVA_TOOL_OPTIONS: ...` on stderr at startup. > **Version scope**: this applies to current master ([apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)). In 1.7.0 the heap dump flags are > added only when `JAVA_OPTIONS` is unset, heap dumps go directly to `logs/java_pid.hprof`, and JVM crash logs go to the install directory. From 546af0f1ade58bed6224bd1dec18f5d06f5e108e Mon Sep 17 00:00:00 2001 From: Ayan Alam Date: Fri, 9 Oct 2026 12:16:28 +0530 Subject: [PATCH 14/19] doc(server): qualify per-JVM dumps and the per-start directory - HotSpot names each dump after the JVM's PID, so a JVM that reuses an earlier PID from the same start cannot write its dump. - Each start creates its empty heapdump_* directory unless creating it failed and dumps fell back to logs/. English and Chinese quickstart, matching apache/hugegraph#3258. --- .../quickstart/hugegraph/hugegraph-server.md | 6 +++--- .../quickstart/hugegraph/hugegraph-server.md | 21 ++++++++++--------- 2 files changed, 14 insertions(+), 13 deletions(-) diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index fde2f846a7..2ad7e47c0a 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md @@ -538,12 +538,12 @@ Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)......OK `bin/hugegraph-server.sh` 会把 `-XX:+HeapDumpOnOutOfMemoryError`、`-XX:HeapDumpPath` 和 `-XX:ErrorFile` 放在 `JAVA_TOOL_OPTIONS` 的最前面。因此无论是否设置了 `JAVA_OPTIONS`，内存溢出时的堆转储（`heapdump_<主机名>_<启动时间>/java_pid.hprof`）和 JVM 崩溃日志（`hs_err_pid_<主机名>_<启动时间>.log`）都会写入 `logs/`，其中 `<启动时间>` 为本地时间，格式是 -`YYYYMMDD-HHMMSS`。每次启动都有自己的 `heapdump_*` 目录，因此服务及其启动的 JVM（例如 computer -任务）会分别写入各自的转储。主机名可避免共用同一日志目录的多个服务选到相同的名字；如果同一主机在同一秒内已经用过该名字，会再加上计数（`<启动时间>-1`、`-2`……）。如果无法创建该目录（例如磁盘已满），服务仍会启动，堆转储改为尽力写入 `logs/` +`YYYYMMDD-HHMMSS`。每次启动都有自己的 `heapdump_*` 目录，因此服务及其启动的 JVM（例如 computer 任务）会分别写入各自的转储（HotSpot 按 JVM 的 PID 命名转储文件，因此同一次启动中复用了先前 PID 的 JVM +无法写入它的转储）。主机名可避免共用同一日志目录的多个服务选到相同的名字；如果同一主机在同一秒内已经用过该名字，会再加上计数（`<启动时间>-1`、`-2`……）。如果无法创建该目录（例如磁盘已满），服务仍会启动，堆转储改为尽力写入 `logs/` 本身；磁盘已满时可能也没有空间写入转储。堆转储可能和堆一样大。启动脚本从不删除转储或 `heapdump_*` 目录：每次启动都会留下一个目录，除非发生内存溢出否则为空；启动脚本保留它，是因为 computer 任务的 JVM 可能在服务退出后仍在使用它。在该次启动的 HugeGraph JVM 都已退出后，可以移走或删除旧目录，但不要动正在运行的服务最新的那个目录；没有它，下一次转储会被写成一个同名文件。JVM 会在这些默认值之后读取你自己的 `JAVA_TOOL_OPTIONS`、`JDK_JAVA_OPTIONS`（包括 `@argfile`）、命令行（`JAVA_OPTIONS`；未设置或为空时为 `-j`）和 `_JAVA_OPTIONS`，因此在其中任意一处为上述参数指定的值都会覆盖默认值。只有环境变量会传给服务启动的 JVM：要对所有 JVM 关闭堆转储，请设置 `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`；通过 `-j` 或 -`JAVA_OPTIONS` 关闭只对服务自身的 JVM 生效。无论哪种方式，每次启动仍会创建空的 `heapdump_*` 目录。由于设置了这些默认值，JVM 启动时会在 stderr 输出 `Picked up JAVA_TOOL_OPTIONS: ...`。 +`JAVA_OPTIONS` 关闭只对服务自身的 JVM 生效。无论哪种方式，每次启动仍会创建空的 `heapdump_*` 目录，除非创建失败而改为写入 `logs/`。由于设置了这些默认值，JVM 启动时会在 stderr 输出 `Picked up JAVA_TOOL_OPTIONS: ...`。 > **版本范围**：以上行为适用于当前 master（[apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)）。1.7.0 只在未设置 `JAVA_OPTIONS` 时添加堆转储参数，堆转储直接写入 > `logs/java_pid.hprof`，JVM 崩溃日志写入安装目录。 diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index d8aa032940..cc29bb896f 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -538,16 +538,17 @@ This indicates the successful creation of the sample graph. `bin/hugegraph-server.sh` puts `-XX:+HeapDumpOnOutOfMemoryError`, `-XX:HeapDumpPath` and `-XX:ErrorFile` first in `JAVA_TOOL_OPTIONS`, so whether or not `JAVA_OPTIONS` is set, an out-of-memory heap dump (`heapdump__/java_pid.hprof`) and a JVM crash log (`hs_err_pid__.log`) land in `logs/`, where `` is the local time as `YYYYMMDD-HHMMSS`. Each start gets its own `heapdump_*` -directory, so the server and the JVMs it starts, such as computer jobs, write separate dumps. The host name keeps servers that share one log directory from -picking the same name, and a counter (`-1`, `-2`, ...) is added when the same host already used that second. If the directory cannot be created, -for example on a full disk, the server still starts and dumps go to `logs/` itself, as a best effort: a full disk may have no room for the dump either. A heap -dump can be as large as the heap. The launcher never deletes dumps or `heapdump_*` directories: each start leaves one, empty unless something ran out of memory, -and the launcher keeps it because a computer-job JVM can go on using it after the server exits. Move or delete old ones once no HugeGraph JVM from that launch -is running, but never the newest one of a running server; without it, the next dump is written as a file with that name. The JVM reads your own -`JAVA_TOOL_OPTIONS`, `JDK_JAVA_OPTIONS` (including `@argfiles`), the command line (`JAVA_OPTIONS`, or `-j` when `JAVA_OPTIONS` is unset or empty) and -`_JAVA_OPTIONS` after these defaults, so a value for one of these flags in any of them overrides the default. Only the environment variables reach the JVMs the -server starts: to turn dumps off for all of them, set `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`, while `-j` or `JAVA_OPTIONS` turns them off for the -server JVM only. Either way each start still creates its empty `heapdump_*` directory. Because of the defaults, the JVM prints +directory, so the server and the JVMs it starts, such as computer jobs, write separate dumps (HotSpot names each dump after the JVM's PID, so a JVM that reuses +an earlier PID from the same start cannot write its dump). The host name keeps servers that share one log directory from picking the same name, and a counter +(`-1`, `-2`, ...) is added when the same host already used that second. If the directory cannot be created, for example on a full disk, the server +still starts and dumps go to `logs/` itself, as a best effort: a full disk may have no room for the dump either. A heap dump can be as large as the heap. The +launcher never deletes dumps or `heapdump_*` directories: each start leaves one, empty unless something ran out of memory, and the launcher keeps it because a +computer-job JVM can go on using it after the server exits. Move or delete old ones once no HugeGraph JVM from that launch is running, but never the newest one +of a running server; without it, the next dump is written as a file with that name. The JVM reads your own `JAVA_TOOL_OPTIONS`, `JDK_JAVA_OPTIONS` (including +`@argfiles`), the command line (`JAVA_OPTIONS`, or `-j` when `JAVA_OPTIONS` is unset or empty) and `_JAVA_OPTIONS` after these defaults, so a value for one of +these flags in any of them overrides the default. Only the environment variables reach the JVMs the server starts: to turn dumps off for all of them, set +`JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`, while `-j` or `JAVA_OPTIONS` turns them off for the server JVM only. Either way each start still creates +its empty `heapdump_*` directory, unless creating it failed and dumps fell back to `logs/`. Because of the defaults, the JVM prints `Picked up JAVA_TOOL_OPTIONS: ...` on stderr at startup. > **Version scope**: this applies to current master ([apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)). In 1.7.0 the heap dump flags are From 406387713fdfeafabdd885524643724ecdf22344 Mon Sep 17 00:00:00 2001 From: Ayan Alam Date: Sat, 10 Oct 2026 14:13:25 +0530 Subject: [PATCH 15/19] doc(server): describe heap dumps for a logs path with a quote or % apache/hugegraph#3258 keeps the 1.7.0 behaviour for the server when the logs path contains a double quote or %: heap dumps go to logs/ itself, with no per-launch directory and no crash log default, and the launcher warns. Say so in the English and Chinese quickstart. --- content/cn/docs/quickstart/hugegraph/hugegraph-server.md | 3 ++- content/en/docs/quickstart/hugegraph/hugegraph-server.md | 5 +++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index 2ad7e47c0a..4a9dfb1f8d 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md @@ -543,7 +543,8 @@ Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)......OK 本身；磁盘已满时可能也没有空间写入转储。堆转储可能和堆一样大。启动脚本从不删除转储或 `heapdump_*` 目录：每次启动都会留下一个目录，除非发生内存溢出否则为空；启动脚本保留它，是因为 computer 任务的 JVM 可能在服务退出后仍在使用它。在该次启动的 HugeGraph JVM 都已退出后，可以移走或删除旧目录，但不要动正在运行的服务最新的那个目录；没有它，下一次转储会被写成一个同名文件。JVM 会在这些默认值之后读取你自己的 `JAVA_TOOL_OPTIONS`、`JDK_JAVA_OPTIONS`（包括 `@argfile`）、命令行（`JAVA_OPTIONS`；未设置或为空时为 `-j`）和 `_JAVA_OPTIONS`，因此在其中任意一处为上述参数指定的值都会覆盖默认值。只有环境变量会传给服务启动的 JVM：要对所有 JVM 关闭堆转储，请设置 `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`；通过 `-j` 或 -`JAVA_OPTIONS` 关闭只对服务自身的 JVM 生效。无论哪种方式，每次启动仍会创建空的 `heapdump_*` 目录，除非创建失败而改为写入 `logs/`。由于设置了这些默认值，JVM 启动时会在 stderr 输出 `Picked up JAVA_TOOL_OPTIONS: ...`。 +`JAVA_OPTIONS` 关闭只对服务自身的 JVM 生效。无论哪种方式，每次启动仍会创建空的 `heapdump_*` 目录，除非创建失败而改为写入 `logs/`。如果日志路径中包含双引号或 `%`，启动脚本会给出警告，并只对服务自身的 JVM 保留 1.7.0 的行为：堆转储直接写入 +`logs/`，不使用每次启动的目录，也不设置崩溃日志的默认值。由于设置了这些默认值，JVM 启动时会在 stderr 输出 `Picked up JAVA_TOOL_OPTIONS: ...`。 > **版本范围**：以上行为适用于当前 master（[apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)）。1.7.0 只在未设置 `JAVA_OPTIONS` 时添加堆转储参数，堆转储直接写入 > `logs/java_pid.hprof`，JVM 崩溃日志写入安装目录。 diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index cc29bb896f..0577842b6a 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -548,8 +548,9 @@ of a running server; without it, the next dump is written as a file with that na `@argfiles`), the command line (`JAVA_OPTIONS`, or `-j` when `JAVA_OPTIONS` is unset or empty) and `_JAVA_OPTIONS` after these defaults, so a value for one of these flags in any of them overrides the default. Only the environment variables reach the JVMs the server starts: to turn dumps off for all of them, set `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`, while `-j` or `JAVA_OPTIONS` turns them off for the server JVM only. Either way each start still creates -its empty `heapdump_*` directory, unless creating it failed and dumps fell back to `logs/`. Because of the defaults, the JVM prints -`Picked up JAVA_TOOL_OPTIONS: ...` on stderr at startup. +its empty `heapdump_*` directory, unless creating it failed and dumps fell back to `logs/`. If the logs path contains a double quote or `%`, the launcher warns +and, for the server alone, keeps the 1.7.0 behaviour: heap dumps go to `logs/` itself, with no per-launch directory and no crash log default. Because of the +defaults, the JVM prints `Picked up JAVA_TOOL_OPTIONS: ...` on stderr at startup. > **Version scope**: this applies to current master ([apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)). In 1.7.0 the heap dump flags are > added only when `JAVA_OPTIONS` is unset, heap dumps go directly to `logs/java_pid.hprof`, and JVM crash logs go to the install directory. From 9977486e8c7829dcbca4419358610f6df29cf457 Mon Sep 17 00:00:00 2001 From: Ayan Alam Date: Sat, 10 Oct 2026 23:23:07 +0530 Subject: [PATCH 16/19] doc(server): describe crash log reuse and the quote/% opt-out - HotSpot names crash logs by PID too, so a JVM that reuses an earlier PID from the same start replaces that JVM's crash log. - For a logs path with a double quote or %, the JAVA_TOOL_OPTIONS opt-out still applies, and a path with both quote characters gets no heap dump default. English and Chinese quickstart, matching apache/hugegraph#3258. --- .../quickstart/hugegraph/hugegraph-server.md | 8 +++--- .../quickstart/hugegraph/hugegraph-server.md | 27 ++++++++++--------- 2 files changed, 18 insertions(+), 17 deletions(-) diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index 4a9dfb1f8d..7a661a64a3 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md @@ -538,13 +538,13 @@ Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)......OK `bin/hugegraph-server.sh` 会把 `-XX:+HeapDumpOnOutOfMemoryError`、`-XX:HeapDumpPath` 和 `-XX:ErrorFile` 放在 `JAVA_TOOL_OPTIONS` 的最前面。因此无论是否设置了 `JAVA_OPTIONS`，内存溢出时的堆转储（`heapdump_<主机名>_<启动时间>/java_pid.hprof`）和 JVM 崩溃日志（`hs_err_pid_<主机名>_<启动时间>.log`）都会写入 `logs/`，其中 `<启动时间>` 为本地时间，格式是 -`YYYYMMDD-HHMMSS`。每次启动都有自己的 `heapdump_*` 目录，因此服务及其启动的 JVM（例如 computer 任务）会分别写入各自的转储（HotSpot 按 JVM 的 PID 命名转储文件，因此同一次启动中复用了先前 PID 的 JVM -无法写入它的转储）。主机名可避免共用同一日志目录的多个服务选到相同的名字；如果同一主机在同一秒内已经用过该名字，会再加上计数（`<启动时间>-1`、`-2`……）。如果无法创建该目录（例如磁盘已满），服务仍会启动，堆转储改为尽力写入 `logs/` +`YYYYMMDD-HHMMSS`。每次启动都有自己的 `heapdump_*` 目录，因此服务及其启动的 JVM（例如 computer 任务）会分别写入各自的转储（HotSpot 按 JVM 的 PID 命名转储文件和崩溃日志，因此同一次启动中复用了先前 PID 的 JVM +无法写入它的转储，它的崩溃日志也会覆盖先前那个 JVM 的）。主机名可避免共用同一日志目录的多个服务选到相同的名字；如果同一主机在同一秒内已经用过该名字，会再加上计数（`<启动时间>-1`、`-2`……）。如果无法创建该目录（例如磁盘已满），服务仍会启动，堆转储改为尽力写入 `logs/` 本身；磁盘已满时可能也没有空间写入转储。堆转储可能和堆一样大。启动脚本从不删除转储或 `heapdump_*` 目录：每次启动都会留下一个目录，除非发生内存溢出否则为空；启动脚本保留它，是因为 computer 任务的 JVM 可能在服务退出后仍在使用它。在该次启动的 HugeGraph JVM 都已退出后，可以移走或删除旧目录，但不要动正在运行的服务最新的那个目录；没有它，下一次转储会被写成一个同名文件。JVM 会在这些默认值之后读取你自己的 `JAVA_TOOL_OPTIONS`、`JDK_JAVA_OPTIONS`（包括 `@argfile`）、命令行（`JAVA_OPTIONS`；未设置或为空时为 `-j`）和 `_JAVA_OPTIONS`，因此在其中任意一处为上述参数指定的值都会覆盖默认值。只有环境变量会传给服务启动的 JVM：要对所有 JVM 关闭堆转储，请设置 `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`；通过 `-j` 或 -`JAVA_OPTIONS` 关闭只对服务自身的 JVM 生效。无论哪种方式，每次启动仍会创建空的 `heapdump_*` 目录，除非创建失败而改为写入 `logs/`。如果日志路径中包含双引号或 `%`，启动脚本会给出警告，并只对服务自身的 JVM 保留 1.7.0 的行为：堆转储直接写入 -`logs/`，不使用每次启动的目录，也不设置崩溃日志的默认值。由于设置了这些默认值，JVM 启动时会在 stderr 输出 `Picked up JAVA_TOOL_OPTIONS: ...`。 +`JAVA_OPTIONS` 关闭只对服务自身的 JVM 生效。无论哪种方式，每次启动仍会创建空的 `heapdump_*` 目录，除非创建失败而改为写入 `logs/`。如果日志路径中包含双引号或 `%`，启动脚本会给出警告，堆转储直接写入 `logs/`，不使用每次启动的目录，也不设置崩溃日志的默认值；通过 +`JAVA_TOOL_OPTIONS` 关闭堆转储的方式仍然有效。同时包含两种引号的路径则完全不设置堆转储默认值。由于设置了这些默认值，JVM 启动时会在 stderr 输出 `Picked up JAVA_TOOL_OPTIONS: ...`。 > **版本范围**：以上行为适用于当前 master（[apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)）。1.7.0 只在未设置 `JAVA_OPTIONS` 时添加堆转储参数，堆转储直接写入 > `logs/java_pid.hprof`，JVM 崩溃日志写入安装目录。 diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index 0577842b6a..5fe46d85fd 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -538,19 +538,20 @@ This indicates the successful creation of the sample graph. `bin/hugegraph-server.sh` puts `-XX:+HeapDumpOnOutOfMemoryError`, `-XX:HeapDumpPath` and `-XX:ErrorFile` first in `JAVA_TOOL_OPTIONS`, so whether or not `JAVA_OPTIONS` is set, an out-of-memory heap dump (`heapdump__/java_pid.hprof`) and a JVM crash log (`hs_err_pid__.log`) land in `logs/`, where `` is the local time as `YYYYMMDD-HHMMSS`. Each start gets its own `heapdump_*` -directory, so the server and the JVMs it starts, such as computer jobs, write separate dumps (HotSpot names each dump after the JVM's PID, so a JVM that reuses -an earlier PID from the same start cannot write its dump). The host name keeps servers that share one log directory from picking the same name, and a counter -(`-1`, `-2`, ...) is added when the same host already used that second. If the directory cannot be created, for example on a full disk, the server -still starts and dumps go to `logs/` itself, as a best effort: a full disk may have no room for the dump either. A heap dump can be as large as the heap. The -launcher never deletes dumps or `heapdump_*` directories: each start leaves one, empty unless something ran out of memory, and the launcher keeps it because a -computer-job JVM can go on using it after the server exits. Move or delete old ones once no HugeGraph JVM from that launch is running, but never the newest one -of a running server; without it, the next dump is written as a file with that name. The JVM reads your own `JAVA_TOOL_OPTIONS`, `JDK_JAVA_OPTIONS` (including -`@argfiles`), the command line (`JAVA_OPTIONS`, or `-j` when `JAVA_OPTIONS` is unset or empty) and `_JAVA_OPTIONS` after these defaults, so a value for one of -these flags in any of them overrides the default. Only the environment variables reach the JVMs the server starts: to turn dumps off for all of them, set -`JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`, while `-j` or `JAVA_OPTIONS` turns them off for the server JVM only. Either way each start still creates -its empty `heapdump_*` directory, unless creating it failed and dumps fell back to `logs/`. If the logs path contains a double quote or `%`, the launcher warns -and, for the server alone, keeps the 1.7.0 behaviour: heap dumps go to `logs/` itself, with no per-launch directory and no crash log default. Because of the -defaults, the JVM prints `Picked up JAVA_TOOL_OPTIONS: ...` on stderr at startup. +directory, so the server and the JVMs it starts, such as computer jobs, write separate dumps (HotSpot names each dump and crash log after the JVM's PID, so a +JVM that reuses an earlier PID from the same start cannot write its dump, and its crash log replaces the earlier one's). The host name keeps servers that share +one log directory from picking the same name, and a counter (`-1`, `-2`, ...) is added when the same host already used that second. If the +directory cannot be created, for example on a full disk, the server still starts and dumps go to `logs/` itself, as a best effort: a full disk may have no room +for the dump either. A heap dump can be as large as the heap. The launcher never deletes dumps or `heapdump_*` directories: each start leaves one, empty unless +something ran out of memory, and the launcher keeps it because a computer-job JVM can go on using it after the server exits. Move or delete old ones once no +HugeGraph JVM from that launch is running, but never the newest one of a running server; without it, the next dump is written as a file with that name. The JVM +reads your own `JAVA_TOOL_OPTIONS`, `JDK_JAVA_OPTIONS` (including `@argfiles`), the command line (`JAVA_OPTIONS`, or `-j` when `JAVA_OPTIONS` is unset or empty) +and `_JAVA_OPTIONS` after these defaults, so a value for one of these flags in any of them overrides the default. Only the environment variables reach the JVMs +the server starts: to turn dumps off for all of them, set `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`, while `-j` or `JAVA_OPTIONS` turns them off for +the server JVM only. Either way each start still creates its empty `heapdump_*` directory, unless creating it failed and dumps fell back to `logs/`. If the logs +path contains a double quote or `%`, the launcher warns and heap dumps go to `logs/` itself, with no per-launch directory and no crash log default; the +`JAVA_TOOL_OPTIONS` opt-out still applies. A path with both quote characters gets no heap dump default at all. Because of the defaults, the JVM prints +`Picked up JAVA_TOOL_OPTIONS: ...` on stderr at startup. > **Version scope**: this applies to current master ([apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)). In 1.7.0 the heap dump flags are > added only when `JAVA_OPTIONS` is unset, heap dumps go directly to `logs/java_pid.hprof`, and JVM crash logs go to the install directory. From e930212c1d63bc6e69b65ebc30aec893228f163c Mon Sep 17 00:00:00 2001 From: Ayan Alam Date: Sun, 11 Oct 2026 18:28:01 +0530 Subject: [PATCH 17/19] docs: qualify the crash-file notes for edge cases - a later `down -v` does not remove a volume orphaned by a plain `down`; point to `docker volume prune` - give the liveness probe enough time to outlast a heap dump - dumps go to logs/ itself when the per-start directory cannot be created, and a reused PID within one start shares names - only starts that reach Java create the heapdump directory - the quickstart's logs/ claim has the exceptions listed below it --- .../docs/guides/hugegraph-docker-cluster.md | 14 +++++---- .../quickstart/hugegraph/hugegraph-server.md | 10 +++---- .../docs/guides/hugegraph-docker-cluster.md | 30 ++++++++++--------- .../quickstart/hugegraph/hugegraph-server.md | 24 +++++++-------- 4 files changed, 41 insertions(+), 37 deletions(-) diff --git a/content/cn/docs/guides/hugegraph-docker-cluster.md b/content/cn/docs/guides/hugegraph-docker-cluster.md index 577b29a8f0..7eb843155a 100644 --- a/content/cn/docs/guides/hugegraph-docker-cluster.md +++ b/content/cn/docs/guides/hugegraph-docker-cluster.md @@ -296,12 +296,14 @@ curl -o /dev/null -w '%{http_code}\n' -u "admin:${HUGEGRAPH_ADMIN_PASSWORD}" \ **查看运行时日志**：使用 `docker logs `（如 `docker logs hg-pd0`）可直接查看日志，无需进入容器。基于当前 master 构建的 PD、Store 以及两个 Server 镜像（`hugegraph/hugegraph` 和 HStore 的 `hugegraph/server`）都设置了 `STDOUT_MODE=true`，服务日志会输出到容器 stdout。对 Server 而言，Hadoop、ZooKeeper、SOFA、Netty 和 Commons 的 WARN 及以上日志也会输出到 stdout；Hadoop、Netty 和 Commons 的 INFO 日志以及审计日志、慢查询日志仍只写入文件，ZooKeeper 和 SOFA 不输出 WARN 以下的日志。`/hugegraph-server/logs` 中包含 `hugegraph-server.log`、JVM -崩溃日志（`hs_err_pid*.log`）和内存溢出时的堆转储（`heapdump_*/java_pid*.hprof`，每次启动一个目录，Server 及其启动的 JVM 分别写入各自的文件）。两个镜像都声明了 `VOLUME /hugegraph-server`，因此 `docker restart` 和 -Compose 重新创建容器都会保留这些文件；`docker compose down` 会留下这个匿名卷，但下一次 `up` 不会再挂载它，直到 `down -v` 将其删除，所以请使用具名卷或绑定挂载来保留这些文件。Kubernetes 每次重启都会新建容器，因此需要在 -`/hugegraph-server/logs` 挂载 `emptyDir` 或 PersistentVolumeClaim。请为每个 Pod 使用单独的卷，或在共享 PVC 上为每个 Pod 使用单独的目录（`subPathExpr: $(POD_NAME)`，并通过 Downward API 从 -`metadata.name` 传入 `POD_NAME`；Helm Chart 两者都没有设置）：崩溃文件的名字各不相同，但日志文件本身的名字是固定的。Helm Chart 目前还不会挂载日志卷。堆转储可能和 JVM 堆一样大，而且每次启动都会使用新目录，因此反复内存溢出的 Server -会把卷写满；请按需要保留的转储数量规划卷大小，并确保不超过 `ephemeral-storage` 限制或 `emptyDir` 的 `sizeLimit`（被驱逐时 `emptyDir` 会连同转储一起删除），也不要使用 `medium: Memory`。启动脚本从不删除转储或 `heapdump_*` 目录，因为 -computer 任务的 JVM 可能在 Server 退出后仍在使用它；每次启动都会留下一个目录，除非发生内存溢出否则为空。在该次启动的 HugeGraph JVM 都已退出后可以删除旧目录，但不要动正在运行的 Server 最新的那个目录。要对所有 JVM 关闭堆转储，请在容器的环境变量中设置 +崩溃日志（`hs_err_pid*.log`）和内存溢出时的堆转储（`heapdump_*/java_pid*.hprof`，每次启动一个目录，Server 及其启动的 JVM 分别写入各自的文件，除非某个 JVM 复用了同一次启动中先前的 PID；如果无法创建该目录，转储会直接写入 +`/hugegraph-server/logs`）。两个镜像都声明了 `VOLUME /hugegraph-server`，因此 `docker restart` 和 Compose 重新创建容器都会保留这些文件；`docker compose down` 会留下这个匿名卷，下一次 `up` 不会再挂载它，之后执行 +`down -v` 也不会删除它（可以用 `docker volume prune` 删除），所以请使用具名卷或绑定挂载来保留这些文件。Kubernetes 每次重启都会新建容器，因此需要在 `/hugegraph-server/logs` 挂载 `emptyDir` 或 +PersistentVolumeClaim。请为每个 Pod 使用单独的卷，或在共享 PVC 上为每个 Pod 使用单独的目录（`subPathExpr: $(POD_NAME)`，并通过 Downward API 从 `metadata.name` 传入 `POD_NAME`；Helm Chart +两者都没有设置）：崩溃文件的名字各不相同，但日志文件本身的名字是固定的。Helm Chart 目前还不会挂载日志卷。堆转储可能和 JVM 堆一样大，而且每次启动都会使用新目录，因此反复内存溢出的 Server 会把卷写满；请按需要保留的转储数量规划卷大小，并确保不超过 `ephemeral-storage` 限制或 +`emptyDir` 的 `sizeLimit`（被驱逐时 `emptyDir` 会连同转储一起删除），也不要使用 `medium: Memory`。请给存活探针留出足够的时间（`failureThreshold` × +`periodSeconds`），让它比写入一次堆转储的时间更长，否则在写转储的过程中重启会留下不完整的文件。启动脚本从不删除转储或 `heapdump_*` 目录，因为 computer 任务的 JVM 可能在 Server 退出后仍在使用它；每次启动到 Java +阶段都会留下一个目录，除非发生内存溢出否则为空。在该次启动的 HugeGraph JVM 都已退出后可以删除旧目录，但不要动正在运行的 Server 最新的那个目录。要对所有 JVM 关闭堆转储，请在容器的环境变量中设置 `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`（可以使用 `docker run -e`，或在 Compose 中 Server 服务的 `environment:` 里添加，自带的 Compose 文件没有设置它，或在 Kubernetes 中使用 `env`；只在宿主机 shell 中导出不会生效），这样会保留镜像默认的 `JAVA_OPTS`；把该参数加到 `JAVA_OPTS` 中只对 Server 自身的 JVM 生效，而且会替换镜像默认值（`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`），需要把这些参数一并写上。 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index 7a661a64a3..a8575f63d1 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md @@ -537,14 +537,14 @@ Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)......OK `bin/stop-hugegraph.sh` 支持 `-m true|false`（默认 `true`），用于控制停止服务时是否同时移除 crontab 监控任务。 `bin/hugegraph-server.sh` 会把 `-XX:+HeapDumpOnOutOfMemoryError`、`-XX:HeapDumpPath` 和 `-XX:ErrorFile` 放在 `JAVA_TOOL_OPTIONS` 的最前面。因此无论是否设置了 -`JAVA_OPTIONS`，内存溢出时的堆转储（`heapdump_<主机名>_<启动时间>/java_pid.hprof`）和 JVM 崩溃日志（`hs_err_pid_<主机名>_<启动时间>.log`）都会写入 `logs/`，其中 `<启动时间>` 为本地时间，格式是 -`YYYYMMDD-HHMMSS`。每次启动都有自己的 `heapdump_*` 目录，因此服务及其启动的 JVM（例如 computer 任务）会分别写入各自的转储（HotSpot 按 JVM 的 PID 命名转储文件和崩溃日志，因此同一次启动中复用了先前 PID 的 JVM +`JAVA_OPTIONS`（下文所述的例外情况除外），内存溢出时的堆转储（`heapdump_<主机名>_<启动时间>/java_pid.hprof`）和 JVM 崩溃日志（`hs_err_pid_<主机名>_<启动时间>.log`）都会写入 `logs/`，其中 `<启动时间>` +为本地时间，格式是 `YYYYMMDD-HHMMSS`。每次启动都有自己的 `heapdump_*` 目录，因此服务及其启动的 JVM（例如 computer 任务）会分别写入各自的转储（HotSpot 按 JVM 的 PID 命名转储文件和崩溃日志，因此同一次启动中复用了先前 PID 的 JVM 无法写入它的转储，它的崩溃日志也会覆盖先前那个 JVM 的）。主机名可避免共用同一日志目录的多个服务选到相同的名字；如果同一主机在同一秒内已经用过该名字，会再加上计数（`<启动时间>-1`、`-2`……）。如果无法创建该目录（例如磁盘已满），服务仍会启动，堆转储改为尽力写入 `logs/` -本身；磁盘已满时可能也没有空间写入转储。堆转储可能和堆一样大。启动脚本从不删除转储或 `heapdump_*` 目录：每次启动都会留下一个目录，除非发生内存溢出否则为空；启动脚本保留它，是因为 computer 任务的 JVM 可能在服务退出后仍在使用它。在该次启动的 HugeGraph JVM +本身；磁盘已满时可能也没有空间写入转储。堆转储可能和堆一样大。启动脚本从不删除转储或 `heapdump_*` 目录：每次启动到 Java 阶段都会留下一个目录，除非发生内存溢出否则为空；启动脚本保留它，是因为 computer 任务的 JVM 可能在服务退出后仍在使用它。在该次启动的 HugeGraph JVM 都已退出后，可以移走或删除旧目录，但不要动正在运行的服务最新的那个目录；没有它，下一次转储会被写成一个同名文件。JVM 会在这些默认值之后读取你自己的 `JAVA_TOOL_OPTIONS`、`JDK_JAVA_OPTIONS`（包括 `@argfile`）、命令行（`JAVA_OPTIONS`；未设置或为空时为 `-j`）和 `_JAVA_OPTIONS`，因此在其中任意一处为上述参数指定的值都会覆盖默认值。只有环境变量会传给服务启动的 JVM：要对所有 JVM 关闭堆转储，请设置 `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`；通过 `-j` 或 -`JAVA_OPTIONS` 关闭只对服务自身的 JVM 生效。无论哪种方式，每次启动仍会创建空的 `heapdump_*` 目录，除非创建失败而改为写入 `logs/`。如果日志路径中包含双引号或 `%`，启动脚本会给出警告，堆转储直接写入 `logs/`，不使用每次启动的目录，也不设置崩溃日志的默认值；通过 -`JAVA_TOOL_OPTIONS` 关闭堆转储的方式仍然有效。同时包含两种引号的路径则完全不设置堆转储默认值。由于设置了这些默认值，JVM 启动时会在 stderr 输出 `Picked up JAVA_TOOL_OPTIONS: ...`。 +`JAVA_OPTIONS` 关闭只对服务自身的 JVM 生效。无论哪种方式，每次启动到 Java 阶段仍会创建空的 `heapdump_*` 目录，除非创建失败而改为写入 `logs/`。如果日志路径中包含双引号或 `%`，启动脚本会给出警告，堆转储直接写入 +`logs/`，不使用每次启动的目录，也不设置崩溃日志的默认值；通过 `JAVA_TOOL_OPTIONS` 关闭堆转储的方式仍然有效。同时包含两种引号的路径则完全不设置堆转储默认值。由于设置了这些默认值，JVM 启动时会在 stderr 输出 `Picked up JAVA_TOOL_OPTIONS: ...`。 > **版本范围**：以上行为适用于当前 master（[apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)）。1.7.0 只在未设置 `JAVA_OPTIONS` 时添加堆转储参数，堆转储直接写入 > `logs/java_pid.hprof`，JVM 崩溃日志写入安装目录。 diff --git a/content/en/docs/guides/hugegraph-docker-cluster.md b/content/en/docs/guides/hugegraph-docker-cluster.md index 32d29d1c11..3237e3e2ca 100644 --- a/content/en/docs/guides/hugegraph-docker-cluster.md +++ b/content/en/docs/guides/hugegraph-docker-cluster.md @@ -297,20 +297,22 @@ Standalone publishes only `8080` and `8088`; minimal HStore publishes `8620` (PD master, the PD, Store and both Server images (`hugegraph/hugegraph` and the HStore `hugegraph/server`) set `STDOUT_MODE=true` and send service logs to stdout. For the Server, WARN and above from Hadoop, ZooKeeper, SOFA, Netty and Commons also reaches stdout; INFO from Hadoop, Netty and Commons and the audit and slow-query logs stay in files, and ZooKeeper and SOFA log nothing below WARN. `/hugegraph-server/logs` holds `hugegraph-server.log`, JVM crash logs -(`hs_err_pid*.log`) and out-of-memory heap dumps (`heapdump_*/java_pid*.hprof`, one directory per start, so the Server and the JVMs it starts get separate -files). Both images declare `VOLUME /hugegraph-server`, so `docker restart` and a Compose recreate keep them; `docker compose down` leaves that anonymous volume -behind unattached until `down -v` deletes it, so use a named volume or bind mount to keep them reachable. Kubernetes starts a new container on every restart, so -mount an `emptyDir` or a PersistentVolumeClaim at `/hugegraph-server/logs`. Give each pod its own volume, or a per-pod directory on a shared PVC -(`subPathExpr: $(POD_NAME)`, with `POD_NAME` passed in from `metadata.name` through the Downward API; the Helm chart sets neither): crash files get distinct -names, but the log files themselves have fixed names. The Helm chart does not mount a logs volume yet. A heap dump can be as large as the JVM heap, and every -start uses a new directory, so a Server that keeps running out of memory fills the volume; size it for the dumps you want to keep, keep it within any -`ephemeral-storage` limit or `emptyDir` `sizeLimit` (eviction deletes the `emptyDir` with the dump), and do not use `medium: Memory`. The launcher never deletes -dumps or `heapdump_*` directories, because a computer-job JVM can go on using one after its Server exits; each start leaves one, empty unless something ran out -of memory. Delete old ones once no HugeGraph JVM from that launch is running, never the newest one of a running Server. To turn dumps off for every JVM, set -`JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError` in the container's environment (`docker run -e`, an `environment:` entry on the Server service in Compose, -which the shipped Compose files do not set, or `env` in Kubernetes; exporting it in the host shell has no effect), which keeps the image's default `JAVA_OPTS`; -putting the flag in `JAVA_OPTS` affects the Server JVM only and replaces that default (`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`), so repeat those -flags. +(`hs_err_pid*.log`) and out-of-memory heap dumps (`heapdump_*/java_pid*.hprof`, one directory per start, so the Server and the JVMs it starts get separate files +unless a JVM reuses an earlier PID from that start; if the directory cannot be created, dumps go to `/hugegraph-server/logs` itself). Both images declare +`VOLUME /hugegraph-server`, so `docker restart` and a Compose recreate keep them; `docker compose down` leaves that anonymous volume behind unattached, and a +later `down -v` does not remove it (delete it with `docker volume prune`), so use a named volume or bind mount to keep them reachable. Kubernetes starts a new +container on every restart, so mount an `emptyDir` or a PersistentVolumeClaim at `/hugegraph-server/logs`. Give each pod its own volume, or a per-pod directory +on a shared PVC (`subPathExpr: $(POD_NAME)`, with `POD_NAME` passed in from `metadata.name` through the Downward API; the Helm chart sets neither): crash files +get distinct names, but the log files themselves have fixed names. The Helm chart does not mount a logs volume yet. A heap dump can be as large as the JVM heap, +and every start uses a new directory, so a Server that keeps running out of memory fills the volume; size it for the dumps you want to keep, keep it within any +`ephemeral-storage` limit or `emptyDir` `sizeLimit` (eviction deletes the `emptyDir` with the dump), and do not use `medium: Memory`. Give the liveness probe +enough slack (`failureThreshold` × `periodSeconds`) to outlast writing a heap dump, or a restart in the middle of a dump leaves a truncated file. The launcher +never deletes dumps or `heapdump_*` directories, because a computer-job JVM can go on using one after its Server exits; each start that reaches Java leaves one, +empty unless something ran out of memory. Delete old ones once no HugeGraph JVM from that launch is running, never the newest one of a running Server. To turn +dumps off for every JVM, set `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError` in the container's environment (`docker run -e`, an `environment:` entry on the +Server service in Compose, which the shipped Compose files do not set, or `env` in Kubernetes; exporting it in the host shell has no effect), which keeps the +image's default `JAVA_OPTS`; putting the flag in `JAVA_OPTS` affects the Server JVM only and replaces that default +(`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`), so repeat those flags. > **Version scope**: the paragraph above describes current master images ([apache/hugegraph#2980](https://github.com/apache/hugegraph/pull/2980) for PD, Store > and the standalone Server, [apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258) for the HStore Server). No 1.7.0 or older image sets diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index 5fe46d85fd..06b9ce471b 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -535,23 +535,23 @@ This indicates the successful creation of the sample graph. `bin/stop-hugegraph.sh` accepts `-m true|false` (default `true`), which controls whether the cron monitor task is removed along with the service. -`bin/hugegraph-server.sh` puts `-XX:+HeapDumpOnOutOfMemoryError`, `-XX:HeapDumpPath` and `-XX:ErrorFile` first in `JAVA_TOOL_OPTIONS`, so whether or not -`JAVA_OPTIONS` is set, an out-of-memory heap dump (`heapdump__/java_pid.hprof`) and a JVM crash log +`bin/hugegraph-server.sh` puts `-XX:+HeapDumpOnOutOfMemoryError`, `-XX:HeapDumpPath` and `-XX:ErrorFile` first in `JAVA_TOOL_OPTIONS`, so, whether or not +`JAVA_OPTIONS` is set and with the exceptions below, an out-of-memory heap dump (`heapdump__/java_pid.hprof`) and a JVM crash log (`hs_err_pid__.log`) land in `logs/`, where `` is the local time as `YYYYMMDD-HHMMSS`. Each start gets its own `heapdump_*` directory, so the server and the JVMs it starts, such as computer jobs, write separate dumps (HotSpot names each dump and crash log after the JVM's PID, so a JVM that reuses an earlier PID from the same start cannot write its dump, and its crash log replaces the earlier one's). The host name keeps servers that share one log directory from picking the same name, and a counter (`-1`, `-2`, ...) is added when the same host already used that second. If the directory cannot be created, for example on a full disk, the server still starts and dumps go to `logs/` itself, as a best effort: a full disk may have no room -for the dump either. A heap dump can be as large as the heap. The launcher never deletes dumps or `heapdump_*` directories: each start leaves one, empty unless -something ran out of memory, and the launcher keeps it because a computer-job JVM can go on using it after the server exits. Move or delete old ones once no -HugeGraph JVM from that launch is running, but never the newest one of a running server; without it, the next dump is written as a file with that name. The JVM -reads your own `JAVA_TOOL_OPTIONS`, `JDK_JAVA_OPTIONS` (including `@argfiles`), the command line (`JAVA_OPTIONS`, or `-j` when `JAVA_OPTIONS` is unset or empty) -and `_JAVA_OPTIONS` after these defaults, so a value for one of these flags in any of them overrides the default. Only the environment variables reach the JVMs -the server starts: to turn dumps off for all of them, set `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`, while `-j` or `JAVA_OPTIONS` turns them off for -the server JVM only. Either way each start still creates its empty `heapdump_*` directory, unless creating it failed and dumps fell back to `logs/`. If the logs -path contains a double quote or `%`, the launcher warns and heap dumps go to `logs/` itself, with no per-launch directory and no crash log default; the -`JAVA_TOOL_OPTIONS` opt-out still applies. A path with both quote characters gets no heap dump default at all. Because of the defaults, the JVM prints -`Picked up JAVA_TOOL_OPTIONS: ...` on stderr at startup. +for the dump either. A heap dump can be as large as the heap. The launcher never deletes dumps or `heapdump_*` directories: each start that reaches Java leaves +one, empty unless something ran out of memory, and the launcher keeps it because a computer-job JVM can go on using it after the server exits. Move or delete +old ones once no HugeGraph JVM from that launch is running, but never the newest one of a running server; without it, the next dump is written as a file with +that name. The JVM reads your own `JAVA_TOOL_OPTIONS`, `JDK_JAVA_OPTIONS` (including `@argfiles`), the command line (`JAVA_OPTIONS`, or `-j` when `JAVA_OPTIONS` +is unset or empty) and `_JAVA_OPTIONS` after these defaults, so a value for one of these flags in any of them overrides the default. Only the environment +variables reach the JVMs the server starts: to turn dumps off for all of them, set `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`, while `-j` or +`JAVA_OPTIONS` turns them off for the server JVM only. Either way each start that reaches Java still creates its empty `heapdump_*` directory, unless creating +it failed and dumps fell back to `logs/`. If the logs path contains a double quote or `%`, the launcher warns and heap dumps go to `logs/` itself, with no +per-launch directory and no crash log default; the `JAVA_TOOL_OPTIONS` opt-out still applies. A path with both quote characters gets no heap dump default at +all. Because of the defaults, the JVM prints `Picked up JAVA_TOOL_OPTIONS: ...` on stderr at startup. > **Version scope**: this applies to current master ([apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)). In 1.7.0 the heap dump flags are > added only when `JAVA_OPTIONS` is unset, heap dumps go directly to `logs/java_pid.hprof`, and JVM crash logs go to the install directory. From 058fb9eae014c647c5604029b3f96097f7e73728 Mon Sep 17 00:00:00 2001 From: Ayan Alam Date: Mon, 12 Oct 2026 11:42:52 +0530 Subject: [PATCH 18/19] docs: remove an orphaned volume by name, not with prune `docker volume prune` deletes every unused anonymous volume on the Docker host. Point to `docker inspect` and `docker volume rm ` and say what prune would also remove, in both languages. --- content/cn/docs/guides/hugegraph-docker-cluster.md | 12 ++++++------ content/en/docs/guides/hugegraph-docker-cluster.md | 3 ++- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/content/cn/docs/guides/hugegraph-docker-cluster.md b/content/cn/docs/guides/hugegraph-docker-cluster.md index 7eb843155a..7f962ffbfd 100644 --- a/content/cn/docs/guides/hugegraph-docker-cluster.md +++ b/content/cn/docs/guides/hugegraph-docker-cluster.md @@ -298,12 +298,12 @@ curl -o /dev/null -w '%{http_code}\n' -u "admin:${HUGEGRAPH_ADMIN_PASSWORD}" \ INFO 日志以及审计日志、慢查询日志仍只写入文件，ZooKeeper 和 SOFA 不输出 WARN 以下的日志。`/hugegraph-server/logs` 中包含 `hugegraph-server.log`、JVM 崩溃日志（`hs_err_pid*.log`）和内存溢出时的堆转储（`heapdump_*/java_pid*.hprof`，每次启动一个目录，Server 及其启动的 JVM 分别写入各自的文件，除非某个 JVM 复用了同一次启动中先前的 PID；如果无法创建该目录，转储会直接写入 `/hugegraph-server/logs`）。两个镜像都声明了 `VOLUME /hugegraph-server`，因此 `docker restart` 和 Compose 重新创建容器都会保留这些文件；`docker compose down` 会留下这个匿名卷，下一次 `up` 不会再挂载它，之后执行 -`down -v` 也不会删除它（可以用 `docker volume prune` 删除），所以请使用具名卷或绑定挂载来保留这些文件。Kubernetes 每次重启都会新建容器，因此需要在 `/hugegraph-server/logs` 挂载 `emptyDir` 或 -PersistentVolumeClaim。请为每个 Pod 使用单独的卷，或在共享 PVC 上为每个 Pod 使用单独的目录（`subPathExpr: $(POD_NAME)`，并通过 Downward API 从 `metadata.name` 传入 `POD_NAME`；Helm Chart -两者都没有设置）：崩溃文件的名字各不相同，但日志文件本身的名字是固定的。Helm Chart 目前还不会挂载日志卷。堆转储可能和 JVM 堆一样大，而且每次启动都会使用新目录，因此反复内存溢出的 Server 会把卷写满；请按需要保留的转储数量规划卷大小，并确保不超过 `ephemeral-storage` 限制或 -`emptyDir` 的 `sizeLimit`（被驱逐时 `emptyDir` 会连同转储一起删除），也不要使用 `medium: Memory`。请给存活探针留出足够的时间（`failureThreshold` × -`periodSeconds`），让它比写入一次堆转储的时间更长，否则在写转储的过程中重启会留下不完整的文件。启动脚本从不删除转储或 `heapdump_*` 目录，因为 computer 任务的 JVM 可能在 Server 退出后仍在使用它；每次启动到 Java -阶段都会留下一个目录，除非发生内存溢出否则为空。在该次启动的 HugeGraph JVM 都已退出后可以删除旧目录，但不要动正在运行的 Server 最新的那个目录。要对所有 JVM 关闭堆转储，请在容器的环境变量中设置 +`down -v` 也不会删除它（请在 `down` 之前用 `docker inspect` 记下卷名，再用 `docker volume rm ` 删除；`docker volume prune` 会同时删除 Docker +主机上所有其他未使用的匿名卷），所以请使用具名卷或绑定挂载来保留这些文件。Kubernetes 每次重启都会新建容器，因此需要在 `/hugegraph-server/logs` 挂载 `emptyDir` 或 PersistentVolumeClaim。请为每个 Pod 使用单独的卷，或在共享 PVC 上为每个 +Pod 使用单独的目录（`subPathExpr: $(POD_NAME)`，并通过 Downward API 从 `metadata.name` 传入 `POD_NAME`；Helm Chart 两者都没有设置）：崩溃文件的名字各不相同，但日志文件本身的名字是固定的。Helm Chart +目前还不会挂载日志卷。堆转储可能和 JVM 堆一样大，而且每次启动都会使用新目录，因此反复内存溢出的 Server 会把卷写满；请按需要保留的转储数量规划卷大小，并确保不超过 `ephemeral-storage` 限制或 `emptyDir` 的 `sizeLimit`（被驱逐时 `emptyDir` +会连同转储一起删除），也不要使用 `medium: Memory`。请给存活探针留出足够的时间（`failureThreshold` × `periodSeconds`），让它比写入一次堆转储的时间更长，否则在写转储的过程中重启会留下不完整的文件。启动脚本从不删除转储或 `heapdump_*` 目录，因为 +computer 任务的 JVM 可能在 Server 退出后仍在使用它；每次启动到 Java 阶段都会留下一个目录，除非发生内存溢出否则为空。在该次启动的 HugeGraph JVM 都已退出后可以删除旧目录，但不要动正在运行的 Server 最新的那个目录。要对所有 JVM 关闭堆转储，请在容器的环境变量中设置 `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`（可以使用 `docker run -e`，或在 Compose 中 Server 服务的 `environment:` 里添加，自带的 Compose 文件没有设置它，或在 Kubernetes 中使用 `env`；只在宿主机 shell 中导出不会生效），这样会保留镜像默认的 `JAVA_OPTS`；把该参数加到 `JAVA_OPTS` 中只对 Server 自身的 JVM 生效，而且会替换镜像默认值（`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`），需要把这些参数一并写上。 diff --git a/content/en/docs/guides/hugegraph-docker-cluster.md b/content/en/docs/guides/hugegraph-docker-cluster.md index 3237e3e2ca..e1eba7f183 100644 --- a/content/en/docs/guides/hugegraph-docker-cluster.md +++ b/content/en/docs/guides/hugegraph-docker-cluster.md @@ -300,7 +300,8 @@ slow-query logs stay in files, and ZooKeeper and SOFA log nothing below WARN. `/ (`hs_err_pid*.log`) and out-of-memory heap dumps (`heapdump_*/java_pid*.hprof`, one directory per start, so the Server and the JVMs it starts get separate files unless a JVM reuses an earlier PID from that start; if the directory cannot be created, dumps go to `/hugegraph-server/logs` itself). Both images declare `VOLUME /hugegraph-server`, so `docker restart` and a Compose recreate keep them; `docker compose down` leaves that anonymous volume behind unattached, and a -later `down -v` does not remove it (delete it with `docker volume prune`), so use a named volume or bind mount to keep them reachable. Kubernetes starts a new +later `down -v` does not remove it (note the volume name from `docker inspect` before `down` and delete it with `docker volume rm `; `docker volume prune` +would also delete every other unused anonymous volume on the Docker host), so use a named volume or bind mount to keep them reachable. Kubernetes starts a new container on every restart, so mount an `emptyDir` or a PersistentVolumeClaim at `/hugegraph-server/logs`. Give each pod its own volume, or a per-pod directory on a shared PVC (`subPathExpr: $(POD_NAME)`, with `POD_NAME` passed in from `metadata.name` through the Downward API; the Helm chart sets neither): crash files get distinct names, but the log files themselves have fixed names. The Helm chart does not mount a logs volume yet. A heap dump can be as large as the JVM heap, From f6face3f91de45929970d04a14e97cb481fc96f1 Mon Sep 17 00:00:00 2001 From: Ayan Alam Date: Tue, 13 Oct 2026 16:35:13 +0530 Subject: [PATCH 19/19] docs: tighten the liveness-probe and shared-PVC notes A failing liveness probe can restart the container about (failureThreshold - 1) x periodSeconds + timeoutSeconds after a dump starts, and the kubelet then waits at most terminationGracePeriodSeconds. Pods on different nodes can share a logs PVC only with storage that supports read-write mounts from several nodes. Both languages. --- .../docs/guides/hugegraph-docker-cluster.md | 15 ++++++------ .../docs/guides/hugegraph-docker-cluster.md | 23 +++++++++++-------- 2 files changed, 21 insertions(+), 17 deletions(-) diff --git a/content/cn/docs/guides/hugegraph-docker-cluster.md b/content/cn/docs/guides/hugegraph-docker-cluster.md index 7f962ffbfd..49722ff265 100644 --- a/content/cn/docs/guides/hugegraph-docker-cluster.md +++ b/content/cn/docs/guides/hugegraph-docker-cluster.md @@ -300,13 +300,14 @@ INFO 日志以及审计日志、慢查询日志仍只写入文件，ZooKeeper `/hugegraph-server/logs`）。两个镜像都声明了 `VOLUME /hugegraph-server`，因此 `docker restart` 和 Compose 重新创建容器都会保留这些文件；`docker compose down` 会留下这个匿名卷，下一次 `up` 不会再挂载它，之后执行 `down -v` 也不会删除它（请在 `down` 之前用 `docker inspect` 记下卷名，再用 `docker volume rm ` 删除；`docker volume prune` 会同时删除 Docker 主机上所有其他未使用的匿名卷），所以请使用具名卷或绑定挂载来保留这些文件。Kubernetes 每次重启都会新建容器，因此需要在 `/hugegraph-server/logs` 挂载 `emptyDir` 或 PersistentVolumeClaim。请为每个 Pod 使用单独的卷，或在共享 PVC 上为每个 -Pod 使用单独的目录（`subPathExpr: $(POD_NAME)`，并通过 Downward API 从 `metadata.name` 传入 `POD_NAME`；Helm Chart 两者都没有设置）：崩溃文件的名字各不相同，但日志文件本身的名字是固定的。Helm Chart -目前还不会挂载日志卷。堆转储可能和 JVM 堆一样大，而且每次启动都会使用新目录，因此反复内存溢出的 Server 会把卷写满；请按需要保留的转储数量规划卷大小，并确保不超过 `ephemeral-storage` 限制或 `emptyDir` 的 `sizeLimit`（被驱逐时 `emptyDir` -会连同转储一起删除），也不要使用 `medium: Memory`。请给存活探针留出足够的时间（`failureThreshold` × `periodSeconds`），让它比写入一次堆转储的时间更长，否则在写转储的过程中重启会留下不完整的文件。启动脚本从不删除转储或 `heapdump_*` 目录，因为 -computer 任务的 JVM 可能在 Server 退出后仍在使用它；每次启动到 Java 阶段都会留下一个目录，除非发生内存溢出否则为空。在该次启动的 HugeGraph JVM 都已退出后可以删除旧目录，但不要动正在运行的 Server 最新的那个目录。要对所有 JVM 关闭堆转储，请在容器的环境变量中设置 -`JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`（可以使用 `docker run -e`，或在 Compose 中 Server 服务的 `environment:` 里添加，自带的 Compose 文件没有设置它，或在 Kubernetes 中使用 -`env`；只在宿主机 shell 中导出不会生效），这样会保留镜像默认的 `JAVA_OPTS`；把该参数加到 `JAVA_OPTS` 中只对 Server 自身的 JVM -生效，而且会替换镜像默认值（`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`），需要把这些参数一并写上。 +Pod 使用单独的目录（`subPathExpr: $(POD_NAME)`，并通过 Downward API 从 `metadata.name` 传入 `POD_NAME`；Helm Chart 两者都没有设置）：崩溃文件的名字各不相同，但日志文件本身的名字是固定的。只有当存储支持多个节点同时读写挂载（通常是 +`ReadWriteMany`）时，不同节点上的 Pod 才能共享同一个 PVC；`ReadWriteOnce` 的 PVC 只能被一个节点读写挂载，否则请为每个 Pod 使用单独的 PVC。Helm Chart 目前还不会挂载日志卷。堆转储可能和 JVM 堆一样大，而且每次启动都会使用新目录，因此反复内存溢出的 +Server 会把卷写满；请按需要保留的转储数量规划卷大小，并确保不超过 `ephemeral-storage` 限制或 `emptyDir` 的 `sizeLimit`（被驱逐时 `emptyDir` 会连同转储一起删除），也不要使用 `medium: Memory`。存活探针失败后，容器最早可能在转储开始后约 +`(failureThreshold - 1) × periodSeconds + timeoutSeconds` 被重启，kubelet 最多再等待 `terminationGracePeriodSeconds` +就会终止它；请让这段时间长于写入一次堆转储所需的时间，否则在写转储的过程中重启会留下不完整的文件。启动脚本从不删除转储或 `heapdump_*` 目录，因为 computer 任务的 JVM 可能在 Server 退出后仍在使用它；每次启动到 Java 阶段都会留下一个目录，除非发生内存溢出否则为空。在该次启动的 +HugeGraph JVM 都已退出后可以删除旧目录，但不要动正在运行的 Server 最新的那个目录。要对所有 JVM 关闭堆转储，请在容器的环境变量中设置 `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError`（可以使用 `docker run -e`，或在 +Compose 中 Server 服务的 `environment:` 里添加，自带的 Compose 文件没有设置它，或在 Kubernetes 中使用 `env`；只在宿主机 shell 中导出不会生效），这样会保留镜像默认的 `JAVA_OPTS`；把该参数加到 `JAVA_OPTS` 中只对 Server +自身的 JVM 生效，而且会替换镜像默认值（`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`），需要把这些参数一并写上。 > **版本范围**：上文描述的是基于当前 master 构建的镜像（PD、Store 和单机 Server 见 [apache/hugegraph#2980](https://github.com/apache/hugegraph/pull/2980)，HStore Server 见 > [apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258)）。1.7.0 及更早的镜像都没有设置 `STDOUT_MODE`，包括上文使用的单机镜像 `hugegraph/hugegraph:1.7.0`：`docker logs` diff --git a/content/en/docs/guides/hugegraph-docker-cluster.md b/content/en/docs/guides/hugegraph-docker-cluster.md index e1eba7f183..0360a7c634 100644 --- a/content/en/docs/guides/hugegraph-docker-cluster.md +++ b/content/en/docs/guides/hugegraph-docker-cluster.md @@ -304,16 +304,19 @@ later `down -v` does not remove it (note the volume name from `docker inspect` b would also delete every other unused anonymous volume on the Docker host), so use a named volume or bind mount to keep them reachable. Kubernetes starts a new container on every restart, so mount an `emptyDir` or a PersistentVolumeClaim at `/hugegraph-server/logs`. Give each pod its own volume, or a per-pod directory on a shared PVC (`subPathExpr: $(POD_NAME)`, with `POD_NAME` passed in from `metadata.name` through the Downward API; the Helm chart sets neither): crash files -get distinct names, but the log files themselves have fixed names. The Helm chart does not mount a logs volume yet. A heap dump can be as large as the JVM heap, -and every start uses a new directory, so a Server that keeps running out of memory fills the volume; size it for the dumps you want to keep, keep it within any -`ephemeral-storage` limit or `emptyDir` `sizeLimit` (eviction deletes the `emptyDir` with the dump), and do not use `medium: Memory`. Give the liveness probe -enough slack (`failureThreshold` × `periodSeconds`) to outlast writing a heap dump, or a restart in the middle of a dump leaves a truncated file. The launcher -never deletes dumps or `heapdump_*` directories, because a computer-job JVM can go on using one after its Server exits; each start that reaches Java leaves one, -empty unless something ran out of memory. Delete old ones once no HugeGraph JVM from that launch is running, never the newest one of a running Server. To turn -dumps off for every JVM, set `JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError` in the container's environment (`docker run -e`, an `environment:` entry on the -Server service in Compose, which the shipped Compose files do not set, or `env` in Kubernetes; exporting it in the host shell has no effect), which keeps the -image's default `JAVA_OPTS`; putting the flag in `JAVA_OPTS` affects the Server JVM only and replaces that default -(`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`), so repeat those flags. +get distinct names, but the log files themselves have fixed names. Pods on different nodes can share one PVC only if its storage supports read-write mounts from +several nodes (typically `ReadWriteMany`); a `ReadWriteOnce` claim is writable from one node only, so otherwise give each pod its own PVC. The Helm chart does +not mount a logs volume yet. A heap dump can be as large as the JVM heap, and every start uses a new directory, so a Server that keeps running out of memory +fills the volume; size it for the dumps you want to keep, keep it within any `ephemeral-storage` limit or `emptyDir` `sizeLimit` (eviction deletes the +`emptyDir` with the dump), and do not use `medium: Memory`. A failing liveness probe can restart the container as soon as about +`(failureThreshold - 1) × periodSeconds + timeoutSeconds` after a dump starts, and the kubelet kills it at most `terminationGracePeriodSeconds` after that; make +that time longer than writing a heap dump takes, or a restart in the middle of a dump leaves a truncated file. The launcher never deletes dumps or `heapdump_*` +directories, because a computer-job JVM can go on using one after its Server exits; each start that reaches Java leaves one, empty unless something ran out of +memory. Delete old ones once no HugeGraph JVM from that launch is running, never the newest one of a running Server. To turn dumps off for every JVM, set +`JAVA_TOOL_OPTIONS=-XX:-HeapDumpOnOutOfMemoryError` in the container's environment (`docker run -e`, an `environment:` entry on the Server service in Compose, +which the shipped Compose files do not set, or `env` in Kubernetes; exporting it in the host shell has no effect), which keeps the image's default `JAVA_OPTS`; +putting the flag in `JAVA_OPTS` affects the Server JVM only and replaces that default (`-XX:+UseContainerSupport -XX:MaxRAMPercentage=50 ...`), so repeat those +flags. > **Version scope**: the paragraph above describes current master images ([apache/hugegraph#2980](https://github.com/apache/hugegraph/pull/2980) for PD, Store > and the standalone Server, [apache/hugegraph#3258](https://github.com/apache/hugegraph/pull/3258) for the HStore Server). No 1.7.0 or older image sets