system_health

Description

Retrieves the health status of a Polkadot node, including peer count, synchronization status, and overall node health. This method is essential for monitoring node performance and network connectivity.

Parameters

This method does not require any parameters.

Returns

Field	Type	Description
peers	number	Number of connected peers
isSyncing	boolean	Whether the node is currently syncing with the network
shouldHavePeers	boolean	Whether the node should have peers (false for dev nodes)

Request Example

{
  "jsonrpc": "2.0",
  "method": "system_health",
  "params": [],
  "id": 1
}

Response Example

{
  "jsonrpc": "2.0",
  "result": {
    "peers": 25,
    "isSyncing": false,
    "shouldHavePeers": true
  },
  "id": 1
}

Code Examples

cURL

curl https://api-polkadot.n.dwellir.com/YOUR_API_KEY \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "system_health",
    "params": [],
    "id": 1
  }'

Python

import requests
import json
import time

def check_node_health():
    url = "https://api-polkadot.n.dwellir.com/YOUR_API_KEY"
    headers = {"Content-Type": "application/json"}
    payload = {"jsonrpc": "2.0", "method": "system_health", "params": [], "id": 1}
    data = requests.post(url, headers=headers, data=json.dumps(payload)).json()
    if "error" in data:
        raise Exception(f"RPC Error: {data['error']}")
    return data["result"]

def monitor_health(interval_seconds=30):
    while True:
        try:
            health = check_node_health()
            status = "Syncing" if health["isSyncing"] else "Synced"
            print(f"Node Status: {status}")
            print(f"Connected Peers: {health['peers']}")
        except Exception as e:
            print(f"Error checking health: {e}")
        time.sleep(interval_seconds)

# Single health check
print(check_node_health())

JavaScript

const checkNodeHealth = async () => {
  const response = await fetch('https://api-polkadot.n.dwellir.com/YOUR_API_KEY', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ jsonrpc: '2.0', method: 'system_health', params: [], id: 1 })
  });
  const { result } = await response.json();
  return result;
};

TypeScript (@polkadot/api)

import { ApiPromise, WsProvider } from '@polkadot/api';

const provider = new WsProvider('wss://api-polkadot.n.dwellir.com/YOUR_API_KEY');
const api = await ApiPromise.create({ provider });
const health = await api.rpc.system.health();
console.log({
  peers: health.peers.toNumber(),
  isSyncing: health.isSyncing.isTrue,
  shouldHavePeers: health.shouldHavePeers.isTrue,
});

Health Status Interpretation

Peer Count

Peers	Status	Description
0	Critical	No network connectivity
1-2	Warning	Low connectivity, may have issues
3-10	Good	Acceptable connectivity
10+	Excellent	Well connected to network

Sync Status

isSyncing	Meaning
true	Node is downloading and processing historical blocks
false	Node is synchronized with the network

Should Have Peers

shouldHavePeers	Meaning
true	Normal network node, should connect to peers
false	Development/isolated node, peer connection optional

Use Cases

1. Monitoring Dashboards: Display node health metrics
2. Alerting Systems: Trigger alerts on connectivity issues
3. Load Balancers: Route traffic based on node health
4. Deployment Validation: Verify node setup and connectivity
5. Troubleshooting: Diagnose synchronization problems

Monitoring Best Practices

Health Check Implementation

class HealthChecker {
  constructor(endpoint, apiKey) {
    this.endpoint = endpoint;
    this.apiKey = apiKey;
    this.healthHistory = [];
  }
  
  async check() {
    try {
      const health = await this.getHealth();
      
      this.healthHistory.push({
        timestamp: Date.now(),
        ...health
      });
      
      // Keep last 100 checks
      if (this.healthHistory.length > 100) {
        this.healthHistory.shift();
      }
      
      return this.analyzeHealth(health);
    } catch (error) {
      return {
        status: 'error',
        message: error.message
      };
    }
  }
  
  analyzeHealth(health) {
    const issues = [];
    
    if (health.peers === 0 && health.shouldHavePeers) {
      issues.push('No peer connections');
    }
    
    if (health.peers < 3 && health.shouldHavePeers) {
      issues.push('Low peer count');
    }
    
    if (health.isSyncing) {
      issues.push('Node syncing');
    }
    
    return {
      status: issues.length === 0 ? 'healthy' : 'degraded',
      issues,
      metrics: health
    };
  }
  
  getAveragePeers() {
    if (this.healthHistory.length === 0) return 0;
    
    const sum = this.healthHistory.reduce(
      (acc, h) => acc + h.peers, 0
    );
    
    return sum / this.healthHistory.length;
  }
}

Related Methods

• chain_getBlock - Check latest block
• chain_getBlockHash - Get block hashes
• state_getMetadata - Get runtime metadata
• author_submitExtrinsic - Submit transactions

Notes

• Health checks should be performed regularly but not excessively
• Peer count can fluctuate normally - look for trends
• Syncing status is normal for new nodes or after downtime
• Consider multiple health checks before triggering alerts
• Different node types (validator, full, light) have different health characteristics