From b9fcff05278da7e60807ae595c45609c42ea1a23 Mon Sep 17 00:00:00 2001 From: Eric Mokaya Date: Mon, 13 Jan 2025 13:51:20 +0300 Subject: [PATCH 1/5] chore(docs): add syncing documentation --- docs/learn/advanced/18-syncing.md | 63 +++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 docs/learn/advanced/18-syncing.md diff --git a/docs/learn/advanced/18-syncing.md b/docs/learn/advanced/18-syncing.md new file mode 100644 index 00000000000..bc19d75d814 --- /dev/null +++ b/docs/learn/advanced/18-syncing.md @@ -0,0 +1,63 @@ +--- +sidebar_position: 1 +--- + +# Syncing + +Syncing is the process of downloading the blockchain and state from a remote node. + +There are two types of syncing: + +1. Blockchain syncing. + With block sync a node is downloading all of the data of an application from genesis and verifying it. +2. State syncing. + With state sync your node will download data related to the head or near the head of the chain and verify the data. This leads to drastically shorter times for joining a network. + + +## Observing syncing progress + +### Block Sync Metrics + +- `blocksync_syncing`: Indicates whether a node is currently block syncing. +- `blocksync_num_txs`: Number of transactions in the latest block. +- `blocksync_total_txs`: Total number of transactions. +- `blocksync_block_size_bytes`: Size of the latest block in bytes. +- `blocksync_latest_block_height`: Height of the latest block. + +### Block sync configuration + +```toml +blocksync: + version: "v0" +``` + + +### State Sync Metrics + +- `statesync_syncing`: Indicates whether a node is currently state syncing. + +### State sync configuration + +```toml +statesync: + enable: true + rpc_servers: "" + trust_height: 0 + trust_hash: "" + trust_period: 168h0m0s + discovery_time: 15s + temp_dir: "" + chunk_request_timeout: 10s + chunk_fetchers: "4" +``` + +### Checking if sync is complete + +- Query for the node status using the REST or GRPC API +- Check the `SyncInfo.CatchingUp` field +- If the field is `false`, then syncing is complete + + + + + From aca8474c9aee735d0965f994e8edb9643df4f5a6 Mon Sep 17 00:00:00 2001 From: Eric Mokaya Date: Mon, 13 Jan 2025 19:41:28 +0300 Subject: [PATCH 2/5] docs: address comments --- docs/learn/advanced/18-syncing.md | 38 +++++++++++++++++++++++++++---- 1 file changed, 34 insertions(+), 4 deletions(-) diff --git a/docs/learn/advanced/18-syncing.md b/docs/learn/advanced/18-syncing.md index bc19d75d814..a059ab28c39 100644 --- a/docs/learn/advanced/18-syncing.md +++ b/docs/learn/advanced/18-syncing.md @@ -16,6 +16,8 @@ There are two types of syncing: ## Observing syncing progress +> ### Note: This section applies to comet users. + ### Block Sync Metrics - `blocksync_syncing`: Indicates whether a node is currently block syncing. @@ -31,6 +33,7 @@ blocksync: version: "v0" ``` +- `version`: The version of the block sync protocol to use. ### State Sync Metrics @@ -51,12 +54,39 @@ statesync: chunk_fetchers: "4" ``` -### Checking if sync is complete +- `enable`: Set to true to enable state sync. +- `rpc_servers`: Comma-separated list of RPC servers for state sync. +- `trust_height`: Block height to trust for state sync. +- `trust_hash`: Block hash to trust for state sync. +- `trust_period`: Trust period for light client verification. +- `discovery_time`: Time to spend discovering snapshots before picking one. +- `temp_dir`: Directory for temporary state sync files. +- `chunk_request_timeout`: Timeout for chunk requests. +- `chunk_fetchers`: Number of concurrent chunk fetchers. -- Query for the node status using the REST or GRPC API -- Check the `SyncInfo.CatchingUp` field -- If the field is `false`, then syncing is complete +### Checking if sync is complete +Query for the node status using the REST or GRPC API: + +REST example: +```bash +curl http://localhost:1317/cosmos/base/tendermint/v1beta1/syncing +``` + +Expected response: +```json +{ + "syncing": false +} +``` + +GRPC example: +```bash +grpcurl -plaintext localhost:9090 cosmos.base.tendermint.v1beta1.Service/GetSyncing +``` + +The response includes `SyncInfo.CatchingUp` field +Syncing is complete when this field is `false` From 804855752837218b87729c2f4e9f477891b213e3 Mon Sep 17 00:00:00 2001 From: Eric Mokaya Date: Tue, 14 Jan 2025 13:45:26 +0300 Subject: [PATCH 3/5] docs: address comments --- docs/learn/advanced/18-syncing.md | 63 ++++++++++++++++--------------- 1 file changed, 33 insertions(+), 30 deletions(-) diff --git a/docs/learn/advanced/18-syncing.md b/docs/learn/advanced/18-syncing.md index a059ab28c39..d2c9a7888e1 100644 --- a/docs/learn/advanced/18-syncing.md +++ b/docs/learn/advanced/18-syncing.md @@ -6,20 +6,33 @@ sidebar_position: 1 Syncing is the process of downloading the blockchain and state from a remote node. -There are two types of syncing: +There are the following types of syncing: + +1. Genesis Sync: operator downloads genesis, sets peers and syncs the blockchain by executing all blocks since genesis. + > **NOTE:** requires a peer node that doesn't prune blocks (CometBFT state). + +2. State Sync: operator need to set `trust_height` and `trust_hash` of a block that s/he trusts as well as `trust_period` - the time how long the operator will trust the given block height. The app will query peer nodes to stream state from that blocks as well as all following blocks. Once the state is downloaded, the node will start executing all blocks since the `trust_height`. + > **NOTE:** requires a peer node that provides a state sync and is trusted by the validator. + +3. Snapshot Sync: operator downloads a snapshot from snapshot provider (usually validators) s/he trusts. From there the operator needs to unpack the snapshot to the node directory, update config, set peers, set moniker, setup validator keys. Once the data directory is properly configured, the validator can start a node. The node will query blocks since the snapshot and execute them. + > **NOTE:** requires a snapshot directory that is trusted by the validator. + +Genesis Sync has zero trust assumptions, but it's the most resource heavy. It also requires a node with all blocks - many validators prune the blocks to optimize space. -1. Blockchain syncing. - With block sync a node is downloading all of the data of an application from genesis and verifying it. -2. State syncing. - With state sync your node will download data related to the head or near the head of the chain and verify the data. This leads to drastically shorter times for joining a network. ## Observing syncing progress -> ### Note: This section applies to comet users. +> ### Note: This section applies to comet users +> +> To enable the Prometheus metrics, set `instrumentation.prometheus=true` in your config file. Metrics will be served under `/metrics` on `26660` port by default. Listen address can be changed in the config file (see `instrumentation.prometheus_listen_addr`). +> +> More [here](https://github.com/cometbft/cometbft/blob/main/docs/explanation/core/metrics.md). ### Block Sync Metrics +They are defined [here](https://github.com/cometbft/cometbft/blob/main/internal/blocksync/metrics.go) and are accessible from the node's metrics endpoint. + - `blocksync_syncing`: Indicates whether a node is currently block syncing. - `blocksync_num_txs`: Number of transactions in the latest block. - `blocksync_total_txs`: Total number of transactions. @@ -29,41 +42,31 @@ There are two types of syncing: ### Block sync configuration ```toml -blocksync: - version: "v0" +[blocksync] +version = "v0" # version of the block sync protocol to use ``` -- `version`: The version of the block sync protocol to use. - ### State Sync Metrics +They are defined [here](https://github.com/cometbft/cometbft/blob/main/internal/statesync/metrics.go) and are accessible from the node's metrics endpoint. + - `statesync_syncing`: Indicates whether a node is currently state syncing. ### State sync configuration ```toml -statesync: - enable: true - rpc_servers: "" - trust_height: 0 - trust_hash: "" - trust_period: 168h0m0s - discovery_time: 15s - temp_dir: "" - chunk_request_timeout: 10s - chunk_fetchers: "4" +[statesync] +enable = true # set to true to enable state sync +rpc_servers = "" # comma-separated list of RPC servers for state sync +trust_height = 0 # block height to trust for state sync +trust_hash = "" # block hash to trust for state sync +trust_period = "168h0m0s" # trust period for light client verification +discovery_time = "15s" # time to spend discovering snapshots before picking one +temp_dir = "" # directory for temporary state sync files +chunk_request_timeout = "10s" # timeout for chunk requests +chunk_fetchers = "4" # number of concurrent chunk fetchers ``` -- `enable`: Set to true to enable state sync. -- `rpc_servers`: Comma-separated list of RPC servers for state sync. -- `trust_height`: Block height to trust for state sync. -- `trust_hash`: Block hash to trust for state sync. -- `trust_period`: Trust period for light client verification. -- `discovery_time`: Time to spend discovering snapshots before picking one. -- `temp_dir`: Directory for temporary state sync files. -- `chunk_request_timeout`: Timeout for chunk requests. -- `chunk_fetchers`: Number of concurrent chunk fetchers. - ### Checking if sync is complete Query for the node status using the REST or GRPC API: From a0de93bd7a68b40afd57a342212165e8f1afa67a Mon Sep 17 00:00:00 2001 From: Eric Mokaya Date: Tue, 14 Jan 2025 13:49:34 +0300 Subject: [PATCH 4/5] docs: address comments --- docs/learn/advanced/18-syncing.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/learn/advanced/18-syncing.md b/docs/learn/advanced/18-syncing.md index d2c9a7888e1..b4f1e1d4259 100644 --- a/docs/learn/advanced/18-syncing.md +++ b/docs/learn/advanced/18-syncing.md @@ -69,6 +69,12 @@ chunk_fetchers = "4" # number of concurrent chunk fetchers ### Checking if sync is complete +Query the status using the app cli: + +```bash +app q consensus comet syncing +``` + Query for the node status using the REST or GRPC API: REST example: From 7ae0f435dae61b899571a81988b68f80f76e6010 Mon Sep 17 00:00:00 2001 From: Eric Mokaya Date: Tue, 14 Jan 2025 19:13:54 +0300 Subject: [PATCH 5/5] docs: fix statesync metrics link --- docs/learn/advanced/18-syncing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/learn/advanced/18-syncing.md b/docs/learn/advanced/18-syncing.md index b4f1e1d4259..131014a32c7 100644 --- a/docs/learn/advanced/18-syncing.md +++ b/docs/learn/advanced/18-syncing.md @@ -48,7 +48,7 @@ version = "v0" # version of the block sync protocol to use ### State Sync Metrics -They are defined [here](https://github.com/cometbft/cometbft/blob/main/internal/statesync/metrics.go) and are accessible from the node's metrics endpoint. +They are defined [here](https://github.com/cometbft/cometbft/blob/main/statesync/metrics.go) and are accessible from the node's metrics endpoint. - `statesync_syncing`: Indicates whether a node is currently state syncing.