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

Merge pull request #1588 from XRPLF/server_info_issue_1446

Browse Source 
Update server_info/state w/ reporting mode details
This commit is contained in:
Rome Reginelli
2022-11-23 13:23:43 -08:00
committed by GitHub
parent d0fcf60de2 45f6ea49a8
commit b3baec9187
6 changed files with 133 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
content/_snippets/etl-source-object.md Normal file
View File

@@ -0,0 +1,13 @@
### ETL Source Object
<!-- This nested object definition is identical across server_state and server_info -->
On a reporting mode server, each member of the `etl_sources` field is an object with the following fields:
| Field | Type | Description |
|-----------------------------|---------|-------------|
| `connected` | Boolean | If `true`, the reporting mode server is connected to this P2P mode server. If `false`, the server is not connected. This could be due to misconfiguration, a network outage, or it could mean that the P2P mode server is down. |
| `grpc_port` | String | The port number on the P2P mode server where this reporting mode server is configured to connect and retrieve ledger data via gRPC. |
| `ip` | String | The IP address (IPv4 or IPv6) of the P2P mode server. |
| `last_message_arrival_time` | String | An ISO 8601 timestamp indicating the most recent time the reporting mode server received a message from this P2P server. |
| `validated_ledgers_range` | String | The range of validated ledger versions this P2P mode server reports that it has available, in the same format as `complete_ledgers`. |
| `websocket_port` | String | The port number on the P2P server where this reporting mode server is configured to forward WebSocket requests that cannot be served directly from reporting mode. |

2
content/concepts/xrpl-servers/rippled-server-modes.md
View File

@@ -70,7 +70,7 @@ For more information about running a validator, see [Run `rippled` as a Validato
## Reporting Mode
[New in: rippled 1.7.0][]
Reporting mode is specialized mode for serving API requests more efficiently. In this mode, the server gets the latest validated ledger data over [gRPC](https://xrpl.org/configure-grpc.html) from a separate `rippled` server running in P2P Mode, then loads that data into a relational database ([PostgreSQL](https://www.postgresql.org/)). The reporting mode server does not directly participate in the peer-to-peer network, though it can forward requests such as transaction submission to the P2P Mode server it uses.
Reporting mode is specialized mode for serving API requests more efficiently. In this mode, the server gets the latest validated ledger data over [gRPC](configure-grpc.html) from a separate `rippled` server running in P2P Mode, then loads that data into a relational database ([PostgreSQL](https://www.postgresql.org/)). The reporting mode server does not directly participate in the peer-to-peer network, though it can forward requests such as transaction submission to the P2P Mode server it uses.
Multiple reporting mode servers can share access to a PostgreSQL database and [Apache Cassandra](https://cassandra.apache.org/) cluster to serve a large amount of history without each server needing a redundant copy of all the data. Reporting mode servers provide this data through the same [`rippled` APIs](http-websocket-apis.html) with some slight changes to accommodate for the differences in how they store the underlying data.

189
content/references/http-websocket-apis/public-api-methods/server-info-methods/server_info.md
View File

@@ -61,56 +61,57 @@ An example of a successful response:
"id": 1,
"result": {
"info": {
"build_version": "1.7.2",
"complete_ledgers": "64572720-65887227",
"hostid": "LARD",
"build_version": "1.9.4",
"complete_ledgers": "32570-75801736",
"hostid": "ARMY",
"initial_sync_duration_us": "273518294",
"io_latency_ms": 1,
"jq_trans_overflow": "0",
"jq_trans_overflow": "2282",
"last_close": {
"converge_time_s": 3.004,
"proposers": 41
"converge_time_s": 3.002,
"proposers": 35
},
"load_factor": 512.578125,
"load_factor_server": 1,
"peer_disconnects": "365016",
"peer_disconnects_resources": "336",
"peers": 211,
"pubkey_node": "n9MozjnGB3tpULewtTsVtuudg5JqYFyV3QFdAtVLzJaxHcBaxuXD",
"load_factor": 1,
"network_id": 0,
"peer_disconnects": "3194",
"peer_disconnects_resources": "3",
"peers": 20,
"pubkey_node": "n9KKBZvwPZ95rQi4BP3an1MRctTyavYkZiLpQwasmFYTE6RYdeX3",
"server_state": "full",
"server_state_duration_us": "3589068181859",
"server_state_duration_us": "69205850392",
"state_accounting": {
"connected": {
"duration_us": "301410595",
"transitions": 2
"duration_us": "141058919",
"transitions": "7"
},
"disconnected": {
"duration_us": "1207534",
"transitions": 2
"duration_us": "514136273",
"transitions": "3"
},
"full": {
"duration_us": "3589270527034",
"transitions": 2
"duration_us": "4360230140761",
"transitions": "32"
},
"syncing": {
"duration_us": "6182323",
"transitions": 2
"duration_us": "50606510",
"transitions": "30"
},
"tracking": {
"duration_us": "43",
"transitions": 2
"duration_us": "40245486",
"transitions": "34"
}
},
"time": "2021-Aug-24 20:46:22.194299 UTC",
"uptime": 3589579,
"time": "2022-Nov-16 21:50:22.711679 UTC",
"uptime": 4360976,
"validated_ledger": {
"age": 3,
"age": 1,
"base_fee_xrp": 0.00001,
"hash": "F00F0E590242702B895BE378B6A6D365C094A047CFC8B11DD323D16F81CC67A5",
"reserve_base_xrp": 20,
"reserve_inc_xrp": 5,
"seq": 65887227
"hash": "3147A41F5F013209581FCDCBBB7A87A4F01EF6842963E13B2B14C8565E00A22B",
"reserve_base_xrp": 10,
"reserve_inc_xrp": 2,
"seq": 75801736
},
"validation_quorum": 33
"validation_quorum": 28
}
},
"status": "success",
@@ -126,55 +127,57 @@ An example of a successful response:
{
"result": {
"info": {
"build_version": "1.7.2",
"complete_ledgers": "64735538-65886965",
"hostid": "TOLL",
"build_version": "1.9.4",
"complete_ledgers": "32570-75801747",
"hostid": "ABET",
"initial_sync_duration_us": "566800928",
"io_latency_ms": 1,
"jq_trans_overflow": "3",
"jq_trans_overflow": "47035",
"last_close": {
"converge_time_s": 3,
"proposers": 41
"proposers": 35
},
"load_factor": 1,
"peer_disconnects": "467400",
"peer_disconnects_resources": "16316",
"peers": 85,
"pubkey_node": "n9Mdk7abYaVvded5zic9oDEY3NULv9RmeJ9Z5hgjXX1ycZqAGhTn",
"network_id": 0,
"peer_disconnects": "542",
"peer_disconnects_resources": "1",
"peers": 24,
"pubkey_node": "n9LvjJyaYHBWUvQUat632RrnpS7UHVLW2tLUGXSZ2yXouh4goDHX",
"server_state": "full",
"server_state_duration_us": "627203282776",
"server_state_duration_us": "3612238603",
"state_accounting": {
"connected": {
"duration_us": "600242389",
"transitions": 40
"duration_us": "125498126",
"transitions": "67"
},
"disconnected": {
"duration_us": "112927",
"transitions": 1
"duration_us": "473415516",
"transitions": "2"
},
"full": {
"duration_us": "3591757226163",
"transitions": 46
"duration_us": "4365855930299",
"transitions": "337"
},
"syncing": {
"duration_us": "5304456",
"transitions": 7
"duration_us": "1383837914",
"transitions": "311"
},
"tracking": {
"duration_us": "13989631",
"transitions": 46
"duration_us": "518995710",
"transitions": "374"
}
},
"time": "2021-Aug-24 20:29:53.291350 UTC",
"uptime": 3592376,
"time": "2022-Nov-16 21:51:03.737667 UTC",
"uptime": 4368357,
"validated_ledger": {
"age": 2,
"age": 1,
"base_fee_xrp": 0.00001,
"hash": "B79D223A27F4EC214C9BA85665B12EE76C1EE2CB887BBCBAFB6484355C43FEFA",
"reserve_base_xrp": 20,
"reserve_inc_xrp": 5,
"seq": 65886965
"hash": "D54A94D5EF620DC212EAB5958D592EC641FC94ED92146477A04DCE5B006DFF05",
"reserve_base_xrp": 10,
"reserve_inc_xrp": 2,
"seq": 75801747
},
"validation_quorum": 33
"validation_quorum": 28
},
"status": "success"
}
@@ -190,55 +193,57 @@ Loading: "/etc/opt/ripple/rippled.cfg"
{
"result": {
"info": {
"build_version": "1.7.2",
"complete_ledgers": "64735538-65886965",
"hostid": "TOLL",
"build_version": "1.9.4",
"complete_ledgers": "32570-75801747",
"hostid": "ABET",
"initial_sync_duration_us": "566800928",
"io_latency_ms": 1,
"jq_trans_overflow": "3",
"jq_trans_overflow": "47035",
"last_close": {
"converge_time_s": 3,
"proposers": 41
"proposers": 35
},
"load_factor": 1,
"peer_disconnects": "467400",
"peer_disconnects_resources": "16316",
"peers": 85,
"pubkey_node": "n9Mdk7abYaVvded5zic9oDEY3NULv9RmeJ9Z5hgjXX1ycZqAGhTn",
"network_id": 0,
"peer_disconnects": "542",
"peer_disconnects_resources": "1",
"peers": 24,
"pubkey_node": "n9LvjJyaYHBWUvQUat632RrnpS7UHVLW2tLUGXSZ2yXouh4goDHX",
"server_state": "full",
"server_state_duration_us": "627203282776",
"server_state_duration_us": "3612238603",
"state_accounting": {
"connected": {
"duration_us": "600242389",
"transitions": 40
"duration_us": "125498126",
"transitions": "67"
},
"disconnected": {
"duration_us": "112927",
"transitions": 1
"duration_us": "473415516",
"transitions": "2"
},
"full": {
"duration_us": "3591757226163",
"transitions": 46
"duration_us": "4365855930299",
"transitions": "337"
},
"syncing": {
"duration_us": "5304456",
"transitions": 7
"duration_us": "1383837914",
"transitions": "311"
},
"tracking": {
"duration_us": "13989631",
"transitions": 46
"duration_us": "518995710",
"transitions": "374"
}
},
"time": "2021-Aug-24 20:29:53.291350 UTC",
"uptime": 3592376,
"time": "2022-Nov-16 21:51:03.737667 UTC",
"uptime": 4368357,
"validated_ledger": {
"age": 2,
"age": 1,
"base_fee_xrp": 0.00001,
"hash": "B79D223A27F4EC214C9BA85665B12EE76C1EE2CB887BBCBAFB6484355C43FEFA",
"reserve_base_xrp": 20,
"reserve_inc_xrp": 5,
"seq": 65886965
"hash": "D54A94D5EF620DC212EAB5958D592EC641FC94ED92146477A04DCE5B006DFF05",
"reserve_base_xrp": 10,
"reserve_inc_xrp": 2,
"seq": 75801747
},
"validation_quorum": 33
"validation_quorum": 28
},
"status": "success"
}
@@ -273,14 +278,18 @@ The `info` object may have some arrangement of the following fields:
| `load_factor_fee_escalation` | Number | _(May be omitted)_ The current multiplier to the [transaction cost][] that a transaction must pay to get into the open ledger. [New in: rippled 0.32.0][] |
| `load_factor_fee_queue` | Number | _(May be omitted)_ The current multiplier to the [transaction cost][] that a transaction must pay to get into the queue, if the queue is full. [New in: rippled 0.32.0][] |
| `load_factor_server` | Number | _(May be omitted)_ The load factor the server is enforcing, not including the [open ledger cost](transaction-cost.html#open-ledger-cost). [New in: rippled 0.33.0][] |
| `peers` | Number | How many other `rippled` servers this one is currently connected to. |
| `peers` | Number | _(Omitted by [reporting mode][Reporting mode] servers)_ How many other `rippled` servers this one is currently connected to. |
| `pubkey_node` | String | Public key used to verify this server for peer-to-peer communications. This [_node key pair_](peer-protocol.html#node-key-pair) is automatically generated by the server the first time it starts up. (If deleted, the server can create a new pair of keys.) You can set a persistent value in the config file using the `[node_seed]` config option, which is useful for [clustering](clustering.html). |
| `pubkey_validator` | String | _(Admin only)_ Public key used by this node to sign ledger validations. This _validation key pair_ is derived from the `[validator_token]` or `[validation_seed]` config field. |
| `reporting` | Object | _([Reporting mode](rippled-server-modes.html) servers only)_ Information about this server's reporting-mode specific configurations. |
| `reporting.etl_sources` | Array | _([Reporting mode](rippled-server-modes.html) servers only)_ A list of P2P-mode servers this reporting mode is retrieving data from. Each entry in this array is an [ETL Source object](#etl-source-object). |
| `reporting.is_writer` | Boolean | _([Reporting mode](rippled-server-modes.html) servers only)_ If `true`, this server is writing to the external database with ledger data. If `false`, it is not currenty writing, possibly because another reporting mode server is currently populating a shared database, or because it's configured as read-only.|
| `reporting.last_publish_time` | String | _([Reporting mode](rippled-server-modes.html) servers only)_ An ISO 8601 timestamp indicating when this server last published a validated ledger to its [subscription streams](subscribe.html). |
| `server_state` | String | A string indicating to what extent the server is participating in the network. See [Possible Server States](rippled-server-states.html) for more details. |
| `server_state_duration_us` | Number | The number of consecutive microseconds the server has been in the current state. [New in: rippled 1.2.0][] |
| `state_accounting` | Object | A map of various [server states](rippled-server-states.html) with information about the time the server spends in each. This can be useful for tracking the long-term health of your server's connectivity to the network. [New in: rippled 0.30.1][] |
| `state_accounting.*.duration_us` | String | The number of microseconds the server has spent in this state. (This is updated whenever the server transitions into another state.) [New in: rippled 0.30.1][] |
| `state_accounting.*.transitions` | Number | The number of times the server has changed into this state. [New in: rippled 0.30.1][] |
| `state_accounting.*.transitions` | String | The number of times the server has changed into this state. [New in: rippled 0.30.1][] |
| `time` | String | The current time in UTC, according to the server's clock. [Updated in: rippled 1.5.0][] |
| `uptime` | Number | Number of consecutive seconds that the server has been operational. [New in: rippled 0.30.1][] |
| `validated_ledger` | Object | _(May be omitted)_ Information about the most recent fully-validated ledger. If the most recent validated ledger is not available, the response omits this field and includes `closed_ledger` instead. |
@@ -295,6 +304,8 @@ The `info` object may have some arrangement of the following fields:
**Note:** If the `closed_ledger` field is present and has a small `seq` value (less than 8 digits), that indicates `rippled` does not currently have a copy of the validated ledger from the peer-to-peer network. This could mean your server is still syncing. Typically, it takes about 5 minutes to sync with the network, depending on your connection speed and hardware specs.
{% include '_snippets/etl-source-object.md' %}
## Possible Errors
* Any of the [universal error types][].

12
content/references/http-websocket-apis/public-api-methods/server-info-methods/server_state.md
View File

@@ -286,14 +286,18 @@ The `state` object may have some arrangement of the following fields:
| `load_factor_fee_queue` | Number | _(May be omitted)_ The current multiplier to the [transaction cost][] to get into the queue, if the queue is full, in [fee levels][]. [New in: rippled 0.32.0][] |
| `load_factor_fee_reference` | Number | _(May be omitted)_ The [transaction cost][] with no load scaling, in [fee levels][]. [New in: rippled 0.32.0][] |
| `load_factor_server` | Number | _(May be omitted)_ The load factor the server is enforcing, not including the [open ledger cost](transaction-cost.html#open-ledger-cost). [New in: rippled 0.33.0][] |
| `peers` | Number | How many other `rippled` servers this one is currently connected to. |
| `peers` | Number | _(Omitted by [reporting mode][Reporting mode] servers)_ How many other `rippled` servers this one is currently connected to. |
| `pubkey_node` | String | Public key used to verify this server for peer-to-peer communications. This _node key pair_ is automatically generated by the server the first time it starts up. (If deleted, the server can create a new pair of keys.) You can set a persistent value in the config file using the `[node_seed]` config option, which is useful for [clustering](clustering.html). |
| `pubkey_validator` | String | _(Admin only)_ Public key used by this node to sign ledger validations. This _validation key pair_ is derived from the `[validator_token]` or `[validation_seed]` config field. |
| `reporting` | Object | _([Reporting mode][] servers only)_ Information about this server's reporting-mode specific configurations. |
| `reporting.etl_sources` | Array | _([Reporting mode][] servers only)_ A list of P2P-mode servers this reporting mode is retrieving data from. Each entry in this array is an [ETL Source object](#etl-source-object). |
| `reporting.is_writer` | Boolean | _([Reporting mode][] servers only)_ If `true`, this server is writing to the external database with ledger data. If `false`, it is not currenty writing, possibly because another reporting mode server is currently populating a shared database, or because it's configured as read-only. |
| `reporting.last_publish_time` | String | _([Reporting mode][] servers only)_ An ISO 8601 timestamp indicating when this server last saw a new validated ledger from any of its P2P mode sources. |
| `server_state` | String | A string indicating to what extent the server is participating in the network. See [Possible Server States](rippled-server-states.html) for more details. |
| `server_state_duration_us` | Number | The number of consecutive microseconds the server has been in the current state. [New in: rippled 1.2.0][] |
| `state_accounting` | Object | A map of various [server states](rippled-server-states.html) with information about the time the server spends in each. This can be useful for tracking the long-term health of your server's connectivity to the network. [New in: rippled 0.30.1][] |
| `state_accounting.*.duration_us` | String | The number of microseconds the server has spent in this state. (This is updated whenever the server transitions into another state.) [New in: rippled 0.30.1][] |
| `state_accounting.*.transitions` | Number | The number of times the server has changed into this state. [New in: rippled 0.30.1][] |
| `state_accounting.*.transitions` | String | The number of times the server has changed into this state. [New in: rippled 0.30.1][] |
| `time` | String | The current time in UTC, according to the server's clock. [Updated in: rippled 1.5.0][] |
| `uptime` | Number | Number of consecutive seconds that the server has been operational. [New in: rippled 0.30.1][] |
| `validated_ledger` | Object | _(May be omitted)_ Information about the most recent fully-validated ledger. If the most recent validated ledger is not available, the response omits this field and includes `closed_ledger` instead. |
@@ -306,6 +310,10 @@ The `state` object may have some arrangement of the following fields:
| `validation_quorum` | Number | Minimum number of trusted validations required to validate a ledger version. Some circumstances may cause the server to require more validations. |
| `validator_list_expires` | Number | _(Admin only)_ When the current validator list will expire, in [seconds since the Ripple Epoch][], or 0 if the server has yet to load a published validator list. [New in: rippled 0.80.1][] |
[Reporting mode]: rippled-server-modes.html
{% include '_snippets/etl-source-object.md' %}
## Possible Errors

17
content/tutorials/manage-the-rippled-server/configuration/configure-grpc.md
View File

@@ -7,9 +7,9 @@ labels:
---
# Configure gRPC
The `rippled` server has an experimental [gRPC API](https://grpc.io/). Currently, this API provides a subset of the full [`rippled` API](http-websocket-apis.html). You can enable the gRPC API on your server with a new configuration stanza. [New in: rippled 1.5.0][]
The `rippled` server has a limited [gRPC API](https://grpc.io/) which [P2P mode servers](rippled-server-modes.html) can provide. Reporting mode servers use this API to retrieve data about the latest validated ledgers and transactions. You can enable the gRPC API on your server with a new configuration stanza. [New in: rippled 1.5.0][]
**Caution:** gRPC support in `rippled` v1.5.0 is experimental. Configuration settings and API formats are likely to have breaking changes in forthcoming versions.
**Caution:** gRPC support is intended specifically for providing data to reporting mode servers from P2P mode servers. Breaking changes to the gRPC API may occur without warning or it may be removed entirely in future versions of the server.
## Prerequisites
@@ -34,26 +34,23 @@ To enable gRPC on your server, complete the following steps:
- `port` field defines the port the server listens on for gRPC connections from client applications. The recommended port is `50051`.
- `ip` defines which interfaces the server listens on. The value `0.0.0.0` listens on all available network interfaces. To limit connections to the local loopback network (same machine), use `127.0.0.1` instead.
{% include '_snippets/conf-file-location.md' %}<!--_ -->
{% include '_snippets/conf-file-location.md' %}
2. Start (or restart) the `rippled` service.
$ sudo systemctl restart rippled
sudo systemctl restart rippled
## See Also
<!-- TODO: add gRPC quickstart, overview docs here when available -->
- **Concepts:**
- [XRP Ledger Overview](xrp-ledger-overview.html)
- [Software Ecosystem](software-ecosystem.html)
- [Parallel Networks](parallel-networks.html)
- [`rippled` Server Modes](rippled-server-modes.html)
- **Tutorials:**
- [Get Started Using HTTP / WebSocket APIs](get-started-using-http-websocket-apis.html)
- [Reliable Transaction Submission](reliable-transaction-submission.html)
- [Manage the rippled Server](manage-the-rippled-server.html)
- **References:**
- [rippled API Reference](http-websocket-apis.html)
- [Ripple Data API v2](data-api.html)
- [HTTP / WebSocket API Reference](http-websocket-apis.html)
<!--{# common link defs #}-->
{% include '_snippets/rippled-api-links.md' %}