yeri

Yeri is a javascript library for graphing timeseries data into an SVG, entirely in the browser. As a bonus, it can also generate a retro low-res text version, using xterm-256 colors and block characters. Timeseries can be loaded in graphite or prometheus formats, or loaded from an RRD file, as used in tools like MRTG and collectd.

This allows a webpage to dynamically fetch time series data and generate a pretty graphs, without any server code.

Yeri is used by netgraph to make simple network latency monitoring: Check out this demo.

Yeri is short for "iyeriwok", an Inuit word meaning "to stare at".

A time series graph shows time along the X axis, and some value along the Y axis. The time range is set by the range of the TimeSeries being drawn. Markers along the left and bottom edges are called "labels". Soft guide lines will be automatically generated in both dimensions. An optional title runs across the top, and an optional "legend" along the bottom can map each color to a time series name.

You can configure:

• the title, if any
• the thickness of the line, and if it should be a line or a filled shape
• if the Y axis should be grounded at 0
• if the Y axis should pin the top at a specific value
• how many horizontal (Y axis) guide lines to draw
• the size of the image, in either virtual pixels or millimeters with an aspect ratio (for SVG), or in character cells (for text)
• whether a text graph should use full character cell blocks, half-height blocks, or quarter-sized blocks
• the time zone used for the X axis
• the various fonts and colors used for each element, and padding and margins
• functions to format the X and Y axis labels, given a DateTime object for the X axis and a value for the Y axis

You can also configure "highlight zones", which are vertical bands of color that highlight particular time ranges. These can be used to indicate things like periods of excessive errors, or "business hours", things like that.

To my eye, the text version of a graph is a cute party trick, but not particularly enlightening compared to the SVG form. It may be useful for small amounts of data in terminal-based UIs and command-line tools.

API

buildSvgGraph

To generate an SVG from a set of time series:

buildSvgGraph(lines: TimeSeriesList, options: Partial<SvgGraphConfig> = {}): string

The SVG data can be embedded into HTML dynamically using code like this:

const img = document.createElement("img");
img.style.width = "100%";
img.style.height = "100%";
img.src = "data:image/svg+xml;base64," + btoa(svgData);

Options are described at the top of svg_graph.ts.

buildTextGraph

To generate text graphics from a set of time series:

buildTextGraph(lines: TimeSeriesList, options: Partial<TextGraphConfig> = {}): string

You can send this string to any xterm-256 terminal to "draw" a blocky version of the graph.

Options are described at the top of text_graph.ts.

TimeSeries / TimeSeriesList

A graph is generated from a TimeSeriesList:

export class TimeSeriesList {
  constructor(public list: TimeSeries[]) { ... }
}

and a TimeSeries is constructed from one of three sources:

// graphite data is an array of: { target: string, datapoints: Array<[ number?, number ]> }
// where each data point is a tuple of [ value, timestamp in seconds ]
const ts = TimeSeries.fromGraphite(data);

// prometheus data is an object with two fields:
//   - metric: metadata, including __name__ which names the target
//   - values: an array of tuples of [ timestamp in seconds, string representing a float value ]
const ts = TimeSeries.fromPrometheus(data);

// raw data is an array of timestamps (in seconds) and a matching array of values
const ts = TimeSeries.fromArrays(name, timestamps, values);

Any value may be undefined to represent missing or incomplete data.

Additionally, a time series may be constructed from parsing an RRD file:

// pass the RRD file's binary contents to the RrdFile constructor
const rrdFile = new RrdFile(data);
// construct a time series from the "key" in an RRD file, from startTime to endTime (in seconds)
// and optionally give it a name separate from the key
const ts = rrdFile.getTimeSeries(key, startTime, endTime, name);

License

Apache 2 (open-source) license, included in 'LICENSE.txt'.

Authors

@robey - Robey Pointer [email protected]

Why did you make an xterm-256 text version?

I don't know! The pandemic has been a weird time.