ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-04 11:55:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

Online deletion revisions

Browse Source 
- Split ledger history section into a parent concept page w/ online
deletion and history sharding as child pages
- Clarified how much data is stored in general
- Covered the special case for backfilling with advisory_delete enabled
(including updating the diagram)
- Changed full history recommendation to NuDB only
This commit is contained in:
mDuo13
2018-12-18 14:21:51 -08:00
parent ab6b4d4435
commit a3400378c4
11 changed files with 317 additions and 166 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
content/_img-sources/online_delete-vs-ledger_history.uxf
View File

@@ -4,8 +4,8 @@
<element>
<id>UMLClass</id>
<coordinates>
<x>30</x>
<y>70</y>
<x>50</x>
<y>140</y>
<w>330</w>
<h>40</h>
</coordinates>
@@ -18,8 +18,8 @@ lt=..</panel_attributes>
<element>
<id>Relation</id>
<coordinates>
<x>20</x>
<y>110</y>
<x>40</x>
<y>180</y>
<w>740</w>
<h>50</h>
</coordinates>
@@ -33,8 +33,8 @@ m2=newest</panel_attributes>
<element>
<id>UMLClass</id>
<coordinates>
<x>360</x>
<y>70</y>
<x>380</x>
<y>140</y>
<w>170</w>
<h>40</h>
</coordinates>
@@ -47,8 +47,8 @@ transparency=0</panel_attributes>
<element>
<id>UMLClass</id>
<coordinates>
<x>530</x>
<y>70</y>
<x>550</x>
<y>140</y>
<w>210</w>
<h>40</h>
</coordinates>
@@ -61,8 +61,8 @@ fg=#f5f7f9</panel_attributes>
<element>
<id>Relation</id>
<coordinates>
<x>520</x>
<y>30</y>
<x>540</x>
<y>100</y>
<w>70</w>
<h>60</h>
</coordinates>
@@ -72,8 +72,8 @@ fg=#f5f7f9</panel_attributes>
<element>
<id>Text</id>
<coordinates>
<x>570</x>
<y>30</y>
<x>590</x>
<y>100</y>
<w>210</w>
<h>30</h>
</coordinates>
@@ -84,8 +84,8 @@ style=wordwrap</panel_attributes>
<element>
<id>Text</id>
<coordinates>
<x>150</x>
<y>30</y>
<x>170</x>
<y>100</y>
<w>170</w>
<h>30</h>
</coordinates>
@@ -96,12 +96,100 @@ style=wordwrap</panel_attributes>
<element>
<id>Relation</id>
<coordinates>
<x>300</x>
<y>30</y>
<x>320</x>
<y>100</y>
<w>80</w>
<h>60</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;&lt;-</panel_attributes>
<additional_attributes>60.0;40.0;60.0;10.0;10.0;10.0</additional_attributes>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>40</x>
<y>430</y>
<w>740</w>
<h>50</h>
</coordinates>
<panel_attributes>lt=-&gt;&gt;
Ledger versions
m1=oldest
m2=newest</panel_attributes>
<additional_attributes>10.0;20.0;720.0;20.0</additional_attributes>
</element>
<element>
<id>Text</id>
<coordinates>
<x>110</x>
<y>320</y>
<w>230</w>
<h>60</h>
</coordinates>
<panel_attributes>online_delete setting, or most recent can_delete point, whichever is older
style=wordwrap</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>50</x>
<y>390</y>
<w>330</w>
<h>40</h>
</coordinates>
<panel_attributes>Delete automatically
bg=#e1e4e8
fg=#23292f
lt=..</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Relation</id>
<coordinates>
<x>310</x>
<y>340</y>
<w>90</w>
<h>70</h>
</coordinates>
<panel_attributes>lt=&lt;&lt;&lt;-</panel_attributes>
<additional_attributes>70.0;50.0;70.0;10.0;10.0;10.0</additional_attributes>
</element>
<element>
<id>UMLClass</id>
<coordinates>
<x>380</x>
<y>390</y>
<w>380</w>
<h>40</h>
</coordinates>
<panel_attributes>Backfill if possible
bg=#1db4ff
transparency=0
fg=#f5f7f9</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Text</id>
<coordinates>
<x>50</x>
<y>60</y>
<w>220</w>
<h>30</h>
</coordinates>
<panel_attributes>*Without advisory deletion*</panel_attributes>
<additional_attributes/>
</element>
<element>
<id>Text</id>
<coordinates>
<x>40</x>
<y>280</y>
<w>220</w>
<h>30</h>
</coordinates>
<panel_attributes>*With advisory deletion*</panel_attributes>
<additional_attributes/>
</element>
</diagram>

0
content/concepts/the-rippled-server/history-sharding.md → content/concepts/the-rippled-server/ledger-history/history-sharding.md
View File

56
content/concepts/the-rippled-server/ledger-history/ledger-history.md Normal file
View File

@@ -0,0 +1,56 @@
# Ledger History
The [consensus process](intro-to-consensus.html) creates a chain of [validated ledger versions](ledgers.html), each derived from the previous one by applying a set of transactions. Every `rippled` server stores ledger versions and transaction history locally. The amount of transaction history a server stores depends on how long that server has been online and how much history it is configured to fetch and keep.
Servers in the peer-to-peer XRP Ledger network share transactions and other data with each other as part of the consensus process. Each server each independently builds each new ledger version and compares results with its trusted validators to ensure consistency. (If a consensus of trusted validators disagrees with a server's results, that server fetches the necessary data from its peers to achieve consistency.) Servers can download older data from their peers to fill gaps in their available history. The structure of the ledger uses cryptographic [hashes](basic-data-types.html#hashes) of the data so that any server can verify the integrity and consistency of the data.
## Databases
Servers keep ledger state data and transactions in a key-value store called the _ledger store_. Additionally, `rippled` maintains a few SQLite database files for more flexible access to things like transaction history, and to track certain settings changes.
It is generally safe to delete all of a `rippled` server's database files when that server is not running. (You may want to do this, for example, if you change the server's storage settings or if you are switching from a test net to the production network.)
## Available History
By design, all data and transactions in the XRP Ledger are public, and anyone can search or query anything. However, your server can only search data that it has available locally. If you try to query for a ledger version or transaction that your server does not have available, your server replies that it cannot find that data. Other servers that have the necessary history can respond successfully to the same query. If you have a business that uses XRP Ledger data, you should be mindful of how much history your server has available.
The [server_info method][] reports how many ledger versions your server has available in the `complete_ledgers` field.
## Fetching History
When it starts, a `rippled` server's first priority is to get a complete copy of the latest validated ledger. From there, it keeps up with advances in the ledger progress. If configured to do so, the server also backfills ledger history up to a configured amount, which must be equal or less than the cutoff beyond which online deletion is configured to delete.
The server can backfill history from before it became synced, as well as filling in any gaps in the history it has collected after syncing. (Gaps in ledger history can occur if a server temporarily becomes too busy to keep up with the network, loses its network connection, or suffers other temporary issues.) To backfill history, the server requests data from its peer `rippled` servers. The amount the server tries to backfill is defined by the `[ledger_history]` setting.
The XRP Ledger identifies data (on several different levels) by a unique hash of its contents. The XRP Ledger's state data contains a short summary of the ledger's history, in the form of the [LedgerHashes object type](ledgerhashes.html). Servers use the LedgerHashes objects to know which ledger versions to fetch, and to confirm that the ledger data they receive is correct and complete.
Backfilling history is one of the server's lowest priorities, so it may take a long time to fill missing history, especially if the server is busy or has less than sufficient hardware and network specs. For recommendations on hardware specs, see [Capacity Planning](capacity-planning.html). Backfilling history also requires that at least one of the server's direct peers has the history in question. <!--{# TODO: link some info for managing your peer connections when that exists #}-->
### With Advisory Deletion
If [online deletion](online-deletion.html) and advisory deletion are both enabled, the server automatically backfills data up to the oldest ledger it has not been allowed to delete yet. This can fetch data beyond the number of ledger versions configured in the `[ledger_history]` and `online_delete` settings. The [can_delete method][] tells the server what ledger versions it is allowed to delete.
## Full History
Some servers in the XRP Ledger network are configured as "full-history" servers. These servers, which require significantly more disk space than other tracking servers, collect all available XRP Ledger history and **do not use online deletion**.
Ripple provides a set of public full-history servers as a public service at `s2.ripple.com`. This service is provided for the benefit of the larger XRP community. Ripple reserves the right to block those who abuse the servers or use more than their fair share of the servers' resources.
**Tip:** Unlike some cryptocurrency networks, servers in the XRP Ledger do not need full history to know the current state and keep up with current transactions.
For instructions setting up full history, see [Configure Full History](configure-full-history.html).
## History Sharding
An alternative to storing the full history of the XRP Ledger on a single expensive machine is to configure many servers to each store a portion of ledger history. The [History Sharding](history-sharding.html) feature makes this possible, storing ranges of ledger history in a separate storage area called the _shard store_. When a peer server asks for specific data (as described in [fetching history](#fetching-history) above), a server can answer using data from either its ledger store or shard store.
Online deletion **does not** delete from the shard store. However, if you configure online deletion to keep at least 32768 ledger versions in your server's ledger store, your server can copy full shards from the ledger store to the shard store before automatically deleting them from the ledger store.
For more information, see [Configure History Sharding](configure-history-sharding.html).
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

107
content/concepts/the-rippled-server/ledger-history/online-deletion.md Normal file
View File

@@ -0,0 +1,107 @@
# Online Deletion
[[Source]<br/>](https://github.com/ripple/rippled/blob/master/src/ripple/app/misc/SHAMapStoreImp.cpp "Source")
The online deletion feature lets the `rippled` server delete the server's local copy of old ledger versions to keep disk usage from rapidly growing over time. The default config file sets online deletion to run automatically, but online deletion can also be configured to run only when prompted. [New in: rippled 0.27.0][]
The server always keeps the complete _current_ state of the ledger, with all the balances and settings it contains. The deleted data includes older transactions and versions of the ledger state that are older than the stored history.
The default config file sets the `rippled` server to keep the most recent 2000 ledger versions and automatically delete older data.
**Tip:** Even with online deletion, the amount of disk space required to store the same time span's worth of ledger data increases over time, because the size of individual ledger versions tends to grow over time. This growth is very slow in comparison to the accumulation of data that occurs without deleting old ledgers. For more information on disk space needs, see [Capacity Planning](capacity-planning.html).
## Background
The `rippled` server stores [ledger history](ledger-history.html) in its _ledger store_. This data accumulates over time.
Inside the ledger store, ledger data is "de-duplicated": data that doesn't change from version to version is only stored once. The records themselves in the ledger store do not indicate which ledger version(s) contain them; part of the work of online deletion is identifying which records are only used by outdated ledger versions. This process is time consuming and affects the disk I/O and application cache, so it is not feasible to delete old data on every ledger close.
## Online Deletion Behavior
The online deletion settings configure how many ledger versions the `rippled` server should keep available in the ledger store at a time. However, the specified number is a guideline, not a hard rule:
- The server never deletes data more recent than the configured number of ledger versions, but it may have less than that amount available if it has not been running for long enough or if it lost sync with the network at any time. (The server attempts to backfill at least some history; see [fetching history](ledger-history.html#fetching-history) for details.)
- The server may store up to twice the configured number of ledger versions if online deletion is set to run automatically. (Each time it runs, it reduces the number of stored ledger versions to approximately the configured number.)
- If advisory deletion is enabled, the server stores all the ledger versions that it has acquired and built until its administrator calls the [can_delete method][].
If you call [can_delete][can_delete method] on a regular basis, the maximum amount of data the server stores is either of the following, whichever is larger:
- A number of ledger versions approximately equal to twice the `online_delete` value. (After deletion, this is reduced to approximately the `online_delete` value.)
- Ledger versions spanning an amount of time that is approximately twice the interval between `can_delete` calls. (After deletion, this is reduced to approximately one interval's worth of data.)
For example, if you call `can_delete` with a value of `now` once per day and an `online_delete` value of 2000, the server typically stores up two full day's worth of ledger versions before running deletion. After running deletion, the server keeps approximately 1 day's worth, but never less than 2000 ledger versions.
With online deletion enabled and running automatically (that is, with advisory delete disabled), the total amount of ledger data stored should remain at minimum equal to the number of ledger versions the server is configured to keep, with the maximum being roughly twice that many.
When online deletion runs, it does not reduce the size of SQLite database files on disk; it only makes space within those files available to be reused for new data. Online deletion _does_ reduce the size of RocksDB or NuDB database files containing the ledger store.
The server only counts validated ledger versions when deciding how far back it can delete. In exceptional circumstances where the server is unable to validate new ledger versions (either because of an outage in its local network connection or because the global XRP Ledger network is unable to reach a consensus) `rippled` continues to close ledgers so that it can recover quickly when the network is restored. In this case, the server may accumulate many closed but not validated ledger versions. These unvalidated ledgers do not affect how many _validated_ ledger versions the server keeps before running online deletion.
### Interrupting Online Deletion
Online deletion automatically stops if the [server state](rippled-server-states.html) becomes less than `full`. If this happens, the server writes a log message with the prefix `SHAMapStore::WRN`. The server attempts to start online deletion again after the next validated ledger version after becoming fully synced.
If you stop the server or it crashes while online deletion is running, online deletion resumes after the server is restarted and the server becomes fully synced.
To temporarily disable online deletion, you can use the [can_delete method][] with an argument of `never`. This change persists until you re-enable online deletion by calling [can_delete][can_delete method] again, even if you change the . For more information on controlling when online deletion happens, see [Advisory Deletion](#advisory-deletion).
## Configuration
The following settings relate to online deletion:
- **`online_delete`** - Specify a number of validated ledger versions to keep. The server periodically deletes any ledger versions that are older than this number. If not specified, no ledgers are deleted.
The default config file specifies 2000 for this value. This cannot be less than 256, because some events like [Fee Voting](fee-voting.html) and the [Amendment Process](amendments.html#amendment-process) update only every 256 ledgers.
**Caution:** If you run `rippled` with `online_delete` disabled, then later enable `online_delete` and restart the server, the server disregards but does not delete existing ledger history that your server already downloaded while `online_delete` was disabled. To save disk space, delete your existing history before re-starting the server with `online_delete` back on.
- **`[ledger_history]`** - Specify a number of validated ledgers, equal to or less than `online_delete`. If the server does not have at least this many validated ledger versions, it attempts to backfill them by fetching the data from peers.
The default for this setting is 256 ledgers.
The following diagram shows the relationship between `online_delete` and `ledger_history` settings:
![Ledgers older than `online_delete` are automatically deleted. Ledgers newer than `ledger_history` are backfilled. Ledgers in between are kept if available but not backfilled](img/online_delete-vs-ledger_history.png)
- **`advisory_delete`** - If enabled, online deletion is not scheduled automatically. Instead, an administrator must manually trigger online deletion. Use the value `0` for disabled or `1` for enabled.
This setting is disabled by default.
- **`[fetch_depth]`** - Specify a number of ledger versions. The server does not accept fetch requests from peers for historical data that is older than the specified number of ledger versions. Specify the value `full` to serve any available data to peers.
The default for `fetch_depth` is `full` (serve all available data).
The `fetch_depth` setting cannot be higher than `online_delete` if both are specified. If `fetch_depth` is set higher, the server treats it as equal to `online_delete` instead.
The following diagram shows how fetch_depth works:
![Ledger versions older than fetch_depth are not served to peers](img/fetch_depth.png)
For estimates of how much disk space is required to store different amounts of history, see [Capacity Planning](capacity-planning.html#historical-data).
### Advisory Deletion
By default, online deletion happens automatically and periodically. If the `advisory_delete` setting is enabled in the config file, online deletion only happens when an administrator triggers it using the [can_delete method][].
You can use advisory deletion with a scheduled job to trigger automatic deletion based on clock time instead of the number of ledger versions closed. If your server is heavily used, the extra load from online deletion can cause your server to fall behind and temporarily de-sync from the consensus network. If this is the case, you can use advisory deletion and schedule online deletion to happen only during off-peak times.
Alternatively, you can use advisory deletion for other reasons, such as if you want to manually confirm that transaction data is backed up to a separate server before deleting it.
The `can_delete` API method can enable or disable automatic deletion, in general or up to a specific ledger version, as long as `advisory_delete` is enabled in the config file. These settings changes persist even if you restart the `rippled` server, unless you disable `advisory_delete` in the config file before restarting.
## See Also
- [Capacity Planning](capacity-planning.html)
- [can_delete method][] API reference documentation
- [Configure Online Deletion](configure-online-deletion.html)
- [Configure Advisory Deletion](configure-advisory-deletion.html)
- [Configure Full History](configure-full-history.html)
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

126
content/concepts/the-rippled-server/online-deletion.md
View File

@@ -1,126 +0,0 @@
# Online Deletion
[[Source]<br/>](https://github.com/ripple/rippled/blob/master/src/ripple/app/misc/SHAMapStoreImp.cpp "Source")
The online deletion feature lets the `rippled` server delete the server's local copy of old ledger versions to keep disk usage from rapidly growing over time. Online deletion happens automatically by default, but can be configured to run only when prompted. [New in: rippled 0.27.0][]
The server always keeps the complete _current_ state of the ledger, with all the balances and settings it contains. The deleted data includes older transactions and versions of the ledger state that are older than the stored history.
The default config file sets the `rippled` server to keep the most recent 2000 ledger versions and automatically delete older data.
**Tip:** Even with online deletion, the amount of disk space required to store the same time span's worth of ledger data increases over time, because the size of individual ledger versions tends to grow over time. This growth is very slow in comparison to the accumulation of data that occurs without deleting old ledgers. For more information on disk space needs, see [Capacity Planning](capacity-planning.html).
## Background
The `rippled` server stores data from recent ledger versions in its _ledger store_. This data accumulates as the XRP Ledger network creates new ledger versions and validates them through the [consensus process](intro-to-consensus.html).
The XRP Ledger stores the complete state of the current ledger, with all balances, settings, and other data, in each ledger version. Unlike many cryptocurrency systems, an XRP Ledger server does not require full history to sync with the network, know the full state, and contribute to making forward progress.
Inside the ledger store, ledger data is "de-duplicated", with data that doesn't change from version to version only stored once. The records themselves in the ledger store do not indicate which ledger version(s) contain them; part of the work of online deletion is identifying which records are only used by outdated ledger versions. This process is time consuming and affects the disk I/O and application cache, so it is not feasible to delete old data on every ledger close.
### Fetching History
When it starts, a `rippled` server's first priority is to get a complete copy of the latest validated ledger. From there, it keeps up with advances in the ledger progress. If configured to do so, the server also backfills ledger history up to a configured amount, which must be equal or less than the cutoff beyond which online deletion is configured to delete.
The server can backfill history from before it became synced, as well as filling in any gaps in the history it has collected after syncing. (Gaps in ledger history can occur if a server temporarily becomes too busy to keep up with the network, loses its network connection, or suffers other temporary issues.) To backfill history, the server requests data from its peer `rippled` servers. The amount the server tries to backfill is defined by the `[ledger_history]` setting.
The XRP Ledger identifies data (on several different levels) by a unique hash of its contents. The XRP Ledger's state data contains a short summary of the ledger's history, in the form of the [LedgerHashes object type](ledgerhashes.html). Servers use the LedgerHashes objects to know which ledger versions to fetch, and to confirm that the ledger data they receive is correct and complete.
Backfilling history is one of the server's lowest priorities, so it may take a long time to fill missing history, especially if the server is busy or has less than sufficient hardware and network specs. For recommendations on hardware specs, see [Capacity Planning](capacity-planning.html). Backfilling history also requires that at least one of the server's direct peers has the history in question. <!--{# TODO: link some info for managing your peer connections when that exists #}-->
### Full History
Some servers in the XRP Ledger network are configured as "full-history" servers. These servers, which require significantly more disk space than other tracking servers, collect all available XRP Ledger history and **do not use online deletion**.
For instructions setting up full history, see [Configure Full History](configure-full-history.html).
### History Sharding
An alternative to storing the full history of the XRP Ledger on a single expensive machine is to configure many servers to each store a portion of ledger history. The [History Sharding](history-sharding.html) feature makes this possible, storing ranges of ledger history in a separate storage area called the _shard store_. When a peer server asks for specific data (as described in [fetching history](#fetching-history) above), a server can answer using data from either its ledger store or shard store.
Online deletion **does not** delete from the shard store. However, if you configure online deletion to keep at least 32768 ledger versions in your server's ledger store, your server can copy full shards from the ledger store to the shard store before automatically deleting them from the ledger store.
For more information, see [Configure History Sharding](configure-history-sharding.html).
## Online Deletion Behavior
The online deletion settings configure how many ledger versions the `rippled` server should keep available in the ledger store at a time. However, the specified number is a guideline, not a hard rule:
- The server may have less than the configured number of ledger versions if it has not been running for long enough or if it lost sync with the network at any time. (The server attempts to backfill at least some history; see [fetching history](#fetching-history) above for details.)
- The server may store up to twice the configured number of ledger versions if online deletion is set to run automatically. (Each time it runs, it reduces the number of stored ledger versions to the configured number.)
- If advisory delete is enabled, the server stores all the ledger versions that it has acquired and built until someone calls the [can_delete method][].
For example, if you call `can_delete` with a value of `now` once per day and an `online_delete` value of 2000, the server typically stores 2000 ledger versions at minimum and just over a full day's worth of ledger versions at maximum.
With online deletion enabled and running automatically (that is, with advisory delete disabled), the total amount of ledger data stored should remain at minimum equal to the number of ledger versions the server is configured to keep, with the maximum being roughly twice that many.
When online deletion runs, it does not reduce the size of the database files on disk; it only makes space within those files available to be reused for new data. To actually reduce the disk space allocated to the database files, you must restart `rippled`.
### Interrupting Online Deletion
Online deletion automatically stops if the [server state](rippled-server-states.html) becomes less than `full`. If this happens, the server writes a log message with the prefix `SHAMapStore::WRN`. The server attempts to start online deletion again after the next validated ledger version after becoming fully synced.
If you stop the server or it crashes while online deletion is running, online deletion resumes after the server is restarted and the server becomes fully synced.
To temporarily disable online deletion, you can use the [can_delete method][] with an argument of `never`. This change persists until the server restarts or you re-enable online deletion by calling [can_delete][can_delete method] again. For more information on controlling when online deletion happens, see [Advisory Deletion](#advisory-deletion).
## Configuration
The following settings relate to online deletion:
- **`online_delete`** - Specify a number of validated ledger versions to keep. The server periodically deletes any ledger versions that are older than this number. If not specified, no ledgers are deleted.
The default config file specifies 2000 for this value. This cannot be less than 256, because some events like [Fee Voting](fee-voting.html) and the [Amendment Process](amendments.html#amendment-process) update only every 256 ledgers.
**Caution:** If you run `rippled` with `online_delete` disabled, then later enable `online_delete` and restart the server, the server disregards but does not delete existing ledger history that your server already downloaded while `online_delete` was disabled. To save disk space, delete your existing history before re-starting the server with `online_delete` back on.
- **`[ledger_history]`** - Specify a number of validated ledgers, equal to or less than `online_delete`. If the server does not have at least this many validated ledger versions, it attempts to backfill them by fetching the data from peers.
The default for this setting is 256 ledgers.
The following diagram shows the relationship between `online_delete` and `ledger_history` settings:
![Ledgers older than `online_delete` are automatically deleted. Ledgers newer than `ledger_history` are backfilled. Ledgers in between are kept if available but not backfilled](img/online_delete-vs-ledger_history.png)
- **`advisory_delete`** - If enabled, online deletion is not scheduled automatically. Instead, an administrator must manually trigger online deletion. Use the value `0` for disabled or `1` for enabled.
This setting is disabled by default.
- **`[fetch_depth]`** - Specify a number of ledger versions. The server does not accept fetch requests from peers for historical data that is older than the specified number of ledger versions. Specify the value `full` to serve any available data to peers.
The default for `fetch_depth` is `full` (serve all available data).
The `fetch_depth` setting cannot be higher than `online_delete` if both are specified. If `fetch_depth` is set higher, the server treats it as equal to `online_delete` instead.
The following diagram shows how fetch_depth works:
![Ledger versions older than fetch_depth are not served to peers](img/fetch_depth.png)
For estimates of how much disk space is required to store different amounts of history, see [Capacity Planning](capacity-planning.html#historical-data).
### Advisory Deletion
By default, online deletion happens automatically and periodically. If the `advisory_delete` setting is enabled, online deletion only happens when an administrator triggers it using the [can_delete method][]. You can run this command with a scheduled job to trigger automatic deletion based on clock time instead of the number of ledger versions closed.
If your server is heavily used, the extra load from online deletion can cause your server to fall behind and temporarily de-sync from the consensus network. If this is the case, you can use advisory delete and schedule online deletion to happen only during off-peak times.
You can also use advisory delete for other reasons, such as if you want to manually confirm that the transaction data is backed up to a separate server before deleting it.
The `can_delete` API method can enable advisory deletion (with the value `never`) or disable advisory delete (with the value `always`). These setting changes persist until you restart the `rippled` server, at which point the settings in the config file override them.
## See Also
- [Capacity Planning](capacity-planning.html)
- [can_delete method][] API reference documentation
- [Configure Online Deletion](configure-online-deletion.html)
- [Configure Advisory Deletion](configure-advisory-deletion.html)
- [Configure Full History](configure-full-history.html)
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}
{% include '_snippets/rippled_versions.md' %}

9
content/references/rippled-api/admin-rippled-methods/logging-and-data-management-methods/can_delete.md
View File

@@ -1,7 +1,7 @@
# can_delete
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/CanDelete.cpp "Source")
With `online_delete` and `advisory_delete` configuration options enabled, the `can_delete` method informs the rippled server of the latest ledger which may be deleted.
The `can_delete` method informs the `rippled` server of the latest ledger version which may be deleted when using [online deletion with advisory deletion enabled](online-deletion.html#advisory-deletion). If advisory deletion is not enabled, this method does nothing.
_The `can_delete` method is an [admin method](admin-rippled-methods.html) that cannot be run by unprivileged users._
@@ -47,7 +47,7 @@ The request includes the following optional parameter:
| `Field` | Type | Description |
|:-------------|:------------------|:------------------------------------------|
| `can_delete` | String or Integer | The maximum ledger to allow to be deleted. For `ledger_index` or `ledger_hash`, see [Specifying Ledgers][]. `never` sets the value to 0, and effectively disables online deletion until another `can_delete` is appropriately called. `always` sets the value to the maximum possible ledger (4294967295), and online deletion occurs as of each configured `online_delete` interval. `now` triggers online deletion at the next validated ledger that meets or exceeds the configured `online_delete` interval, but no further. |
| `can_delete` | String or Integer | The [Ledger Index][] of the maximum ledger version to allow to be deleted. The special case `never` disables online deletion. The special case `always` enables automatic online deletion as if advisory deletion was disabled. The special case `now` allows online deletion one time at the next validated ledger that meets or exceeds the configured `online_delete` value. |
If no parameter is specified, no change is made.
@@ -68,6 +68,11 @@ Use this command with no parameter to query the existing `can_delete` setting.
* `lgrNotFound` - Ledger not found.
* `invalidParams` - Invalid parameters.
## See Also
- [Online Deletion](online-deletion.html)
- [Configure Advisory Deletion](configure-advisory-deletion.html)
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}
{% include '_snippets/tx-type-links.md' %}

10
content/tutorials/manage-the-rippled-server/configuration/configure-advisory-deletion.md
View File

@@ -1,6 +1,6 @@
# Configure Advisory Deletion
In its default configuration, the `rippled` server automatically deletes outdated history of XRP Ledger state and transactions as new ledger versions become available. If your server uses most of its hardware resources during peak hours, you can configure the server to delete ledgers only when prompted by a command scheduled to run during off-peak hours to reduce the chances of online deletion
The default config file sets `rippled` to automatically delete outdated history of XRP Ledger state and transactions as new ledger versions become available. If your server uses most of its hardware resources during peak hours, you can configure the server to delete ledgers only when prompted by a command scheduled to run during off-peak hours to reduce the chances of online deletion.
## Prerequisites
@@ -37,7 +37,7 @@ To configure advisory deletion with a daily schedule, perform the following step
online_delete=2000
advisory_delete=1
- Set `advisory_delete` to `1` to require approval before running online deletion. (Set it to `0` to run online deletion automatically as new ledger versions become available.)
- Set `advisory_delete` to `1` to run online deletion only when prompted. (Set it to `0` to run online deletion automatically as new ledger versions become available.)
- Set `online_delete` to the minimum number of ledger versions to keep after running online deletion. The server accumulates more history than this until online deletion runs.
{% include '_snippets/conf-file-location.md' %}<!--_ -->
@@ -57,6 +57,8 @@ To configure advisory deletion with a daily schedule, perform the following step
}
}
The server only deletes those ledger versions if the number of _newer_ validated ledger versions it has is equal to or greater than the `online_delete` setting.
3. Configure your `cron` daemon to run the `can_delete` method you tested in the previous step at a scheduled time.
Edit your `cron` configuration:
@@ -67,9 +69,9 @@ To configure advisory deletion with a daily schedule, perform the following step
5 1 * * * rippled --conf /etc/opt/ripple/rippled.cfg can_delete now
Be sure that you schedule the command to run based on the time zone your server's clock is configured to use. Ripple recommends running all production servers with the UTC time zone.
Be sure that you schedule the command to run based on your server's configured time zone.
**Tip:** You do not need to schedule a `cron` job to run online deletion if you have `advisory_delete` disabled. In that case, `rippled` runs online deletion automatically when the server's oldest available ledger is twice as old as the number of ledgers to keep after deletion.
**Tip:** You do not need to schedule a `cron` job to run online deletion if you have `advisory_delete` disabled. In that case, `rippled` runs online deletion automatically when the server has approximately twice the number of ledgers to keep after deletion.
4. Start (or restart) the `rippled` service.

16
content/tutorials/manage-the-rippled-server/configuration/configure-full-history.md
View File

@@ -20,23 +20,17 @@ To configure your server to acquire and store full history, complete the followi
$ sudo systemctl stop rippled
0. Remove (or comment out) the `online_delete` and `advisory_delete` settings from the `[node_db]` stanza of your server's config file:
0. Remove (or comment out) the `online_delete` and `advisory_delete` settings from the `[node_db]` stanza of your server's config file, and change the type to `NuDB` if you haven't already:
[node_db]
type=RocksDB
path=/var/lib/rippled/db/rocksdb
open_files=2000
filter_bits=12
cache_mb=256
file_size_mb=8
file_size_mult=2
compression=1
type=NuDB
path=/var/lib/rippled/db/nudb
#online_delete=2000
#advisory_delete=0
You can store full history with either RocksDB or NuDB as the key-value store behind the ledger store. NuDB requires less RAM but RocksDB requires less disk space. For more information, see [Capacity Planning](capacity-planning.html).
On a full-history server, you should use NuDB for the ledger store, because RocksDB requires too much RAM when the database is that large. For more information, see [Capacity Planning](capacity-planning.html). You can remove the following performance-related configuration options from the default `[node_db]` stanza, because they only apply to RocksDB: `open_files`, `filter_bits`, `cache_mb`, `file_size_mb`, and `file_size_mult.`
If you are using RocksDB, add `compression=1` to enable Snappy compression, which reduces the disk space necessary to store full history (at a cost of greater CPU usage when reading or writing history).
**Caution:** If you have any history already downloaded with RocksDB, you must either delete that data or change the `path` field when you switch to NuDB. Otherwise, the server may [fail to start](server-wont-start.html). <!--{# TODO: link a specific case for this error #}-->
{% include '_snippets/conf-file-location.md' %}<!--_ -->

19
content/tutorials/manage-the-rippled-server/installation/capacity-planning.md
View File

@@ -64,14 +64,18 @@ RocksDB has performance-related configuration options that you can set in `rippl
```
[node_db]
type=RocksDB
path={path_to_ledger_store}
path=/var/lib/rippled/db/rocksdb
open_files=512
filter_bits=12
cache_mb=512
file_size_mb=64
file_size_mult=2
online_delete=2000
advisory_delete=0
```
(Adjust the `path` to the directory where you want to keep the ledger store on disk. Adjust the `online_delete` and `advisory_delete` settings as desired for your configuration.)
#### More About Using NuDb
[NuDB](https://github.com/vinniefalco/nudb#introduction) is an append-only key-value store that is optimized for SSD drives.
@@ -80,8 +84,17 @@ NuDB has nearly constant performance and memory footprints regardless of the amo
Non-validator production servers should be configured to use NuDB and to store the amount of historical data required for the use case.
NuDB does not have performance-related configuration options available in `rippled.cfg`.
NuDB does not have performance-related configuration options available in `rippled.cfg`. Here is the recommended configuration for a `rippled` server using NuDB:
```
[node_db]
type=NuDB
path=/var/lib/rippled/db/nudb
online_delete=2000
advisory_delete=0
```
(Adjust the `path` to the directory where you want to keep the ledger store on disk. Adjust the `online_delete` and `advisory_delete` settings as desired for your configuration.)
### Historical Data
@@ -98,7 +111,7 @@ The following table approximates the requirements for different amounts of histo
| 90 days | 2,250,000 | 720 GB | 1 TB |
| 1 year | 10,000,000 | 3 TB | 4.5 TB |
| 2 years | 20,000,000 | 6 TB | 9 TB |
| Full history (through 2018) | 43,000,000+ | 9 TB | (Unknown) |
| Full history (through 2018) | 43,000,000+ | (Not recommended) | ~9 TB |
These numbers are estimates. They depend on several factors, most importantly the volume of transactions in the network. As transaction volume increases, each ledger version stores more unique data.

20
dactyl-config.yml
View File

@@ -536,24 +536,36 @@ pages:
targets:
- local
- md: concepts/the-rippled-server/history-sharding.md
html: history-sharding.html
- md: concepts/the-rippled-server/ledger-history/ledger-history.md
html: ledger-history.html
funnel: Docs
doc_type: Concepts
category: The rippled Server
blurb: History sharding divides the work of keeping historical ledger data among rippled servers.
subcategory: Ledger History
blurb: rippled servers store a variable amount of transaction and state history locally.
targets:
- local
- md: concepts/the-rippled-server/online-deletion.md
- md: concepts/the-rippled-server/ledger-history/online-deletion.md
html: online-deletion.html
funnel: Docs
doc_type: Concepts
category: The rippled Server
subcategory: Ledger History
blurb: Online deletion purges outdated transaction and state history.
targets:
- local
- md: concepts/the-rippled-server/ledger-history/history-sharding.md
html: history-sharding.html
funnel: Docs
doc_type: Concepts
category: The rippled Server
subcategory: Ledger History
blurb: History sharding divides the work of keeping historical ledger data among rippled servers.
targets:
- local
- md: concepts/the-rippled-server/peer-protocol.md
html: peer-protocol.html
funnel: Docs

BIN
img/online_delete-vs-ledger_history.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 7.9 KiB

After

Width:  |  Height:  |  Size: 21 KiB