Node metrics specification

Target releaseMercury
EpicMonitoring and metrics for the node
Document status
Document owner


  • The node can emit metrics
  • Node operators are able to pull metrics from the node through the metrics API or Prometheus integration
  • Demonstration of a node monitoring system at launch of test net

Background and strategic fit

Node operators are fairly similar to site reliability engineers.  They will want to know how their nodes are operating and performing.  To that end, the node supports the ability to emit metrics and a way for node operators to pull metrics.  The node will not generate metrics It will emit raw numbers from the system. Node operators will be able to access metrics through the metrics API or through Prometheus integration. Node operators can use these interface tools to create relevant visualizations of metrics related to node performance.


  • Node operators will be responsible for setting up a node monitoring system.
  • Node operators will be able to use available RCHain documentation to interface with the node metrics API to pull data needed for their monitoring system.


#TitleUser StoryImportanceNotesStatus 
1Node emits metrics through the metrics APINode operators want access to any and all metrics related to node operation and performance.Must have
  • The node emits metrics

  • Expose extensive metrics on the system and JVM
  • At minimum the following metrics should be exposed:
    • CPU
    • RAM
    • Disk
    • Network core metrics at the core level
    • JVM performance
    • Garbage collection
    • Size of memory pools
    • Consumption of memory pools
  • Monitoring systems can pull metrics from the node
  • The node does not push metrics
  • The node does not report on itself
Metrics emitted on http port 40403.  Complete (metrics emitted via API) 
2Node measures COMM EventsCOMM events are a measure of an RChain transaction.  The node must report on how many raw comm events are being processed, so we can demonstrate 40K COMM events /secondMust Have
  • Create a counter of COMM events as a total count of events in the last hour.  Rita Allen to confirm with SRE if the metrics should reset in the past hour.
  • COMM events should be measured for Propose (block creation) and Replay RSpace.
Rita Allen to validate the requirement, see what has been implemented.
3Node reports on CPU UtilizationThe Node reports on the percentage of CPU that is being consumed. Must Have
  • Report on the percentage of CPU being consumed at the time the request for metrics is being made.
Rita Allen Please confirm the status
4Node reports on total RAM consumedThe node reports on the amount of RAM being consumedMust Have
  • Report on the total amount of RAM being consumed at the time the request for metrics is being made
Rita Allen Please confirm the status
5Deploy CountThe node reports on the total number of deployments receivedMust Have
  • Report on the total number of times the deploy API receives a request.
6Deploys since last proposeThe node reports the total number of deploys received since the last proposeNice to haveReport on the total number of deploys received via the deploy API since the last successful proposeRHOL-913
7Blocks proposedA validating node proposes blocksMust Have
  • Total blocks proposed by the node in the past hour.  Metric should reset in the past hour.  
8Fork Choice TipFor something like, it would be good to show the current fork choice tip for each nodeNice to have
  • Show the hash of the block that is the current fork choice rule.

9Blocks being processed?

10Demonstration of a node operating monitoring systemNode operators will have various needs and expectations for their node monitoring system. The RChain node will not dictate the system they use. However, at launch of test net there will be an example of a node operating system to share as an example, along with documentation in the event a node operator wants to reproduce the example monitoring system.Must have
  • Create a Pyrofex node monitoring system
  • Document the system so others can create something similar.
  • This system will be created using Prometheus and Grafana
  • Needed at time of launch of test net

11Documentation on how to export metrics using PrometheusNode operators need to know how to access the Prometheus integration in the node.Must have

12Documentation on how to export metrics from metrics API using Scala

Node operators need to know how to interface with the metrics API. 

Developers need to know how to interface with the metrics API when integrating features with the node.

Must have
  • Pawel to help create a template
    • Jeremy to use template to create export for required metrics listed above
In progress. First draft at RChain RNode Metrics - Node Operator
13Metrics acceptability testingValidate exposure and pull of metrics works using both Prometheus and the metrics APIMust have 
  • Acceptable when:
    • Node comes up
    • Node emits metrics
    • Metrics are scrapable through metric API 
    • Metrics are scrapable with Prometheus
      • Metrics pulled through metric API and Prometheus match

14Integration with Docker composeSome node operators may want the option to monitor the node using Docker composeOptional
  • Integrate node with Docker compose
  • Maintain the integration over time
  • Document the integration - this is already available.

Traceability matrix

key summary type assignee reporter priority status resolution fixversions sprint

User interaction and design


Below is a list of questions to be addressed as a result of this requirements document:

What if node operators want a specific type of metrics interface?Initially we will offer Prometheus integration. It is a widely accepted monitoring interface that will be successful at scale. We do not want to be in the business of customizing the RChain node for the need of all users. Requests, however will be considered on a case-by-case basis. For example, if a large or significant end-user want integration with a different monitoring tool other than Prometheus and when the metrics API does not suffice.
Why don't we want the node to push metrics on performance?This adds complexity and will potentially reduce node performance. The best-practice is to expose raw data from the node and allow users to pull or scrape the data.
Why don't we primarily offer metrics through Docker compose?

Running a node monitoring system using Docker containers is one way. For some node operators who have limited programming experience, this may be the best way. For more experienced end-users, or developers building on the RChain platform, this is less likely to be the preferred way. 

There is also a risk related to maintaining successful integration with Docker over time. 

For these reasons, the best solution is to natively expose metrics through the metrics API for users to pull raw data. They can then choose the method that is best for them.

RNode-0.2 offers a Docker integration for metrics. Because of the maintenance issue, it may not always be a supported option for monitoring. 

Notes from Meeting:

  • Metrics are expensive - Not expensive per call.  But eventually it adds up.  Then you start pushing blocks of data - and it gets expensive.  Recommend that you start and stop metrics.  Over time these can get expensive.
  • Chris loves Prometheus for stuff.  Much simpler and great local visualization tools.   No histograms in Prometheus.  Allow Prometheus to scrape after we turn on metrics
  • Loves the tools with statsD.  it's right if you want to analyze your metrics offsite.

Not Doing