Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
..
Failed to load latest commit information.
app
bin
client
lib
public
test
README.md
index.js
package.json

README.md

zag

Zag-Web serves the graphing frontend.

Setup

Start the server:

require('zag')(
{ host:        "address:port"
, db:          "postgres://postgres:1234@localhost/postgres"
, env:         "dev" or "prod"
, daemons:    ["address:port", ...]
, defaultPath: "/graph/your_favorite_metric"
, backend:     require('zag-backend-pg')
// This directory needs to be readable and writable by the process.
, public:      "/tmp/metrics-public"
}).on("error", function(err) {
  // An error occurred.
}).on("ready", function() {
  // The server is listening.
})

Features

  • Press ? for keyboard shortcuts.
  • Graphs
    • To zoom a graph, click and drag vertically or horizontally.
    • To revert the zoom, double-click the graph.
    • To pan a graph, shift click and drag.
    • To monitor a live graph, select an interval from the "minutes" row of the range picker.
  • Tree
    • Clicking on a triangle expands/collapses the keys.
    • Shift-clicking on a triangle graphs all of the key's children.
    • Shift-click on a leaf to overlay it on the current graph.
  • Tags
    • Each "tag" has a timestamp, a label, and a category. The category determines the tag color.
    • Use the admin.js script to create and manage tag categories.
    • To create a tag manually, right-click a graph's X axis.
    • To edit an existing tag, left-click it's tick mark on the X axis.
  • There is an API CLI in web/bin/admin.js.

HTTP API

Metrics

GET /api/metrics/:mkey

Get historical (not live) metrics data for a :mkey.

Querystring
  • start - Integer timestamp, required
  • end - Integer timestamp, required
  • delta - Integer milliseconds. The downsample interval (e.g. 60000, 300000, ...) optional. Defaults to 1 minute (60000).
Response: 200

The response JSON will depending on whether the data is a histogram, counter, heat map, etc.

Histogram:

[ { "ts":    Integer
  , "count": Number
  , "mean":  Number
  , "p10":   Number
  , ...
  } or { "ts": Integer, "empty": true }
, ...
]

Counter:

[ { "ts":    Integer
  , "count": Number
  } or { "ts": Integer, "empty": true }
, ...
]

Heat map: (buckets are sorted)

[ [timestamp, bucketA, frequencyA, bucketB, frequencyB, ...]
, ...
]

Keys

GET /api/keys

Get a sorted list of the top-level metrics keys.

Response: 200
[ { "key":         String
  , "hasChildren": Boolean
  , "type":       "histogram" | "counter" | "none"
  }
, ...
]

"none" is the type of the key A when data is sent to A>B, because there is no actual metrics data associated with it.

GET /api/keys/:parents

Get the children of 1 or more parent metrics keys.

:parents is a comma-separated list of metrics keys to look up.

Response: 200

Returns lists of the child keys keyed by their parents.

{ "parentkey1":
  [ { "key":         String
    , "hasChildren": Boolean
    , "type":       "histogram" | "counter" | "none"
    }
  , ...
  ]
, ...
}

DELETE /api/keys/:mkey

Delete a metrics key and all of its children. The associated metrics data is not deleted.

Response: 204

GET /api/filter

Get a list of metrics keys matching a query.

Querystring
  • q - String, the query. required
  • limit - Integer, max results optional
Response: 200
[ { "key":         String
  , "hasChildren": Boolean
  , "type":       "histogram" | "counter" | "none"
  }
, ...
]

GET /api/allkeys

Get a sorted list of all metrics keys (recursive).

Response: 200
[ "key1"
, "key2"
, "key2|bar"
, "key2|foo"
, "key3"
, ...
]

Tags

GET /api/tags

Get a list of tags in a time range, sorted by ts.

Querystring
  • begin - Integer timestamp, required
  • end - Integer timestamp, required
Response: 200
[ { "id":    String, unique tag identifier
  , "ts":    Integer, position timestamp
  , "label": String
  , "color": String, hex e.g. "#f00"
  }
, ...
]

POST /api/tags

Create a tag.

Querystring
  • ts - Integer timestamp, required
  • color - String hex color, required
  • label - String tag label, required
  • id - String, optional. If id isn't passed, it will be assigned.
Response: 204

DELETE /api/tags/:id

Delete a tag by :id.

Response: 204

Tag types

GET /api/tagtypes

List all tag types.

Response: 200
[ { "color": String
  , "name":  String
  , "id":    String
  }
, ...
]

POST /api/tagtypes

Create a tag type.

Querystring
  • color - String, e.g. "#ff0000" required
  • name - String, a short description of the category required
Response: 204

DELETE /api/tagtypes/:id

Delete a tag type by :id. The tag type's ID can by found via GET /api/tagtypes.

Response: 204

Dashboards

GET /api/dashboards

Get a sorted list of all dashboard IDs.

Response: 200
[ "dashboard1"
, "dashboard1>subdashboard"
, "dashboard2"
, ...
]

GET /api/dashboards/:id

Get a dashboard by :id.

Response: 200
{ "id": String :id
, "graphs":
  { "<graph id 1>":
    { "id":      "<graph id 1>"
    , "key":     [String metrics key]
    , "title"     String, optional
    , "subkey"    String, optional
    , "renderer"  String, optional
    , "histkeys" [String], optional
    }
  , ...
  }
}

POST /api/dashboards/:id

Replace the dashboard. The post data should be {"graphs": {all the graphs}}.

Response: 204

PATCH /api/dashboards/:id

To rename a dashboard, the request body should be {"id": "<new id>"}.

To edit a dashboard's graphs, the request body should be {"graphs": {updated graphs by graph id}}. Graphs that are not included will be left unchanged, not removed.

Response: 204

DELETE /api/dashboards/:id

Delete the dashboard by :id.

Response: 204