# turtle-race

> Real-time metric graphs in the terminal

Latest version **1.0.7** (published 2016-01-26) · BSD-2-Clause license · 0 weekly downloads

## Install

```sh
npm install turtle-race
pnpm add turtle-race
yarn add turtle-race
bun add turtle-race
```

Provides the command `turtle-race`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.7 |
| Published | 2016-01-26 |
| First published | 2016-01-09 |
| Weekly downloads | 0 |
| License | BSD-2-Clause |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 7 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 8 |
| Author | Laurent Bovet |
| Maintainers | lbovet |
| Keywords | terminal, console, graph, chart, metric, statistics, real-time, timeline, time series |

## Links

- npm: https://www.npmjs.com/package/turtle-race
- Repository: https://github.com/lbovet/turtle-race
- Homepage: https://github.com/lbovet/turtle-race#readme
- Issues: https://github.com/lbovet/turtle-race/issues
- npm.io page: https://npm.io/package/turtle-race

## Dependencies (7)

- [tail](https://npm.io/package/tail.md) ^0.4.0
- [ttys](https://npm.io/package/ttys.md) 0.0.3
- [chalk](https://npm.io/package/chalk.md) ~1.1.1
- [split](https://npm.io/package/split.md) ^1.0.0
- [zibar](https://npm.io/package/zibar.md) ^1.0.14
- [blessed](https://npm.io/package/blessed.md) ~0.1.81
- [minimist](https://npm.io/package/minimist.md) ^1.2.0

## Alternatives

- [d3-force-3d](https://npm.io/package/d3-force-3d.md) — 1.0M weekly downloads
- [ng2-charts](https://npm.io/package/ng2-charts.md) — 486.8K weekly downloads
- [@arcgis/core](https://npm.io/package/@arcgis/core.md) — 257.8K weekly downloads
- [react-sparklines](https://npm.io/package/react-sparklines.md) — 249.3K weekly downloads
- [react-native-gifted-charts](https://npm.io/package/react-native-gifted-charts.md) — 182.3K weekly downloads

## Recent versions

- 1.0.7 (latest) — 2016-01-26
- 1.0.6 — 2016-01-25
- 1.0.5 — 2016-01-16
- 1.0.4 — 2016-01-16
- 1.0.2 — 2016-01-16
- 1.0.1 — 2016-01-16
- 0.15.0 — 2016-01-11
- 0.14.0 — 2016-01-11
- 0.13.0 — 2016-01-11
- 0.12.0 — 2016-01-11
- 0.11.0 — 2016-01-11
- 0.10.0 — 2016-01-11
- 0.9.0 — 2016-01-11
- 0.8.0 — 2016-01-10
- 0.7.0 — 2016-01-10
- … 6 more at https://npm.io/package/turtle-race/versions

## README

# Turtle Race
Real-time metric graphs in the terminal.

![anim](https://cloud.githubusercontent.com/assets/692124/12593996/2566ab4e-c474-11e5-8d24-bf0b5da0108f.gif)

# Installation
```
npm install turtle-race -g
```  
If you don't know what npm is, read [this](https://docs.npmjs.com/getting-started/installing-node).

# Usage
```
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>
```

Example:
```
(while true; do echo one $RANDOM; echo two $RANDOM; sleep 0.5; done) | turtle-race
```
![anim](https://cloud.githubusercontent.com/assets/692124/12594442/72240ff6-c476-11e5-88f1-8cc4630ba29b.gif)

## Keys

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

## Configuration

```javascript
{
  "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.

## Customizing

Graphs can be customized using [zibar configuration](https://www.npmjs.com/package/zibar#configuration).

## Aggregators

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
```

![marking values](https://cloud.githubusercontent.com/assets/692124/12594246/6756e784-c475-11e5-8ae6-017969efb82c.png)

# Using as a library

```
npm install turtle-race --save
```

```javascript
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.push(5.4);
metric.mark("▼");  // marker above graph
metric.mark({ symbol:"▼", color: "yellow,bold" }); // styled marker
metric.vline("white"); // vertical line
```

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

```javascript
turtle.start();
```

## Status message
A message can be displayed in the bottom line.

```javascript
turtle.message("hello");
```

## 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.

```javascript
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](https://www.npmjs.com/package/blessed), you can embed it in an existing node by specifying it as `container` parameter in the config.

---
_Source: https://npm.io/package/turtle-race · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._