OpenTSDB 2.0

Formatters - GnuGraph

OpenTSDB can generate PNG graphs using GnuPlot. Data is retrieved for the query, then passed to the GnuPlot executable via a system call. The resulting graph is retrieved from disk and returned via HTTP.

Supported Functions:

Module Protocols Description
DataGet HTTP Generates a graph of the data and returns either the PNG image or JSON metadata about the graph


The default OpenTSDB GUI uses the GnuGraph formatter to generate PNG images of the requested data. After the data for a query is compiled, it's written to disk in a format GnuPlot can understand. Then a shell script is executed by the TSD that feeds the data to GnuPlot and captures any errors to disk. If the plot was successful, a new PNG image will be on disk, and if not, there will be an error returned to the user. All files are located in the configured cache directory.

By default, a call to this formatter will return JSON with some metadata about the graph including how many data points were plotted, etc. The graph can then be retrieved from the /cache endpoint. However if you add the "png" flag, this formatter will return the image directly.

A number of request options alter the graphing behavior:

Field Data Type Default Description Example
wxh String 1282x788 Determines the width and height of the PNG image. The width and height must be integers separated by a lower case "x" without spaces in between. 1024x768
yrange ? ? ? left axis ?
y2range ? ? ? right axis ?
ylabel String ? Label for the left Y axis ?
y2label String ? Label for the right Y axis ?
yformat String ? Format string for the left Y axis? ?
y2format String ? Format string for the right Y axis? ?
ylog Boolean false Enables log scaling for the left Y axis true
y2log Boolean false Enables log scaling for the right Y axis true
key ? ? ? ?
nokey Boolean false Removes the key (legend) from the graph ?
o ? ? Gnuplot options ?
png Boolean false Whether or not to return the actual graph image as a PNG file, or return the JSON metadata True

Example Query:


Example JSON response:

    "etags": [
    "plotted": 618,
    "agg_points": 618,
    "image": "15dd910.png",
    "raw_points": 1854,
    "tsuids": 3

Example Graph (retrieved by calling)


Example Graph with Annotations