Node metrics specification

Target release	Mercury
Epic	Monitoring and metrics for the node
Document status	COMPLETE
Document owner	Medha Parlikar (Unlicensed)
Designer
Developers
QA

Goals

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.

Assumptions

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.

Requirements

#	Title	User Story	Importance	Notes
1	Node emits metrics through the metrics API	Node operators want access to any and all metrics related to node operation and performance.	Must have	The node emits metrics Expose estensive 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
2	Demonstration of a node operating monitoring system	Node 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 Graphana Needed at time of launch of test net
3	Documentation on how to export metrics using Prometheus	Node operators need to know how to access the Prometheus integration in the node.	Must have
4	Documentation 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
5	Metrics acceptability testing	Validate exposure and pull of metrics works using both Prometheus and the metrics API	Must 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
6	Integration with Docker compose	Some node operators may want the option to monitor the node using Docker compose	Optional	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

Loading...

Refresh

User interaction and design

Questions

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

Question

Outcome

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.