Skip to content

Conversation

@jonatack
Copy link
Member

@jonatack jonatack commented Jan 2, 2021

This is the help doc commit of #20764 without the rest of the PR or anything new since the 0.21.0 branch-off in order to target giving users a -netinfo help doc for 0.21.

  • to test the new help
$ ./src/bitcoin-cli -netinfo help
  • to see the updated short help
$ ./src/bitcoin-cli -help | grep -A4 netinfo
-netinfo help doc

$ ./src/bitcoin-cli -netinfo help
-netinfo level|"help" 

Returns a network peer connections dashboard with information from the remote server.
Under the hood, -netinfo fetches the data by calling getpeerinfo and getnetworkinfo.
An optional integer argument from 0 to 4 can be passed for different peers listings.
Pass "help" to see this detailed help documentation.
If more than one argument is passed, only the first one is read and parsed.
Suggestion: use with the Linux watch(1) command for a live dashboard; see example below.

Arguments:
1. level (integer 0-4, optional)  Specify the info level of the peers dashboard (default 0):
                                  0 - Connection counts and local addresses
                                  1 - Like 0 but with a peers listing (without address or version columns)
                                  2 - Like 1 but with an address column
                                  3 - Like 1 but with a version column
                                  4 - Like 1 but with both address and version columns
2. help (string "help", optional) Print this help documentation instead of the dashboard.

Result:

* The peers listing in levels 1-4 displays all of the peers sorted by direction and minimum ping time:

  Column   Description
  ------   -----------
  <->      Direction
           "in"  - inbound connections are those initiated by the peer
           "out" - outbound connections are those initiated by us
  type     Type of peer connection
           "full"   - full relay, the default
           "block"  - block relay; like full relay but does not relay transactions or addresses
  net      Network the peer connected through ("ipv4", "ipv6", "onion", "i2p", or "cjdns")
  mping    Minimum observed ping time, in milliseconds (ms)
  ping     Last observed ping time, in milliseconds (ms)
  send     Time since last message sent to the peer, in seconds
  recv     Time since last message received from the peer, in seconds
  txn      Time since last novel transaction received from the peer and accepted into our mempool, in minutes
  blk      Time since last novel block passing initial validity checks received from the peer, in minutes
  age      Duration of connection to the peer, in minutes
  asmap    Mapped AS (Autonomous System) number in the BGP route to the peer, used for diversifying
           peer selection (only displayed if the -asmap config option is set)
  id       Peer index, in increasing order of peer connections since node startup
  address  IP address and port of the peer
  version  Peer version and subversion concatenated, e.g. "70016/Satoshi:21.0.0/"

* The connection counts table displays the number of peers by direction, network, and the totals
  for each, as well as a column for block relay peers.

* The local addresses table lists each local address broadcast by the node, the port, and the score.

Examples:

Connection counts and local addresses only
> bitcoin-cli -netinfo

Compact peers listing
> bitcoin-cli -netinfo 1

Full dashboard
> bitcoin-cli -netinfo 4

Full live dashboard, adjust --interval or --no-title as needed (Linux)
> watch --interval 1 --no-title bitcoin-cli -netinfo 4

See this help
> bitcoin-cli -netinfo help

@DrahtBot DrahtBot added the Docs label Jan 2, 2021
@michaelfolkson
Copy link

Very detailed help, looks great. Followed your above instructions and looked over code.

ACK 2a742a7d63d028e32b584aafdee6bc533d566ade

Copy link
Contributor

@theStack theStack left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ACK 2a742a7d63d028e32b584aafdee6bc533d566ade 📝

Copy link
Contributor

@theStack theStack left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

re-ACK 2fc153dfa8f3f1417f576c4a28bc46b6aedc19c3
(verified that the only change since my previous ACK was replacing "watch" by "watch(1)" in the "Suggestion: ..." string.)

@DrahtBot
Copy link
Contributor

DrahtBot commented Jan 2, 2021

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Conflicts

Reviewers, this pull request conflicts with the following ones:

If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.

@jonatack
Copy link
Member Author

jonatack commented Jan 2, 2021

@theStack you may have seen it already, but #20764 also adds the bip152-hb fields to the -netinfo dashboard that you provided in #19776.

@michaelfolkson
Copy link

Re-ACK 2fc153dfa8f3f1417f576c4a28bc46b6aedc19c3

@jonatack
Copy link
Member Author

jonatack commented Jan 4, 2021

Thanks @theStack and @michaelfolkson for the review ACKs.

Maintainers, this help doc targets 0.21.0, please consider it for backport to 0.21.0rc6.

Copy link
Contributor

@RiccardoMasutti RiccardoMasutti left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ACK 2fc153d

@jonatack
Copy link
Member Author

jonatack commented Jan 5, 2021

Thanks for the reviews!

git diff 2fc153d 6f2c4fd

diff --git a/src/bitcoin-cli.cpp b/src/bitcoin-cli.cpp
index 7f46cca5bb..94043a6b45 100644
--- a/src/bitcoin-cli.cpp
+++ b/src/bitcoin-cli.cpp
@@ -353,7 +353,7 @@ private:
     const UniValue NetinfoHelp()
     {
         return std::string{
-            "-netinfo level \"help\" \n\n"
+            "-netinfo level|\"help\" \n\n"
             "Returns a network peer connections dashboard with information from the remote server.\n"
             "Under the hood, -netinfo fetches the data by calling getpeerinfo and getnetworkinfo.\n"
             "An optional integer argument from 0 to 4 can be passed for different peers listings.\n"
@@ -402,7 +402,7 @@ private:
             "Full dashboard\n"
             "> bitcoin-cli -netinfo 4\n\n"
             "Full live dashboard, adjust --interval or --no-title as needed (Linux)\n"
-            "> watch --interval 1 --no-title ./src/bitcoin-cli -netinfo 4\n\n"
+            "> watch --interval 1 --no-title bitcoin-cli -netinfo 4\n\n"
             "See this help\n"
             "> bitcoin-cli -netinfo help\n"};
     }
@@ -420,6 +420,8 @@ public:
                 m_details_level = n;
             } else if (args.at(0) == "help") {
                 m_is_help_requested = true;
+            } else {
+                throw std::runtime_error(strprintf("invalid -netinfo argument: %s", args.at(0)));
             }

Updates:

  1. help begins with -netinfo level|"help"

  2. raise on invalid arg (ignores any args after the first one)

$ ./src/bitcoin-cli -netinfo he1
error: invalid -netinfo argument: he1
$ ./src/bitcoin-cli -netinfo ho ho ho
error: invalid -netinfo argument: ho
  1. make the last example like the other ones (just noticed this)
-            "> watch --interval 1 --no-title ./src/bitcoin-cli -netinfo 4\n\n"
+            "> watch --interval 1 --no-title bitcoin-cli -netinfo 4\n\n"

and drop no longer needed sort description header to save screen space
@laanwj
Copy link
Member

laanwj commented Jan 6, 2021

ACK 6f2c4fd

@laanwj laanwj merged commit 3b6d1b6 into bitcoin:master Jan 6, 2021
sidhujag pushed a commit to syscoin/syscoin that referenced this pull request Jan 6, 2021
6f2c4fd netinfo: add user help documentation (Jon Atack)

Pull request description:

  This is the help doc commit of bitcoin#20764 without the rest of the PR or anything new since the 0.21.0 branch-off in order to target giving users a -netinfo help doc for 0.21.

  - to test the new help
  ```
  $ ./src/bitcoin-cli -netinfo help
  ```
  - to see the updated short help
  ```
  $ ./src/bitcoin-cli -help | grep -A4 netinfo
  ```

  <details><summary><code>-netinfo</code> help doc</summary><p>

  ```
  $ ./src/bitcoin-cli -netinfo help
  -netinfo level "help"

  Returns a network peer connections dashboard with information from the remote server.
  Under the hood, -netinfo fetches the data by calling getpeerinfo and getnetworkinfo.
  An optional integer argument from 0 to 4 can be passed for different peers listings.
  Pass "help" to see this detailed help documentation.
  If more than one argument is passed, only the first one is read and parsed.
  Suggestion: use with the Linux watch(1) command for a live dashboard; see example below.

  Arguments:
  1. level (integer 0-4, optional)  Specify the info level of the peers dashboard (default 0):
                                    0 - Connection counts and local addresses
                                    1 - Like 0 but with a peers listing (without address or version columns)
                                    2 - Like 1 but with an address column
                                    3 - Like 1 but with a version column
                                    4 - Like 1 but with both address and version columns
  2. help (string "help", optional) Print this help documentation instead of the dashboard.

  Result:

  * The peers listing in levels 1-4 displays all of the peers sorted by direction and minimum ping time:

    Column   Description
    ------   -----------
    <->      Direction
             "in"  - inbound connections are those initiated by the peer
             "out" - outbound connections are those initiated by us
    type     Type of peer connection
             "full"   - full relay, the default
             "block"  - block relay; like full relay but does not relay transactions or addresses
    net      Network the peer connected through ("ipv4", "ipv6", "onion", "i2p", or "cjdns")
    mping    Minimum observed ping time, in milliseconds (ms)
    ping     Last observed ping time, in milliseconds (ms)
    send     Time since last message sent to the peer, in seconds
    recv     Time since last message received from the peer, in seconds
    txn      Time since last novel transaction received from the peer and accepted into our mempool, in minutes
    blk      Time since last novel block passing initial validity checks received from the peer, in minutes
    age      Duration of connection to the peer, in minutes
    asmap    Mapped AS (Autonomous System) number in the BGP route to the peer, used for diversifying
             peer selection (only displayed if the -asmap config option is set)
    id       Peer index, in increasing order of peer connections since node startup
    address  IP address and port of the peer
    version  Peer version and subversion concatenated, e.g. "70016/Satoshi:21.0.0/"

  * The connection counts table displays the number of peers by direction, network, and the totals
    for each, as well as a column for block relay peers.

  * The local addresses table lists each local address broadcast by the node, the port, and the score.

  Examples:

  Connection counts and local addresses only
  > bitcoin-cli -netinfo

  Compact peers listing
  > bitcoin-cli -netinfo 1

  Full dashboard
  > bitcoin-cli -netinfo 4

  Full live dashboard, adjust --interval or --no-title as needed (Linux)
  > watch --interval 1 --no-title ./src/bitcoin-cli -netinfo 4

  See this help
  > bitcoin-cli -netinfo help

  ```
  </p></details>

ACKs for top commit:
  laanwj:
    ACK 6f2c4fd

Tree-SHA512: dd49b1ce65546dacfb8ba9f9d57de0eae55560fd05533cf26c0b5d6ec65bf1de789c3287e90a0e2f47707532fab2fe62919a4192a7ffd58ac8eec18293e9aaeb
@jonatack jonatack deleted the netinfo-help-doc branch January 6, 2021 16:34
@luke-jr
Copy link
Member

luke-jr commented Jan 6, 2021

I wonder if this should document that the interface is not stable, should be expected to change regularly, and not scraped?

@jonatack
Copy link
Member Author

jonatack commented Jan 6, 2021

I thought about it, but since it's a client-side-only CLI, ISTM it is by definition intended for use by humans (some reviewers described it as "getpeerinfo for humans") and software clients should depend on getpeerinfo and getnetworkinfo instead, which are subject to API stability constraints.

@jonatack
Copy link
Member Author

jonatack commented Jan 6, 2021

If we think it's worth adding, we can do it in #20764 which is the next step.

@jonatack
Copy link
Member Author

jonatack commented Jan 7, 2021

I wonder if this should document that the interface is not stable, should be expected to change regularly, and not scraped?

Discussed on IRC today at http://www.erisian.com.au/bitcoin-core-dev/log-2021-01-07.html#l-99. Will update #20764 to document the interface is expected to change regularly.

Edit: done in #20877.

@bitcoin bitcoin locked as resolved and limited conversation to collaborators Aug 16, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

7 participants