Merge pull request #4160 from marta-lokhova/survey_documentation

Improve survey documentation

Reviewed-by: graydon

Author: latobarita

docs/software/admin.md

@@ -819,6 +819,8 @@ Once the responses are received, the `getsurveyresult` command will return a res
          ],
          "numTotalInboundPeers" : 2,
          "numTotalOutboundPeers" : 0,
+         "maxInboundPeerCount" : 64,
+         "maxOutboundPeerCount" : 8,
          "outboundPeers" : null
       }
    }
@@ -833,7 +835,24 @@ Notable field definitions
 * `badResponseNodes` : List of nodes that sent a malformed response
 * `topology` : Map of nodes to connection information
   * `inboundPeers`/`outboundPeers` : List of connection information by nodes
+    * `bytesRead`: The total number of bytes read from this peer.
+    * `bytesWritten`: The total number of bytes written to this peer.
+    * `duplicateFetchBytesRecv`: The number of bytes received that were duplicate transaction sets and quorum sets.
+    * `duplicateFetchMessageRecv`: The count of duplicate transaction sets and quorum sets received from this peer.
+    * `duplicateFloodBytesRecv`: The number of bytes received that were transactions and SCP votes duplicates.
+    * `duplicateFloodMessageRecv`: The count of duplicate transactions and SCP votes received from this peer.
+    * `messagesRead`: The total number of messages read from this peer.
+    * `messagesWritten`: The total number of messages written to this peer.
+    * `nodeId`: Node's public key.
+    * `secondsConnected`: The total number of seconds this peer has been connected to the surveyed node.
+    * `uniqueFetchBytesRecv`: The number of bytes received that were unique transaction sets and quorum sets.
+    * `uniqueFetchMessageRecv`: The count of unique transaction sets and quorum sets received from this peer.
+    * `uniqueFloodBytesRecv`: The number of bytes received that were unique transactions and SCP votes.
+    * `uniqueFloodMessageRecv`: The count of unique transactions and SCP votes received from this peer.
+    * `version`: stellar-core version.
+
   * `numTotalInboundPeers`/`numTotalOutboundPeers` : The number of total inbound and outbound peers this node is connected to. The response will have a random subset of 25 connected peers per direction (inbound/outbound). These fields tell you if you're missing nodes so you can send another request out to get another random subset of nodes.
+  * `maxInboundPeerCount`/`maxOutboundPeerCount` : The number of total inbound and outbound peers that this node can accept. These fields correspond to stellar-core configurations `MAX_ADDITIONAL_PEER_CONNECTIONS` and `TARGET_PEER_CONNECTIONS`, respectively.
 
 ### Quorum Health
 

scripts/README.md

@@ -19,7 +19,7 @@ This folder is for storing any scripts that may be helpful for using stellar-cor
         - `-sr SURVEYRESULT`, `--surveyResult SURVEYRESULT` - output file for survey results
     - sub command `analyze` - analyze an existing graph
         - `-gmla GRAPHMLANALYZE`, `--graphmlAnalyze GRAPHMLANALYZE` - input graphml file
-    - sub command `augment` - analyze an existing graph
+    - sub command `augment` - augment an existing graph with information from  stellarbeat.io. Currently, only Public Network graphs are supported.
         - `-gmli GRAPHMLINPUT` - input graphml file
         - `-gmlo GRAPHMLOUTPUT` - output graphml file
     - sub command `flatten` - Take a graphml file containing a bidrectional graph (possibly augmented with StellarBeat data) and flatten it into an undirected graph in JSON.

src/overlay/SurveyManager.h

@@ -17,6 +17,12 @@ namespace stellar
 {
 class Application;
 
+/*
+SurveyManager orchestrates network surveys by initiating them and
+maintaining a backlog of peers to survey, sending and processing messages,
+throttling requests to prevent overload, aggregating results, and concluding the
+survey upon completion or expiry.
+*/
 class SurveyManager : public std::enable_shared_from_this<SurveyManager>,
                       public NonMovableOrCopyable
 {

src/overlay/SurveyMessageLimiter.h

@@ -14,12 +14,15 @@ namespace stellar
 class Application;
 
 /*
-SurveyMessageLimiter filters out -
-1. Messages if the Surveyor-Surveyed key pair was already seen
-2. Messages with an expired ledger number
-3. Requests from any given Surveyor if more than mMaxRequestLimit requests were
-sent
+The SurveyMessageLimiter module manages survey message traffic through specific
+filtering policies:
+ * It validates ledger numbers of survey messages, restricting messages to a
+predefined ledger range to maintain relevance.
+  * It enforces a cap on the number of survey requests a node can handle (via
+`mMaxRequestLimit`)
+  * It implements duplication checks for `Surveyor-Surveyed` pairs
 */
+
 class SurveyMessageLimiter
 {
   public: