API Documentation | Worksheet

Worksheets are simply a collection of graphs and allow quick correlation across them.


_cid string
The primary key
A string containing a worksheet cid
description string
Description of what the worksheet is for
"One graph per active server in our primary data center"
A string containing freeform text
favorite boolean
Mark (star) this worksheet as a favorite
Either true or false
graphs array
The graphs that compose this worksheet
An array
object (zero or more times)

An object
graph string
The graph that is in this worksheet
A string containing a graph cid
notes string
A place to store notes about this worksheet
"Currently maintained by Oscar"
A string containing freeform text
smart_queries array
The smart queries that will be displayed on this worksheet
[{"query":"virtual","order":["/graph/d75f3727-313c-427b-ab6b-a1f6f39643a4"],"name":"Virtual Machines"}]
An array
object (zero or more times)

An object
name string
The name (heading) for the smart graph section in the worksheet.
A string containing freeform text
query string
A search query that determines which graphs will be shown.
A string containing freeform text
order array
A list controlling the order in which graphs are displayed (however, graphs in this list will not be included if they do not match the query.) Graphs that match this query not explictly stated in this list will placed at the end.
An array
string (zero or more times)
A graph which may or may not match the query
A string containing a graph cid
tags array
The tags associated with this worksheet
An array of tags. The tags in the array are automatically sorted, deduplicated and transformed into their lowercase canonical form.
string (zero or more times)
An associated tag
A tag is just a string, with or without a colon, such as 'foo', 'bar', 'datacenter:london', or 'os:linux'. The part of the string before the colon is considered the category the tag is in; Tag strings without a colon will place the string in the 'uncategorized' category. Circonus will lowercase the contents of the string before storing it.
title string
The title of the worksheet
"Primary Datacenter Server Graphs"
A string containing freeform text


Fetching Worksheets

Fetching a worksheet is as simple as performing a GET on the worksheet cid:

GET /worksheet/2ea0ca3a-b317-429f-9507-d0ee6c31e3c1
{"title":"Primary Datacenter Server Graphs","graphs":[{"graph":"/graph/d5765e5e-e45b-c15c-f938-a36800b5bb66"},{"graph":"/graph/6dbc5d45-4608-49bf-a466-0ac3a4bb8f0c"},{"graph":"/graph/82fdc844-1640-4e74-bd13-9c1c3f70675c"},{"graph":"/graph/ddd6e0ba-8b1f-4f24-8e0f-89371c9a79ba"},{"graph":"/graph/5db480d2-f79d-4d4e-95ba-56bb2266a2f1"},{"graph":"/graph/9c407395-e64b-404b-8c01-e12fde42d67d"}],"_cid":"/worksheet/2ea0ca3a-b317-429f-9507-d0ee6c31e3c1","favorite":true,"description":"One graph per active server in our primary data center","notes":"Currently maintained by Oscar","smart_queries":[{"name":"Virtual Machines","order":["/graph/d75f3727-313c-427b-ab6b-a1f6f39643a4"],"query":"virtual"}],"tags":["datacenter:primary"]}

From this we can see some important things:

  • Each graph has a title (which must be unique in a given account) and two fields of user set freeform data in description and notes.
  • There's a list of graphs contained in the worksheet.
  • Worksheets can be tagged and this one has the "datacenter:primary" tag associated with it
  • Any graph that matches the search "virtual" will also be included on the worksheet under the "Virtual Machines" heading

Creating and Updating Worksheets

Creating a new worksheet is as simple as making a HTTP POST request to /worksheet and passing JSON representing the new worksheet:

POST /worksheet
{"graphs":[{"graph":"/graph/eb3edeeb-7de2-487b-9332-59d649de1ee5"},{"graph":"/graph/53c3d530-b588-488d-b7f4-4ada8612cc1b"}],"title":"things to improve this week"}

As is usual, the POST request returns the full JSON in the response (including the new worksheets's cid, and any default and read only values)

Worksheets can be updated simply by using the PUT HTTP method with new field values:

PUT /worksheet/9027419c-1bc2-4b66-98c4-6c073ef2c22a

As is normal with Circonus the PUT method returns the full JSON of the updated worksheet in response.

Smart Queries

As well as explictly including a graph in a worksheet, you can also include any graph that matches a search query (i.e. anything you might type into the search box on the graphs page.) For example to have two sections, the first that includes graphs matching the search for "good" and the second to include graphs matching the search for "bad":

PUT /worksheet/02ce6295-0eb6-482d-af51-732ab18f1396
{"smart_queries":[{"name":"All Good Graphs","query":"good"},{"query":"bad","name":"All Bad Graphs"}]}

You can also control the ordering of the graphs within the smart query section by specifying a list of graph cids:

PUT /worksheet/02ce6295-0eb6-482d-af51-732ab18f1396
{"smart_queries":[{"name":"All Good Graphs","query":"good","order":["/graph/b5e9cd11-f638-4d78-b8a2-68624abfe8ff","/graph/83649a2e-ddea-432e-a890-91908b9f39ce"]},{"name":"All Bad Graphs","query":"bad"}]}

Graphs listed in "order" will be included first before all other matching graphs in the order they were listed in the API call (though it's worth noting that if a graph doesn't match the query it won't be included in a smart query even if its cid is listed under "order".)

Listing and Searching for Worksheets

All Worksheets can be listed simply by performing a HTTP GET request on /worksheet:

GET /worksheet
[{"smart_queries":[{"order":["/graph/d75f3727-313c-427b-ab6b-a1f6f39643a4"],"query":"virtual","name":"Virtual Machines"}],"notes":"Currently maintained by Oscar","tags":["datacenter:primary"],"_cid":"/worksheet/2ea0ca3a-b317-429f-9507-d0ee6c31e3c1","graphs":[{"graph":"/graph/d5765e5e-e45b-c15c-f938-a36800b5bb66"},{"graph":"/graph/6dbc5d45-4608-49bf-a466-0ac3a4bb8f0c"},{"graph":"/graph/82fdc844-1640-4e74-bd13-9c1c3f70675c"},{"graph":"/graph/ddd6e0ba-8b1f-4f24-8e0f-89371c9a79ba"},{"graph":"/graph/5db480d2-f79d-4d4e-95ba-56bb2266a2f1"}],"title":"Primary Datacenter Server Graphs","description":"One graph per active server in our primary data center","favorite":true},{"favorite":false,"description":null,"title":"Things to get Mark to take a look at","graphs":[{"graph":"/graph/9c407395-e64b-404b-8c01-e12fde42d67d"},{"graph":"/graph/abd725b5-b787-4f89-99fe-94cb67d4f59b"}],"_cid":"/worksheet/afe1f728-05b0-418d-a29b-84da350387ad","tags":[],"smart_queries":[],"notes":null},{"description":null,"favorite":true,"_cid":"/worksheet/9027419c-1bc2-4b66-98c4-6c073ef2c22a","graphs":[{"graph":"/graph/eb3edeeb-7de2-487b-9332-59d649de1ee5"},{"graph":"/graph/53c3d530-b588-488d-b7f4-4ada8612cc1b"},{"graph":"/graph/b8b64b0b-c859-e65b-eae7-d95abdced7ff"}],"title":"things to improve this week","tags":["favorite","hitlist"],"notes":null,"smart_queries":[]}]

You search in the usual way, for example to search for a worksheet by name:

GET /worksheet?search=Primary%20Datacenter%20Server%20Graphs
[{"tags":["datacenter:primary"],"notes":"Currently maintained by Oscar","smart_queries":[{"name":"Virtual Machines","order":["/graph/d75f3727-313c-427b-ab6b-a1f6f39643a4"],"query":"virtual"}],"description":"One graph per active server in our primary data center","favorite":true,"title":"Primary Datacenter Server Graphs","graphs":[{"graph":"/graph/d5765e5e-e45b-c15c-f938-a36800b5bb66"},{"graph":"/graph/6dbc5d45-4608-49bf-a466-0ac3a4bb8f0c"},{"graph":"/graph/82fdc844-1640-4e74-bd13-9c1c3f70675c"},{"graph":"/graph/ddd6e0ba-8b1f-4f24-8e0f-89371c9a79ba"},{"graph":"/graph/5db480d2-f79d-4d4e-95ba-56bb2266a2f1"},{"graph":"/graph/9c407395-e64b-404b-8c01-e12fde42d67d"}],"_cid":"/worksheet/2ea0ca3a-b317-429f-9507-d0ee6c31e3c1"}]

Or list just those worksheets with a certain tag:

GET /worksheet?search=(tags%3Ahitlist)
[{"favorite":true,"description":null,"title":"things to improve this week","graphs":[{"graph":"/graph/eb3edeeb-7de2-487b-9332-59d649de1ee5"},{"graph":"/graph/53c3d530-b588-488d-b7f4-4ada8612cc1b"},{"graph":"/graph/b8b64b0b-c859-e65b-eae7-d95abdced7ff"}],"_cid":"/worksheet/9027419c-1bc2-4b66-98c4-6c073ef2c22a","tags":["favorite","hitlist"],"smart_queries":[],"notes":null}]

Deleting Worksheets

Worksheets can be simply removed by using the DELETE HTTP method on the cid:

DELETE /worksheet/9027419c-1bc2-4b66-98c4-6c073ef2c22a