Metrics are variables that can be used by widgets within boards for display of data that may change in real time as it's updated. Metrics can be numbers, text, sets, tables, or dictionaries.

When making metric requests, the metric key MUST be preceded by a '$', for example, if your metric's key is "example_key", then in the body of your request your metric would be referred to as $example_key

Creating a Metrics Collection Agent

You will need to create a piece of software that you control that can query your data sources, transform it to metrics and submit them to Telemetry's API. We call this a Metrics Collection Agent. This agent is likely deployed inside your firewall next to your data. This allows you to keep your data proprietary to you while only sending the derived metrics you need to TelemetryTV. Residing inside the firewall allows you to push these metrics out, rather than having to set up an API that something needs to reach in through the firewall to bring data out. This will help satisfy many security and compliance requirements that many organizations are required to follow for data protection.

Your Metrics Collection Agent can be written in any language you're comfortable with.

Metric Types

A metric may be of different types, encoded as JSON. Available types are numbers, text, sets, tables or dictionaries. Certain widget types expect certain types of metrics. Make sure your metric conforms to the type of metric

Numbers

Numbers are the simplest sort of Metric. They may be integers or floating point. Usually used on Gauge or Number widgets.

{"$mynumber": 902}

Text

Text contain textual content. This can be anything you like that fits in to the widget.
Our text metric also accepts a limited flavour of markup. You can set the font size and color; and bolden, italicize, and underline text when the metric displayed on a text widget.

Markup syntax options:

Color Options: { red, pink, purple, blue, cyan, green, yellow, orange, gray, white, black, #FF000 }

Size Options: ( sub, super, small, extra-small, large, extra-large )

*bold* ~italic~ _Underline_

{"$mytext": "Hello World"}
{"$big_red_text": "{red|(extra-large|Hello World)}"}
{"$big_red_text": "{#FF000|(extra-large|Hello World)}"}

Sets

Sets are arrays of data. You will send a JSON array with a string or number for each item in the array.

{"$myset": ["Alpha", "Bravo", "Charlie"]}

Tables

Tables are multidimensional arrays. This is an array containing an array. Each item represents a cell in the resulting table.
Our table metric also accepts a limited flavour of markup when being displayed using a table widget. (See the available options under the description of the Text Metric above).

{"$mytable":  [["Row1Col1", "Row1Col2"], ["Row2Col1", "Row2Col2"]]}

Dictionaries

Dictionaries are JSON dictionaries containing keys and values. The values can be numbers or strings.

{"$mydictionary": {"alpha": 1, "bravo": 2, "charlie": 3}}

Using Widgets to Visualize Metrics Data

Widgets
Widgets are Telemetry's real-time data visualization tools. They are powered by metrics, and are found within our board editor.

Widget Types:

Number

Number Widget
The number widget (unsurprisingly) takes number metrics and displays them. It can apply a transformation of the data (for example, an average or count), or just display the current value.
If the metric's bucket is set, comparison data can be displayed as well.

Accepted Metric Types:

Number:

{“$bounce_rate”:27}

Text

Text Widget
Simply displays the value of a text metric.

Accepts our markup syntax (see Text Metric for available options and examples)

Accepted Metric Types:

Text:

{"$some_text": "*_This is some text._*\nThis? This is some more text!"}

Linechart

Linechart Widget
Displays the changes of the value of a number metric over time, or plots the values of a set (equally spaced, and in order). You can choose from a variety of chart types within this widget, such as scatter plot or area.

Accepted Metric Types:

Number (with a set bucket/range):

{“$direct_traffic”:27}

Set:

{“$direct_traffic”: [27,15,41,36,42]}

Gauge

Gauge Widget
Displays the value of a number metric.

Accepted Metric Types:

Number:

{”$rps”: 10}

Table

Table Widget
Displays the value of a table metric.

Accepts our markup syntax for string fields (see Text Metric for available options and examples)

Accepted Metric Types:

Table:

{”$mediums”: [
    ["Direct-Other",145],
    ["Referral",52],
    ["Organic",48],
    ["In-app",2]]}

Piechart

Piechart Widget
Allows you to enter either a dictionary or multiple number metrics as slices for comparison as a piechart.

Accepted Metric Types:

Number:

{”$direct”: 167}

Dictionary

{”$pie_dict”:{
    "direct": 167,
	"other": 41}}

Barchart

Barchart Widget
Displays arrays of key, value pairs in a horizontal barchart.

Accepted Metric Types:

Table:

{”$mediums”: [
    ["Direct-Other",145],
    ["Referral",52],
    ["Organic",48],
    ["In-app",2]]}

Set (of dictionaries):

{"$mediums":[
    {"label": "Direct-Other","value": 145},
    {"label": "Referral","value": 52},
    {"label": "Organic","value": 48},
    {"label": "In-app","value": 2}]}

Time

Time Widget
The time widget can be given a number metric as a value type for its countdown functionality. It will interpret the number as a UNIX epoch timestamp. (Make sure to trim milliseconds off the the time.)\

Accepted Metric Types:

Number:

{”$target_time”: 1548984616}

Leaderboard

Leaderboard Widget
The leaderboard widget is used to sort and display tuples of name, description, and points.

Accepted Metric Types:

Table:

{”$employees”: [
    ["Developers","Gameplay/Systems/Tools",174],
    ["Artists","In-Game/Concept",87],
    ["Sound","Engineers/Composers",26],
    ["Producers","",31]]}

Set (of dictionaries):

{$employees: [
    {"description": "Gameplay/Systems/Tools","name": "Developers","points": 174},
    {"description": "In-Game/Concept","name": "Artists","points": 87},
    {"description": "Engineers/Composers","name": "Sound","points": 26},
    {"description": "","name": "Producers","points": 31}]}