add memory management docs (#1165)

Signed-off-by: John Alon G <[email protected]> Signed-off-by: Nicolas MASSART <[email protected]> Signed-off-by: Alexandra Tran <[email protected]> Co-authored-by: John Alon G <[email protected]> Co-authored-by: Nicolas MASSART <[email protected]> Co-authored-by: Alexandra Tran <[email protected]>
hyperledger · Sep 13, 2022 · b9d08d2 · b9d08d2
1 parent 1a1fa57
commit b9d08d2
Show file tree

Hide file tree

Showing 8 changed files with 101 additions and 9 deletions.
diff --git a/CI/linkchecker/link_check_conf.json b/CI/linkchecker/link_check_conf.json
@@ -22,6 +22,7 @@
             "pattern": "^http(s)?://consensys.net"
         }
     ],
+    "timeout": "20s",
     "aliveStatusCodes":[200, 206],
     "retryOn429":true
 }
diff --git a/docs/private-networks/how-to/index.md b/docs/private-networks/how-to/index.md
@@ -9,9 +9,8 @@ This section provides instructional content for private network features.
 The following features are shared with [public networks](../../public-networks/index.md) and the
 content can be found in the public networks section:
 
-- Configuration:
+- Configure and manage:
     - [Use a configuration file](../../public-networks/how-to/configuration-file.md)
-    - [Pass JVM options](../../public-networks/how-to/pass-jvm-options.md)
     - [Configure high availability](../../public-networks/how-to/configure-ha/index.md)
     - [Configure mining](../../public-networks/how-to/use-pow/mining.md)
 - [Use the Besu API](../../public-networks/how-to/use-besu-api/index.md):
@@ -25,10 +24,13 @@ content can be found in the public networks section:
     - [Configure ports](../../public-networks/how-to/connect/configure-ports.md)
     - [Manage peers](../../public-networks/how-to/connect/manage-peers.md)
     - [Specify NAT method](../../public-networks/how-to/connect/specify-nat.md)
+- [Configure the Java Virtual Machine](../../public-networks/how-to/configure-jvm/index.md)
+    - [Pass JVM options](../../public-networks/how-to/configure-jvm/pass-jvm-options.md)
+    - [Manage JVM memory](../../public-networks/how-to/configure-jvm/manage-memory.md)
+    - [Use Java Flight Recorder](../../public-networks/how-to/configure-jvm/java-flight-recorder.md)
 - Develop dapps:
     - [Use Truffle](../../public-networks/how-to/develop/truffle.md)
     - [Use client libraries](../../public-networks/how-to/develop/client-libraries.md)
 - Troubleshoot:
     - [Use EVM tool](../../public-networks/how-to/troubleshoot/evm-tool.md)
-    - [Use Java Flight Recorder](../../public-networks/how-to/troubleshoot/java-flight-recorder.md)
     - [Trace transactions](../../public-networks/how-to/troubleshoot/trace-transactions.md)
diff --git a/docs/public-networks/how-to/configure-jvm/index.md b/docs/public-networks/how-to/configure-jvm/index.md
@@ -0,0 +1,11 @@
+---
+title: Configure Java and Besu
+tags:
+  - private networks
+hide:
+  - feedback
+---
+
+# Configure the Java Virtual Machine
+
+This section contains information on configuring Besu and the Java Virtual Machine (JVM).
diff --git a/...w-to/troubleshoot/java-flight-recorder.md → ...-to/configure-jvm/java-flight-recorder.md b/...w-to/troubleshoot/java-flight-recorder.md → ...-to/configure-jvm/java-flight-recorder.md
diff --git a/docs/public-networks/how-to/configure-jvm/manage-memory.md b/docs/public-networks/how-to/configure-jvm/manage-memory.md
@@ -0,0 +1,74 @@
+---
+description: Besu memory management
+tags:
+  - private networks
+---
+
+# Manage JVM memory
+
+You can manage Java Virtual Machine (JVM) memory usage for Besu by modifying the maximum heap size.
+
+By default, the JVM uses 25% of system RAM.
+For example, if you have 16 GB RAM installed, the JVM uses 4 GB by default.
+
+On public networks, we recommend setting the maximum heap size to:
+
+- 3 GB on an 8 GB RAM system.
+- 5 GB on a 16 GB RAM system.
+- 8 GB on a system with at least 24 GB RAM.
+
+!!! note
+
+    Setting a higher maximum heap size speeds up the sync period but doesn't have much impact
+    after sync.
+    Thus, we recommend setting it to 8 GB only when you have available RAM.
+
+You can set the maximum heap size using the `BESU_OPTS` environment variable and the `-Xmx` option.
+The following examples set the maximum heap size to 8 GB:
+
+=== "Exported environment variable example"
+
+    Set the variable for the whole shell before running Besu.
+
+    ```bash
+    export BESU_OPTS=-Xmx8g
+    ```
+
+=== "Inline environment variable example"
+
+    Set the variable only for the specific Besu command.
+
+    ```bash
+    BESU_OPTS=-Xmx8g besu [Besu options]
+    ```
+
+=== "`.service` file example"
+
+    ```bash
+    [Service]
+    ...
+    Environment="BESU_OPTS=-Xmx8g"
+    ExecStart=besu [Besu options]
+    ...
+    ```
+
+## Manage the heap dump
+
+Heap dump file generation is disabled by default.
+To enable it, set the `-XX:+HeapDumpOnOutOfMemoryError` Java option.
+
+```bash
+BESU_OPTS="-XX:+HeapDumpOnOutOfMemoryError"
+```
+
+When heap dump file generation is enabled, and an out-of-memory error occurs, the heap dump file is
+saved in the Besu runtime directory by default.
+
+The heap dump file might be large and can saturate your drive.
+It can be up to the size of the allocated memory.
+For example, for 8 GB heap memory, the file can be up to 8 GB.
+Specify the directory where you want the dump to be saved using the `-XX:HeapDumpPath` Java option.
+
+```bash
+BESU_OPTS="-XX:HeapDumpPath=/<path>/<to>/<directory>"
+```
diff --git a/...ublic-networks/how-to/pass-jvm-options.md → .../how-to/configure-jvm/pass-jvm-options.md b/...ublic-networks/how-to/pass-jvm-options.md → .../how-to/configure-jvm/pass-jvm-options.md
@@ -6,8 +6,8 @@ tags:
 
 # Pass JVM options
 
-To perform tasks such as attaching a debugger or configuring the garbage collector, pass JVM
-options to Hyperledger Besu.
+To perform tasks such as attaching a debugger or configuring the garbage collector, pass Java
+Virtual Machine (JVM) options to Hyperledger Besu.
 
 Besu passes the contents of the `BESU_OPTS` environment variable to the JVM. Set standard JVM
 options in the `BESU_OPTS` variable.

diff --git a/mkdocs.navigation.yml b/mkdocs.navigation.yml
@@ -43,10 +43,14 @@ nav:
               - Use metrics: public-networks/how-to/monitor/metrics.md
               - Understand metrics: public-networks/how-to/monitor/understand-metrics.md
               - Configure logging: public-networks/how-to/monitor/logging.md
-          - Pass JVM options: public-networks/how-to/pass-jvm-options.md
           - Configure high availability:
               - public-networks/how-to/configure-ha/index.md
               - Sample load balancer configurations: public-networks/how-to/configure-ha/sample-configuration.md
+          - Configure the Java Virtual Machine:
+              - public-networks/how-to/configure-jvm/index.md
+              - Pass JVM options: public-networks/how-to/configure-jvm/pass-jvm-options.md
+              - Manage JVM memory: public-networks/how-to/configure-jvm/manage-memory.md
+              - Use Java Flight Recorder: public-networks/how-to/configure-jvm/java-flight-recorder.md
           - Develop dapps:
               - Use Truffle: public-networks/how-to/develop/truffle.md
               - Use client libraries: public-networks/how-to/develop/client-libraries.md
@@ -55,7 +59,6 @@ nav:
           - Upgrade Besu: public-networks/how-to/upgrade-node.md
           - Troubleshoot:
               - Use EVM tool: public-networks/how-to/troubleshoot/evm-tool.md
-              - Use Java Flight Recorder: public-networks/how-to/troubleshoot/java-flight-recorder.md
               - Trace transactions: public-networks/how-to/troubleshoot/trace-transactions.md
       - Concepts:
           - The Merge: public-networks/concepts/the-merge.md

diff --git a/mkdocs.redirects.yml b/mkdocs.redirects.yml
@@ -85,15 +85,15 @@ plugins:
       HowTo/Monitor/OpenTelemetry-Collector.md: private-networks/how-to/monitor/opentelemetry.md
       HowTo/Configure/Using-Configuration-File.md: public-networks/how-to/configuration-file.md
       HowTo/Configure/Configure-Mining.md: public-networks/how-to/use-pow/mining.md
-      HowTo/Configure/Passing-JVM-Options.md: public-networks/how-to/pass-jvm-options.md
+      HowTo/Configure/Passing-JVM-Options.md: public-networks/how-to/configure-jvm/pass-jvm-options.md
       Concepts/Merge.md: public-networks/concepts/the-merge.md
       Concepts/NetworkID-And-ChainID.md: public-networks/concepts/network-and-chain-id.md
       Concepts/Events-and-Logs.md: public-networks/concepts/events-and-logs.md
       HowTo/Configure/Genesis-File.md: public-networks/concepts/genesis-file.md
       HowTo/Upgrade/Upgrade-Node.md: public-networks/how-to/upgrade-node.md
       HowTo/Upgrade/Upgrade-Protocol.md: private-networks/how-to/upgrade.md
       HowTo/Troubleshoot/Use-EVM-Tool.md: public-networks/how-to/troubleshoot/evm-tool.md
-      HowTo/Troubleshoot/Java-Flight-Recording.md: public-networks/how-to/troubleshoot/java-flight-recorder.md
+      HowTo/Troubleshoot/Java-Flight-Recording.md: public-networks/how-to/configure-jvm/java-flight-recorder.md
       HowTo/Troubleshoot/Trace-Transactions.md: public-networks/how-to/troubleshoot/trace-transactions.md
       Concepts/Node-Keys.md: public-networks/concepts/node-keys.md
       Concepts/Data-Storage-Formats.md: public-networks/concepts/data-storage-formats.md
@@ -199,3 +199,4 @@ plugins:
       HowTo/Configure/Configure-HA/Sample-Configuration.md: public-networks/how-to/configure-ha/sample-configuration.md
       Concepts/Pruning.md: public-networks/concepts/data-storage-formats.md
       Concepts/TLS.md: private-networks/how-to/configure/tls/client-and-server.md
+      public-networks/how-to/troubleshoot/java-flight-recorder.md: public-networks/how-to/configure-jvm/java-flight-recorder.md