Add bonsai-limit-trie-logs options and update how to page (#1627)

* Add cli options for bonsai-limit-trie-logs-enabled and bonsai-trie-logs-pruning-window-size Signed-off-by: Simon Dudley <[email protected]> * Update how to page Signed-off-by: Simon Dudley <[email protected]> * Update docs/public-networks/how-to/bonsai-limit-trie-logs.md Co-authored-by: Joan E <[email protected]> Signed-off-by: Simon Dudley <[email protected]> * Use note as prerequisite Signed-off-by: Simon Dudley <[email protected]> * Adding pruning prerequisite Signed-off-by: Simon Dudley <[email protected]> * typo Signed-off-by: Simon Dudley <[email protected]> * edit and add to versioned docs Signed-off-by: Alexandra Tran <[email protected]> * edits Signed-off-by: Alexandra Tran <[email protected]> --------- Signed-off-by: Simon Dudley <[email protected]> Signed-off-by: Alexandra Tran <[email protected]> Co-authored-by: Joan E <[email protected]> Co-authored-by: Alexandra Tran <[email protected]>
hyperledger · Jun 24, 2024 · 83aa373 · 83aa373
1 parent 54e6da3
commit 83aa373
Show file tree

Hide file tree

Showing 4 changed files with 233 additions and 34 deletions.
diff --git a/docs/public-networks/how-to/bonsai-limit-trie-logs.md b/docs/public-networks/how-to/bonsai-limit-trie-logs.md
@@ -9,26 +9,34 @@ tags:
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-To decrease the database size when using the [Bonsai Trie](../concepts/data-storage-formats#bonsai-tries) data storage format, enable the early access feature `--Xbonsai-limit-trie-logs-enabled`. 
+When using the [Bonsai Tries](../concepts/data-storage-formats#bonsai-tries) data storage format,
+[`--bonsai-limit-trie-logs-enabled`](../reference/cli/options.md#bonsai-limit-trie-logs-enabled) is
+enabled by default. 
 When enabled, this feature can reduce database growth by more than 3 GB each week on Mainnet.
 
-## Limit and prune trie logs
+:::note
+If [`--sync-mode=FULL`](../reference/cli/options.md#sync-mode) is set, the
+[`--bonsai-limit-trie-logs-enabled`](../reference/cli/options.md#bonsai-limit-trie-logs-enabled)
+option is disallowed and must be set to `false`.
+:::
 
-:::caution
+## Limit and prune trie logs
 
-The following commands are examples. Before executing these example commands on your node, modify them to apply to your node's configuration.
+If you're running Besu without
+[`--bonsai-limit-trie-logs-enabled`](../reference/cli/options.md#bonsai-limit-trie-logs-enabled),
+you might have a backlog of redundant trie logs.
+You can prune these using the following instructions.
 
+:::note
+Ensure you are using Besu version 24.6.0 or later.
+If you are using an older version, upgrade Besu or refer to the older version of the documentation.
 :::
 
-1. Add the `--Xbonsai-limit-trie-logs-enabled` option to the [Besu configuration file](use-configuration-file).
-
-    :::note
-
-    If you are using a `systemd` service file, as recommended by [CoinCashew](https://www.coincashew.com/coins/overview-eth/guide-or-how-to-setup-a-validator-on-eth2-mainnet/part-i-installation/step-3-installing-execution-client/besu) 
-    and [Somer Esat](https://someresat.medium.com/guide-to-staking-on-ethereum-ubuntu-teku-f09ecd9ef2ee), ensure you execute `sudo systemctl daemon-reload`.
-
-    :::
-
+:::caution
+The following commands are examples.
+Before executing these example commands on your node, modify them to apply to your node's configuration.
+:::
+
 1. Stop Besu.
 1. (Optional) Run the Besu trie log prune command. Specify the Bonsai Trie data storage format and the data directory for your Besu database:
     ```bash
@@ -39,15 +47,17 @@ The following commands are examples. Before executing these example commands on
 
 ### Prune outdated trie logs
 
-When you start Besu with `--Xbonsai-limit-trie-logs-enabled`, it continuously prunes the unnecessary trie log data, removing it one block at a time.
+When you start Besu with
+[`--bonsai-limit-trie-logs-enabled`](../reference/cli/options.md#bonsai-limit-trie-logs-enabled), it
+continuously prunes the unnecessary trie log data, removing it one block at a time.
 This process begins after an initial reduction in the database size during startup.
 
-Enabling `--Xbonsai-limit-trie-logs-enabled` on a long-running node does not immediately clear your backlog of trie logs in the same way resyncing does. 
+Enabling `--bonsai-limit-trie-logs-enabled` on a long-running node does not immediately clear your backlog of trie logs in the same way resyncing does. 
 Instead of resyncing, you can run an offline command to immediately prune old trie logs. 
 To run the offline command, you must shut down Besu for a minimal period. 
-If the `--Xbonsai-limit-trie-logs-enabled` option is enabled, you do not need to run the offline command again after initially running it.
+If the `--bonsai-limit-trie-logs-enabled` option is enabled, you do not need to run the offline command again after initially running it.
 
-For minimal downtime, we recommend running the offline command before restarting Besu with `--Xbonsai-limit-trie-logs-enabled`.
+For minimal downtime, we recommend running the offline command before restarting Besu with `--bonsai-limit-trie-logs-enabled`.
 
 If you are following the guides by [Somer Esat](https://someresat.medium.com/guide-to-staking-on-ethereum-ubuntu-teku-f09ecd9ef2ee) or [CoinCashew](https://www.coincashew.com/coins/overview-eth/guide-or-how-to-setup-a-validator-on-eth2-mainnet/part-i-installation/step-3-installing-execution-client/besu), you have set the following options in your `besu.service` or `execution.service` systemd file:
 

diff --git a/docs/public-networks/reference/cli/options.md b/docs/public-networks/reference/cli/options.md
@@ -356,14 +356,105 @@ bonsai-historical-block-limit=256
 
 </Tabs>
 
-When using [Bonsai Tries](../../concepts/data-storage-formats.md#bonsai-tries), the [maximum number of previous blocks](../../concepts/data-storage-formats.md#accessing-data) for which Bonsai can reconstruct a historical state. The default is 512. 
+When using [Bonsai Tries](../../concepts/data-storage-formats.md#bonsai-tries), the
+[maximum number of previous blocks](../../concepts/data-storage-formats.md#accessing-data) for which
+Bonsai can reconstruct a historical state.
+The default is `512`. 
 
 :::note
 
 If you plan on querying historical blocks or state using the [JSON-RPC API](../api/index.md), you might need to adjust the default value or your configured value to avoid errors. 
 
 :::
 
+### `bonsai-limit-trie-logs-enabled`
+
+<Tabs>
+
+<TabItem value="Syntax" label="Syntax" default>
+
+```bash
+--bonsai-limit-trie-logs-enabled=[=<true|false>]
+```
+
+</TabItem>
+
+<TabItem value="Example" label="Example">
+
+```bash
+--bonsai-limit-trie-logs-enabled=false
+```
+
+</TabItem>
+
+<TabItem value="Environment variable" label="Environment variable">
+
+```bash
+BESU_BONSAI_LIMIT_TRIE_LOGS_ENABLED=false
+```
+
+</TabItem>
+
+<TabItem value="Example configuration file" label="Example configuration file"> 
+
+```bash
+bonsai-limit-trie-logs-enabled=false
+```
+
+</TabItem>
+
+</Tabs>
+
+Enables or disables limiting the number of
+[Bonsai Trie](../../concepts/data-storage-formats.md#bonsai-tries) logs that are retained.
+When enabled, this limit is set to the value of
+[`--bonsai-historical-block-limit`](#bonsai-historical-block-limit).
+The default is `true`, unless [`--sync-mode=FULL`](#sync-mode) is set, in which case this option is
+disallowed and must be set to `false`.
+
+### `bonsai-trie-logs-pruning-window-size`
+
+<Tabs>
+
+<TabItem value="Syntax" label="Syntax" default>
+
+```bash
+--bonsai-trie-logs-pruning-window-size=<INTEGER>
+```
+
+</TabItem>
+
+<TabItem value="Example" label="Example">
+
+```bash
+--bonsai-trie-logs-pruning-window-size=100000
+```
+
+</TabItem>
+
+<TabItem value="Environment variable" label="Environment variable">
+
+```bash
+BESU_BONSAI_TRIE_LOGS_PRUNING_WINDOW_SIZE=100000
+```
+
+</TabItem>
+
+<TabItem value="Example configuration file" label="Example configuration file"> 
+
+```bash
+bonsai-trie-logs-pruning-window-size=100000
+```
+
+</TabItem>
+
+</Tabs>
+
+When using [`--bonsai-limit-trie-logs-enabled`](#bonsai-limit-trie-logs-enabled), the number of trie
+logs to prune during one pruning operation.
+A larger value might impact node performance.
+The default is `30000`.
+
 ### `bootnodes`
 
 <Tabs>

diff --git a/versioned_docs/version-24.6.0/public-networks/how-to/bonsai-limit-trie-logs.md b/versioned_docs/version-24.6.0/public-networks/how-to/bonsai-limit-trie-logs.md
@@ -9,26 +9,34 @@ tags:
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-To decrease the database size when using the [Bonsai Trie](../concepts/data-storage-formats#bonsai-tries) data storage format, enable the early access feature `--Xbonsai-limit-trie-logs-enabled`. 
+When using the [Bonsai Tries](../concepts/data-storage-formats#bonsai-tries) data storage format,
+[`--bonsai-limit-trie-logs-enabled`](../reference/cli/options.md#bonsai-limit-trie-logs-enabled) is
+enabled by default.
 When enabled, this feature can reduce database growth by more than 3 GB each week on Mainnet.
 
+:::note
+If [`--sync-mode=FULL`](../reference/cli/options.md#sync-mode) is set, the
+[`--bonsai-limit-trie-logs-enabled`](../reference/cli/options.md#bonsai-limit-trie-logs-enabled)
+option is disallowed and must be set to `false`.
+:::
+
 ## Limit and prune trie logs
 
-:::caution
+If you're running Besu without
+[`--bonsai-limit-trie-logs-enabled`](../reference/cli/options.md#bonsai-limit-trie-logs-enabled),
+you might have a backlog of redundant trie logs.
+You can prune these using the following instructions.
 
-The following commands are examples. Before executing these example commands on your node, modify them to apply to your node's configuration.
+:::note
+Ensure you are using Besu version 24.6.0 or later.
+If you are using an older version, upgrade Besu or refer to the older version of the documentation.
+:::
 
+:::caution
+The following commands are examples.
+Before executing these example commands on your node, modify them to apply to your node's configuration.
 :::
 
-1. Add the `--Xbonsai-limit-trie-logs-enabled` option to the [Besu configuration file](use-configuration-file).
-
-    :::note
-
-    If you are using a `systemd` service file, as recommended by [CoinCashew](https://www.coincashew.com/coins/overview-eth/guide-or-how-to-setup-a-validator-on-eth2-mainnet/part-i-installation/step-3-installing-execution-client/besu) 
-    and [Somer Esat](https://someresat.medium.com/guide-to-staking-on-ethereum-ubuntu-teku-f09ecd9ef2ee), ensure you execute `sudo systemctl daemon-reload`.
-
-    :::
-
 1. Stop Besu.
 1. (Optional) Run the Besu trie log prune command. Specify the Bonsai Trie data storage format and the data directory for your Besu database:
     ```bash
@@ -39,15 +47,17 @@ The following commands are examples. Before executing these example commands on
 
 ### Prune outdated trie logs
 
-When you start Besu with `--Xbonsai-limit-trie-logs-enabled`, it continuously prunes the unnecessary trie log data, removing it one block at a time.
+When you start Besu with
+[`--bonsai-limit-trie-logs-enabled`](../reference/cli/options.md#bonsai-limit-trie-logs-enabled), it
+continuously prunes the unnecessary trie log data, removing it one block at a time.
 This process begins after an initial reduction in the database size during startup.
 
-Enabling `--Xbonsai-limit-trie-logs-enabled` on a long-running node does not immediately clear your backlog of trie logs in the same way resyncing does. 
+Enabling `--bonsai-limit-trie-logs-enabled` on a long-running node does not immediately clear your backlog of trie logs in the same way resyncing does. 
 Instead of resyncing, you can run an offline command to immediately prune old trie logs. 
 To run the offline command, you must shut down Besu for a minimal period. 
-If the `--Xbonsai-limit-trie-logs-enabled` option is enabled, you do not need to run the offline command again after initially running it.
+If the `--bonsai-limit-trie-logs-enabled` option is enabled, you do not need to run the offline command again after initially running it.
 
-For minimal downtime, we recommend running the offline command before restarting Besu with `--Xbonsai-limit-trie-logs-enabled`.
+For minimal downtime, we recommend running the offline command before restarting Besu with `--bonsai-limit-trie-logs-enabled`.
 
 If you are following the guides by [Somer Esat](https://someresat.medium.com/guide-to-staking-on-ethereum-ubuntu-teku-f09ecd9ef2ee) or [CoinCashew](https://www.coincashew.com/coins/overview-eth/guide-or-how-to-setup-a-validator-on-eth2-mainnet/part-i-installation/step-3-installing-execution-client/besu), you have set the following options in your `besu.service` or `execution.service` systemd file:
 

diff --git a/versioned_docs/version-24.6.0/public-networks/reference/cli/options.md b/versioned_docs/version-24.6.0/public-networks/reference/cli/options.md
@@ -364,6 +364,94 @@ If you plan on querying historical blocks or state using the [JSON-RPC API](../a
 
 :::
 
+### `bonsai-limit-trie-logs-enabled`
+
+<Tabs>
+
+<TabItem value="Syntax" label="Syntax" default>
+
+```bash
+--bonsai-limit-trie-logs-enabled=[=<true|false>]
+```
+
+</TabItem>
+
+<TabItem value="Example" label="Example">
+
+```bash
+--bonsai-limit-trie-logs-enabled=false
+```
+
+</TabItem>
+
+<TabItem value="Environment variable" label="Environment variable">
+
+```bash
+BESU_BONSAI_LIMIT_TRIE_LOGS_ENABLED=false
+```
+
+</TabItem>
+
+<TabItem value="Example configuration file" label="Example configuration file"> 
+
+```bash
+bonsai-limit-trie-logs-enabled=false
+```
+
+</TabItem>
+
+</Tabs>
+
+Enables or disables limiting the number of
+[Bonsai Trie](../../concepts/data-storage-formats.md#bonsai-tries) logs that are retained.
+When enabled, this limit is set to the value of
+[`--bonsai-historical-block-limit`](#bonsai-historical-block-limit).
+The default is `true`, unless [`--sync-mode=FULL`](#sync-mode) is set, in which case this option is
+disallowed and must be set to `false`.
+
+### `bonsai-trie-logs-pruning-window-size`
+
+<Tabs>
+
+<TabItem value="Syntax" label="Syntax" default>
+
+```bash
+--bonsai-trie-logs-pruning-window-size=<INTEGER>
+```
+
+</TabItem>
+
+<TabItem value="Example" label="Example">
+
+```bash
+--bonsai-trie-logs-pruning-window-size=100000
+```
+
+</TabItem>
+
+<TabItem value="Environment variable" label="Environment variable">
+
+```bash
+BESU_BONSAI_TRIE_LOGS_PRUNING_WINDOW_SIZE=100000
+```
+
+</TabItem>
+
+<TabItem value="Example configuration file" label="Example configuration file"> 
+
+```bash
+bonsai-trie-logs-pruning-window-size=100000
+```
+
+</TabItem>
+
+</Tabs>
+
+When using [`--bonsai-limit-trie-logs-enabled`](#bonsai-limit-trie-logs-enabled), the number of trie
+logs to prune during one pruning operation.
+A larger value might impact node performance.
+The default is `30000`.
+
 ### `bootnodes`
 
 <Tabs>