Echo_cli

Table of Contents

• Installation
  • Quick Start
  • Long Start
• Metrics Explained
  • Posting Data to Echo
• Usage
  • Commands
• Development
  • Testing
• Contributing
• License

Installation

Quick Start

NOTE: requires rbenv and git already installed

$ export ECHO_CLI_HOST = {ECHO_IP}
$ sudo gem install echo_cli
$ echo_cli

Replace ECHO_IP with Echo's instance IP address (e.g. 10.100.100.100)

Long Start

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

Finally, export the environment variable "ECHO_CLI_HOST", and set this value to be the IP of the Echo instance you would like to use (e.g. export ECHO_CLI_HOST=XX.XXX.XXX.XXX). This environment variable can be set inside your .bashrc file to ensure ease of use of the Echo CLI every time you create a new bash environment.

Metrics Explained

Posting data to Echo

The Echo server receives data in text format with the following syntax:

<Application_name>.<tag1>.<tag2>

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.

help

$ echo_cli help [COMMAND]

Provides a longer description and sample use case of an echo_cli command.

Example:

$ echo_cli help post

now

$ echo_cli now

Prints the current date/time in two formats: Epoch and human-readable.

Example:

$ echo_cli now

post

$ echo_cli post '<metric>' {number} {-z}

Parameters:

'<metric>': (required) the application name, as well as any tags, and data value and data type to be posted to StatsD. Note the single-quotes surrounding the metric, these are required as well.

{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

{-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 'sample.post.here:1|c' 10

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, and it would be posted 10 times.

query

$ echo_cli query '<metric>' {time_start} {time_end} {-n}

Parameters:

'<metric>': (required) the application name, including any tags, with which the query for Graphite will be constructed

{time_start}: (optional) the start of the range you are attempting to query in seconds from January 1, 1970 (epoch time)

{time_end}: (optional) the end of the range you are attempting to query in seconds from January 1, 1970 (epoch time)

{-n}: (optional) return all datapoints upon a successful query, including null datapoints

See: https://graphite-api.readthedocs.io/en/latest/api.html#from-until for possible time_start and time_end formats.

The default timestamp query range begins 15 minutes prior to the current time, to now.

Example:

$ echo_cli query 'sample.query.here:1|c' 1492464745 1492465045

The previous example will query Graphite with the application name 'sample' and tags 'query' and 'here' between the times of '1492464745' and '1492465045'.

Development (Echo Devs Only)

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.

Be sure to delete any old echo_cli-gem files before committing

$ 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.