wavefront-client 3.1.0 → 3.2.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    MjE5OWM5OWIyYjcxNWI2MGJjNGRiOWI1YjBlMjI1OWFiMzIyMWVjYg==
+    YmVlOTljMDc5ZWJkOTAwYzZiMDlhOTJhYTY3ZTI2YjRjNTBjZDliMw==
   data.tar.gz: !binary |-
-    OGJkZTg1ZTgwMDdjMmZhZDhiYjIyZDVlYmJlYzMzNGZiZDI4ZWEyOQ==
+    M2Y4ZDExZTE1NDFmNjUxZTI1NGYzOTExYzQ0ZmU2YjVhMTMzMGVmZA==
 SHA512:
   metadata.gz: !binary |-
-    YTBhNmI4OWJmOWJlM2I2NDMwYTNhNjIzMGNjZjM0OWVlMjdjMzU1YWUwNjYy
-    MTZjYjIwYjI2MDhlNDU3ZmJjYmZjODk1NmY0ZTM0OGJlMzMzMDJjZmNjN2Jk
-    MDk4N2MxODQzYzQ0MDQxMzRkY2Y2YzMwOWE3ODA3ZGFjZDA2MGM=
+    NjRmYmU4NjU2NGQ0MGIwMzU4N2Q0MjQwNzQ4NWViYTJkYTZlNjk1Njk0Mzlh
+    MWU1MTYyNDc3NzhlYzNiMDhmMjkwOWNiODExNDMwOWNlYWY5NWMzYWJhNjYw
+    ZTdiMmVlNGYzOTY1MWQxMjZjYTUyZjA4ZjZiODY2MTI0Y2ZmZjE=
   data.tar.gz: !binary |-
-    YjJhOGNmOTEyYzE1ZmRlN2JhMjNkMTgwMmVmOGU2YWJhYjY2MGRjMGVmNTFm
-    YjQwZmJhMTRhYTBhYWRmM2ViNGIyZjlhYTQ5Y2JiYzIxOTMyZTQyZDUxNTdl
-    MGNlMWVhMjNlNjkzM2U2MjAwNjdmY2QxYzgyOWExZGQyYTc2ZDE=
+    ZjUzOTZlZDlhOGY3M2NkZWU3ZDUwM2E4Y2NmNWJiNmFmZGI4MjQ4NmI1Mzk3
+    NjZiMmQ1MTE5MzAwYmRhN2NkZTI0NTVmYjkyNDM0YzNiNWViMWNiYjExNTE1
+    YmQ2ZTIzNzVmMTY4ZDJmNjI2YmQ1ZDg2NzYxMzIzZjJmYTY4N2M=

data/README-cli.md

@@ -0,0 +1,289 @@
+# Wavefront CLI
+
+`wavefront <command> [options]`
+
+The `wavefront` command provides CLI access to Wavefront. Different
+command keywords enable different functionality.
+
+## Global Options
+
+The following options are valid in almost all contexts.
+
+```
+-c, --config=FILE    path to configuration file [default: ~/.wavefront]
+-P, --profile=NAME   profile in configuration file [default: default]
+-E, --endpoint=URI   cluster endpoint [default: metrics.wavefront.com]
+-t, --token=TOKEN    Wavefront authentication token
+-D, --debug          enable debug mode
+-h, --help           show help for command
+```
+
+## `ts` Mode: Retrieving Timeseries Data
+
+The `ts` command is used to submit a standard timeseries query to
+Wavefront. It can output the timeseries data in a number of formats.
+You must specify a query granularity, and you can timebox your
+query.
+
+```
+Usage:
+  wavefront ts [-c file] [-P profile] [-E endpoint] [-t token] [-OD]
+            [-S | -m | -H | -d] [-s time] [-e time] [-f format] [-p num]
+            [-X bool] <query>
+
+Options:
+  -S, --seconds                 query granularity of seconds
+  -m, --minutes                 query granularity of minutes
+  -H, --hours                   query granularity of hours
+  -d, --days                    query granularity of days
+  -s, --start=TIME              start of query window in epoch seconds or
+                                strptime parseable format
+  -e, --end=TIME                end of query window in epoch seconds or
+                                strptime parseable format
+  -f, --format=STRING           output format (raw, ruby, graphite,
+                                highcharts, human)
+                                [default: raw]
+  -p, --prefixlength=NUM        number of path elements to treat as prefix
+                                in schema manipulation. [default: 1]
+  -X, --strict=BOOL             Do not return points outside the query
+                                window. [default: true]
+  -O, --includeObsoleteMetrics  include metrics unreported for > 4 weeks
+```
+
+The `-X` flag is now more-or-less obsolete. It was required when the
+API defaulted to returning data outside the specified query window.
+
+### Examples
+
+View ethernet traffic on the host `shark`, in one-minute buckets,
+starting at noon today, in human-readable format.
+
+```
+$ wavefront ts -f human -m --start=12:00 \
+  'ts("lab.generic.host.interface-phys.if_packets.*", source=shark)'
+query               ts("lab.generic.host.interface-phys.if_packets.*", source=shark)
+timeseries          0
+label               lab.generic.host.interface-phys.if_packets.tx
+host                shark
+2016-06-27 12:00:00 136.0
+2016-06-27 12:01:00 15.666666666666668
+2016-06-27 12:02:00 15.8
+2016-06-27 12:03:00 15.3
+2016-06-27 12:04:00 19.35
+2016-06-27 12:05:00 315.451
+2016-06-27 12:06:00 110.98316666666668
+2016-06-27 12:07:00 34.40016666666667
+2016-06-27 12:08:00 308.667
+2016-06-27 12:09:00 239.05016666666666
+2016-06-27 12:10:00 17.883333333333333
+...
+```
+
+Show all events between 6pm and 8pm today:
+
+```
+$ ./wavefront  ts -f human -m --start=18:00 --end=20:00 'events()'
+2016-06-27 16:55:59 -> 2016-06-27 16:56:40 (41s)                             new event                 [shark,box]
+2016-06-27 18:41:57 -> 2016-06-27 18:41:57 (inst)    info    alert-updated   Alert Edited: Point Rate
+2016-06-27 18:42:03 -> 2016-06-27 18:44:09 (2m 6s)   severe  alert           Point Rate                []
+2016-06-27 18:44:09 -> 2016-06-27 18:44:09 (inst)    info    alert-updated   Alert Edited: Point Rate
+2016-06-27 18:46:33 -> 2016-06-27 18:46:33 (inst)                            instantaneous_event       [box]
+2016-06-27 18:47:53 -> 2016-06-27 18:47:53 (inst)                            instantaneous_event       [box] something important just happened
+2016-06-27 19:25:16 -> 2016-06-27 19:26:32 (1m 15s)  info                    puppet_run                [box] Puppet run
+```
+
+Output is different for event queries.  The columns are: start time -> end
+time, (duration), severity, event type, [source(s)], details.
+
+## `alerts` Mode: Retrieving Alert Data
+
+The `alerts` command lets you view alerts. It does not currently
+allow creation and removal of alerts. Alert data can be presented in
+a number of formats, but defaults to a human-readable form. If you
+wish to parse the output, please use the `ruby` or `json`
+formatters.
+
+```
+Usage:
+  wavefront alerts [-c file] [-P profile] [-E endpoint] [-t token]
+            [-f format] [-p tag] [ -s tag] <state>
+
+Options:
+  -f, --format=STRING  output format (ruby, json, human)
+                       [default: human]
+  -p, --private=TAG    retrieve only alerts with named private tags,
+                       comma delimited.
+  -s, --shared=TAG     retrieve only alerts with named shared tags, comma
+                       delimited.
+```
+
+### Examples
+
+List all alerts in human-readable format. Alerts are separated by a
+single blank line.
+
+```
+$ wavefront alerts -P sysdef all
+name                  over memory cap
+created               2016-06-06 13:35:32 +0100
+severity              SMOKE
+condition             deriv(ts("prod.www.host.tenant.memory_cap.nover")) > 0
+displayExpression     ts("prod.www.host.tenant.memory_cap.nover")
+minutes               2
+resolveAfterMinutes   10
+updated               2016-06-06 13:35:32 +0100
+alertStates           CHECKING
+metricsUsed
+hostsUsed
+additionalInformation A process has pushed the instance over its memory cap.
+                      That is, the `memory_cap:nover` counter has been
+                      incremented. Check memory pressure.
+
+name                  JPC Memory Shortage
+created               2016-05-16 16:49:20 +0100
+severity              WARN
+...
+```
+
+Show alerts currently firing, in JSON format:
+
+```
+$ wavefront alerts -P sysdef --format ruby active
+"[{\"customerTagsWithCounts\":{},\"userTagsWithCounts\":{},\"created\":1459508340708,\"name\":\"Point Rate\",\"conditionQBEnabled\":false,\"displayExpressionQBEnabled\":false,\"condition\":\"sum(deriv(ts(~collector.points.valid))) > 50000\",\"displayExpression\":\"sum(deriv(ts(~collector.points.valid)))\",\"minutes\":5,\"target\":\"alerts@company.com,\",\"event\":{\"name\":\"Point Rate\",\"startTime\":1467049323203,\"annotations\":{\"severity\":\"severe\",\"type\":\"alert\",\"created\":\"1459508340708\",\"target\":\"alerts@company.com,\"},\"hosts\":[\"\"],\"table\":\"sysdef\"},\"failingHostLabelPairs\":[{\"label\":\"\",\"observed\":5,\"firing\":5}],\"updated\":1467049317802,\"severity\":\"SEVERE\",\"additionalInformation\":\"We have exceeded our agreed point rate.\",\"activeMaintenanceWindows\":[],\"inMaintenanceHostLabelPairs\":[],\"prefiringHostLabelPairs\":[],\"alertStates\":[\"ACTIVE\"],\"inTrash\":false,\"numMetricsUsed\":1,\"numHostsUsed\":1}]"
+```
+
+## `event` Mode: Opening and Closing Events
+
+The `event` command is used to open and close Wavefront events.
+
+```
+Usage:
+  wavefront event create [-V] [-c file] [-P profile] [-E endpoint] [-t token]
+           [-d description] [-s time] [-i | -e time] [-l level] [-t type]
+           [-H host] [-n] <event>
+  wavefront event close [-V] [-c file] [-P profile] [-E endpoint] [-t token]
+           [<event>] [<timestamp>]
+  wavefront event show
+  wavefront event --help
+
+Options:
+  -i, --instant        create an instantaneous event
+  -V, --verbose        be verbose
+  -s, --start=TIME     time at which event begins
+  -e, --end=TIME       time at which event ends
+  -l, --level=LEVEL    level of event (info, smoke, warn, severe)
+  -T, --type=TYPE      type of event
+  -d, --desc=STRING    description of event
+  -H, --host=STRING    list of hosts to tag with even (comma separated)
+  -n, --nostate        do not create a local file recording the event
+```
+
+To close an event in the Wavefront API it must be identified by its
+name and the millisecond time at which it was opened. This
+information is returned when the event is opened, and the
+`wavefront` command provides a handy way of caching it locally.
+
+When a non-instantaneous event is opened and no end time is
+specified, the CLI will write a file to
+`/var/tmp/wavefront/event/<username>`. The name of the file
+is the time the event was opened followed by `::`, followed by the
+name of the event. Consider the `event/` directory as a stack:
+a newly opened event is "pushed" onto the "stack". Running
+`wavefront event close` simply pops the last event off the stack and
+closes it. You can be more specific by running `wavefront event
+close <name>`, which will close the last event opened and called `name`.
+
+You can also specify the open-time when closing and event, bypassing
+the local caching mechanism altogether.
+
+The `wavefront event show` command lists the cached events. To
+properly query events, use the `events()` command in a `ts` query.
+
+### Examples
+
+Create an instantaneous alert, bound only to the host making the API
+call. Show the data returned by Wavefront.
+
+```
+$ wavefront event create -d "something important just happened" -i \
+  -V instantaneous_event
+{
+  "name": "instantaneous_event",
+  "startTime": 1467049673400,
+  "endTime": 1467049673401,
+  "annotations": {
+    "details": "something important just happened"
+  },
+  "hosts": [
+    "box"
+  ],
+  "isUserEvent": true,
+  "table": "sysdef"
+}
+```
+
+Mark a Puppet run by opening an event of `info` level, to be closed
+when the run finishes.
+
+```
+$ ./wavefront event create -P sysdef -d 'Puppet run' -l info puppet_run
+Event state recorded at /var/tmp/wavefront/events/rob/1467051916712::puppet_run.
+```
+
+The run has finished, close the event.
+
+```
+$ wavefront event close puppet_run
+Closing event 'puppet_run'. [2016-06-27 19:25:16 +0100]
+Removing state file /var/tmp/wavefront/events/rob/1467051916712::puppet_run.
+```
+
+## Notes on Options
+
+### Times
+
+Timeseries query windows and events be defined by using Unix epoch
+times (as shown by `date "%+s"`) or by entering any Ruby
+`strptime`-parseable string.  For instance:
+
+```
+$ wavefront --start 12:15 --end 12:20 ...
+```
+
+will request data points between 12:15 and 12:20pm today. If you ran
+that in the morning, the time would be invalid, and you would get a
+400 error from Wavefront, so something of the form
+`2016-04-17T12:25:00` would remove all ambiguity.
+
+There is no need to include a timezone in your time: the `wavefront`
+CLI will automatically use your local timezone when it parses the
+string.
+
+### Default Configuration
+
+Passing tokens and endpoints into the `wavefront` command can become
+tiresome, so you can put such data into an `ini`-style configuration
+file. By default this file should be located at `${HOME}/.wavefront`,
+though you can override the location with the `-c` flag.
+
+You can switch between Wavefront accounts using profile stanzas,
+selected with the `-P` option.  If `-P` is not supplied, the
+`default` profile will be used. Not having a useable configuration
+file will not cause an error.
+
+A configuration file looks like this:
+
+```
+[default]
+token = abcdefab-1234-abcd-1234-abcdefabcdef
+endpoint = companya.wavefront.com
+format = human
+
+[companyb]
+token = 12345678-abcd-0123-abcd-123456789abc
+endpoint = metrics.wavefront.com
+```
+
+The key for each key-value pair can match any long option show in the
+command `help`, so you can set, for instance, a default output
+format, as shown above.

data/README.md

@@ -1,6 +1,5 @@
-Wavefront
+Wavefront [![Build Status](https://travis-ci.org/wavefrontHQ/ruby-client.svg?branch=master)](https://travis-ci.org/wavefrontHQ/ruby-client) [![Gem Version](https://badge.fury.io/rb/wavefront-client.svg)](https://badge.fury.io/rb/wavefront-client) ![](http://ruby-gem-downloads-badge.herokuapp.com/wavefront-client?type=total)
 ==========
-[![Build Status](https://travis-ci.org/wavefrontHQ/ruby-client.svg?branch=v0.5.2)](https://travis-ci.org/wavefrontHQ/ruby-client)
 
 This is a ruby gem for speaking to the [Wavefront][1] monitoring and graphing system.
 
@@ -165,105 +164,8 @@ response.highcharts[0]['data'].first  # [1436849460000, 517160277.3333333]
 ```
 
 ### Command-line client
-A command line client is included too. You can see the full list of options by typing `wavefront --help` from a prompt.
-
-```bash
-Usage: wavefront COMMAND QUERY (OPTIONS)
-    -h, --help      Display this message
-
-Available commands:
-
-  ts       Query the timeseries
-  alerts   Query alerts
-
-See `<command> --help` for more information on a specific command.
-
-$ wavefront ts --help
-Usage: wavefront COMMAND QUERY (OPTIONS)
-    -c, --config                      path to configuration file (default: ${HOME}/.wavefront)
-    -P, --profile                     profile in configuration file (default: default)
-    -D, --debug                       Enable debug mode
-    -S, --seconds                     Query granularity of seconds
-    -m, --minutes                     Query granularity of minutes
-    -H, --hours                       Query granularity of hours
-    -d, --days                        Query granularity of days
-    -s, --start                       start of query window in epoch seconds or parseable format
-    -e, --end                         end of query window in epoch seconds or parseable format
-    -t, --token                       Wavefront authentication token
-    -E, --endpoint                    Connect to alternative cluster endpoint (default: metrics.wavefront.com)
-    -f, --format                      Output format (raw, ruby, graphite, highcharts, human) (default: raw)
-    -p, --prefixlength                The number of path elements to treat as a prefix when doing schema manipulations (default: 1)
-    -X, --strict                      Flag to not return points outside the query window [q;s)  (default: true)
-    -O, --includeObsoleteMetrics      Flag to include metrics that have not been reporting for more than 4 weeks,defaults to false
-    -h, --help                        Display this message
-
-$ wavefront ts "ts(my.metric.path.host.cpu-0.percent-idle)" -t SECRET -m -f ruby
-#<Wavefront::Response::Ruby:0x007f02f6bf9d70
- @granularity=60,
- @name="Unknown",
- @options=
-  {:response_format=>:ruby,
-   :prefix_length=>1,
-
-   ...
-
-$ wavefront alerts snoozed -t TOKEN -f json --shared ops
-[
-  {
-    "customerTagsWithCounts": {
-
-   ...
-```
-
-#### Notes on Options
-
-##### Times
-
-The query window can be defined by using Unix epoch times (as shown
-by `date "%+s"`) or by entering any Ruby `strptime`-parseable string.
-For instance:
-
-```bash
-$ wavefront --start 12:15 --end 12:20 ...
-```
-
-will request data points between 12:15 and 12:20pm today. If you ran
-that in the morning, the time would be invalid, and you would get a
-400 error from Wavefront, so something of the form
-`2016-04-17T12:25:00` would remove all ambiguity.
-
-There is no need to include a timezone in your parseable string: the
-`wavefront` CLI will automatically use your local timezone when it
-parses the string.
-
-#### Default Configuration
-
-Passing tokens and endpoints into the `wavefront` command can become
-tiresome, so you can put such data into an `ini`-style configuration
-file. By default this file should be located at `${HOME}/.wavefront`,
-though you can override the location with the `-c` flag.
-
-You can switch between Wavefront accounts using profile stanzas,
-selected with the `-P` option.  If `-P` is not supplied, the
-`default` profile will be used. Not having a useable configuration
-file will not cause an error.
-
-A configuration file looks like this:
-
-```
-[default]
-token = abcdefab-1234-abcd-1234-abcdefabcdef
-endpoint = companya.wavefront.com
-format = human
-
-[companyb]
-token = 12345678-abcd-0123-abcd-123456789abc
-endpoint = metrics.wavefront.com
-```
-
-The key for each key-value pair can match any long option show in the
-command `help`, so you can set, for instance, a default output
-format, as shown above.
+A command line client is included too. Please see [README-cli.md]
+for details.
 
 ## Building and installing
 

data/bin/wavefront

@@ -13,93 +13,153 @@
 # See the License for the specific language governing permissions and
 #    limitations under the License.
 #
-require 'wavefront/client'
-require 'slop'
+
 require 'pathname'
+require 'wavefront/client'
 require 'wavefront/cli'
+require 'docopt'
+include Wavefront::Constants
 
-begin
-options = Slop.parse(strict: true) do
-  banner 'Usage: wavefront COMMAND QUERY (OPTIONS)'
-    on 'h', 'help', 'Display this message'
-
-  command :version do
-    description 'Display the client version and exit'
-    run do
-      puts Wavefront::Client::VERSION
-      exit 0
-    end
+def sanitize_keys(hash)
+  hash.each_with_object({}) do |(k, v), aggr|
+    aggr[k.gsub(/-/, '').to_sym] = v
   end
+end
 
-  command 'ts' do
-    description "Query the timeseries"
-    on 'c', 'config=', 'path to configuration file', default:
-                      Pathname.new(ENV['HOME']) + '.wavefront'
-    on 'P', 'profile=', 'profile in configuration file', default: 'default'
-    on 'D', 'debug', 'Enable debug mode'
-    on 'S', 'seconds', 'Query granularity of seconds'
-    on 'm', 'minutes', 'Query granularity of minutes'
-    on 'H', 'hours', 'Query granularity of hours'
-    on 'd', 'days', 'Query granularity of days'
-    on 's', 'start=', 'start of query window in epoch seconds or parseable format'
-    on 'e', 'end=', 'end of query window in epoch seconds or parseable format'
-    on 't', 'token=', 'Wavefront authentication token'
-    on 'E', 'endpoint=', 'Connect to alternative cluster endpoint', default: Wavefront::Client::DEFAULT_HOST.to_s
-    on 'f', 'format=', "Output format (#{Wavefront::Client::FORMATS.join(', ')})", default: Wavefront::Client::DEFAULT_FORMAT.to_s
-    on 'p', 'prefixlength=', 'Number of path elements to treat as a prefix in schema manipulation', default: Wavefront::Client::DEFAULT_PREFIX_LENGTH
-    on 'X', 'strict=','Flag to not return points outside the query window [q;s) ', default: Wavefront::Client::DEFAULT_STRICT
-    on 'O', 'includeObsoleteMetrics=', 'Include metrics which have not reported for > 4 weeks', default: Wavefront::Client::DEFAULT_OBSOLETE_METRICS
-    on 'h', 'help', 'Display this message'
-    run do |options, arguments|
-      pf_opts = Wavefront::Cli.new(options, arguments).load_profile || {}
-      require 'wavefront/cli/ts'
-      cli = Wavefront::Cli::Ts.new(options.to_hash.merge(pf_opts), arguments)
-      begin
-        cli.run
-      rescue => e
-        puts 'Timeseries query failed.'
-        puts e
-        exit 1
-      end
-    end
-  end
+ME = Pathname.new(__FILE__).basename
+DEF_CF = Pathname.new(ENV['HOME']) + '.wavefront'
+
+# The global_opts are available in every command.
+#
+global_opts = %Q(
+Global options:
+  -c, --config=FILE    path to configuration file [default: #{DEF_CF}]
+  -P, --profile=NAME   profile in configuration file [default: default]
+  -E, --endpoint=URI   cluster endpoint [default: #{DEFAULT_HOST}]
+  -t, --token=TOKEN    Wavefront authentication token
+  -D, --debug          enable debug mode
+  -h, --help           show this message
+)
+
+# The following hash contains the docopt strings defining all the
+# commands we offer. They must include the global_opts.
+#
+usage = {
+ts: %Q(
+Usage:
+  #{ME} ts [-c file] [-P profile] [-E endpoint] [-t token] [-OD]
+            [-S | -m | -H | -d] [-s time] [-e time] [-f format] [-p num]
+            [-X bool] <query>
+#{global_opts}
+Options:
+  -S, --seconds                 query granularity of seconds
+  -m, --minutes                 query granularity of minutes
+  -H, --hours                   query granularity of hours
+  -d, --days                    query granularity of days
+  -s, --start=TIME              start of query window in epoch seconds or
+                                strptime parseable format
+  -e, --end=TIME                end of query window in epoch seconds or
+                                strptime parseable format
+  -f, --format=STRING           output format (#{FORMATS.join(', ')})
+                                [default: #{DEFAULT_FORMAT}]
+  -p, --prefixlength=NUM        number of path elements to treat as prefix
+                                in schema manipulation. [default: #{DEFAULT_PREFIX_LENGTH}]
+  -X, --strict=BOOL             Do not return points outside the query
+                                window. [default: #{DEFAULT_STRICT}]
+  -O, --includeObsoleteMetrics  include metrics unreported for > 4 weeks
+),
+
+alerts: %Q(
+Usage:
+  #{ME} alerts [-c file] [-P profile] [-E endpoint] [-t token]
+            [-f format] [-p tag] [ -s tag] <state>
+#{global_opts}
+Options:
+  -f, --format=STRING  output format (#{ALERT_FORMATS.join(', ')})
+                       [default: #{DEFAULT_ALERT_FORMAT}]
+  -p, --private=TAG    retrieve only alerts with named private tags,
+                       comma delimited.
+  -s, --shared=TAG     retrieve only alerts with named shared tags, comma
+                       delimited.
+),
 
-  command 'alerts' do
-    banner 'Usage: wavefront alerts (OPTIONS) ALERT_STATE'
-    description "Query alerts"
-    on 'c', 'config=', 'path to configuration file', default:
-                      Pathname.new(ENV['HOME']) + '.wavefront'
-    on 'P', 'profile=', 'profile in configuration file', default: 'default'
-    on 'E', 'endpoint=', 'Connect to alternative cluster endpoint', default: Wavefront::Client::DEFAULT_HOST.to_s
-    on 'f', 'format=', 'Output format (ruby, json)', default: 'ruby'
-    on 'f', 'format=', "Output format (#{Wavefront::Client::ALERT_FORMATS.join(', ')})", default: Wavefront::Client::DEFAULT_ALERT_FORMAT.to_s
-    on 'h', 'help', 'Display this message'
-    on 'p', 'private=', 'Retrieve only alerts with named private tags, comma delimited.'
-    on 's', 'shared=', 'Retrieve only alerts with named shared tags, comma delimited.'
-    on 't', 'token=', 'Wavefront authentication token'
-    run do |options, arguments|
-      pf_opts = Wavefront::Cli.new(options, arguments).load_profile || {}
-      require 'wavefront/cli/alerts'
-      cli = Wavefront::Cli::Alerts.new(options.to_hash.merge(pf_opts),
-                                       arguments)
-      begin
-        cli.run
-      rescue => e
-        puts 'Alert query failed.'
-        puts e
-        exit 1
-      end
+event: %Q(
+Usage:
+  #{ME} event create [-V] [-c file] [-P profile] [-E endpoint] [-t token]
+           [-d description] [-s time] [-i | -e time] [-l level] [-t type]
+           [-H host] [-n] <event>
+  #{ME} event close [-V] [-c file] [-P profile] [-E endpoint] [-t token]
+           [<event>] [<timestamp>]
+  #{ME} event show
+  #{ME} event --help
+#{global_opts}
+Options:
+  -i, --instant        create an instantaneous event
+  -V, --verbose        be verbose
+  -s, --start=TIME     time at which event begins
+  -e, --end=TIME       time at which event ends
+  -l, --level=LEVEL    level of event (#{EVENT_LEVELS.join(', ')})
+  -T, --type=TYPE      type of event
+  -d, --desc=STRING    description of event
+  -H, --host=STRING    list of hosts to tag with even (comma separated)
+  -n, --nostate        do not create a local file recording the event
+
+View events in detail using the 'ts' command with the 'events()' function.
+),
+default: %Q(
+Wavefront CLI
+
+Usage:
+  #{ME} [options] command [options]
+  #{ME} --version
+  #{ME} --help
+
+Commands:
+  ts          view timeseries data
+  alerts      view alerts
+  event       open and close events
+
+Use '#{ME} <command> --help' for further information.)
+}
+
+# Parse the input. We have to do this twice because of the nested
+# help/option parser generation.
+#
+begin
+  opts = Docopt::docopt(usage[:default], version: '3.2.0')
+rescue Docopt::Exit => e
+  cmd = ARGV.length > 0 ? ARGV.first.to_sym : nil
+
+  if usage.keys.include?(cmd)
+    begin
+      opts = sanitize_keys(Docopt::docopt(usage[cmd]))
+    rescue Docopt::Exit => e
+      abort e.message
     end
+  else
+    abort e.message
   end
+end
 
+# Load the config file. Values in there take priority. Probably
+# should be the other way round.
+#
+opts.merge!(Wavefront::Cli.new(opts, nil).load_profile || {})
 
-end
-rescue Slop::InvalidOptionError => e
-  puts 'invalid option error: '+ e.to_s
-  exit 1
-rescue Slop::MissingArgumentError => e
-  puts 'option parsing error: '+ e.to_s
-  exit 1
+case cmd
+when :ts
+  require 'wavefront/cli/ts'
+  cli = Wavefront::Cli::Ts.new(opts, [opts[:'<query>']])
+when :event
+  require 'wavefront/cli/events'
+  cli = Wavefront::Cli::Events.new(opts, [opts[:'<query>']])
+when :alerts
+  require 'wavefront/cli/alerts'
+  cli = Wavefront::Cli::Alerts.new(opts, [opts[:'<state>']])
 end
 
-puts options
+begin
+  cli.run
+rescue => e
+  abort "#{cmd} query failed. #{e}"
+end

data/lib/wavefront/cli/alerts.rb

@@ -123,6 +123,7 @@ class Wavefront::Cli::Alerts < Wavefront::Cli
     #
     # Put each host on its own line, indented.
     #
+    return k unless v
     v.sort!
     [human_line(k, v.shift)] + v.map {|el| human_line('', el)}
   end

data/lib/wavefront/cli/events.rb

@@ -0,0 +1,220 @@
+require 'wavefront/events'
+require 'wavefront/cli'
+require 'json'
+require 'time'
+require 'fileutils'
+require 'etc'
+require 'socket'
+#
+# Open and close events via the Wavefront API.
+#
+# It is straightforward to create instantaneous events, or events
+# with a defined start and end time: one API call is all you need,
+# and the job is done.  But often when you open an event you don't
+# know when you want to close it, and closing requires very specific
+# information which the API returns when the event is opened.
+#
+# To help the user close these events, we use a files in a local
+# directory to record the state of any events we open.  The
+# directory behaves like an event "stack": a freshly created event
+# is "pushed" onto the "stack", and telling the script to close an
+# event with no further specification "pops" the last even off the
+# "stack", and closes it.  We give each user their own state
+# directory, under /var/tmp/wavefront/events.
+#
+# We also provide a way of seeing which events the CLI thinks are
+# open. This is in no way a substitute for using an events() query
+# in a timeseries API call.
+#
+class Wavefront::Cli::Events < Wavefront::Cli
+  attr_accessor :state_dir, :hosts, :hostname, :t_start, :t_end, :wf_event
+
+  include Wavefront::Constants
+  include Wavefront::Mixins
+
+  def run
+    @state_dir = EVENT_STATE_DIR + Etc.getlogin
+    @hostname = Socket.gethostname
+    @hosts = prep_hosts(options[:host])
+    @t_start = prep_time(:start)
+    @t_end = prep_time(:end)
+
+    @wf_event = Wavefront::Events.new(options[:token])
+
+    if options[:create]
+      create_event_handler
+    elsif options[:close]
+      close_event_handler
+    elsif options[:show]
+      show_open_events
+    else
+      fail 'undefined event error.'
+    end
+  end
+
+  def prep_time(t)
+    #
+    # Wavefront would like times in epoch milliseconds, so whatever
+    # we have got, turn them into that.
+    #
+    options[t] ? time_to_ms(parse_time(options[t])) : false
+  end
+
+  def prep_hosts(hosts)
+    #
+    # We allow the user to associate an event with multiple hosts,
+    # or to pass in some identifer other than the hostname. If they
+    # have not done this, hostname is used
+    #
+    hosts = hostname unless hosts
+    hosts.split(',')
+  end
+
+  def create_event_handler
+    #
+    # Wrapper around the method calls which actually create events.
+    #
+    output = create_event
+
+    unless options[:end] || options[:instant]
+      create_state_dir
+      create_state_file(output) unless options[:nostate]
+    end
+
+    puts JSON.pretty_generate(JSON.parse(output)) if options[:verbose]
+  end
+
+  def create_event
+    #
+    # Make the API call and pass back the response.
+    #
+    req_obj = {
+      n: options[:'<event>'],
+      d: options[:desc],
+      h: hosts,
+      c: options[:instant],
+      l: options[:level]
+    }
+
+    req_obj[:s] = t_start if t_start
+    req_obj[:e] = t_end if t_end
+
+    begin
+      response = wf_event.create(req_obj)
+    rescue RestClient::Unauthorized
+      raise 'Cannot connect to Wavefront API'
+    rescue => e
+      puts e
+      raise 'Cannot create event'
+    end
+
+    response
+  end
+
+  def close_event_handler
+    #
+    # The user can specify all, some, or none of the information
+    # needed to close an event. If we have all of it, we can jump
+    # straight to the API call. Otherwise, we have to go and look
+    # for a state fuile
+    #
+    if options[:'<timestamp>'] && options[:'<event>']
+      close_event(options[:'<event>'], options[:'<timestamp>'])
+    else
+      ev_file = pop_event(options[:'<event>'])
+
+      if ev_file
+        close_event(ev_file[1], ev_file[0])
+      else
+        fail "No event '#{options[:'<event>']}' to close."
+      end
+    end
+  end
+
+  def close_event(ev_name, ts)
+    puts "Closing event '#{ev_name}'. [#{Time.at(ts.to_i / 1000)}]"
+
+    begin
+      wf_event.close(
+        s: ts,
+        n: ev_name
+      )
+    rescue RestClient::Unauthorized
+      raise 'Not authorized to connect to Wavefront.'
+    rescue => e
+      puts e
+      raise
+    end
+
+    # Remove the state file, if there was one
+    #
+    state_file = state_filename(ev_name, ts)
+
+    return unless state_file.exist?
+
+    puts "Removing state file #{state_file}."
+    File.unlink state_file
+  end
+
+  def show_open_events
+    #
+    # Everything we need to know about an event is in the name of
+    # its state file.
+    #
+    events = state_dir.children
+
+    if events.length == 0
+      puts 'No open events.'
+    else
+      events.each { |e| puts e.basename }
+    end
+  end
+
+  def pop_event(name = false)
+    #
+    # Get the last event this script created. If you supply a name,
+    # you get the last event with that name. If not, you get the
+    # last event. Chances are you'll only ever have one in-play at
+    # once.
+    #
+    # Returns an array of [timestamp, event_name]
+    #
+    list = state_dir.children
+    list.select! { |f| f.basename.to_s.split('::').last == name } if name
+    return false if list.length == 0
+    list.sort.last.basename.to_s.split('::')
+  end
+
+  def create_state_dir
+    FileUtils.mkdir_p(state_dir)
+    unless state_dir.exist? && state_dir.directory? && state_dir.writable?
+      fail 'Cannot create state directory.'
+    end
+  end
+
+  def state_filename(ev_name, ts)
+    #
+    # Consistently generate event state file names
+    #
+    state_dir + [ts, ev_name].join('::')
+  end
+
+  def create_state_file(response)
+    #
+    # Write a state file. We put the hosts bound to the event into
+    # the file. These aren't currently used by anything in the CLI,
+    # but they might be useful to someone, somewhere, someday.
+    #
+    ts = JSON.parse(response)['startTime']
+    fname = state_filename(options[:'<event>'], ts)
+
+    begin
+      File.open(fname, 'w') { hosts.to_s }
+    rescue
+      JSON.pretty_generate(JSON.parse(response))
+      raise 'Event was created but state file was not.'
+    end
+
+    puts "Event state recorded at #{fname}."
+  end
+end

data/lib/wavefront/cli/ts.rb

@@ -20,18 +20,9 @@ require 'json'
 require 'date'
 
 class Wavefront::Cli::Ts < Wavefront::Cli
-
+  include Wavefront::Mixins
   attr_accessor :options, :arguments
 
-  def parse_time(t)
-    return Time.at(t.to_i) if t.match(/^\d+$/)
-    begin
-      return DateTime.parse("#{t} #{Time.now.getlocal.zone}").to_time.utc
-    rescue
-      raise "cannot parse timestamp '#{t}'."
-    end
-  end
-
   def run
     raise 'Please supply a query.' if @arguments.empty?
     query = @arguments[0]

data/lib/wavefront/client/version.rb

@@ -16,6 +16,6 @@ See the License for the specific language governing permissions and
 
 module Wavefront
   class Client
-    VERSION = "3.1.0"
+    VERSION = "3.2.0"
   end
 end

data/lib/wavefront/constants.rb

@@ -14,6 +14,8 @@ See the License for the specific language governing permissions and
 
 =end
 
+require 'pathname'
+
 module Wavefront
   module Constants
     DEFAULT_HOST = 'metrics.wavefront.com'
@@ -26,5 +28,7 @@ module Wavefront
     ALERT_FORMATS = [:ruby, :json, :human]
     DEFAULT_ALERT_FORMAT = :human
     GRANULARITIES = %w( s m h d )
+    EVENT_STATE_DIR = Pathname.new('/var/tmp/wavefront/events')
+    EVENT_LEVELS = %w(info smoke warn severe)
   end
 end

data/lib/wavefront/events.rb

@@ -21,10 +21,12 @@ module Wavefront
     include Wavefront::Constants
     DEFAULT_PATH = '/api/events/'
 
-    attr_reader :token
+    attr_reader :headers
 
     def initialize(token)
-      @token = token
+      @headers = {
+        'X-AUTH-TOKEN': token,
+      }
     end
 
     def create(payload = {}, options = {})
@@ -34,10 +36,16 @@ module Wavefront
       uri = URI::HTTPS.build(
         host:  options[:host],
         path:  options[:path],
-        query: "t=#{@token}"
       )
 
-      RestClient.post(uri.to_s, payload)
+      # It seems that posting the hash means the 'host' data is
+      # lost. Making a query string works though, so let's do that.
+      #
+      hosts = payload[:h]
+      payload.delete(:h)
+      query = mk_qs(payload)
+      hosts.each { |host| query.<< "&h=#{host}" }
+      RestClient.post(uri.to_s, query, headers)
     end
 
     def close(payload = {}, options = {})
@@ -51,17 +59,18 @@ module Wavefront
       uri = URI::HTTPS.build(
         host:  options[:host],
         path:  options[:path] + 'close',
-        query: URI.escape(
-          payload.map { |k, v| [k, v].join('=') }.join('&') + '&t=' + @token
-        )
+
       )
-      puts uri.to_s
 
-      RestClient.post(uri.to_s, payload)
+      RestClient.post(uri.to_s, mk_qs(payload), headers)
     end
 
     private
 
+    def mk_qs(payload)
+      URI.escape(payload.map { |k, v| [k, v].join('=') }.join('&'))
+    end
+
     def debug(enabled)
       RestClient.log = 'stdout' if enabled
     end

data/lib/wavefront/mixins.rb

@@ -1,4 +1,4 @@
-=begin 
+=begin
     Copyright 2015 Wavefront Inc.
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -25,5 +25,21 @@ module Wavefront
       interpolated.flatten!
       return interpolated.join('.')
     end
+
+    def parse_time(t)
+      return Time.at(t.to_i) if t.match(/^\d+$/)
+      begin
+        return DateTime.parse("#{t} #{Time.now.getlocal.zone}").to_time.utc
+      rescue
+        raise "cannot parse timestamp '#{t}'."
+      end
+    end
+
+    def time_to_ms(t)
+      #
+      # Return the time as milliseconds since the epoch
+      #
+      (t.to_f * 1000).round
+    end
   end
 end

data/lib/wavefront/response.rb

@@ -121,21 +121,11 @@ module Wavefront
       def initialize(response, options={})
         super
 
-        if self.respond_to?(:timeseries)
-          out = ['%-20s%s' % ['query', self.query]]
-
-          self.timeseries.each_with_index do |ts, i|
-            out.<< '%-20s%s' % ['timeseries', i]
-            out += ts.select{|k,v| k != 'data' }.map do |k, v|
-              if k == 'tags'
-                v.map { |tk, tv| 'tag.%-16s%s' % [tk, tv] }
-              else
-                '%-20s%s' % [k, v]
-              end
-            end
-            out += ts['data'].map do |t, v|
-              [Time.at(t).strftime('%F %T'), v].join(' ')
-            end
+        if self.response
+          if self.respond_to?(:timeseries)
+            out = process_timeseries
+          elsif self.respond_to?(:events)
+            out = process_events
           end
         else
           out = self.warnings
@@ -143,6 +133,77 @@ module Wavefront
 
         @human = out.join("\n")
       end
+
+      def process_timeseries
+        out = ['%-20s%s' % ['query', self.query]]
+
+        self.timeseries.each_with_index do |ts, i|
+          out.<< '%-20s%s' % ['timeseries', i]
+          out += ts.select{|k,v| k != 'data' }.map do |k, v|
+            if k == 'tags'
+              v.map { |tk, tv| 'tag.%-16s%s' % [tk, tv] }
+            else
+              '%-20s%s' % [k, v]
+            end
+          end
+          out += ts['data'].map do |t, v|
+            [Time.at(t).strftime('%F %T'), v].join(' ')
+          end
+        end
+
+        out
+      end
+
+      def process_events
+        sorted = self.events.sort_by { |k| k['start'] }
+
+        sorted.each_with_object([]) do |e, out|
+          hosts = e['hosts'] ? '[' + e['hosts'].join(',') + ']' : ''
+
+          if e['tags']
+            severity = e['tags']['severity']
+            type = e['tags']['type']
+            details = e['tags']['details']
+          else
+            severity = type = details = ''
+          end
+
+          t = [format_event_time(e['start']), '->',
+               format_event_time(e['end']),
+               '%-9s' % ('(' + format_event_duration(e['start'],
+                                                     e['end']) + ')'),
+               '%-7s' % severity,
+               '%-15s' % type,
+               '%-25s' % e['name'],
+               hosts,
+               details,
+              ].join(' ')
+
+          out.<< t
+        end
+      end
+
+      def format_event_time(tms)
+        Time.at(tms / 1000).strftime('%F %T')
+      end
+
+      def format_event_duration(ts, te)
+        #
+        # turn an event start and end into a human-readable,
+        # approximate, time.  Truncates after the first two parts in
+        # the interests of space.
+        #
+        dur = (te - ts) / 1000
+
+        return 'inst' if dur == 0
+
+        {s: 60, m: 60, h: 24, d: 1000 }.map do |sfx, val|
+          next unless dur > 0
+          dur, n = dur.divmod(val)
+          n.to_s + sfx.to_s
+        end.compact.reverse[0..1].join(' ')
+      end
+
     end
   end
 end

data/wavefront-client.gemspec

@@ -39,9 +39,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rspec"
 
   spec.add_dependency "rest-client", ">= 1.6.7", "<= 1.8"
-  spec.add_dependency "slop", ">= 3.4.7", "<= 3.6"
+  spec.add_dependency "docopt", "~> 0.5.0"
   spec.add_dependency 'inifile',  '3.0.0'
   spec.required_ruby_version = Gem::Requirement.new(">= 1.9.3")
-
 end
-

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wavefront-client
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 3.2.0
 platform: ruby
 authors:
 - Sam Pointer
@@ -13,7 +13,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-05-20 00:00:00.000000000 Z
+date: 2016-07-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -78,25 +78,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.8'
 - !ruby/object:Gem::Dependency
-  name: slop
+  name: docopt
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: 3.4.7
-    - - <=
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '3.6'
+        version: 0.5.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: 3.4.7
-    - - <=
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '3.6'
+        version: 0.5.0
 - !ruby/object:Gem::Dependency
   name: inifile
   requirement: !ruby/object:Gem::Requirement
@@ -125,12 +119,14 @@ files:
 - Gemfile
 - LICENSE
 - NOTICE
+- README-cli.md
 - README.md
 - Rakefile
 - bin/wavefront
 - lib/wavefront/alerting.rb
 - lib/wavefront/cli.rb
 - lib/wavefront/cli/alerts.rb
+- lib/wavefront/cli/events.rb
 - lib/wavefront/cli/ts.rb
 - lib/wavefront/client.rb
 - lib/wavefront/client/version.rb