Using Metrics

What are TelemetryTV Metrics

Gersham Meharg avatar
Written by Gersham Meharg
Updated over a week ago

TelemetryTV has a feature called Metrics.  These are little bits of data that may be used within your playlist to show dynamic data elements.   Not every display requires metrics, only those which you desire to have dynamic data that changes on a regular basis.

Using metrics in your playlist allows you to create dynamic dashboards or other dynamic widgets for use within your signage.

Metrics originate from outside of TelemetryTV.  Typically a metric will be within your database, a cloud API you have access to or located on a computer within your office or datacenter.

Sending data to the Metrics App

In order to send data to telemetry you'll need to create a server that can query your data, derive a metric from the data (such as a gauge value) and then send that metric up to TelemetryTV's API for display on your dashboard.

Please see our metrics API Documentation for more information.

For instructions on how to set up a Metrics App dashboard, you can view our helpdesk article.

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.

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 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}}


Linecharts take an array of numbers for a series:

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

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

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

Did this answer your question?