Skip to content

Commit c2184f0

Browse files
0x009922WRRicht3ra-zorina
authored
docs: update status/metrics/peers endpoints + reference rc.2.0 (#520)
Co-authored-by: William Richter <[email protected]> Co-authored-by: quacumque <[email protected]> Co-authored-by: Alexandra Zorina <[email protected]>
1 parent 13876fc commit c2184f0

File tree

4 files changed

+157
-122
lines changed

4 files changed

+157
-122
lines changed

‎etc/meta.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
export const IROHA_RC_1 = 'v2.0.0-rc.1.0'
1+
export const IROHA_REV = 'v2.0.0-rc.2.0'
22

33
/**
44
* hyperledger-iroha/iroha-javascript#iroha2 (rc13)

‎etc/snippet-sources.ts‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import type { SnippetSourceDefinition } from './types'
2-
import { IROHA_JAVA_REV_DEV, IROHA_JS_REV, IROHA_RC_1 } from './meta'
2+
import { IROHA_JAVA_REV_DEV, IROHA_JS_REV, IROHA_REV } from './meta'
33
import { render as renderDataModelSchema } from './schema'
44

55
// *****
@@ -102,11 +102,11 @@ const javascriptSnippets = [
102102

103103
export default [
104104
{
105-
src: `https://raw.githubusercontent.com/hyperledger-iroha/iroha/${IROHA_RC_1}/MAINTAINERS.md`,
105+
src: `https://raw.githubusercontent.com/hyperledger-iroha/iroha/${IROHA_REV}/MAINTAINERS.md`,
106106
filename: 'iroha-maintainers.md',
107107
},
108108
{
109-
src: `https://raw.githubusercontent.com/hyperledger-iroha/iroha/${IROHA_RC_1}/docs/source/references/schema.json`,
109+
src: `https://raw.githubusercontent.com/hyperledger-iroha/iroha/${IROHA_REV}/docs/source/references/schema.json`,
110110
filename: `data-model-schema.md`,
111111
transform: (source) => {
112112
return renderDataModelSchema(JSON.parse(source))
@@ -116,16 +116,16 @@ export default [
116116
src: './src/example_code/lorem.rs',
117117
},
118118
{
119-
src: `https://raw.githubusercontent.com/hyperledger-iroha/iroha/${IROHA_RC_1}/docs/source/references/client.template.toml`,
119+
src: `https://raw.githubusercontent.com/hyperledger-iroha/iroha/${IROHA_REV}/docs/source/references/client.template.toml`,
120120
},
121121
{
122-
src: `https://raw.githubusercontent.com/hyperledger-iroha/iroha/${IROHA_RC_1}/docs/source/references/peer.template.toml`,
122+
src: `https://raw.githubusercontent.com/hyperledger-iroha/iroha/${IROHA_REV}/docs/source/references/peer.template.toml`,
123123
},
124124
{
125-
src: `https://raw.githubusercontent.com/hyperledger-iroha/iroha/${IROHA_RC_1}/defaults/genesis.json`,
125+
src: `https://raw.githubusercontent.com/hyperledger-iroha/iroha/${IROHA_REV}/defaults/genesis.json`,
126126
},
127127
{
128-
src: `https://raw.githubusercontent.com/hyperledger-iroha/iroha/${IROHA_RC_1}/crates/iroha/examples/tutorial.rs`,
128+
src: `https://raw.githubusercontent.com/hyperledger-iroha/iroha/${IROHA_REV}/crates/iroha/examples/tutorial.rs`,
129129
filename: 'tutorial-snippets.rs',
130130
},
131131

‎src/guide/advanced/metrics.md‎

Lines changed: 65 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@ The progress on the configuration reference can be tracked in the following GitH
2121

2222
After the above is configured, you can use the IP address set in the `"TORII_TELEMETRY_URL"` variable to access the metrics data from within a running Iroha instance.
2323

24+
<!-- FIXME: irrelevant information about configuration above -->
25+
2426
**Example**:
2527

2628
```bash
@@ -30,19 +32,67 @@ $ curl http://127.0.0.1:8180/metrics
3032
This returns a result similar to the following:
3133

3234
```bash
33-
# HELP blocks_height Total number of blocks in chain
34-
# TYPE blocks_height gauge
35-
blocks_height 135543
36-
# HELP peers_number Total number peers to send transactions and request proposals
37-
# TYPE peers_number gauge
38-
peers_number 7
39-
# HELP number_of_domains Total number of domains in WSV
40-
# TYPE number_of_domains gauge
41-
number_of_domains 14
42-
# HELP total_number_of_transactions Total number of transactions in blockchain
43-
# TYPE total_number_of_transactions gauge
44-
total_number_of_transactions 216499
45-
# HELP number_of_signatures_in_last_block Number of signatures in last block
46-
# TYPE number_of_signatures_in_last_block gauge
47-
number_of_signatures_in_last_block 5
35+
# HELP accounts User accounts registered at this time
36+
# TYPE accounts gauge
37+
accounts{domain="garden_of_live_flowers"} 1
38+
accounts{domain="genesis"} 1
39+
accounts{domain="wonderland"} 2
40+
# HELP block_height Current block height
41+
# TYPE block_height counter
42+
block_height 2
43+
# HELP block_height_non_empty Current count of non-empty blocks
44+
# TYPE block_height_non_empty counter
45+
block_height_non_empty 1
46+
# HELP commit_time_ms Average block commit time on this peer
47+
# TYPE commit_time_ms histogram
48+
commit_time_ms_bucket{le="100"} 2
49+
commit_time_ms_bucket{le="400"} 2
50+
commit_time_ms_bucket{le="1600"} 2
51+
commit_time_ms_bucket{le="6400"} 2
52+
commit_time_ms_bucket{le="25600"} 2
53+
commit_time_ms_bucket{le="+Inf"} 2
54+
commit_time_ms_sum 13
55+
commit_time_ms_count 2
56+
# HELP connected_peers Total number of currently connected peers
57+
# TYPE connected_peers gauge
58+
connected_peers 3
59+
# HELP domains Total number of domains
60+
# TYPE domains gauge
61+
domains 3
62+
# HELP dropped_messages Sumeragi dropped messages
63+
# TYPE dropped_messages counter
64+
dropped_messages 0
65+
# HELP last_commit_time_ms Time (since block creation) it took for the latest block to be committed by this peer
66+
# TYPE last_commit_time_ms gauge
67+
last_commit_time_ms 13
68+
# HELP queue_size Number of the transactions in the queue
69+
# TYPE queue_size gauge
70+
queue_size 0
71+
# HELP tx_amount average amount involved in a transaction on this peer
72+
# TYPE tx_amount histogram
73+
tx_amount_bucket{le="-1000000000"} 0
74+
tx_amount_bucket{le="-10000000"} 0
75+
tx_amount_bucket{le="-100000"} 0
76+
tx_amount_bucket{le="-1000"} 0
77+
tx_amount_bucket{le="-10"} 0
78+
tx_amount_bucket{le="0"} 0
79+
tx_amount_bucket{le="10"} 0
80+
tx_amount_bucket{le="1000"} 2
81+
tx_amount_bucket{le="100000"} 2
82+
tx_amount_bucket{le="10000000"} 2
83+
tx_amount_bucket{le="1000000000"} 2
84+
tx_amount_bucket{le="+Inf"} 2
85+
tx_amount_sum 57
86+
tx_amount_count 2
87+
# HELP txs Transactions committed
88+
# TYPE txs counter
89+
txs{type="accepted"} 4
90+
txs{type="rejected"} 0
91+
txs{type="total"} 4
92+
# HELP uptime_since_genesis_ms Network up-time, from creation of the genesis block
93+
# TYPE uptime_since_genesis_ms gauge
94+
uptime_since_genesis_ms 529270
95+
# HELP view_changes Number of view changes in the current round
96+
# TYPE view_changes gauge
97+
view_changes 0
4898
```

‎src/reference/torii-endpoints.md‎

Lines changed: 84 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,6 @@ To establish two-way communication with the `TORII` endpoints, the following add
4343
This address is the same as the `TORII_API_URL` address in the `configs/client_cli/config.json` client configuration file.
4444
- `TELEMETRY_URL` — connects to the [Prometheus](https://prometheus.io/) endpoint address that is used as a [metrics](../guide/advanced/metrics.md) tool to monitor the network performance.
4545
46-
4746
-->
4847

4948
[[toc]]
@@ -252,6 +251,33 @@ request, after which the server sends an
252251
Healthy
253252
```
254253

254+
## Peers
255+
256+
- **Protocol**: `HTTP`
257+
- **Method**: `GET`
258+
- **Encoding**: `JSON`
259+
- **Endpoint**: `/peers`
260+
261+
#### Requests
262+
263+
A `GET` request to the endpoint.
264+
265+
#### Responses
266+
267+
| Code | Response |
268+
| ---- | -------------------- |
269+
| 200 | List of online peers |
270+
271+
**Example:**
272+
273+
```json
274+
[
275+
"ed01204EE2FCD53E1730AF142D1E23951198678295047F9314B4006B0CB61850B1DB10@irohad2:1339",
276+
"ed01209897952D14BDFAEA780087C38FF3EB800CB20B882748FC95A575ADB9CD2CB21D@irohad1:1338",
277+
"ed0120CACF3A84B8DC8710CE9D6B968EE95EC7EE4C93C85858F026F3B4417F569592CE@irohad3:1340"
278+
]
279+
```
280+
255281
## Query
256282

257283
- **Protocol**: `HTTP`
@@ -376,42 +402,65 @@ This operation requires the Iroha 2 network to be established with the
376402
```bash
377403
# HELP accounts User accounts registered at this time
378404
# TYPE accounts gauge
405+
accounts{domain="garden_of_live_flowers"} 1
379406
accounts{domain="genesis"} 1
380-
accounts{domain="wonderland"} 1
407+
accounts{domain="wonderland"} 2
381408
# HELP block_height Current block height
382409
# TYPE block_height counter
383-
block_height 1
410+
block_height 2
411+
# HELP block_height_non_empty Current count of non-empty blocks
412+
# TYPE block_height_non_empty counter
413+
block_height_non_empty 1
414+
# HELP commit_time_ms Average block commit time on this peer
415+
# TYPE commit_time_ms histogram
416+
commit_time_ms_bucket{le="100"} 2
417+
commit_time_ms_bucket{le="400"} 2
418+
commit_time_ms_bucket{le="1600"} 2
419+
commit_time_ms_bucket{le="6400"} 2
420+
commit_time_ms_bucket{le="25600"} 2
421+
commit_time_ms_bucket{le="+Inf"} 2
422+
commit_time_ms_sum 13
423+
commit_time_ms_count 2
384424
# HELP connected_peers Total number of currently connected peers
385425
# TYPE connected_peers gauge
386-
connected_peers 0
426+
connected_peers 3
387427
# HELP domains Total number of domains
388428
# TYPE domains gauge
389-
domains 2
429+
domains 3
430+
# HELP dropped_messages Sumeragi dropped messages
431+
# TYPE dropped_messages counter
432+
dropped_messages 0
433+
# HELP last_commit_time_ms Time (since block creation) it took for the latest block to be committed by this peer
434+
# TYPE last_commit_time_ms gauge
435+
last_commit_time_ms 13
436+
# HELP queue_size Number of the transactions in the queue
437+
# TYPE queue_size gauge
438+
queue_size 0
390439
# HELP tx_amount average amount involved in a transaction on this peer
391440
# TYPE tx_amount histogram
392-
tx_amount_bucket{le="0.005"} 0
393-
tx_amount_bucket{le="0.01"} 0
394-
tx_amount_bucket{le="0.025"} 0
395-
tx_amount_bucket{le="0.05"} 0
396-
tx_amount_bucket{le="0.1"} 0
397-
tx_amount_bucket{le="0.25"} 0
398-
tx_amount_bucket{le="0.5"} 0
399-
tx_amount_bucket{le="1"} 0
400-
tx_amount_bucket{le="2.5"} 0
401-
tx_amount_bucket{le="5"} 0
441+
tx_amount_bucket{le="-1000000000"} 0
442+
tx_amount_bucket{le="-10000000"} 0
443+
tx_amount_bucket{le="-100000"} 0
444+
tx_amount_bucket{le="-1000"} 0
445+
tx_amount_bucket{le="-10"} 0
446+
tx_amount_bucket{le="0"} 0
402447
tx_amount_bucket{le="10"} 0
448+
tx_amount_bucket{le="1000"} 2
449+
tx_amount_bucket{le="100000"} 2
450+
tx_amount_bucket{le="10000000"} 2
451+
tx_amount_bucket{le="1000000000"} 2
403452
tx_amount_bucket{le="+Inf"} 2
404-
tx_amount_sum 26
453+
tx_amount_sum 57
405454
tx_amount_count 2
406455
# HELP txs Transactions committed
407456
# TYPE txs counter
408-
txs{type="accepted"} 1
457+
txs{type="accepted"} 4
409458
txs{type="rejected"} 0
410-
txs{type="total"} 1
459+
txs{type="total"} 4
411460
# HELP uptime_since_genesis_ms Network up-time, from creation of the genesis block
412461
# TYPE uptime_since_genesis_ms gauge
413-
uptime_since_genesis_ms 54572974
414-
# HELP view_changes Number of view_changes in the current round
462+
uptime_since_genesis_ms 529270
463+
# HELP view_changes Number of view changes in the current round
415464
# TYPE view_changes gauge
416465
view_changes 0
417466
```
@@ -424,34 +473,6 @@ To learn more about metrics, see [Metrics](../guide/advanced/metrics.md).
424473

425474
:::
426475

427-
## Telemetry / Peers <Badge text="feature: telemetry" type=tip />
428-
429-
- **Protocol**: `HTTP`
430-
- **Method**: `GET`
431-
- **Encoding**: `JSON`
432-
- **Endpoint**: `/peers`
433-
434-
#### Requests
435-
436-
A `GET` request to the endpoint.
437-
438-
#### Responses
439-
440-
| Code | Response |
441-
| ---- | -------------------- |
442-
| 200 | List of online peers |
443-
444-
**Example:**
445-
446-
```json
447-
[
448-
{
449-
"address": "0.0.0.0:8081",
450-
"id": "ed0120B23E14F659B91736AAB980B6ADDCE4B1DB8A138AB0267E049C082A744471714E"
451-
}
452-
]
453-
```
454-
455476
## Telemetry / Status <Badge text="feature: telemetry" type=tip />
456477

457478
::: info
@@ -485,49 +506,9 @@ is used by default.
485506

486507
#### Responses
487508

488-
| Code | Response | Description |
489-
| :--: | ------------ | ------------------------------------------------------------------------------------------ |
490-
| 200 | Iroha Status | Returns the Iroha network status report encoded as specified in the header of the request. |
491-
492-
The response body has the following structure:
493-
494-
`200 OK` reports status as JSON:
495-
496-
::: details Sample response
497-
498-
```json5
499-
// Note: while this snippet is JSON5 (for better readability),
500-
// the actual response is JSON
501-
{
502-
/**
503-
* Number of connected peers, except for the reporting peer itself
504-
*/
505-
peers: 3,
506-
/**
507-
* Number of committed blocks (block height)
508-
*/
509-
blocks: 1,
510-
/**
511-
* Total number of accepted transactions
512-
*/
513-
txs_accepted: 3,
514-
/**
515-
* Total number of rejected transactions
516-
*/
517-
txs_rejected: 0,
518-
/**
519-
* Uptime with nanosecond precision since creation of the genesis block
520-
*/
521-
uptime: {
522-
secs: 5,
523-
nanos: 937000000,
524-
},
525-
/**
526-
* Number of view changes in the current round
527-
*/
528-
view_changes: 0,
529-
}
530-
```
509+
| Code | Response | Body | Description |
510+
| :--: | -------- | -------- | ------------------------------------------------------------------------------------------ |
511+
| 200 | OK | [`Status`](/reference/data-model-schema#status) | Returns the Iroha network status report encoded as specified in the header of the request. |
531512

532513
::: details Examples
533514

@@ -539,7 +520,9 @@ The following examples represent the same data:
539520
{
540521
"peers": 4,
541522
"blocks": 5,
542-
"txs_accepted": 31,
523+
"blocks_non_empty": 3,
524+
"commit_time_ms": 130,
525+
"txs_approved": 31,
543526
"txs_rejected": 3,
544527
"uptime": {
545528
"secs": 5,
@@ -551,7 +534,7 @@ The following examples represent the same data:
551534
```
552535

553536
```[SCALE]
554-
10 14 7C 0C 14 40 7C D9 37 08 48
537+
10 14 0C 09 02 7C 0C 14 40 7C D9 37 08 48
555538
```
556539

557540
:::
@@ -590,7 +573,9 @@ values are only returned in the JSON format.
590573
{
591574
"peers": 4,
592575
"blocks": 5,
593-
"txs_accepted": 31,
576+
"blocks_non_empty": 3,
577+
"commit_time_ms": 130,
578+
"txs_approved": 31,
594579
"txs_rejected": 3,
595580
"uptime": {
596581
"secs": 5,
@@ -634,8 +619,8 @@ This endpoint expects the following data:
634619

635620
#### Responses
636621

637-
| Code | Response | Description |
638-
| :--: | ---------------------------------------- | ---------------------------------------------------------------------------------- |
639-
| 200 | Transaction Accepted | Transaction has been accepted, but is not yet guaranteed to have passed consensus. |
640-
| 400 | Transaction Rejected (Malformed) | Transaction is rejected due to being malformed. |
641-
| 401 | Transaction Rejected (Improperly signed) | Transaction is rejected due to being improperly signed. |
622+
| Code | Response | Description |
623+
| :--: | ------------------------------------ | ---------------------------------------------------------------------------------- |
624+
| 200 | OK, Transaction Accepted | The transaction has been accepted, but is not yet guaranteed to have passed consensus. |
625+
| 400 | Bad Request, Transaction Rejected | The transaction has been rejected due to being malformed. |
626+
| 500 | Internal Error, Transaction Rejected | Iroha could not accept the transaction due to e.g. its queue being full. |

0 commit comments

Comments
 (0)