Echo_cli
Installation
Ensure git and rbenv (or rvm, NOT both) are installed on your machine:
Verify the 'rbenv' and 'git' commands are found
$ git
$ rbenv
If you are missing git:
Install git:
$ brew update
$ brew install git
See more about git here: https://www.atlassian.com/git/tutorials/install-git
If you are missing rbenv:
Install rbenv:
$ git clone https://github.com/rbenv/rbenv.git ~/.rbenv
$ echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bash_profile
$ ~/.rbenv/bin/rbenv init
See more about rbenv here: https://github.com/rbenv/rbenv
Install 'echo_cli':
$ sudo gem install echo_cli
Test the installation to ensure it is working properly (no errors should occur if the installation was successful):
$ echo_cli
Metrics Explained
Posting data to Echo
The Echo server receives data in text format with the following syntax:
<Application_name>.<tag1>.<tag2>…<tag(n)>:<value>|<metric type>
Application name
This is the name of the application that you are sending the data from. It is what you are measuring. It must be a text string.
Tag1 – tag(n)
The database works off of tags to identify metrics. What ever tags you use will be what identifies your measurement in the database and in the front end. We recommend that you use two to three tags for each measurement type.
Value
This is a numeric value that is representative of the metric being tracked. It must be a number in text format.
Metric type
A special flag that tells the Echo server what type of data you are recording. The server will perform different calculations depending on this value. There are three types of flags that are currently supported by Echo:
- c: (Count) – Tells the Echo server that the values represent a count.
- ms: (Time Duration) – Tells the server that values represent a duration of time. The number is recorded in milliseconds and is to be transmitted as a number, not a time stamp. Note: in practice, ms does not have to represent time. It can represent any number. The system does not care, it only records.
- g: (Gauge) – Represents a Gauge function. When a number is received, the server will continue to record that number every 10 seconds until a new number is received. Note: The gauge auto repost function has been turned off in the sandbox environment. This is to reduce the amount of noise in the data as people test and configure different measurements.
Usage
View available echo_cli commands and their short descriptions:
$ echo_cli
View a command's long description and an example of its use:
$ echo_cli help [COMMAND]
Commands
convert
$ echo_cli convert <timestamp>
Parameters:
<timestamp>: (required) the timestamp you wish to convert, it can be given in either epoch time or a human-readable format. Ensure that the epoch timestamp is in seconds, and does not have any punctuation. Ensure that the human-readable timestamp is of the form: YYYY-MM-DDTHH:MM:SS (decimals may follow the SS value).
Example:
$ echo_cli convert 1492186214
The previous example will convert the provided epoch timestamp into a human-readable format.
Example:
$ echo_cli convert 2017-05-11T15:05:23-07:00
This example will convert from a human-readable timestamp to an epoch timestamp.
cpost
$ echo_cli cpost <URL> '<metric>' {frequency} {-v} {-z}
Parameters:
<URL>: (required) specifies the StatsD endpoint you are attempting to post a metric to
'<metric>': (required) the application name, as well as any tags, and data value and data type to be posted to StatsD
{frequency}: (optional) the rate at which the metric will be continuously posted to Echo's server. If left unspecified, this value will default to 10 seconds.
{-v}: (optional) continuously output a 'successfully posted' message, with updated start and end times, to the command line.
{-z}: (optional) spawn the continuous post process in the background. Additionally, this option will return a PID (Process ID) that can be used in the future to kill the command. Use kill -9 <PID> to kill the process.
Example:
$ echo_cli cpost https://localhost:8125/metrix 'example.post:1|c' 5 -z
The previous example will post the metric 'example' with tag 'post' to Echo's StatsD server instance at 'https://localhost:8125/metrix' once every 5 seconds. The specified '-z' option will spawn the process in the background, and return the newly spawned process ID in the command line.
help
$ echo_cli help [COMMAND]
Provides a longer description and sample use case of an echo_cli command.
Example:
$ echo_cli help post
post
$ echo_cli post <URL> '<metric>' {number} {-q}
Parameters:
<URL>: (required) specifies the StatsD endpoint you are attempting to post a metric to
'<metric>': (required) the application name, as well as any tags, and data value and data type to be posted to StatsD
{number}: (optional) the number of posts to occur, e.g. a number value of '10' would post the metric 10 times to the StatsD server
{-q}: (optional) does an automatic query of OpenTSDB immediately following the successful post of the metric to ensure the data transfer between StatsD and OpenTSDB. This option requires approx. 15 seconds to complete, as data flush and HA require ~15 seconds to occur
Example:
$ echo_cli https://localhost:8125/metrix 'sample.post.here:1|c' 10 -q
The previous example would post the application name 'sample' with tags 'post' and 'here' with data value '1' and with data type 'c' (for count). This information would be posted to the instance of StatsD located at 'https://localhost:8125/metrix', and it would be posted 10 times. Additionally, because of the '-q' specified option, OpenTSDB will be queried immediately after the post to StatsD, to verify it has been received by Echo's instance of OpenTSDB.
query
$ echo_cli query <URL> '<metric>' <time_start> <time_end> {-v} {-e} {-s}
Parameters:
<URL>: (required) specifies the OpenTSDB endpoint you are attempting to query
'<metric>': (required) the application name, including any tags, with which the query for OpenTSDB will be constructed
<time_start>: (required) the start of the range you are attempting to query in seconds from January 1, 1970 (epoch time)
<time_end>: (required) the end of the range you are attempting to query in seconds from January 1, 1970 (epoch time)
{-v}: (optional) verbosely prints the status code and response body of the query
{-e}: (optional) formats the response datapoints such that their timestamps are in the epoch format, must have '-v' option selected for changes to appear
{-s}: (optional) formats the response datapoints to be usable as SQL statements for insertions into SQL-esque databases, must have '-v' option selected for changes to appear
Example:
$ echo_cli https://localhost:4242/api/query 'sample.query.here' 1492464745 1492465045 -v
The previous example will query OpenTSDB with the application name 'sample' and tags 'query' and 'here' between the times of '1492464745' and '1492465045'. Additionally, the '-v' specified option will also return the response code and response body upon completion.
quick_query
$ echo_cli quick_query <URL> '<metric>' <range> {-e} {-s}
Parameters:
<URL>: (required) specifies the OpenTSDB endpoint you are attempting to query
'<metric>': (required) the application name, including any tags, with which the query for OpenTSDB will be constructed
<range>: (required) the time, in seconds, from the current time (epoch time) that you would like to query, e.g. a 'range' value of 300 would query OpenTSDB for the specified metric in the last 5 minutes of time-series data
{-e}: (optional) formats the response datapoints such that their timestamps are in the epoch format
{-s}: (optional) formats the response datapoints to be usable as SQL statements for insertions into SQL-esque databases
Example:
$ echo_cli https://localhost:4242/api/query 'sample.query.here' 300 -s
The previous example will query OpenTSDB located on 'https://localhost:4242/api/query' with the application name 'sample' and tags 'query' and 'here', within the time range spanning from the current time to '300' seconds before the current time. The '-s' option will return the data as SQL statements for later insertion into a SQL database.
Development
After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.
$ bundle install
$ git add .
$ git commit -m
$ git push
$ gem install gem-release
$ gem bump minor/major
$ rake build
$ rake install
$ rake release
$ gem install echo_cli
Testing
$ gem install webmock
$ ruby test/echo_cli_test.rb
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/echo_cli. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
License
The gem is available as open source under the terms of the MIT License.