Skip to main content

Sui Node Monitoring

This page explains how to view the metrics a Sui full node exposes on port 9184, which metrics show sync health, and how to scrape them with Prometheus, visualize them with Grafana, and set up alerts.

info

These instructions are for advanced users. If you just need a local development environment, you should instead follow the instructions in Create a Local Sui Network to create a local full node, validators, and faucet.

The examples below scrape localhost:9184/metrics, so run them on the node host itself or through an SSH tunnel to it. The default full node template binds metrics to 0.0.0.0:9184. Restrict metrics-address with a firewall or bind it to a private interface in production.

You can view the metrics in the metrics UI, or use a tool like curl to get the metrics in a format that is easy to parse.

$ curl -s http://localhost:9184/metrics | grep -E 'sui_validator|sui_fullnode'

What metrics does a Sui node expose?​

The following metrics are the most important for monitoring node health. The three checkpoint metrics track progress in stages: the node learns about a checkpoint from the network (known), fully syncs its contents and effects (synced), and executes it (executed).

MetricTypeWhat it tells you
highest_known_checkpointGaugeHighest checkpoint the node knows about from the network
highest_synced_checkpointGaugeHighest checkpoint fully synced (contents and effects)
last_executed_checkpointGaugeLast checkpoint the node executed
last_executed_checkpoint_timestamp_msGaugeTimestamp of the last executed checkpoint
current_epochGaugeCurrent epoch ID
uptimeCounterNode uptime in seconds (includes version and chain_identifier labels)
total_transaction_certificatesCounterTotal transaction certificates handled

Sync health check: Compare highest_known_checkpoint with highest_synced_checkpoint. If the gap grows, the node is falling behind. Compare your node's highest_synced_checkpoint against a trusted public endpoint to measure absolute lag:

# Check your node's sync progress
$ curl -s http://localhost:9184/metrics | grep -E 'highest_known_checkpoint|highest_synced_checkpoint|last_executed_checkpoint'

How do I monitor a Sui node in production?​

For production monitoring, use Prometheus to scrape metrics and Grafana to visualize them.

Add a scrape target for your node in your Prometheus configuration:

scrape_configs:
  - job_name: 'sui-fullnode'
    static_configs:
      - targets: ['localhost:9184']
    scrape_interval: 15s

How do I set up alerts for my Sui node?​

Set up alerts for the following conditions. The conditions are written as PromQL expressions for use in Prometheus alerting rules:

  • Sync lag: highest_known_checkpoint - highest_synced_checkpoint > 100 sustained for 5 minutes indicates the node is falling behind.
  • Node down: up{job="sui-fullnode"} == 0 sustained for 2 minutes indicates the node is unreachable.
  • Execution lag: last_executed_checkpoint_timestamp_ms > 0 and time() - last_executed_checkpoint_timestamp_ms / 1000 > 120 sustained for 2 minutes indicates that the node is executing checkpoints more than 2 minutes behind chain time. This alert also fires while a healthy node catches up after an outage or snapshot restore. The > 0 guard avoids false alerts during startup, when the timestamp has not yet been populated. To detect a stalled executor separately, alert when last_executed_checkpoint does not advance over a suitable interval.