Skip to content

Commit d4a91eb

Browse files
Jim8yNeo Bot
Jim8y
authored and
Neo Bot
committed
Add telemetry documentation and monitoring configs
1 parent 23822f6 commit d4a91eb

File tree

1 file changed

+66
-64
lines changed

1 file changed

+66
-64
lines changed

‎src/Plugins/Telemetry/README.md‎

Lines changed: 66 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -14,20 +14,22 @@ A comprehensive telemetry and metrics collection plugin for Neo N3 full nodes, p
1414
## Installation
1515

1616
1. Build the plugin:
17+
1718
```bash
18-
dotnet build src/Plugins/TelemetryPlugin/TelemetryPlugin.csproj
19+
dotnet build src/Plugins/Telemetry/Telemetry.csproj
1920
```
2021

21-
2. Copy the output to your Neo node's `Plugins/TelemetryPlugin/` directory:
22+
2. Copy the output to your Neo node's `Plugins/Telemetry/` directory:
23+
2224
```bash
23-
cp -r bin/Debug/net10.0/* /path/to/neo-node/Plugins/TelemetryPlugin/
25+
cp -r bin/Debug/net9.0/* /path/to/neo-node/Plugins/Telemetry/
2426
```
2527

2628
3. Configure the plugin by editing `config.json` in the plugin directory.
2729

2830
## Configuration
2931

30-
Create or edit `config.json` in the `Plugins/TelemetryPlugin/` directory:
32+
Create or edit `config.json` in the `Plugins/Telemetry/` directory:
3133

3234
```json
3335
{
@@ -37,7 +39,7 @@ Create or edit `config.json` in the `Plugins/TelemetryPlugin/` directory:
3739
"PrometheusPort": 9100,
3840
"PrometheusHost": "localhost",
3941
"PrometheusPath": "/metrics",
40-
"HealthPort": 9100,
42+
"HealthPort": 9101,
4143
"SystemMetricsIntervalMs": 5000,
4244
"CollectBlockchainMetrics": true,
4345
"CollectNetworkMetrics": true,
@@ -51,82 +53,82 @@ Create or edit `config.json` in the `Plugins/TelemetryPlugin/` directory:
5153

5254
### Configuration Options
5355

54-
| Option | Type | Default | Description |
55-
|--------|------|---------|-------------|
56-
| `Enabled` | bool | `true` | Enable/disable the telemetry plugin |
57-
| `ExceptionPolicy` | string | `StopPlugin` | Exception handling policy (`StopNode`, `StopPlugin`, `Ignore`) |
58-
| `PrometheusPort` | int | `9100` | Port for the Prometheus metrics endpoint |
59-
| `PrometheusHost` | string | `localhost` | Host address for the metrics endpoint |
60-
| `PrometheusPath` | string | `/metrics` | URL path for the metrics endpoint |
61-
| `HealthPort` | int | `9100` | Port for `/health`, `/ready`, `/live` endpoints |
62-
| `SystemMetricsIntervalMs` | int | `5000` | Interval for collecting system metrics (ms) |
63-
| `CollectBlockchainMetrics` | bool | `true` | Enable blockchain metrics collection |
64-
| `CollectNetworkMetrics` | bool | `true` | Enable network metrics collection |
65-
| `CollectMempoolMetrics` | bool | `true` | Enable mempool metrics collection |
66-
| `CollectSystemMetrics` | bool | `true` | Enable system resource metrics collection |
67-
| `NodeId` | string | hostname | Unique identifier for this node |
68-
| `NetworkName` | string | auto-detect | Network name label (mainnet, testnet, etc.) |
56+
| Option | Type | Default | Description |
57+
| -------------------------- | ------ | -------------- | ---------------------------------------------------------------------------- |
58+
| `Enabled` | bool | `true` | Enable/disable the telemetry plugin |
59+
| `ExceptionPolicy` | string | `StopPlugin` | Exception handling policy (`StopNode`, `StopPlugin`, `Ignore`) |
60+
| `PrometheusPort` | int | `9100` | Port for the Prometheus metrics endpoint |
61+
| `PrometheusHost` | string | `localhost` | Host address for the metrics endpoint |
62+
| `PrometheusPath` | string | `/metrics` | URL path for the metrics endpoint |
63+
| `HealthPort` | int? | PrometheusPort | Port for `/health`, `/ready`, `/live` endpoints (defaults to PrometheusPort) |
64+
| `SystemMetricsIntervalMs` | int | `5000` | Interval for collecting system metrics (ms) |
65+
| `CollectBlockchainMetrics` | bool | `true` | Enable blockchain metrics collection |
66+
| `CollectNetworkMetrics` | bool | `true` | Enable network metrics collection |
67+
| `CollectMempoolMetrics` | bool | `true` | Enable mempool metrics collection |
68+
| `CollectSystemMetrics` | bool | `true` | Enable system resource metrics collection |
69+
| `NodeId` | string | hostname | Unique identifier for this node |
70+
| `NetworkName` | string | auto-detect | Network name label (mainnet, testnet, etc.) |
6971

7072
## Metrics Reference
7173

7274
### Blockchain Metrics
7375

74-
| Metric | Type | Description |
75-
|--------|------|-------------|
76-
| `neo_blockchain_height` | Gauge | Current block height |
77-
| `neo_blockchain_header_height` | Gauge | Current header height |
78-
| `neo_blockchain_blocks_persisted_total` | Counter | Total blocks persisted |
79-
| `neo_blockchain_block_persist_duration_milliseconds` | Histogram | Block persist duration |
80-
| `neo_blockchain_block_transactions` | Gauge | Transactions in last block |
81-
| `neo_blockchain_transactions_processed_total` | Counter | Total transactions processed |
82-
| `neo_blockchain_sync_status` | Gauge | Sync status (1=synced, 0=syncing) |
83-
| `neo_blockchain_blocks_behind` | Gauge | Blocks behind network |
84-
| `neo_blockchain_time_since_last_block_seconds` | Gauge | Time since last block |
76+
| Metric | Type | Description |
77+
| ---------------------------------------------------- | --------- | --------------------------------- |
78+
| `neo_blockchain_height` | Gauge | Current block height |
79+
| `neo_blockchain_header_height` | Gauge | Current header height |
80+
| `neo_blockchain_blocks_persisted_total` | Counter | Total blocks persisted |
81+
| `neo_blockchain_block_persist_duration_milliseconds` | Histogram | Block persist duration |
82+
| `neo_blockchain_block_transactions` | Gauge | Transactions in last block |
83+
| `neo_blockchain_transactions_processed_total` | Counter | Total transactions processed |
84+
| `neo_blockchain_sync_status` | Gauge | Sync status (1=synced, 0=syncing) |
85+
| `neo_blockchain_blocks_behind` | Gauge | Blocks behind network |
86+
| `neo_blockchain_time_since_last_block_seconds` | Gauge | Time since last block |
8587

8688
### Network Metrics
8789

88-
| Metric | Type | Description |
89-
|--------|------|-------------|
90-
| `neo_network_peers_connected` | Gauge | Connected peer count |
91-
| `neo_network_peers_unconnected` | Gauge | Unconnected peer count |
92-
| `neo_network_peer_connections_total` | Counter | Total peer connections |
90+
| Metric | Type | Description |
91+
| --------------------------------------- | ------- | ------------------------- |
92+
| `neo_network_peers_connected` | Gauge | Connected peer count |
93+
| `neo_network_peers_unconnected` | Gauge | Unconnected peer count |
94+
| `neo_network_peer_connections_total` | Counter | Total peer connections |
9395
| `neo_network_peer_disconnections_total` | Counter | Total peer disconnections |
94-
| `neo_network_messages_received_total` | Counter | Messages received by type |
95-
| `neo_network_messages_sent_total` | Counter | Messages sent by type |
96-
| `neo_network_bytes_received_total` | Counter | Total bytes received |
97-
| `neo_network_bytes_sent_total` | Counter | Total bytes sent |
96+
| `neo_network_messages_received_total` | Counter | Messages received by type |
97+
| `neo_network_messages_sent_total` | Counter | Messages sent by type |
98+
| `neo_network_bytes_received_total` | Counter | Total bytes received |
99+
| `neo_network_bytes_sent_total` | Counter | Total bytes sent |
98100

99101
### Mempool Metrics
100102

101-
| Metric | Type | Description |
102-
|--------|------|-------------|
103-
| `neo_mempool_transactions` | Gauge | Current mempool size |
104-
| `neo_mempool_verified_transactions` | Gauge | Verified transaction count |
105-
| `neo_mempool_unverified_transactions` | Gauge | Unverified transaction count |
106-
| `neo_mempool_capacity` | Gauge | Mempool capacity |
107-
| `neo_mempool_utilization_ratio` | Gauge | Mempool utilization (0-1) |
108-
| `neo_mempool_transactions_added_total` | Counter | Total transactions added |
109-
| `neo_mempool_transactions_removed_total` | Counter | Total transactions removed |
103+
| Metric | Type | Description |
104+
| ---------------------------------------- | ------- | ---------------------------- |
105+
| `neo_mempool_transactions` | Gauge | Current mempool size |
106+
| `neo_mempool_verified_transactions` | Gauge | Verified transaction count |
107+
| `neo_mempool_unverified_transactions` | Gauge | Unverified transaction count |
108+
| `neo_mempool_capacity` | Gauge | Mempool capacity |
109+
| `neo_mempool_utilization_ratio` | Gauge | Mempool utilization (0-1) |
110+
| `neo_mempool_transactions_added_total` | Counter | Total transactions added |
111+
| `neo_mempool_transactions_removed_total` | Counter | Total transactions removed |
110112

111113
### System Metrics
112114

113-
| Metric | Type | Description |
114-
|--------|------|-------------|
115-
| `neo_system_cpu_usage_ratio` | Gauge | CPU usage ratio (0-1) |
116-
| `neo_system_memory_usage_bytes` | Gauge | Memory usage by type |
117-
| `neo_system_gc_collection_count` | Gauge | GC collections by generation |
118-
| `neo_system_threadpool_worker_threads` | Gauge | Active worker threads |
115+
| Metric | Type | Description |
116+
| ----------------------------------------------- | ----- | ------------------------------ |
117+
| `neo_system_cpu_usage_ratio` | Gauge | CPU usage ratio (0-1) |
118+
| `neo_system_memory_usage_bytes` | Gauge | Memory usage by type |
119+
| `neo_system_gc_collection_count` | Gauge | GC collections by generation |
120+
| `neo_system_threadpool_worker_threads` | Gauge | Active worker threads |
119121
| `neo_system_threadpool_completion_port_threads` | Gauge | Active completion port threads |
120-
| `neo_system_process_uptime_seconds` | Gauge | Process uptime |
122+
| `neo_system_process_uptime_seconds` | Gauge | Process uptime |
121123

122124
### Node Info Metrics
123125

124-
| Metric | Type | Description |
125-
|--------|------|-------------|
126-
| `neo_node_info` | Gauge | Node information (version labels) |
127-
| `neo_node_start_time_seconds` | Gauge | Node start timestamp |
128-
| `neo_plugins_loaded` | Gauge | Number of loaded plugins |
129-
| `neo_plugin_status` | Gauge | Individual plugin status |
126+
| Metric | Type | Description |
127+
| ----------------------------- | ----- | --------------------------------- |
128+
| `neo_node_info` | Gauge | Node information (version labels) |
129+
| `neo_node_start_time_seconds` | Gauge | Node start timestamp |
130+
| `neo_plugins_loaded` | Gauge | Number of loaded plugins |
131+
| `neo_plugin_status` | Gauge | Individual plugin status |
130132

131133
## Prometheus Integration
132134

@@ -136,9 +138,9 @@ Add to your `prometheus.yml`:
136138

137139
```yaml
138140
scrape_configs:
139-
- job_name: 'neo-node'
141+
- job_name: "neo-node"
140142
static_configs:
141-
- targets: ['localhost:9100']
143+
- targets: ["localhost:9100"]
142144
scrape_interval: 15s
143145
```
144146

0 commit comments

Comments
 (0)