Metric Structure

Metrics within TelemetryTV have a defined structure that must be adhered to. 

Metrics have an optional parameter of folder that allows you to specify which folder the metric will be assigned to within the TelemetryTV interface.  This folder is for organizational and permission oriented functionality.  You may omit the folder when creating a metric. 

If you specify a folder for the metric and the folder doesn't exist it will be created for you.

All metrics have a key that identifies them.  This is a unique string that is used as the default title for the widget where the metric is assigned and is used within the TelemetryTV interface to identify the metric so you may search for it and assign it to different widgets.

You must always prepend a metric with the $ sign in the API submission.  This is how the API differentiates between a metric and a parameter.  The Metric key can be 1 to 32 characters long and include the characters in the set:

Metrics have an optional bucket parameter which is a string.  This is only valid for metrics that are submitted as numbers.  Other metric types do not aggregate or keep history.

The bucket value can be either one of 'none', 'minute', 'hour', 'day', 'week', 'month' or 'year'. It defaults to 'day'.   Data is automatically bucketed and aggregated by TelemetryTV in to these intervals.  For instance with the default day parameter TelemetryTV will aggregate metrics by day: if you send a metric four times in one day then the individual values are thrown away but the last, average, maximum and minimum are kept.   This is useful for generating charts and statistics without the performance penalty of keeping all the data.

Using an optional range number parameter you can specify  how many intervals of buckets to keep the data for.    The minimum value of the range is always zero.  The default and maximum value varies based on the type of bucket.   The defaults/maximums are as follows:
Year: 10/100, Month: 12/120, Week: 4/52, Day: 30/365, Hour: 24/72, Minute: 60/300

Ranges outside of the permitted range will be set to the defaults.  

The time for a metric defaults to now.  Optionally you may specify a timestamp parameter to set the time for the metrics in the submission.  This must be a UNIX epoch timestamp integer.   Using this you can back-load data from the past to jumpstart your historical data. 

Metrics have an optional description text parameter that you may use to identify the metric to others who are using TelemetryTV.  

Value
This is the value of the metric, it always follows the metric key.

TelemetryTV supports numbers, strings, sets, tables and dictionaries.  The type of the metric will determine what metric is available for a particular widget type.   The widget types for a metric are as follows:

Numbers, Gauges

Numbers and gauges take a number:

{"$my_metric": 123} 

Tables

Tables take an array of arrays (the first array being the rows, the nested array being the columns within the row).  The values can be strings or numbers:

{"$my_metric": [["Row 1, Column 1", "Row 1, Column 2"], ["Row Two, Column 1", "Row 2 Column 2"]]}

Piechart, Barchart

Piecharts and barcharts take dictionaries (the keys are the labels and the values are the numbers):

{"$my_metric":{"foo": 123, "bar":456}}

Linechart

Linecharts take an array of numbers for a series:

{"$my_metric": [33,22,44,55,77,11]}

Tables
Tables take an array of arrays to make the table cells. 

{"$my_metric": [["One", "Two"], ["Three", "Four"]]}