--metrics flag when starting the Parallax client. Some metrics are classed as especially expensive and are only enabled when the --metrics.expensive flag is supplied. For example, per-packet network traffic data is considered expensive.
The goal of the Parallax client metrics system is that - similar to logs - arbitrary metric collections can be added to any part of the code without requiring fancy constructs to analyze them (counter variables, public interfaces, crossing over the APIs, console hooks, etc). Instead, metrics should be “updated” whenever and wherever needed and be automatically collected, surfaced through the APIs, queryable and visualizable for analysis.
Metric types
The Parallax client’s metrics can be classified into four types: meters, timers, counters and guages.Meters
Analogous to physical meters (electricity, water, etc), the Parallax client’s meters are capable of measuring the amount of “things” that pass through and at the rate at which they do. A meter doesn’t have a specific unit of measure (byte, block, malloc, etc), it just counts arbitrary events. At any point in time a meter can report:- Total number of events that passed through the meter
- Mean throughput rate of the meter since startup (events / second)
- Weighted throughput rate in the last 1, 5 and 15 minutes (events / second) (“weighted” means that recent seconds count more that in older ones*)
Timers
Timers are extensions of meters, the duration of an event is collected alongside a log of its occurrence. Similarly to meters, a timer can also measure arbitrary events but each requires a duration to be assigned individually. In addition generating all of the meter report types, a timer also reports:- Percentiles (5, 20, 50, 80, 95), reporting that some percentage of the events took less than the reported time to execute (e.g. Percentile 20 = 1.5s would mean that 20% of the measured events took less time than 1.5 seconds to execute; inherently 80%(=100%-20%) took more that 1.5s)
- Percentile 5: minimum durations (this is as fast as it gets)
- Percentile 50: well behaved samples (boring, just to give an idea)
- Percentile 80: general performance (these should be optimised)
- Percentile 95: worst case outliers (rare, just handle gracefully)
Counters
A counter is a single int64 value that can be incremented and decremented. The current value of the counter can be queried.Gauges
A gauge is a single int64 value. Its value can increment and decrement - as with a counter - but can also be set arbitrarily.Querying metrics
The Parallax client collects metrics if the--metrics flag is provided at startup. Those metrics are available via an HTTP server if the --metrics.addr flag is also provided. By default the metrics are served at 127.0.0.1:6060/debug/metrics but a custom IP address can be provided. A custom port can also be provided to the --metrics.port flag. More computationally expensive metrics are toggled on or off by providing or omitting the --metrics.expensive flag. For example, to serve all metrics at the default address and port:
--metrics.influxdb flag must be provided at startup. The API endpoint, username, password and other influxdb tags can also be provided. The available tags are:
http://127.0.0.1:6060/debug/metrics/prometheus URL, eg:
Creating and updating metrics
Metrics can be added easily in the Parallax client source code:NewOrRegisteredX() functions. This creates a new meter if no meter with this name is available or returns the existing meter.