Updated Diagnostics Tool and minor fixes

Bloxster · Bloxster · commit c075199a71d8 · 2025-02-23T17:56:30.000+01:00
diff --git a/LICENSE.txt b/LICENSE.txt
@@ -1,3 +1,3 @@
 The Erigon 3 documentation © 2025 by Erigon contributors is licensed under CC BY 4.0.
 
-To view a copy of this license, visit https://creativecommons.org/licenses/by/4.0/
+To view a copy of this license, visit https://creativecommons.org/licenses/by/4.0/.
diff --git a/src/SUMMARY.md b/src/SUMMARY.md
@@ -50,10 +50,11 @@
     - [Caplin](advanced/bp-caplin.md)
 
 - [Tools](tools.md)
-    - [Dagnostic Tools](tools/introduction.md)
+    - [Diagnostics Tool](tools/introduction.md)
         - [Installation](tools/installation.md)
         - [Setup](tools/setup.md)
-        - [User Interface](tools/user_interface.md)
+        - [Options](tools/options.md)
+        - [Browser Interface](tools/user_interface.md)
     - [Otterscan](tools/otterscan.md)
 
 - [Frequently Asked Questions](faq.md)
diff --git a/src/about/contributing.md b/src/about/contributing.md
@@ -1,6 +1,13 @@
-# Contributing to Erigon 3
+# Contributing
 
-## Development
+ 
+- [Contributing to Erigon 3](#contributing-to-erigon-3)
+- [Contributing to Documentation](#contributing-to-documentation)
+
+
+## Contributing to Erigon 3
+
+### Development
 
 Erigon is an open-source project that welcomes contributions from developers worldwide who are passionate about advancing the Ethereum ecosystem. Bounties may be offered for noteworthy contributions, as the team is committed to continuously enhancing the tool to better serve the Erigon community.
 
@@ -39,6 +46,6 @@ Visit also Erigon's **[Wiki](https://github.com/ledgerwatch/erigon/wiki)** to ga
 - Transaction Pool Design
 - Using Postman to test RPC.
 
-# Documentation
+# Contributing to Documentation
 
-To contribute to this documentation, commit your change to the development branch on **[Github](https://github.com/erigontech/docs/tree/development)**. You might want to run it locally to verify the output before committing, see how MdBook works [here](https://rust-lang.github.io/mdBook/index.html).
+To contribute to the Erigon 3 book, commit your change to the development branch on **[Github](https://github.com/erigontech/docs/tree/development)**. You might want to run it locally to verify the output before committing, see how MdBook works [here](https://rust-lang.github.io/mdBook/index.html).
diff --git a/src/about/license.md b/src/about/license.md
@@ -1,3 +1,7 @@
 # License
 
-The Erigon 3 Book © 2024 by Erigon contributors is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+Copyright 2025 Erigon Technologies AG.
+
+Licensed under the [LGPL-3.0](https://github.com/erigontech/erigon/blob/release/2.60/COPYING.LESSER), [GPL-3.0](https://github.com/erigontech/erigon/blob/release/2.60/COPYING).
+
+*Permissions of this copyleft license are conditioned on making available complete source code of licensed works and modifications under the same license or the GNU GPLv3. Copyright and license notices must be preserved. Contributors provide an express grant of patent rights. However, a larger work using the licensed work through interfaces provided by the licensed work may be distributed under different terms and without source code for the larger work.*
diff --git a/src/about/reachus.md b/src/about/reachus.md
@@ -2,14 +2,15 @@
 
 The Erigon Technologies AG office is located in the CV Labs in Zug:
 
-
 ```
-Erigon Technologies AG 
+Erigon Technologies AG
 Damstrasse 16
 6300 Zug
 Switzerland
 ```
 
+**[erigon.tech](https://erigon.tech)**
+
 ## Erigon Discord Server
 
 The most important discussions take place on the Discord server where also some support is provided. To get an invite, send an email to bloxster [at] proton.me with your name, profession, a short explanation why you want to join the Discord server and how you heard about Erigon.
diff --git a/src/images/diag_create_session_1.png b/src/images/diag_create_session_1.png
diff --git a/src/images/diag_create_session_2.png b/src/images/diag_create_session_2.png
diff --git a/src/images/diag_create_session_3.png b/src/images/diag_create_session_3.png
diff --git a/src/images/diag_create_session_4.png b/src/images/diag_create_session_4.png
diff --git a/src/images/logoDEF-07.png b/src/images/logoDEF-07.png
diff --git a/src/tools.md b/src/tools.md
@@ -1,3 +1,8 @@
 # Tools
 
-<img src="/images/WIP.png" alt="" style="display: block; margin: 0 auto;">
+Erigon offers a range of tools to enhance your experience and provide valuable assistance when:
+
+1. Troubleshooting issues with your local or remote Erigon node using our [Diagnostics Tool](/tools/introduction.md), which helps you identify and resolve problems efficiently.
+2. Exploring the blockchain with [Otterscan](/tools/otterscan.md), a feature-rich EVM block explorer that allows you to browse and analyze blockchain data with ease.
+
+Both tools are developed internally and are fully supported for our users.
diff --git a/src/tools/installation.md b/src/tools/installation.md
@@ -1 +1,16 @@
 # Installation
+
+## Pre-requisites
+
+- Erigon Node running locally;
+- Ngrok, in case you are planning to monitor a remote node, see installation at <https://ngrok.com/docs/getting-started/>.
+
+## Diagnostics Tool Set Up
+
+```bash
+git clone https://github.com/erigontech/diagnostics.git
+cd diagnostics
+make build
+```
+
+You are now ready to run the Diagnostic Tool.
diff --git a/src/tools/introduction.md b/src/tools/introduction.md
@@ -1,12 +1,13 @@
-# Diagnostic Tool
+# Diagnostics Tool
 
-As the Erigon ecosystem expands, the demand for an effective system to diagnose and resolve user issues grows. The Erigon Diagnostics Tool is designed to offer a simplified approach to pinpointing the underlying reasons for problems faced by Erigon users, be they individuals, companies utilizing Erigon internally, or enterprises granting Erigon node access to others.
-Key Features
+As the Erigon ecosystem expands, the demand for an effective system to diagnose and resolve user issues grows. The Erigon Diagnostics Tool is designed to offer a simplified approach to pinpointing the underlying reasons for problems faced by Erigon users.
+
+## Key Features
 
 The Erigon Diagnostics tool offers the following features:
 
 - **Automated Data Collection**: The tool can gather essential information about the user's Erigon node, including the Erigon version, system parameters, and recent console output, without requiring extensive manual input from the user.
 
 - **Interactive Diagnostics**: When additional data is needed to pinpoint the issue, the tool facilitates an interactive process, guiding the user through targeted data collection to optimize the troubleshooting process.
 
-- **Diagnostic Reporting**: The tool generates comprehensive diagnostic reports, making it easier for the Erigon development team to analyze the issues and provide effective solutions.
+- **Diagnostic Reporting**: The tool generates comprehensive diagnostic reports, making it easier to analyze the issues.
diff --git a/src/tools/options.md b/src/tools/options.md
@@ -0,0 +1,49 @@
+# Options
+
+The following flags can be used to configure various parameters of the Diagnostics Tool.
+
+## Configuration File:
+
+- `--config` : Specify a configuration file (default is `$HOME/.cobra.yaml`).
+
+## Network Settings:
+
+- `--addr` : Network interface to listen on (default is `localhost`).
+- `--port` : Port to listen on (default is `8080`).
+
+## Session Management:
+
+- `--node.sessions` : Maximum number of node sessions to allow (default is `5000`).
+- `--ui.sessions` : Maximum number of UI sessions to allow (default is `5000`).
+
+## Logging Configuration:
+
+- `--log.dir.path` : Directory path to store log data (default is `./logs`).
+- `--log.file.name` : Name of the log file (default is `diagnostics.log`).
+- `--log.file.size.max` : Maximum size of log file in megabytes (default is `100`).
+- `--log.file.age.max` : Maximum age in days a log file can persist in the system (default is `28`).
+- `--log.max.backup` : Maximum number of log files that can persist (default is `5`).
+- `--log.compress` : Whether to compress historical log files (default is `false`).
+
+
+# Other options
+
+To display other available options for Diagnostics Tool digit:
+
+```bash
+cd erigon
+./build/bin/erigon support --help
+```
+
+The `--help` flag listing is reproduced below for your convenience.
+
+- `--diagnostics.addr [value]`: By default, the diagnostics address is `localhost:8080`. You may tunnel it to connect to a remote node, you must specify it for this flag.
+- `--debug.addrs [value]`: Comma separated list of URLs to the debug endpoints thats are being diagnosed [`15sk` ] (default: "localhost:6062")
+- `--diagnostics.addr [value]`: Address of the diagnostics system provided by the support team, include unique session PIN (default: "`localhost:8080`")
+- `--diagnostics.sessions [value]`: Comma separated list of session PINs to connect to
+- `--pprof`: Enable the pprof HTTP server (default: false)
+- `--pprof.addr [value]`: pprof HTTP server listening interface (default: "`127.0.0.1`")
+- `--pprof.port [value]`: pprof HTTP server listening port (default: `6060`)
+- `--pprof.cpuprofile [value]`: Write CPU profile to the given file
+- `--trace [value]`: Write execution trace to the given file
+- `--help`, `-h`: show help
diff --git a/src/tools/setup.md b/src/tools/setup.md
@@ -1 +1,112 @@
 # Setup
+*How to connect the Diagnostics Tool to your Erigon node*
+
+To monitor your node using the Diagnostic Tool, you must first establish a connection. The necessary steps to connect are:
+
+1. Run your Erigon node
+2. Run the Diagnostic Tool
+3. Create a new session in the Diagnostic Tool
+4. Connect the Diagnostic Tool to your node
+5. Refresh the Diagnostic Tool
+
+## 1. Run your Erigon node
+
+If you are not sure what to run, start from a testnet with Caplin as the Consensus Engine. 
+
+```
+./build/bin/erigon --chain=holesky
+```
+
+## 2. Run the Diagnostics Tool
+
+Run the Diagnostic Tool application from the machine where you intend to monitor your node.
+
+```bash
+cd diagnostics
+make run-self-signed
+```
+
+The Diagnostics Tool page will automatically be available in your browser at the address <http://localhost:8080>.
+
+> Leaving the terminal session will close the Diagnostics Tool interface.
+
+## 3. Create a new session in the Diagnostics Tool
+
+The Diagnostics Tool is now operational, but to access the data, it must be connected to the Erigon node. Proceed to the **Admin** section in the left navigation menu and select **Create Session**. 
+
+<img src="/images/diag_create_session_1.png">
+
+Assign a name to your session and click **Create**  to proceed.
+
+<img src="/images/diag_create_session_2.png">
+
+Upon successful creation of a new session, a unique 8-digit code, referred to as `YOUR SESSION PIN`, will be generated. You can find this PIN displayed next to the session name in the list of created sessions.
+
+To copy the Session PIN or the support command, click on the copy button next to it. This will copy the information to your clipboard for easy reference or use.
+
+<img src="/images/diag_create_session_3.png">
+
+In this example, we created a session named "Holesky", and it was assigned the PIN 34424089. The corresponding support command is displayed beside the PIN:
+
+```bash
+./build/bin/erigon support --Diagnostics.sessions 34424089.
+```
+
+## 4. Connect the Diagnosticss Tool to your node
+
+### 4.1 Local Node
+
+If your Erigon node is running on your local machine, open a new console window in the Erigon folder and run the following command:
+
+```bash
+cd erigon
+./build/bin/erigon support --diagnostics.sessions YOUR_SESSION_PIN
+```
+Replace `YOUR_SESSION_PIN` with the 8-digit PIN allocated to your session during the previous step, or use the suggested support command:
+
+```bash
+./build/bin/erigon support --diagnostics.sessions 34424089
+```
+
+This will attach the Diagnostics Tool to the Erigon node using the provided session PIN. 
+
+See also other [options](/tools/options.md).
+
+### 4.2 Remote Node
+
+If your Erigon node is running on a Virtual Private Server (VPS) such as Amazon AWS, you can connect the Diagnostics Tool on your local machine with [ngrok](https://ngrok.com/docs/getting-started/) utility. 
+
+> **ngrok** was chosen because of its easy of use and because the free version is useful for our scope. It is possible to use any other similar tool.
+
+You can run ngrok on your local machine in order to tunnel `localhost:8080`: 
+
+```bash
+ngrok http http://localhost:8080
+```
+
+The ngrok utility will start and return a page similar to the below example:
+
+<img src="/images/diag_create_session_4.png">
+
+Your diagnostic address is in the Forwarding field. Copy only the part of the address after the URL prefix https://, in this case `8ac3-79-56-45-3.ngrok-free.app`.
+
+In the machine hosting your Erigon node, go to the Erigon directory and run this command to attach the Diagnostics Tool to the Erigon node:
+
+```bash
+./build/bin/erigon support --diagnostics.addr YOUR_DIAGNOSTIC_ADDRESS --diagnostics.sessions YOUR_SESSION_PIN
+```
+
+Replace `YOUR_DIAGNOSTIC_ADDRESS` with the address obtained with ngrok amd `YOUR_SESSION_PIN` with your session PIN from point 3. For example:
+
+```bash
+./build/bin/erigon support --diagnostics.addr 8ac3-79-56-45-3.ngrok-free.app --diagnostics.sessions 34424089
+```
+
+By following these steps, you can establish a connection between the Diagnostic Tool on your local machine and the Erigon node running on the VPS, enabling you to monitor and diagnose the node's performance.
+
+More information about the Erigon support command can be find here.
+
+## 5. Refresh the Diagnostic Tool
+
+Once the Diagnostics Tool is successfully connected to the Erigon node, return to your web browser and reload the page. 
+This step is necessary to query data from the connected node.
diff --git a/src/tools/user_interface.md b/src/tools/user_interface.md
@@ -1 +1,20 @@
-# User Interface
+# Browser Interface
+
+By navigating to <http://localhost:8080> in your browser, you can access the Diagnostics Tool and explore its various sections. These sections provide a comprehensive overview of your Erigon node's status and activity, covering aspects such as session details, node configuration, network interactions, download status, log files, and more.
+
+1. **Status Bar**: Displays essential information about the current session and operating Erigon node.
+2. **Process Tab**:
+	* **Command**: Inspect the command line arguments used to launch the Erigon node.
+	* **Flags**: Examine the flags set in the CLI context by the user when launching the node.
+	* **Node info**: Contains detailed information about the Erigon node.
+3. **Network Tab**:
+	* **Peers Data**: Collect and view information about network peers, including active peers, static peers, and total seen peers.
+	* **Downloader**: Provides detailed information about the progress, download status, estimated time, and resource allocation for "Snapshots" download.
+4. **Logs Tab**: View and download logs from the Erigon node, with log rotation and filtering capabilities.
+5. **Data Tab**: Inspect databases and their tables.
+6. **Admin Tab**:
+	* **Session Management**: View active sessions, create new sessions, and obtain session PINs for connections.
+	* **Data Management**: Clear all sessions and data .
+7. **Available Flags**: Configure various parameters of the diagnostics UI, including network settings, session management, logging configuration, and more.
+
+See currently implemented diagnostics [here](https://github.com/erigontech/diagnostics/blob/main/README.md#currently-implemented-diagnostics).

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`	`1`	`The Erigon 3 documentation © 2025 by Erigon contributors is licensed under CC BY 4.0.`
`2`	`2`
`3`		`-To view a copy of this license, visit https://creativecommons.org/licenses/by/4.0/`
	`3`	`+To view a copy of this license, visit https://creativecommons.org/licenses/by/4.0/.`