Telemetry

This gem provides a wrapper around the Telemetry API (http://www.telemetryapp.com).

Installation

Install on your system:

$ gem install telemetry

Basic Usage

This gem allows you to interact with the API using simple POST, GET, PATCH, PUT, DELETE. You should use the following methods:

Telemetry::Api.delete(path)
Telemetry::Api.get(path)
Telemetry::Api.patch(path, body)
Telemetry::Api.post(path, body)
Telemetry::Api.put(path, body)

Where path is the path for the resource (for instance "/boards/:board_id") and body is a hash of the body to send to the server. You do not need to JSON encode the body, it will be converted to JSON for you.

require 'telemetry'

Telemetry.token = $YOUR_API_TOKEN
@board = Telemetry::Api.get("/boards/#{@board_id}")

Sending Data To a Flow

To use this gem you must require it in your file and specify your API Token that you can find on the Telemetry API Token page

Create a new flow object of the variant that you want to use. Use its emit method to send the data to Telemetry.

require 'telemetry'

Telemetry.token = "test-api-token"
gauge = Telemetry::Gauge.new(tag: "test-flow-gauge", value: 3434)
gauge.emit

Supported flow object variants are as follows:

Telemetry::Barchart
Telemetry::Bulletchart
Telemetry::Clock
Telemetry::Compass
Telemetry::Countdown
Telemetry::Funnelchart
Telemetry::Gauge
Telemetry::Graph
Telemetry::Grid
Telemetry::Icon
Telemetry::Iframe
Telemetry::Image
Telemetry::Log
Telemetry::Map
Telemetry::Multigauge
Telemetry::Multivalue
Telemetry::Piechart
Telemetry::Scatterplot
Telemetry::Servers
Telemetry::Status
Telemetry::Table
Telemetry::Text
Telemetry::Tickertape
Telemetry::Timechart
Telemetry::Timeline
Telemetry::Upstatus
Telemetry::Value
Telemetry::Video
Telemetry::Waterfall
Telemetry::Weather

For documentation on the different properties for the various data elements please see the data documentation pages.

Batch Updating Multiple Flows at Once

You may send data to more than one flow in a single API call. To do this construct an array of flows and use the Telemetry::Api.flow_update_batch(flows) method. A code example follows:

require 'telemetry'

Telemetry.token = "test-api-token"
flows = []
flows << Telemetry::Value.new({tag: "test-flow-value", value: 3432})
flows << Telemetry::Gauge.new({tag: "test-flow-gauge", value: 33})
Telemetry::Api.flow_update_batch(flows)

Virtual Channels

This gem supports virtual channel sending. You must have a pro or higher account to use virtual channels. In order to use this you must call:

Telemetry::Api.channel_send(unique-identifier, flow)
Telemetry::Api.channel_send_batch(unique-identifier, flows)

An example of code to do this would be:

require 'telemetry'

Telemetry.token = "test-api-token"
flow = Telemetry::Value.new(tag: "test-flow-value", value: 3434)
Telemetry::Api.channel_send("channel-tag", flow)

For more information see the virtual channel documentation.

Affiliates

This gem supports affiliate data sending. You must have an enterprise account and get support to enable your account for affiliates first. In order to use this capability call either:

Telemetry::Api.affiliate_send(affiliate-identifier, flow)
Telemetry::Api.affiliate_send_batch(affiliate-identifier, flows)

An example of code to do this would be:

require 'telemetry'

Telemetry.token = "test-api-token"
flow = Telemetry::Value.new(tag: "test-flow-value", value: 3434)
Telemetry::Api.affiliate_send("affiliate-identifier", flow)

For more information see the affiliate documentation.

Aggregations

This gem supports the aggregations API interface. Aggregations allow you to send data point by point and have Telemetry aggregate the data for you. The gem supports the following methods:

Telemetry::Api.aggregate(bucket, value)
Telemetry::Api.aggregate_set_interval(bucket, interval, values)

An example of code to do this would be:

require 'telemetry'

Telemetry.token = "test-api-token"
Telemetry::Api.aggregate("my-bucket", 23124)

For more infromation see the aggregations documentation

Daemon

Telemetry also supports a daemon mode where a binary (telemetryd) runs indefintely and loops through a configuration file triggering updates to the API as it goes.

Create a config file on your disk (by default /etc/telemetryd_config.rb). This file may have ruby code in it, you may include your own gems, etc. The file supports three configuration directives "interval", "api_token" and "flows_expire_in". The interval is how frequently each flow block is executed with the results sent to the server. The flows_expire_in sets the expiry timout of the flows. If they do not get fresh data before that period of time the board will display and expired logo on their widgets. Please note if the result from a block is unchanged from the previous execution then it will be sent to the server only once per day when flows_expire_in is not set.

For more details please see our website.

Example simple config:

interval 5            
flows_expire_in 300
api_token "test-api-token"

gauge "test-flow-gauge" do
    set value: 45
    set max: 100
end

To start the daemon daemonized:

$ telemetryd.rb -d

To kill the daemon:

$ telemetryd.rb -k

To specify a logfile:

$ telemetryd.rb -l /var/log/telemetry.log

To enable debugging output:

$ telemetryd.rb --debug

Omitting the -d will start the process in the foreground and log to stdout. This is useful for debugging your config file. The daemon can be started with -o to run once and exit. Use --debug for enhanced debug logging.

Custom update intervals are supported on a per flow basis. To configure the update interval append an integer with the number of seconds to update as per the following:

gauge "test-flow-gauge", 86400 do
    set value: 50
end

Deamon mode does not currently support encrypting values.

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request