Real-time metric graphs in the terminal

Turtle Race

Real-time metric graphs in the terminal.

npm install turtle-race -g

If you don't know what npm is, read this.

Usage: <command> | turtle-race [-c config-file]

The turtle-race command reads metrics from the standard input. On line per value formatted as follows:

<name> <value>


(while true; do echo one $RANDOM; echo two $RANDOM; sleep 0.5; done) | turtle-race


  • Left/Right: scroll
  • Home/End: scroll to start/end
  • Ctrl-C or q: quit


  "interval": 500,                // sampling period in ms (default: 1000)
  "seconds" : true,               // shows only number of seconds since start
  "keep": true,                   // keeps showing the last value
  "pattern": "([^-]*)-(.*)",      // pattern to parse the metric name (see metric groups below)
  "metrics": {                    // specific configuration for a given metric
    "<metric-name>": {            // the metric name (without group, see below)
      "aggregator": "growth",     // function aggregating values (see aggregators below)
      "color": "yellow,bold",     // zibar configuration (see customizing below)

Metric Groups

Metrics can be grouped. By default, the group name prefixes the metric name, separated with a dot. So the metric line format is:

<group>.<name> <value>

When using a metric source with a different format, you can specify in the pattern configuration value the regular expression that will be used to parse the metric group and name. It should provide one or two capture groups, for the group name and the metric name.


Graphs can be customized using zibar configuration.


When multiples values are received during the sampling period, they are combined using an aggregator function.

  • avg (default)
  • last
  • sum
  • min
  • max
  • count

Additionally, for values that are only growing, like counters, it may be interesting to show only the difference in each sample. This is actually a non-zero derivative.

  • growth

Marking values

In addition to values, the input can contain zibar markers and styling for the current value. Example:

nginx.cpu red,bold       # styles the graph bar  
mysql.requests ▼         # place a mark above the graph
redis.memory |white      # draws a vertical line

Using as a library
npm install turtle-race --save
var config = {
  seconds : true,
  interval: 500,
  keep: true,
  pattern: "[^-]*-(.*)",
  metrics: {
    one: {
      aggregator: "growth",
      color: "yellow,bold"

var turtle = require('turtle-race')(config);

turtle.metric("one").push(5.4);  // metric without group
turtle.metric("nginx", "cpu").push(5.4); // metric with group
turtle.metric("nginx", "cpu").push(5.4).color("red,bold"); // fluent api

var metric = turtle.metric("nginx", "cpu");
metric.mark("▼");  // marker above graph
metric.mark({ symbol:"▼", color: "yellow,bold" }); // styled marker
metric.vline("white"); // vertical line


By default, the rendering starts automatically. You can control it yourself with the config parameter noAutoStart: true then start it when appropriate.


Status message

A message can be displayed in the bottom line.


Custom Aggregator Function

In the metric configuration, additionally to the named builtin aggregators, you can use a custom function. For example, an aggregator using the first value received during the sampling period.

aggregator: function(values, context) { return values[0] }

The context parameter is an object associated to the metric. You can use it to store data you want to use across calls, e.g. to implement statistics windows.

Blessed Integration

As turtle-race is based on blessed, you can embed it in an existing node by specifying it as container parameter in the config.






扫码加入 JavaScript 社区