API Documentation | Graph

Graphs are the workhorse of visualizations in the system. This endpoint allows mass creation, editing and removal of graphs. Unlike other systems graphs do not store the data with them, so a graph created today or a month from now will still show the same data.

Fields

_cid string
The primary key
"/graph/ba575c89-77bd-4356-a242-58eb3f1b48a8"
A string containing a graph cid
access_keys array
Access keys allow non Circonus users to view your graphs via standalone link or embeddable URL. Various options allow for full control of a graph or a locked down view.
[]
An array
object (zero or more times)

An object
active boolean
Is this share active (accessible via the secret URL)?
Either true or false
custom_zoom_levels array

An array
string (zero or more times)

A string containing freeform text
height number
The height of the shared graph
A number containing an integer number of pixels.
key string
The secret key
A string containing freeform text
legend boolean
Should the shared graph show a legend?
Either true or false
lock_date boolean
Should the shared graph allow changing of the date period that is being viewed
Either true or false
lock_mode string
If the date range is locked, is it locked to a specific date range or zoomed to a range relative to the current time
A string containing either 'zoom', 'range' or null
lock_range_end number
When using 'range' lock_mode, the latest time viewable on the shared graph.
A positive integer that contains the number of seconds since the UNIX epoch (midnight on January 1st, 1970 in Greenwich, United Kingdom)
lock_range_start number
When using 'range' lock_mode, the earliest time viewable on the shared graph.
A positive integer that contains the number of seconds since the UNIX epoch (midnight on January 1st, 1970 in Greenwich, United Kingdom)
lock_show_times boolean

Either true or false
lock_zoom string
When using 'zoom' lock_mode, how much historic data to show on the shared graph relative to the current time
A string containing freeform text
nickname string
Private nickname for the share used in the web interface
A string containing freeform text
overlays string

A string containing freeform text
title boolean
Should the shared graph show the title?
Either true or false
width number
The width of the shared graph
A number containing an integer number of pixels.
x_labels boolean
Should the shared graph show the x labels?
Either true or false
y_labels boolean
Should the shared graph show the y labels?
Either true or false
composites array
The composites you want on your graph
[{"stack":null,"name":"Time After First Byte","legend_formula":null,"axis":"l","data_formula":"=A-B","hidden":false,"color":"#000000"}]
An array
object (zero or more times)
An individual composite on the graph and how it should be displayed
An object
axis string
which axis will the value appear on
A string containing either 'l' or 'r'
color string
The color of the line / area on the graph
A string containing a RGB hex color
data_formula string
Formula that should be aplied to both the values in the graph and the legend
A string containing freeform text
hidden boolean
Hide the datapoint and do not display it on the graph
Either true or false
legend_formula string
Formula that should be applied to values in the legend
A string containing freeform text
name string
A name which will appear in the graph legend
A string containing freeform text
stack number
If this metric is to be stacked, which stack set does it belong to (starting at 0)
A number containing an integer greater than or equal to zero
datapoints array
How the metrics are rendered on this graph
[{"alpha":null,"metric_name":"duration","color":"#ff0000","hidden":false,"derive":"gauge","name":"Total Request Time","stack":null,"legend_formula":null,"data_formula":"=VAL/1000","check_id":11641,"axis":"l","metric_type":"numeric"},{"check_id":11641,"metric_type":"numeric","axis":"l","hidden":false,"derive":"gauge","metric_name":"tt_firstbyte","color":"#00ff00","alpha":null,"data_formula":"=VAL/1000","legend_formula":null,"stack":null,"name":"Time Till First Byte"},{"metric_type":"numeric","axis":"r","check_id":11641,"stack":null,"name":"Bytes","legend_formula":null,"data_formula":null,"hidden":false,"derive":"gauge","alpha":null,"color":"#0000ff","metric_name":"bytes"}]
An array
object (zero or more times)
An individual metric on the graph and how it should be displayed
An object
axis string
which axis will the value appear on
A string containing either 'l', 'r' or null
color string
The color of the line / area on the graph
A string containing a RGB hex color
data_formula string
Formula that should be aplied to both the values in the graph and the legend
A string containing freeform text
derive string
what derivative value, if any, should be used
string containing gauge / derive / counter (_stddev)
hidden boolean
Hide the datapoint and do not display it on the graph
Either true or false
legend_formula string
Formula that should be applied to values in the legend
A string containing freeform text
metric_type string
The type of the metric
A string containing either 'numeric', 'text', 'histogram', 'composite', or 'caql'
name string
A name which will appear in the graph legend
A string containing freeform text
stack number
If this metric is to be stacked, which stack set does it belong to (starting at 0)
A number containing an integer greater than or equal to zero
alpha number
Alpha channel value
A number containing a floating point number between 0 and 1
caql string
CAQL formula
A string containing freeform text
check_id number
The check that this metric belongs to
A number containing an integer greater than or equal to zero
metric_name string
The name of the metric
A string containing freeform text
search string
Metric search query
A string containing freeform text
description string
Description of what the graph is for
"Time to first byte verses time to whole thing"
A string containing freeform text. Optional.
guides array

An array
object (zero or more times)

An object
color string
The color of the line / area on the graph
A string containing a RGB hex color
data_formula string
Formula that should be aplied to both the values in the graph and the legend
A string containing freeform text
hidden boolean
Hide the datapoint and do not display it on the graph
Either true or false
legend_formula string
Formula that will determine where on the graph this guide will display
A string containing freeform text
name string
The name of your guide
A string containing freeform text
line_style string
How the line should change between points
"interpolated"
A string containing either 'stepped', 'interpolated' or null
logarithmic_left_y number
Use a logarithmic scale on the left axis.
10
A number indicating the logarithmic base to use (or null, indicating a linear scale)
logarithmic_right_y number
Use a logarithmic scale on the right axis
null
A number indicating the logarithmic base to use (or null, indicating a linear scale)
max_left_y number
Maximum value on the left axis
null
A number
max_right_y number
Maximum value on the right axis
null
A number
metric_clusters array
Experimental feature (interface may change without warning.) The metric clusters you want on your graph
An array
object (zero or more times)
An individual metric cluster included on the graph and how it should be displayed
An object
axis string
which axis will the values appear on
A string containing either 'l' or 'r'
color string
The color of the line / area on the graph; only used if 'aggregate_function' is set
A string containing a RGB hex color
data_formula string
Formula that should be aplied to both the values in the graph and the legend
A string containing freeform text
hidden boolean
Hide the datapoints matching this cluster and do not display them on the graph
Either true or false
legend_formula string
Formula that should be applied to values in the legend
A string containing freeform text
metric_cluster string
The metric_cluster that will provide datapoints for this graph
A string containing a metric_cluster cid
name string
A name for the cluster which will appear in the graph legend when editing the graph
A string containing freeform text
stack number
If the metrics matching this cluster are to be stacked, which stack set they belong to (starting at 0)
A number containing an integer greater than or equal to zero
aggregate_function string
The aggregate function to apply across this metric cluster to create a single value
A string containing either 'none', 'min', 'max', 'sum', 'mean', 'geometric_mean' or null. Optional.
min_left_y number
Minimum value on the left axis
null
A number
min_right_y number
Minimum value on the right axis
null
A number
notes string
A place for storing notes about this graph
"This graph shows just the main webserver -- Mark"
A string containing freeform text. Optional.
overlay_sets string
Collection of Sets of Overlays; see documentation below.
{}
A string containing freeform text
style string
How the graph should be rendered
"line"
A string containing either 'area', 'line' or null
tags array
["datacenter:primary"]
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 graph
"Slow Webserver"
A string containing freeform text. Required.

Example

Fetching Graphs

Fetching details for a graph is as simple as performing a GET on the graph cid:

GET /graph/ba575c89-77bd-4356-a242-58eb3f1b48a8
{"min_left_y":null,"_cid":"/graph/ba575c89-77bd-4356-a242-58eb3f1b48a8","max_right_y":null,"datapoints":[{"stack":null,"name":"Total Request Time","legend_formula":null,"data_formula":"=VAL/1000","alpha":null,"color":"#ff0000","metric_name":"duration","hidden":false,"derive":"gauge","axis":"l","metric_type":"numeric","check_id":11641},{"derive":"gauge","hidden":false,"metric_name":"tt_firstbyte","color":"#00ff00","alpha":null,"data_formula":"=VAL/1000","legend_formula":null,"stack":null,"name":"Time Till First Byte","check_id":11641,"metric_type":"numeric","axis":"l"},{"check_id":11641,"axis":"r","metric_type":"numeric","color":"#0000ff","metric_name":"bytes","alpha":null,"derive":"gauge","hidden":false,"data_formula":null,"legend_formula":null,"stack":null,"name":"Bytes"}],"min_right_y":null,"access_keys":[],"notes":"This graph shows just the main webserver -- Mark","max_left_y":null,"logarithmic_left_y":10,"title":"Slow Webserver","line_style":"interpolated","description":"Time to first byte verses time to whole thing","logarithmic_right_y":null,"tags":["datacenter:primary"],"composites":[{"color":"#000000","hidden":false,"data_formula":"=A-B","axis":"l","legend_formula":null,"stack":null,"name":"Time After First Byte"}],"style":"line"}

There are several basic things you can see from this output:

You can also see several things about the datapoints (lines) on the graph:

Creating a Graph

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

POST /graph
{"title":"Ping Test","datapoints":[{"data_formula":null,"name":"Average Ping Time","stack":null,"legend_formula":null,"metric_name":"average","color":"#ffff00","hidden":false,"derive":"gauge","axis":"l","metric_type":"numeric","check_id":62513}]}

Updating a Graph

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

PUT /graph/748ca029-1874-46f4-9bee-b68ec5dce15a
{"title":"This is the new name for my graph"}

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

Updating a Graph: Adding Datapoints

The datapoints represent the data that should be rendered on the graph.

PUT /graph/748ca029-1874-46f4-9bee-b68ec5dce15a
{"datapoints":[{"check_id":11641,"axis":"l","metric_type":"numeric","alpha":null,"color":"#ff0000","metric_name":"duration","derive":"gauge","hidden":false,"legend_formula":null,"stack":null,"name":"Total Request Time","data_formula":"=VAL/1000"},{"axis":"l","metric_type":"numeric","check_id":11641,"data_formula":"=VAL/1000","stack":null,"legend_formula":null,"name":"Time Till First Byte","color":"#00ff00","metric_name":"tt_firstbyte","alpha":null,"hidden":false,"derive":"gauge"},{"check_id":11641,"metric_type":"numeric","axis":"r","derive":"gauge","hidden":false,"alpha":null,"color":"#00ffff","metric_name":"bytes","stack":null,"name":"Bytes","legend_formula":null,"data_formula":null}]}

Because "datapoints" is a single field you must PUT every datapoint that you want to remain on the graph back each time.

Metric Types

Circonus allows you to plot different types of metrics on the same graph. For example, you may have configured your checks to gather both numeric and histogram data of the same metric name; In this case the "metric_type" will distinguish the metrics, plotting the numeric data as a line or area graph and plotting the histogram data as a heatmap:

PUT /graph/25c1151e-2b09-4d94-8013-a4656ff5510a
{"datapoints":[{"axis":"l","metric_type":"numeric","check_id":78149,"data_formula":null,"name":"Computer load (http trap)","stack":null,"legend_formula":null,"color":"#4fa18e","metric_name":"load","alpha":null,"derive":"gauge","hidden":false},{"legend_formula":null,"stack":null,"name":"Computer load (http trap)","data_formula":null,"alpha":null,"metric_name":"load","color":"#657aa6","hidden":false,"derive":"gauge","axis":"l","metric_type":"histogram","check_id":78149}]}

It's also possible to plot text data on the same graph. The graph will show a vertical line whenever the value of the metric changes (and you'll be able to access the different value in the graph legend like any other value.)

PUT /graph/25c1151e-2b09-4d94-8013-a4656ff5510a
{"datapoints":[{"color":"#4fa18e","metric_name":"load","alpha":null,"hidden":false,"derive":"gauge","data_formula":null,"name":"Computer load (http trap)","stack":null,"legend_formula":null,"check_id":78149,"axis":"l","metric_type":"numeric"},{"data_formula":null,"stack":null,"name":"Computer load (http trap)","legend_formula":null,"color":"#657aa6","metric_name":"load","alpha":null,"derive":"gauge","hidden":false,"axis":"l","metric_type":"histogram","check_id":78149},{"check_id":78150,"axis":"l","metric_type":"text","metric_name":"load","color":"#000000","alpha":null,"hidden":false,"derive":"gauge","data_formula":null,"stack":null,"name":"User logged in","legend_formula":null}]}

Axis

Circonus graphs support showing different values on the left and right axis of the graph. This is controlled by the the "axis" property of the datapoint which may be set to "l" or "r".

PUT /graph/671590c7-48ab-4fa8-992b-42a14c234abd
{"datapoints":[{"legend_formula":null,"stack":null,"name":"Total Signed Up Users","data_formula":null,"alpha":null,"color":"#0000ff","metric_name":"users`total","derive":"gauge","hidden":false,"axis":"l","metric_type":"numeric","check_id":5987325},{"check_id":3298309,"axis":"r","metric_type":"numeric","metric_name":"s3`bytes","color":"#ff0000","alpha":null,"derive":"gauge","hidden":false,"data_formula":null,"stack":null,"legend_formula":null,"name":"Total S3 storage space"}]}

In the above example the total number of users will be displayed on the left axis and the total number of bytes stored in S3 will be displayed on the right axis.

We can also independently control what the maximum and minimum values will be limited to on each axis:

PUT /graph/671590c7-48ab-4fa8-992b-42a14c234abd
{"min_right_y":805306368,"max_left_y":90000,"max_right_y":1073741824,"min_left_y":80000}

(leaving the value at null will allow circonus to auto-size.)

If we so choose we can use a logarithmic scale on either left or right axis (or both) by setting the base we want to use:

PUT /graph/671590c7-48ab-4fa8-992b-42a14c234abd
{"logarithmic_right_y":2,"logarithmic_left_y":10}

Derive

In the previous examples we have used a "derive" type of "gauge". This causes the graph to simply render the value stored by the metric. Circonus graphs can also show how quickly the data is changing by showing the differential instead of the actual value, i.e. by how much a value is increasing or decreasing per second

The first option is to set the "derive" to "derive":

PUT /graph/2b3136c6-e723-4c2d-af23-0a5e86a066f6
{"datapoints":[{"metric_type":"numeric","axis":"l","check_id":5987325,"stack":null,"legend_formula":null,"name":"Change in number of users","data_formula":null,"hidden":false,"derive":"derive","alpha":null,"color":"#0000ff","metric_name":"users`total"}]}

In this example we're not concerned with graphing how many users have signed up to the website in total, but how many members have signed up in the last second verses how many members have quit the service.

We can also set "derive" to "counter":

PUT /graph/a843a480-f6ea-48e2-80d5-a6917d9b56ed
{"datapoints":[{"alpha":null,"color":"#0000ff","metric_name":"offset_ms","derive":"counter","hidden":false,"name":"NTP offset","stack":null,"legend_formula":null,"data_formula":null,"check_id":870091,"axis":"l","metric_type":"numeric"}]}

The renders the graph showing only the magnitude of the change, so a 20ms change in the clock drift either slower or faster than what it was before will be rendered the same way on the graph, allowing us to see how quickly the clock is drifting

Data Formulas

Data formulas allow you to do arbitrarily complex conversions to your data before you render it on the graph (this transformation only applies to the displayed data, the original data stored in circonus is untouched.)

At the simpliest it can be used to convert milliseconds into seconds:

PUT /graph/748ca029-1874-46f4-9bee-b68ec5dce15a
{"datapoints":[{"metric_type":"numeric","axis":"l","check_id":6301874,"stack":null,"name":"Time Till First Byte","legend_formula":null,"data_formula":"=VAL/1000","derive":"gauge","hidden":false,"alpha":null,"metric_name":"tt_firstbyte","color":"#0000ff"}]}

Formulas may be written in either reverse polish notation (RPN) or infix notation (more common).

To use infix notation, begin your formula with = and insert VAL as a placeholder for the data value. To use RPN you don’t need to begin your formula with any special character, but be sure to use commas to separate your numbers, operators and functions (RPN formulas automatically begin calculations with the data value, so no data value placeholder is needed).

In addition to the mathematical operators + - * / and ^, both e and pi are supported as well as the following functions:

round(a,n)
rounds a number to ‘n’ decimal places
ceil(a)
rounds a number up to the nearest integer
floor(a)
rounds a number down to the nearest integer
min(a,b)
chooses the smaller of two numbers
max(a,b)
chooses the larger of two numbers
ln(a) or log(a)
the natural logarithm of a number
log2(a)
the base 2 logarithm of a number
log10(a)
the base 10 logarithm of a number

Stacking

Circonus allows you to create stacked graphs. For example, imagine you had several metrics that show CPU usage on a machine. Rather than plotting "system" and "user" time as lines relative to the baseline Circonus can stack these on-top of one another creating both a visualization of the individual metrics but also of the total CPU use.

To create a stacked graph using the API you should set the "stack" property (which is normally null) to a number. All datapoints with the same "stack" number will be stacked on top of each other (by using different "stack" numbers circonus allows you to have multiple distinct stacks on the same graph)

PUT /graph/748ca029-1874-46f4-9bee-b68ec5dce15a
{"datapoints":[{"axis":"l","metric_type":"numeric","check_id":32786,"name":"CPU System","stack":0,"legend_formula":null,"data_formula":null,"alpha":null,"metric_name":"cpu`system","color":"#0000ff","derive":"gauge","hidden":false},{"metric_type":"numeric","axis":"l","check_id":32786,"stack":0,"legend_formula":null,"name":"CPU User","data_formula":null,"derive":"gauge","hidden":false,"alpha":null,"metric_name":"cpu`user","color":"#ff0000"},{"check_id":69843,"metric_type":"numeric","axis":"r","derive":"gauge","hidden":false,"metric_name":"http`requests`logged","color":"#000000","alpha":null,"data_formula":null,"legend_formula":null,"stack":1,"name":"Logged-in requests"},{"data_formula":null,"name":"Logged-out requests","stack":1,"legend_formula":null,"metric_name":"http`requests`unlogged","color":"#555555","alpha":null,"hidden":false,"derive":"gauge","axis":"r","metric_type":"numeric","check_id":69843}]}

In the above example we're plotting CPU usage against requests, and breaking both down using stacks into system/user and logged-in/Logged-out respectively

Updating a Graph: Adding Composites

Composites allow you to combine two or more datapoints on the same graph to make a new summary line. For example, the total refunds graph:

PUT /graph/9956520a-b8bf-454f-abcf-5085e6839fb2
{"composites":[{"color":"#ff0000","alpha":"0.3","hidden":false,"data_formula":"=A+B","stack":null,"name":"Time After First Byte","legend_formula":null,"axis":"l"}],"datapoints":[{"data_formula":null,"name":"Customer refunds due to complaints","stack":null,"legend_formula":null,"derive":"gauge","hidden":true,"metric_name":"refunds`complaints","color":"#ff0000","alpha":"0.3","metric_type":"numeric","axis":"l","check_id":876591},{"metric_type":"numeric","axis":"l","check_id":876591,"legend_formula":null,"stack":null,"name":"Customer refunds due to canceled orders","data_formula":null,"derive":"gauge","hidden":true,"alpha":"0.3","color":"#ff0000","metric_name":"refunds`canceled"}]}

In this graph the two datapoints are added together to create the composite value. Because the datapoints are hidden ("hidden" is set to true) only the composite line shows on the graph when it is rendered.

The "data_formula" for composite values works just the same as it does for datapoints, except rather than using VAL to represent the single value, you use A, B, C, etc to represent the values of the first, second, third, etc datapoint.

Updating a Graph: Adding Overlays

Overlays may be added by specifying a hash of zero or more sets of overlays with the "overlay_sets" parameter.

Here are some types of overlays you can include, together with some comments as to recommendations and requirements. Overlays will be validated and invalid overlay parameters are not permitted.

  PUT /graph/9956520a-b8bf-454f-abcf-5085e6839fb2
  {
    "overlay_sets": {
      "AbC3d": {
        "overlays":
        /*
         * ----------> Capacity Planning: Auto <----------
         */
        { "Kvf1M9":
          {
            // an alphanumeric string which is unique amongst overlays in this set
            // of overlays (we typically use six random characters)
            // REQUIRED: yes
            "id":      "Kvf1M9",
            // the data_opts and ui_specs settings objects will vary amongst the
            // overlays, but both are required
            "data_opts":{
              // REQUIRED: yes
              // ALLOWED: 'auto'
              "method":   "auto",
              // REQUIRED: yes
              // ALLOWED: 'snowth::reg_v2'
              "transform":"snowth::reg_v2"
            },
            "ui_specs": {
              // this ID must match the main ID above
              // REQUIRED: yes
              "id":   "Kvf1M9",
              // this specifies the stacking order of the overlays, with the
              // original graph being z:0 (negative values stack below the
              // original graph, positive values stack above it)
              // REQUIRED: yes
              // ALLOWED: 
              "z":     1,
              // this is the readable title of this overlay; the below value is
              // suggested for this type of overlay, but any string may be used
              // REQUIRED: yes
              "label":"Automatic",
              // this is the unique identifier for this type of overlay
              // REQUIRED: yes
              // ALLOWED: 'auto_regression'
              "type": "auto_regression",
              // whether or not to render this overlay and the original graph with
              // matching Y axes, adjusting one or both sets of Y axes if necessary
              // (decoupled == non-matching Y axes, coupled == matching Y axes)
              // REQUIRED:    no
              // DEFAULT:     false
              // ALLOWED:     true | false
              // RECOMMENDED: false (for this type of overlay)
              "decouple":false
            }
        },
        /*
         * ----------> Capacity Planning: Linear <----------
         */
        "Lvf1M9":
          {
            "id":      "Lvf1M9",
            "data_opts":{
              // REQUIRED: yes
              // ALLOWED: 'lin'
              "method":   "lin",
              // REQUIRED: yes
              // ALLOWED: 'snowth::reg_v2'
              "transform":"snowth::reg_v2"
            },
            "ui_specs": {
              // this ID must match the main ID above
              // REQUIRED: yes
              "id":   "Lvf1M9",
              // this specifies the stacking order of the overlays, with the
              // original graph being z:0 (negative values stack below the original
              // graph, positive values stack above it)
              // REQUIRED: yes
              // ALLOWED: 
              "z":     1,
              // this is the readable title of this overlay; the below value is
              // suggested for this type of overlay, but any string may be used
              // REQUIRED: yes
              "label":"Linear",
              // this is the unique identifier for this type of overlay
              // REQUIRED: yes
              // ALLOWED: 'linear_regression'
              "type": "linear_regression",
              // whether or not to render this overlay and the original graph with
              // matching Y axes, adjusting one or both sets of Y axes if necessary
              // (decoupled == non-matching Y axes, coupled == matching Y axes)
              // REQUIRED:    no
              // DEFAULT:     false
              // ALLOWED:     true | false
              // RECOMMENDED: false (for this type of overlay)
              "decouple":false
            }
        },
        /*
         * ----------> Capacity Planning: Exponential <----------
         */
        "Mvf1M9":
          {
            "id":      "Mvf1M9",
            "data_opts":{
              // REQUIRED: yes
              // ALLOWED: 'exp'
              "method":   "exp",
              // REQUIRED: yes
              // ALLOWED: 'snowth::reg_v2'
              "transform":"snowth::reg_v2"
            },
            "ui_specs": {
              // this ID must match the main ID above
              // REQUIRED: yes
              "id":   "Mvf1M9",
              // this specifies the stacking order of the overlays, with the
              // original graph being z:0 (negative values stack below the
              // original graph, positive values stack above it)
              // REQUIRED: yes
              // ALLOWED: 
              "z":     1,
              // this is the readable title of this overlay; the below value is
              // suggested for this type of overlay, but any string may be used
              // REQUIRED: yes
              "label":"Exponential",
              // this is the unique identifier for this type of overlay
              // REQUIRED: yes
              // ALLOWED: 'exponential_regression'
              "type": "exponential_regression",
              // whether or not to render this overlay and the original graph with
              // matching Y axes, adjusting one or both sets of Y axes if necessary
              // (decoupled == non-matching Y axes, coupled == matching Y axes)
              // REQUIRED:    no
              // DEFAULT:     false
              // ALLOWED:     true | false
              // RECOMMENDED: false (for this type of overlay)
              "decouple":false
            }
        },
        /*
         * ----------> Capacity Planning: Periodic <----------
         */
        "Nvf1M9":
          {
            "id":      "Nvf1M9",
            "data_opts":{
              // REQUIRED: yes
              // ALLOWED:  1
              "array_output": 1,
              // REQUIRED: yes
              // ALLOWED: 86400 (daily period) | 604800 (weekly period)
              "season_length":86400,
              // REQUIRED: yes
              // ALLOWED:  'snowth::holtwinters'
              "transform":   "snowth::holtwinters"
            },
            "ui_specs": {
              // this ID must match the main ID above
              // REQUIRED: yes
              "id":   "Nvf1M9",
              // this specifies the stacking order of the overlays, with the
              // original graph being z:0 (negative values stack below the
              // original graph, positive values stack above it)
              // REQUIRED: yes
              // ALLOWED: 
              "z":     1,
              // this is the readable title of this overlay; the below value is
              // suggested for this type of overlay, but any string may be used
              // REQUIRED: yes
              "label":"Periodic",
              // this is the unique identifier for this type of overlay
              // REQUIRED: yes
              // ALLOWED: 'periodic'
              "type": "periodic",
              // whether or not to render this overlay and the original graph with
              // matching Y axes, adjusting one or both sets of Y axes if necessary
              // (decoupled == non-matching Y axes, coupled == matching Y axes)
              // REQUIRED:    no
              // DEFAULT:     false
              // ALLOWED:     true | false
              // RECOMMENDED: false (for this type of overlay)
              "decouple":false
            }
        },
        /*
         * ----------> Anomaly Detection <----------
         */
        "Ovf1M9":
          {
            "id":      "Ovf1M9",
            "data_opts":{
              // whether to show the anomaly score as a numeric line
              // (range: 0-100), or to show the anomalous regions (time ranges
              //  when the anomaly score was 100)
              // REQUIRED: yes
              // ALLOWED:  0 (show score) | 2 (show regions)
              "alerts":       2,
              // REQUIRED: yes
              // ALLOWED: 'lua/anomaly_detection'
              "extension":   "lua/anomaly_detection",
              // this specifies which model to use in forecasting the data
              // REQUIRED:     yes
              // ALLOWED:     'auto' (automatically chooses the best model) |
              // 'constant' (values which generally stay the same) |
              // 'trending' (values which change in a linear manner) |
              // 'periodic' (values which vary by the specified period, no trends
              // assumed)
              // RECOMMENDED: 'auto'
              "model":       "auto",
              // this should be an empty string unless {model} is 'periodic'
              // REQUIRED: yes
              // ALLOWED: '' | '1w' (weekly period) | '1d' (daily period)
              "model_period":"",
              // how sensitive the model should be to variations in the forecast
              // values (lower is less sensitive, resulting in fewer anomalies)
              // REQUIRED:    yes
              // ALLOWED:     
              // MINIMUM:     0
              // MAXIMUM:     100
              // RECOMMENDED: 50
              "sensitivity":  50,
              // REQUIRED: yes
              // ALLOWED: 'snowth::anomaly_detection'
              "transform":   "snowth::anomaly_detection",
              // REQUIRED: yes
              // ALLOWED:  1
              "version":      1
            },
            "ui_specs": {
              // this ID must match the main ID above
              // REQUIRED: yes
              "id":     "Ovf1M9",
              // this specifies the stacking order of the overlays, with the
              // original graph being z:0 (negative values stack below the original
              // graph, positive values stack above it)
              // REQUIRED: yes
              // ALLOWED: 
              "z":       1,
              // this is the readable title of this overlay; the below value is
              // suggested for this type of overlay, but any string may be used
              // REQUIRED: yes
              "label":  "Anomaly Detection",
              // this is the unique identifier for this type of overlay
              // REQUIRED: yes
              // ALLOWED: 'anomaly_detection'
              "type":   "anomaly_detection",
              // whether or not to render this overlay and the original graph with
              // matching Y axes, adjusting one or both sets of Y axes if necessary
              // (decoupled == non-matching Y axes, coupled == matching Y axes)
              // REQUIRED:    no
              // DEFAULT:     false
              // ALLOWED:     true | false
              // RECOMMENDED: true (for this type of overlay)
              "decouple":true
            }
        },
        /*
         * ----------> Service Level Monitoring: Percentiles <----------
         */
        "Pvf1M9":
          {
            "id":      "Pvf1M9",
            "data_opts":{
              // REQUIRED: yes
              // ALLOWED:  0
              "base_period":   0,
              // REQUIRED: yes
              // ALLOWED: 'lua/allquantile'
              "extension":    "lua/allquantile",
              // REQUIRED: yes
              // ALLOWED: 'true'
              "in_percent":   "true",
              // REQUIRED: yes
              // ALLOWED:  0
              "inverse":       0,
              // the quantile(s) to be calculated and rendered; may contain more
              // than one if they're comma-separated
              // REQUIRED: yes
              // ALLOWED:  
              "quantiles":    "50,90,99",
              // whether to calculate a single quantile for the entire date range,
              // or smaller quantile windows (specified by {target_period} and
              // {time_offset})
              // REQUIRED: yes
              // ALLOWED:  1 | 0
              "single_value":  0,
              // if {single_value} is 0, this specifies the period of the windows
              // used to calculate the quantiles; must be an empty string if
              // {single_value} is 1
              // REQUIRED: yes
              // ALLOWED: '' | '' (any duration literal string:
              // 's' -> seconds, 'M' -> minutes, 'h' -> hours,
              // 'd' -> days... '3d 5M' === 259500 seconds)
              "target_period":"1M",
              // if {single_value} is 0, this specifies how much to offset the
              // beginning of the windows from 00:00 UTC; must be an empty string
              // if {single_value} is 1
              // REQUIRED: yes
              // ALLOWED: '' | '' (any duration literal string:
              // 's' -> seconds, 'M' -> minutes,
              // 'h' -> hours... '7h' === 25200 seconds)
              "time_offset":  "7h",
              // REQUIRED: yes
              // ALLOWED: 'snowth::allquantile'
              "transform":    "snowth::allquantile"
            },
            "ui_specs": {
              // this ID must match the main ID above
              // REQUIRED: yes
              "id":   "Pvf1M9",
              // this specifies the stacking order of the overlays, with the
              // original graph being z:0 (negative values stack below the
              // original graph, positive values stack above it)
              // REQUIRED: yes
              // ALLOWED: 
              "z":     1,
              // this is the readable title of this overlay; the below value is
              // suggested for this type of overlay, but any string may be used
              // REQUIRED: yes
              "label":"Percentiles",
              // this is the unique identifier for this type of overlay
              // REQUIRED: yes
              // ALLOWED: 'quantile'
              "type": "quantile",
              // whether or not to render this overlay and the original graph with
              // matching Y axes, adjusting one or both sets of Y axes if necessary
              // (decoupled == non-matching Y axes, coupled == matching Y axes)
              // REQUIRED:    no
              // DEFAULT:     false
              // ALLOWED:     true | false
              // RECOMMENDED: false (for this type of overlay)
              "decouple":false
            }
        },
        /*
         * ----------> Service Level Monitoring: Inverse Percentiles <----------
         */
        "Qvf1M9":
          {
            "id":      "Qvf1M9",
            "data_opts":{
              // REQUIRED: yes
              // ALLOWED:  0
              "base_period":   0,
              // REQUIRED: yes
              // ALLOWED: 'lua/allquantile'
              "extension":    "lua/allquantile",
              // REQUIRED: yes
              // ALLOWED: 'true'
              "in_percent":   "true",
              // REQUIRED: yes
              // ALLOWED:  1
              "inverse":       1,
              // the values from which to calculate quantiles; may contain more
              // than one if they're comma-separated
              // REQUIRED: yes
              // ALLOWED:  
              "quantiles":    "100,200",
              // whether to calculate a single quantile for the entire date range,
              // or smaller quantile windows (specified by {target_period} and
              // {time_offset})
              // REQUIRED: yes
              // ALLOWED:  1 | 0
              "single_value":  0,
              // if {single_value} is 0, this specifies the period of the windows
              // used to calculate the quantiles; must be an empty string if
              // {single_value} is 1
              // REQUIRED: yes
              // ALLOWED: '' | '' (any duration literal string:
              // 's' -> seconds, 'M' -> minutes, 'h' -> hours,
              // 'd' -> days... '3d 5M' === 259500 seconds)
              "target_period":"1M",
              // if {single_value} is 0, this specifies how much to offset the
              // beginning of the windows from 00:00 UTC; must be an empty string
              // if {single_value} is 1
              // REQUIRED: yes
              // ALLOWED: '' | '' (any duration literal string:
              // 's' -> seconds, 'M' -> minutes,
              // 'h' -> hours... '7h' === 25200 seconds)
              "time_offset":  "7h",
              // REQUIRED: yes
              // ALLOWED: 'snowth::allquantile'
              "transform":    "snowth::allquantile"
            },
            "ui_specs": {
              // this ID must match the main ID above
              // REQUIRED: yes
              "id":     "Qvf1M9",
              // this specifies the stacking order of the overlays, with the
              // original graph being z:0 (negative values stack below the original
              // graph, positive values stack above it)
              // REQUIRED: yes
              // ALLOWED: 
              "z":       1,
              // this is the readable title of this overlay; the below value is
              // suggested for this type of overlay, but any string may be used
              // REQUIRED: yes
              "label":  "Inverse Percentiles",
              // this is the unique identifier for this type of overlay
              // REQUIRED: yes
              // ALLOWED: 'invquantile'
              "type":   "invquantile",
              // whether or not to render this overlay and the original graph with
              // matching Y axes, adjusting one or both sets of Y axes if necessary
              // (decoupled == non-matching Y axes, coupled == matching Y axes)
              // REQUIRED:    no
              // DEFAULT:     false
              // ALLOWED:     true | false
              // RECOMMENDED: true (for this type of overlay)
              "decouple":true
            }
        },
        /*
         * ----------> Service Level Monitoring: Percentile Aggregation <----------
         */
        "Rvf1M9":
          {
            "id":      "Rvf1M9",
            "data_opts":{
              // REQUIRED: yes
              // ALLOWED:  0
              "base_period":  0,
              // REQUIRED: yes
              // ALLOWED: 'lua/allquantile'
              "extension":   "lua/allquantile",
              // REQUIRED: yes
              // ALLOWED: 'true'
              "in_percent":  "true",
              // REQUIRED: yes
              // ALLOWED:  0
              "inverse":      0,
              // the name of the preset quantiles to use (if specified, {quantiles}
              // needs to contain the corresponding value: 'min_max' -> '0,100',
              // 'box_plot' -> '0,25,50,75,100',
              // 'custom' -> '')
              // REQUIRED: no
              // ALLOWED: 'min_max' | 'box_plot' | 'custom'
              "presets":     "min_max",
              // the quantile(s) to be calculated and rendered, may contain more
              // than one if they're comma-separated
              // REQUIRED: yes
              // ALLOWED:  
              "quantiles":   "0,100"   || "0,25,50,75,100" || "",
              // REQUIRED: yes
              // ALLOWED:  0
              "single_value": 0,
              // REQUIRED: yes
              // ALLOWED:  0
              "target_period":0,
              // REQUIRED: yes
              // ALLOWED: 'snowth::allquantile'
              "transform":   "snowth::allquantile"
            },
            "ui_specs": {
              // this ID must match the main ID above
              // REQUIRED: yes
              "id":   "Rvf1M9",
              // this specifies the stacking order of the overlays, with the
              // original graph being z:0 (negative values stack below the original
              // graph, positive values stack above it)
              // REQUIRED: yes
              // ALLOWED: 
              "z":     1,
              // this is the readable title of this overlay; the below value is
              // suggested for this type of overlay, but any string may be used
              // REQUIRED: yes
              "label":"Percentile Aggregation",
              // this is the unique identifier for this type of overlay
              // REQUIRED: yes
              // ALLOWED: 'quantileagg'
              "type": "quantileagg",
              // whether or not to render this overlay and the original graph with
              // matching Y axes, adjusting one or both sets of Y axes if necessary
              // (decoupled == non-matching Y axes, coupled == matching Y axes)
              // REQUIRED:    no
              // DEFAULT:     false
              // ALLOWED:     true | false
              // RECOMMENDED: false (for this type of overlay)
              "decouple":false
            }
        },
        /*
         * ----------> Service Level Monitoring: Histogram Aggregation <----------
         */
        "Svf1M9":
          {
            "id":      "Svf1M9",
            "data_opts":{
              // REQUIRED: yes
              // ALLOWED: 'lua/histogram_aggregation'
              "extension":"lua/histogram_aggregation",
              // REQUIRED: yes
              // ALLOWED: 'snowth::histogram_aggregation'
              "transform":"snowth::histogram_aggregation"
            },
            "ui_specs": {
              // this ID must match the main ID above
              // REQUIRED: yes
              "id":     "Svf1M9",
              // this specifies the stacking order of the overlays, with the
              // original graph being z:0 (negative values stack below the original
              // graph, positive values stack above it)
              // REQUIRED: yes
              // ALLOWED: 
              "z":       1,
              // this is the readable title of this overlay; the below value is
              // suggested for this type of overlay, but any string may be used
              // REQUIRED: yes
              "label":  "Histogram Aggregation",
              // this is the unique identifier for this type of overlay
              // REQUIRED: yes
              // ALLOWED: 'histogram_agg'
              "type":   "histogram_agg",
              // whether or not to render this overlay and the original graph with
              // matching Y axes, adjusting one or both sets of Y axes if necessary
              // (decoupled == non-matching Y axes, coupled == matching Y axes)
              // REQUIRED:    no
              // DEFAULT:     false
              // ALLOWED:     true | false
              // RECOMMENDED: true (for this type of overlay)
              "decouple":true
            }
        },
        /*
         * ----------> Graph Comparison <----------
         */
        "Tvf1M9":
          {
            "id":      "Tvf1M9",
            "data_opts":{
              // the ID of the graph to be rendered (may contain the ID of the
              // current graph)
              // REQUIRED: yes
              "graph_id":   "a75df2b4-cf56-438b-b9f6-0dfc9544263e",
              // the title of the graph to be rendered (may just be "Current Graph"
              // if the current graph is being rendered again in the overlay)
              // REQUIRED: yes
              // ALLOWED: '' | 'Current Graph'
              "graph_title":"Current Graph",
              // how much to shift the date range of this graph as compared to the
              // date range of the original graph; may be an empty string to match
              // the date range of the original graph
              // REQUIRED: yes
              // ALLOWED: '' | '' (any duration literal string:
              // 's' -> seconds, 'M' -> minutes, 'h' -> hours, 'd' -> days,
              // 'm' -> months, 'y' -> years... '3d 5M' === 259500 seconds)
              "x_shift":    "" || "1d"
            },
            "ui_specs": {
              // this ID must match the main ID above
              // REQUIRED: yes
              "id":     "Tvf1M9",
              // this specifies the stacking order of the overlays, with the
              // original graph being z:0 (negative values stack below the original
              // graph, positive values stack above it)
              // REQUIRED: yes
              // ALLOWED: 
              "z":       1,
              // this is the readable title of this overlay; the below value is
              // suggested for this type of overlay, but any string may be used
              // REQUIRED: yes
              "label":  "Current Graph (Time-Shift: 1d)" || "Graph: ",
              // this is the unique identifier for this type of overlay
              // REQUIRED: yes
              // ALLOWED: 'graph_comparison'
              "type":   "graph_comparison",
              // whether or not to render this overlay and the original graph with
              // matching Y axes, adjusting one or both sets of Y axes if necessary
              // (decoupled == non-matching Y axes, coupled == matching Y axes)
              // REQUIRED:    no
              // DEFAULT:     false
              // ALLOWED:     true | false
              // RECOMMENDED: true (for other graphs) | false (for current graph)
              "decouple":true
            }
        },
        /*
         * ----------> Other: Exponential Prediction <----------
         */
        "Uvf1M9":
          {
            "id":      "Uvf1M9",
            "data_opts":{
              // how far into the future to predict, in seconds
              // REQUIRED: yes
              // ALLOWED:  
              "delay":         3600,
              // REQUIRED: yes
              // ALLOWED: 'lua/reg'
              "extension":    "lua/reg",
              // REQUIRED: yes
              // ALLOWED: 'exp'
              "method":       "exp",
              // REQUIRED: yes
              // ALLOWED: ''
              "model_end":    "",
              // REQUIRED: yes
              // ALLOWED:  1
              "model_relative":1,
              // REQUIRED: yes
              // ALLOWED: 'value'
              "out":          "value",
              // REQUIRED: yes
              // ALLOWED: 'snowth::reg'
              "transform":    "snowth::reg"
            },
            "ui_specs": {
              // this ID must match the main ID above
              // REQUIRED: yes
              "id":   "Uvf1M9",
              // this specifies the stacking order of the overlays, with the
              // original graph being z:0 (negative values stack below the original
              // graph, positive values stack above it)
              // REQUIRED: yes
              // ALLOWED: 
              "z":     1,
              // this is the readable title of this overlay; the below value is
              // suggested for this type of overlay, but any string may be used
              // REQUIRED: yes
              "label":"Exponential Prediction",
              // this is the unique identifier for this type of overlay
              // REQUIRED: yes
              // ALLOWED: 'expreg'
              "type": "expreg",
              // whether or not to render this overlay and the original graph with
              // matching Y axes, adjusting one or both sets of Y axes if necessary
              // (decoupled == non-matching Y axes, coupled == matching Y axes)
              // REQUIRED:    no
              // DEFAULT:     false
              // ALLOWED:     true | false
              // RECOMMENDED: false (for this type of overlay)
              "decouple":false
            }
        },
        /*
         * ----------> Other: Automatic Prediction <----------
         */
        "Vvf1M9":
          {
            "id":      "Vvf1M9",
            "data_opts":{
              // how far into the future to predict, in seconds
              // REQUIRED: yes
              // ALLOWED:  
              "delay":         3600,
              // REQUIRED: yes
              // ALLOWED: 'lua/reg'
              "extension":    "lua/reg",
              // REQUIRED: yes
              // ALLOWED: 'auto'
              "method":       "auto",
              // REQUIRED: yes
              // ALLOWED: ''
              "model_end":    "",
              // REQUIRED: yes
              // ALLOWED:  1
              "model_relative":1,
              // REQUIRED: yes
              // ALLOWED: 'value'
              "out":          "value",
              // REQUIRED: yes
              // ALLOWED: 'snowth::reg'
              "transform":    "snowth::reg"
            },
            "ui_specs": {
              // this ID must match the main ID above
              // REQUIRED: yes
              "id":   "Vvf1M9",
              // this specifies the stacking order of the overlays, with the
              // original graph being z:0 (negative values stack below the original
              // graph, positive values stack above it)
              // REQUIRED: yes
              // ALLOWED: 
              "z":     1,
              // this is the readable title of this overlay; the below value is
              // suggested for this type of overlay, but any string may be used
              // REQUIRED: yes
              "label":"Automatic Prediction",
              // this is the unique identifier for this type of overlay
              // REQUIRED: yes
              // ALLOWED: 'autoreg'
              "type": "autoreg",
              // whether or not to render this overlay and the original graph with
              // matching Y axes, adjusting one or both sets of Y axes if necessary
              // (decoupled == non-matching Y axes, coupled == matching Y axes)
              // REQUIRED:    no
              // DEFAULT:     false
              // ALLOWED:     true | false
              // RECOMMENDED: false (for this type of overlay)
              "decouple":false
            }
        },
        /*
         * ----------> Other: Linear Prediction <----------
         */
        "Wvf1M9":
          {
            "id":      "Wvf1M9",
            "data_opts":{
              // how far into the future to predict, in seconds
              // REQUIRED: yes
              // ALLOWED:  
              "delay":         3600,
              // REQUIRED: yes
              // ALLOWED: 'lua/reg'
              "extension":    "lua/reg",
              // REQUIRED: yes
              // ALLOWED: 'lin'
              "method":       "lin",
              // REQUIRED: yes
              // ALLOWED: ''
              "model_end":    "",
              // REQUIRED: yes
              // ALLOWED:  1
              "model_relative":1,
              // REQUIRED: yes
              // ALLOWED: 'value'
              "out":          "value",
              // REQUIRED: yes
              // ALLOWED: 'snowth::reg'
              "transform":    "snowth::reg"
            },
            "ui_specs": {
              // this ID must match the main ID above
              // REQUIRED: yes
              "id":   "Wvf1M9",
              // this specifies the stacking order of the overlays, with the
              // original graph being z:0 (negative values stack below the original
              // graph, positive values stack above it)
              // REQUIRED: yes
              // ALLOWED: 
              "z":     1,
              // this is the readable title of this overlay; the below value is
              // suggested for this type of overlay, but any string may be used
              // REQUIRED: yes
              "label":"Linear Prediction",
              // this is the unique identifier for this type of overlay
              // REQUIRED: yes
              // ALLOWED: 'linreg'
              "type": "linreg",
              // whether or not to render this overlay and the original graph with
              // matching Y axes, adjusting one or both sets of Y axes if necessary
              // (decoupled == non-matching Y axes, coupled == matching Y axes)
              // REQUIRED:    no
              // DEFAULT:     false
              // ALLOWED:     true | false
              // RECOMMENDED: false (for this type of overlay)
              "decouple":false
            }
        },
        /*
         * ----------> Other: Holt-Winters <----------
         */
        "Xvf1M9":
          {
            "id":      "Xvf1M9",
            "data_opts":{
              // REQUIRED: yes
              // ALLOWED:  1
              "array_output":1,
              // whether to use additive or multiplicative modeling
              // REQUIRED: yes
              // ALLOWED: 'add' | 'mult'
              "method":     "add" || "mult",
              // how many weeks of historical data to use in the model
              // REQUIRED:    yes
              // ALLOWED:     
              // RECOMMENDED: 2
              "prequel":     2,
              // REQUIRED: yes
              // ALLOWED: 'snowth::holtwinters'
              "transform":  "snowth::holtwinters"
            },
            "ui_specs": {
              // this ID must match the main ID above
              // REQUIRED: yes
              "id":   "Xvf1M9",
              // this specifies the stacking order of the overlays, with the
              // original graph being z:0 (negative values stack below the original
              // graph, positive values stack above it)
              // REQUIRED: yes
              // ALLOWED: 
              "z":     1,
              // this is the readable title of this overlay; the below value is
              // suggested for this type of overlay, but any string may be used
              // REQUIRED: yes
              "label":"Holt-Winters",
              // this is the unique identifier for this type of overlay
              // REQUIRED: yes
              // ALLOWED: 'SnowthHWFetch'
              "type": "SnowthHWFetch",
              // whether or not to render this overlay and the original graph with
              // matching Y axes, adjusting one or both sets of Y axes if necessary
              // (decoupled == non-matching Y axes, coupled == matching Y axes)
              // REQUIRED:    no
              // DEFAULT:     false
              // ALLOWED:     true | false
              // RECOMMENDED: false (for this type of overlay)
              "decouple":false
            }
        },
        /*
         * ----------> Other: Histogram Mode Detection (mvalue) <----------
         */
        "Yvf1M9":
          {
            "id":      "Yvf1M9",
            "data_opts":{
              // REQUIRED: yes
              // ALLOWED: 'lua/mvalue'
              "extension":"lua/mvalue",
              // REQUIRED: yes
              // ALLOWED: 'snowth::mvalue'
              "transform":"snowth::mvalue"
            },
            "ui_specs": {
              // this ID must match the main ID above
              // REQUIRED: yes
              "id":     "Yvf1M9",
              // this specifies the stacking order of the overlays, with the
              // original graph being z:0 (negative values stack below the original
              // graph, positive values stack above it)
              // REQUIRED: yes
              // ALLOWED: 
              "z":       1,
              // this is the readable title of this overlay; the below value is
              // suggested for this type of overlay, but any string may be used
              // REQUIRED: yes
              "label":  "Histogram Mode Detection (mvalue)",
              // this is the unique identifier for this type of overlay
              // REQUIRED: yes
              // ALLOWED: 'mvalue'
              "type":   "mvalue",
              // whether or not to render this overlay and the original graph with
              // matching Y axes, adjusting one or both sets of Y axes if necessary
              // (decoupled == non-matching Y axes, coupled == matching Y axes)
              // REQUIRED:    no
              // DEFAULT:     false
              // ALLOWED:     true | false
              // RECOMMENDED: true (for this type of overlay)
              "decouple":true
            }
        },
        /*
         * ----------> Other: Sliding Window <----------
         */
        "Zvf1M9":
          {
            "id":      "Zvf1M9",
            "data_opts":{
              // this specifies the period of the windows being calculated, in
              // seconds
              // REQUIRED: yes
              // ALLOWED: 
              "window":    300,
              // this specifies how much to offset the beginning of the windows,
              // in seconds
              // REQUIRED: yes
              // ALLOWED:  
              "time_shift":-3600,
              // REQUIRED: yes
              // ALLOWED: 'lua/sliding_window'
              "extension":"lua/sliding_window",
              // REQUIRED: yes
              // ALLOWED: 'snowth::sliding_window'
              "transform":"snowth::sliding_window"
            },
            "ui_specs": {
              // this ID must match the main ID above
              // REQUIRED: yes
              "id":   "Zvf1M9",
              // this specifies the stacking order of the overlays, with the
              // original graph being z:0 (negative values stack below the original
              // graph, positive values stack above it)
              // REQUIRED: yes
              // ALLOWED: 
              "z":     1,
              // this is the readable title of this overlay; the below value is
              // suggested for this type of overlay, but any string may be used
              // REQUIRED: yes
              "label":"Sliding Window",
              // this is the unique identifier for this type of overlay
              // REQUIRED: yes
              // ALLOWED: 'sliding_window'
              "type": "sliding_window",
              // whether or not to render this overlay and the original graph with
              // matching Y axes, adjusting one or both sets of Y axes if necessary
              // (decoupled == non-matching Y axes, coupled == matching Y axes)
              // REQUIRED:    no
              // DEFAULT:     false
              // ALLOWED:     true | false
              // RECOMMENDED: false (for this type of overlay)
              "decouple":false
            }
        }
        "title": "Example Overlay Sets"
      }
    }
  }

"overlay_set" overwrites the previous "overlay_set" for a graph.

The "overlay_set" parameter can also be specified as part of a POST request.

Updating a Graph: Adding a Metric Cluster

Metric Clusters on graphs are an experimental feature of Circonus; The Circonus web user interface may or may not correctly reflect the clusters you include on your graph; The API interface may change without warning

By telling your graph to include a Metric Cluster you can have Circonus search for metrics that match certain criteria and add them to your graph whenever it's displayed

PUT /graph/1f2c6ae4-7fb4-4e01-8350-596d34592dac
{"metric_clusters":[{"color":"#214da5","hidden":false,"legend_formula":null,"name":"All refund`* metrics","stack":null,"data_formula":null,"metric_cluster":"/metric_cluster/31415926","axis":"r"}]}

In this graph we're including a metric cluster that's been previously set up with the metric cluster UI on the website or via the /metric_cluster API.

It's possible to include values via the API that will be applied when rendering all the datapoints that result from the metric cluster. For example, the above call sets the axis to "r", causing all the datapoints for this cluster to have their values displayed on the the right hand side axis.

Updating a Graph: Sharing a Graph

The API allows you to manage graph sharing (sharing graphs to people who do not have Circonus accounts by using a secret URL)

The shares can be created by altering the "access_keys" field.

PUT /graph/fda34e23-2591-4978-b6a0-d38bd92c335f
{"access_keys":[{"lock_range_end":null,"legend":true,"title":true,"active":true,"lock_zoom":null,"nickname":"all webserver data","lock_date":false,"y_labels":true,"lock_range_start":null,"width":800,"x_labels":true,"lock_show_times":true,"height":600,"lock_mode":null,"key":"eBLX2z"}]}

This creates two secret URLs with whatever we put in the "key" property (in this case eBLX2z):

Because the "lock_date" was set to false anyone viewing the URL can move the start and end of the graph around, zoom in, and essentially see all the data in the account ever. You can lock this down in several ways; For example restricting the graph to only showing data from the last two days:

PUT /graph/748ca029-1874-46f4-9bee-b68ec5dce15a
{"access_keys":[{"key":"eBLX2z","lock_show_times":true,"height":600,"lock_mode":"zoom","width":800,"x_labels":true,"lock_range_start":null,"lock_date":false,"y_labels":true,"lock_zoom":"2d","nickname":"webserver data for last two days","active":true,"title":true,"legend":true,"lock_range_end":null}]}

Note that we changed "lock_date" to true, "lock_mode" to "zoom" and "lock_zoom" to "2d" to achieve this.

Another aproach could be to force the graph to only display data between two particular times (for example, creating a URL you can email to someone to highlight an area of the graph that demonstrates some problems with the systems that are being monitored):

PUT /graph/748ca029-1874-46f4-9bee-b68ec5dce15a
{"access_keys":[{"lock_zoom":"","nickname":"broken bit","active":true,"title":true,"legend":true,"lock_range_end":1383777077,"lock_show_times":true,"lock_mode":"range","height":600,"key":"eBLX2z","x_labels":true,"width":800,"lock_range_start":1383604277,"lock_date":true,"y_labels":true}]}

This time we also changed "lock_date" to true, and changed "lock_mode" to "range" and set "lock_range_start" and "lock_range_end" to the epoch seconds we're locking the user into

Revoking Shares

If we want to remove access to the graph we have three simple options:

Listing and Filtering Graphs

Graphs can be listed simply by performing a HTTP GET request on /graph. You can apply filters in the usual way, for example to list all graphs with the word "Customer" in the title and filter for a line_style of stepped.

Note on filtering, you should not use a filter without a search parameter as well, using just a filter may become unsupported in the future. Please see the section on API searching.

GET /graph?serch=*Customer*&f_line_style=stepped
[{"description":"","line_style":"stepped","logarithmic_left_y":null,"title":"Broken Customer Orders Stats Tracker","style":"area","tags":[],"composites":[],"logarithmic_right_y":null,"min_right_y":null,"guides":[],"datapoints":[{"metric_type":"numeric","axis":"l","check_id":3128,"data_formula":null,"stack":null,"name":"Failed orders per hour","legend_formula":null,"derive":"gauge","hidden":false,"metric_name":"orders`failed","color":"#ff0000","alpha":"0.3"}],"max_right_y":null,"_cid":"/graph/eafeb4fa-a242-4f63-8899-40bd0fa6d6f2","min_left_y":null,"max_left_y":null,"notes":null,"access_keys":[]},{"notes":null,"access_keys":[],"max_left_y":null,"_cid":"/graph/0b77dbb2-a209-42bb-bdb8-2037faec172c","max_right_y":null,"min_left_y":null,"datapoints":[{"check_id":93421,"axis":"l","metric_type":"numeric","color":"#ff0000","metric_name":"custserv`calls","alpha":"0.3","derive":"gauge","hidden":false,"data_formula":null,"stack":null,"name":"Customer call per five minutes","legend_formula":null}],"guides":[],"min_right_y":null,"style":"area","tags":[],"composites":[],"logarithmic_right_y":null,"line_style":"stepped","description":"","title":"Customer Calls Stats Tracker","logarithmic_left_y":null}]

Or get every graph containing the fixme tag:

GET /graph?search=(tags%3Afixme)
[{"notes":null,"access_keys":[],"max_left_y":null,"_cid":"/graph/b0854668-7fcf-4efb-95ed-383c2fb1c288","max_right_y":null,"min_left_y":null,"guides":[],"datapoints":[{"data_formula":null,"legend_formula":null,"stack":null,"name":"Bad requests logged on the webserver","metric_name":"webserver`badrequest`count","color":"#33aa33","alpha":"0.3","derive":"gauge","hidden":false,"axis":"l","metric_type":"numeric","check_id":980091}],"min_right_y":null,"style":"area","tags":["fixme"],"logarithmic_right_y":null,"composites":[],"line_style":"stepped","description":"","title":"time first byte twoshortplanks","logarithmic_left_y":null}]

Removing Graphs

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

DELETE /graph/25171dac-8354-4796-a83b-1ebdbe510f19