Tremolo
InfluxDB UDP Tracker built on Celluloid::IO
Installation
Add this line to your application's Gemfile:
gem 'tremolo'
And then execute:
$ bundle
Or install it yourself as:
$ gem install tremolo
Is it any good?
It's getting there, but some of the nuance of the method API and Celluloid's behavior are still being worked out. I'll let you know when it's settled down a bit more.
Usage
# Start by creating a supervised tracker
# and point it at our InfluxDB server's UDP port
Tremolo.supervised_tracker(:tracker, '0.0.0.0', 4444)
# options that can be set on the tracker:
# namespace, a string prefix for all series names on this tracker, joined with '.' (default="")
tracker = Tremolo.supervised_tracker(:tracker, '0.0.0.0', 4444, namespace: 'appname')
# whenever you want to use this tracker, you can fetch it
tracker = Tremolo.fetch(:tracker)
# if there is no tracker by this name, it will return a NoopTracker
# useful when in testing or development
tracker = Tremolo.fetch(:notreallythere)Now that we have our tracker, let's send some data to InfluxDB:
# Write a point to 'series-name' series
tracker.write_point('series-name', {:value => 121, :otherdata => 998142})
# Create a series for repeated tracking
series = tracker.series('series-name')
# Write multiple points to the series with this name
series.write_point({:value => 18, :otherdata => 1986})
series.write_point({:value => 82, :otherdata => 1984})
series.write_point({:value => 11, :otherdata => 1984})
# track a value of 1 to a series
tracker.increment('count.series-name')
series = tracker.series('count.series-name')
series.increment
# track a value of -1 to a series
tracker.decrement('count.series-name')
series = tracker.series('count.series-name')
series.increment
# send some timing data
tracker.timing('timing.series-name', 48) # integer for ms
series = tracker.series('timing.series-name')
series.timing(210)
# returns the result of the block, and tracks the timing into series-name
value = tracker.time('timing.series-name') { Net::HTTP.get(URI('http://google.com')) }
series = tracker.series('timing.series-name')
value = series.time { Net::HTTP.get(URI('http://google.com')) }Tags
A Hash of tags data can be passed to increment, decrement, timing, time, and write_point, as the last argument. Very useful for segmenting data by some "metadata".
series.write_point({:value => 18}, {:otherdata => 1986})Databases, Namespace and Series names
Since version 0.7.1 of InfluxDB, multiple databases can be configured for different UDP ports. All tracking in Tremolo is done by way of UDP.
So, port 4444 from the examples above goes to one database as configured, and port 8191 could go to a second DB.
This somewhat negates the need for the namespace option to be set for a tracker since each application
could be configured to go to its own InfluxDB database.
Note If disconnected, the tracker will silently fail to send stats to InfluxDB. These stats will be lost. It will try to send each time, though. so when the server comes back up stats will begin sending again.
Some thought should be given to the design and structure of the namespace and series name. I like to have pattern like:
- use 'count.series-names' for any individual values, such as
incrementanddecrement - use 'timing.series-names' for any value tracked as milliseconds
Note The default precision is ms it appears. So far there is no way to configure time_precision when using UDP. More info here: http://influxdb.com/docs/v0.7/api/reading_and_writing_data.html#time-precision-on-written-data
Note Be careful passing data to write_point that includes the keys time or sequence_number, they have special meaning to InfluxDB: http://influxdb.com/docs/v0.7/api/reading_and_writing_data.html#specifying-time-and-sequence-number-on-writes