wavefront-cli 2.18.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4880abc13df515eb2e0446b72e0988c99d21cc8e28e7c1adfa532f063c58e1f3
-  data.tar.gz: fa812c04d90125e2a53161b13a52b0978e9e43bcdf949e8ab089f40152e261f9
+  metadata.gz: de9815c9b9f4313ee08d41e7890edfd991f2c59e8d8a59edf21e616f4c40dbf1
+  data.tar.gz: 391a6628ebdb0fd14621050e72e806d8da2fffb3f6f6cacdf098a614c8b7c198
 SHA512:
-  metadata.gz: 92c1347338ecc3fa32995ada2d922fe40192730ffcc51eedb13f03f8efe87593c0f8e2bca3191575f2251033cc6792ff5218cd67c7af412288febb589e7f5509
-  data.tar.gz: c6500c4047b9b3565facc8a3bdbba78a536aefa0d66280dceb568712055ee5c3ecb18e1bcac7d7cd175a28b9241a8535dfe4bc196da98fa4a93b9a6d7245d405
+  metadata.gz: ba5158a38ab4708f07db85b861e093c4f9e0e03761845eeced6fcc320b67b2b9829846dec1f03941b10d809fd8d1680c04d77afdbfa8aa5c5d85e7348f21f21a
+  data.tar.gz: 775b238037143d7b2b56c3a2a6e643737f80de93b3079027e243a8bff9e2900bfed2b3d662c40d1c231dfa1b16a2241fcd973afd83b56545f5fa781bc353b98c

data/.gitignore

@@ -4,5 +4,6 @@ Gemfile.lock
 .*swp
 *.gem
 .ruby-version
+.nfs*
 spec/gen_test.sh
 spec/parabola.rb

data/.rubocop.yml

@@ -1,5 +1,12 @@
 ---
 
+AllCops:
+  DisplayStyleGuide: true
+  TargetRubyVersion: 2.3
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
 Style/FormatStringToken:
   Enabled: false
 

data/.travis.yml

@@ -1,12 +1,11 @@
 language: ruby
 cache: bundler
 rvm:
-  - 2.2.10
   - 2.3.8
   - 2.4.5
-  - 2.5.3
-  - 2.6.0
-before_install: gem install bundler -v 1.17.3 --no-document
+  - 2.5.5
+  - 2.6.2
+before_install: gem install bundler --no-document
 deploy:
   provider: rubygems
   api_key:
@@ -15,7 +14,7 @@ deploy:
   on:
     tags: true
     repo: snltd/wavefront-cli
-    ruby: 2.5.3
+    ruby: 2.6.2
 notifications:
   email: false
   slack:

data/HISTORY.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 3.0.0 (23/03/2019)
+* Drop support for Ruby 2.2. (Potentially breaking change.)
+* Remove the (deprecated) `report` command. Send points directly to
+  Wavefront with `write --use api`. (Potentially breaking change.)
+* Added `settings` command to view and manage system preferences.
+* `dashboard` command supports new ACL mechanism.
+* All commands now accept the `-f` (`--format`) option.
+* New, improved `human` output. Finally fixes a very old bug where
+  heavily indented columns could run into one another.
+* In long listings, items with empty values now display as `<none`>
+  instead of being omitted.
+* Move `id` and `name` to the top of objects in long listings, for
+  easier reading.
+* Improved output testing
+* `wf write` understands `--`, which makes it easier to send
+  negative values.
+* Fix ugly output when a raw query did not specify a host.
+* New `config about` subcommand gives diagnostic info.
+* Require 3.0.0 of [the SDK](https://github.com/snltd/wavefront-sdk).
+
 ## 2.18.0 (22/02/2019)
 * Add `usergroup` command, and extend `user` command to cover new
   RBAC features.
@@ -14,7 +34,6 @@
   headers`, not `-F header`.
 
 ## 2.16.1 (29/12/2018)
-
 * Fix regression which broke query time ranges.
 * Fix regression which made `--noop` silent unless `--verbose` was
   also specified.

data/README.md

@@ -1,9 +1,9 @@
 # Wavefront CLI
 [![Build Status](https://travis-ci.org/snltd/wavefront-cli.svg?branch=master)](https://travis-ci.org/snltd/wavefront-cli) [![Maintainability](https://api.codeclimate.com/v1/badges/9b712047af0b2dafc146/maintainability)](https://codeclimate.com/github/snltd/wavefront-cli/maintainability) [![Gem Version](https://badge.fury.io/rb/wavefront-cli.svg)](https://badge.fury.io/rb/wavefront-cli) ![](http://ruby-gem-downloads-badge.herokuapp.com/wavefront-cli?type=total)
 
-This package provides a complete command-line interface to
+This is a complete command-line interface to
 [Wavefront](https://www.wavefront.com/)'s API. It also provides easy
-ways to write data through a proxy.
+ways to get data into Wavefront.
 
 The gem is hosted [on
 Rubygems](https://rubygems.org/gems/wavefront-cli) and can be
@@ -15,7 +15,7 @@ $ gem install wavefront-cli
 
 It is built on [our Wavefront Ruby
 SDK](https://github.com/snltd/wavefront-sdk) and requires Ruby >=
-2.2. It has no "native extension" dependencies.
+2.3. It has no "native extension" dependencies.
 
 For a far more comprehensive overview/tutorial, please read [this
 article](http://sysdef.xyz/post/2017-07-26-wavefront-cli).
@@ -43,7 +43,6 @@ Commands:
   notificant         view and manage Wavefront alert targets
   proxy              view and manage Wavefront proxies
   query              query the Wavefront API
-  report             send data directly to Wavefront
   savedsearch        view and manage saved searches
   source             view and manage source tags and descriptions
   user               view and manage Wavefront users
@@ -130,13 +129,16 @@ something.
 
 ### Formats, Importing, and Exporting
 
-Most commands and sub-commands support the `-f` option. This takes
-one of `json`, `yaml`, `human` and `raw`, and tells the CLI to
-present the information it fetches from the Wavefront API in that
-format. (`raw` is the raw Ruby representation, which, for instance,
-you could paste into `irb`.) Some object types can be exported in
-HCL, for easy integration with Space Ape's Wavefront Terraform
-provider.
+All commands support the `-f` option. This takes one of `json`,
+`yaml`, `human` and `raw`, and tells the CLI to present the
+information it fetches from the Wavefront API in that format. (`raw`
+is the raw Ruby representation, which, for instance, you could paste
+into `irb`.) Some object types can be exported in other formats.
+Alerts, notificants and dashboards can be exported as HCL, for easy
+integration with [Space Ape's Wavefront Terraform
+provider](https://tech.spaceapegames.com/2017/09/28/building-a-custom-terraform-provider-for-wavefront/).
+Query results can be presented as CSV files, or in the native
+Wavefront data format.
 
 Human output can be selective. As well as the time formatting
 mentioned above, human-readable listings and desctiptions may omit
@@ -192,21 +194,55 @@ that in the morning, the time would be invalid, and you would get a
 
 There is no need to include a timezone in your time: the `wf`
 CLI will automatically use your local timezone when it parses the
-string.
+string. You can also specify relative times: for instance '-10m' for
+the last ten minutes.
 
-The following options are valid in almost all contexts.
+## Querying Data
+
+Use the `query` subcommand with any timeseries expression.
 
 ```
--c, --config=FILE    path to configuration file [default: ~/.wavefront]
--P, --profile=NAME   profile in configuration file [default: default]
--D, --debug          enable debug mode
--V, --verbose        enable verbose mode
--h, --help           show help for command
+ ./wf query "ts(cpu.*.pc.user, source=cube)" | more
+name          ts(cpu.*.pc.user, source=cube)
+query         ts(cpu.*.pc.user, source=cube)
+timeseries
+  label       cpu.0.pc.user
+  sparkline   > ▇▅     █<
+  host        cube
+  tags
+    env       lab
+  data                     13:39:00    26.081756828668336
+                           13:40:00    20.37380923087
+                           13:41:00    4.086552186471667
+                           13:42:00    2.5642049289966664
+                           13:43:00    2.542284133615
+                           13:44:00    2.6524157880366666
+                           13:45:00    2.1158611431600005
+                           13:46:00    27.911804005566665
+              2019-03-07   13:38:00    3.8412758439216668
+              ------------------------------------------------------------------
+  label       cpu.1.pc.user
+  sparkline   > █▅     ▇<
+  host        cube
+  tags
+    env       lab
+  data                     13:39:00    27.45281202666833
+                           13:40:00    19.441659754188333
+                           13:41:00    3.96397654233
+                           13:42:00    2.49657063456
+                           13:43:00    2.4946187951783334
+                           13:44:00    2.8966526517783335
+                           13:45:00    2.636301021795
+                           13:46:00    25.407542657531668
+              2019-03-07   13:38:00    4.655340261835
+...
+events        <none>
+warnings      <none>
+
 ```
 
-Debug mode will show you combined options, and debug output from
-`faraday`. It also shows the full stack trace should a command
-fail. This output can be very verbose.
+By default you get the last ten minutes of data, but the time
+windowing rules can be used to specify any range.
 
 ## Writing Points
 
@@ -219,8 +255,7 @@ $ wf write point cli.example 10
 and you can add point tags, if you like.
 
 ```
-$ wf write point cli.example 9.4 -E wavefront -T proxy=wavefront \
-  -T from=README
+$ wf write point cli.example 9.4 -E wavefront -T proxy=wavefront -T from=README
 ```
 
 or force a timestamp:
@@ -251,15 +286,30 @@ $ while true; do echo $RANDOM; sleep 1; done | wf write file -m cli.demo -Fv -
 ```
 
 If you wish to write points directly via the API, and you have the
-"direct ingestion" privilege, just swap `write` for `report`, or add
-`-u api` to your `write` command. To send points to a proxy over
-HTTP, use `-u http`.
+"direct ingestion" privilege, just add `-u api` to your `write`
+command. To send points to a proxy over HTTP, use `-u http`, and to
+write to a Unix socket use `-u unix`.
 
-Due to limitations in [docopt](https://github.com/docopt/docopt.rb),
-writing negative values is a bit of a mess.
+You can write delta metrics with `-i` (for increment).
 
 ```
+$ wf write point -i counter.example 4
+```
+
+To sent negative values, you must use `--` to tell `wf` that you
+have finished declaring options, or get creative with your quoting.
+
+```
+$ wf write point cli.example -- -10
 $ wf write point cli.example "\-10"
 ```
 
-You can write delta metrics with `-i` (for increment),
+You can even write distibutions. Either list every number
+individually, or use `x` to specify multiples of any value. You can
+mix and match within the same line.
+
+```
+$ wf write distribution dist.example 3 1 4 1 1 2 3 6 4 1 3 2
+$ wf write distribution dist.example 3x3 4x1 2x4 2x2 1x6
+$ wf write distribution dist.example 3x3 4x1 4 4 2x2 6
+```

data/lib/wavefront-cli/base.rb

@@ -152,7 +152,8 @@ module WavefrontCli
     #
     def format_var
       options[:format].to_sym
-      # (self.class.name.split('::').last.downcase + 'format').to_sym
+    rescue NoMethodError
+      :human
     end
 
     # Works out the user's command by matching any options docopt has
@@ -202,7 +203,7 @@ module WavefrontCli
     # instance variable.
     #
     # @param data [WavefrontResponse] an object returned by a
-    #   Wavefront SDK method. This will contain a 'response'
+    #   Wavefront SDK method. This will contain 'response'
     #   and 'status' structures.
     # @param method [String] the name of the method which produced
     #   this output. Used to find a suitable humanize method.
@@ -489,5 +490,28 @@ module WavefrontCli
     def cannot_noop!
       raise WavefrontCli::Exception::UnsupportedNoop if options[:noop]
     end
+
+    # A recursive function which fetches list of values from a
+    # nested hash. Used by WavefrontCli::Dashboard#do_queries
+    # @param obj [Object] the thing to search
+    # @param key [String, Symbol] the key to search for
+    # @param aggr [Array] values of matched keys
+    # @return [Array]
+    #
+    def extract_values(obj, key, aggr = [])
+      if obj.is_a?(Hash)
+        obj.each_pair do |k, v|
+          if k == key && !v.to_s.empty?
+            aggr.<< v
+          else
+            extract_values(v, key, aggr)
+          end
+        end
+      elsif obj.is_a?(Array)
+        obj.each { |e| extract_values(e, key, aggr) }
+      end
+
+      aggr
+    end
   end
 end

data/lib/wavefront-cli/commands/alert.rb

@@ -8,28 +8,28 @@ class WavefrontCommandAlert < WavefrontCommandBase
   end
 
   def _commands
-    ["list #{CMN} [-al] [-O fields] [-f format] [-o offset] [-L limit]",
-     "firing #{CMN} [-f format] [-o offset] [-L limit]",
-     "snoozed #{CMN} [-f format] [-o offset] [-L limit]",
-     "describe #{CMN} [-f format] [-v version] <id>",
+    ["list #{CMN} [-al] [-O fields] [-o offset] [-L limit]",
+     "firing #{CMN} [-o offset] [-L limit]",
+     "snoozed #{CMN} [-o offset] [-L limit]",
+     "describe #{CMN} [-v version] <id>",
      "delete #{CMN} <id>",
      "undelete #{CMN} <id>",
-     "history #{CMN} [-f format] [-o offset] [-L limit] <id>",
+     "history #{CMN} [-o offset] [-L limit] <id>",
      "import #{CMN} <file>",
      "snooze #{CMN} [-T time] <id>",
      "update #{CMN} <key=value> <id>",
      "unsnooze #{CMN} <id>",
-     "search #{CMN} [-al] [-f format] [-o offset] [-L limit] <condition>...",
-     "tags #{CMN} [-f format] <id>",
+     "search #{CMN} [-al] [-o offset] [-L limit] <condition>...",
+     "tags #{CMN} <id>",
      "tag set #{CMN} <id> <tag>...",
      "tag clear #{CMN} <id>",
      "tag add #{CMN} <id> <tag>",
      "tag delete #{CMN} <id> <tag>",
-     "currently #{CMN} [-f format] <state>",
-     "queries #{CMN} [-f format] [-b] [<id>]",
+     "currently #{CMN} <state>",
+     "queries #{CMN} [-b] [<id>]",
      "install #{CMN} <id>",
      "uninstall #{CMN} <id>",
-     "summary #{CMN} [-f format] [-a]"]
+     "summary #{CMN} [-a]"]
   end
 
   def _options

data/lib/wavefront-cli/commands/base.rb

@@ -1,6 +1,7 @@
 require_relative '../stdlib/string'
 
-CMN = '[-DnV] [-c file] [-P profile] [-E endpoint] [-t token]'.freeze
+CMN = '[-DnV] [-c file] [-P profile] [-E endpoint] [-t token] ' \
+      '[-f format]'.freeze
 
 # A base class which all command classes extend.
 #
@@ -36,13 +37,25 @@ class WavefrontCommandBase
   # @return [Array]
   #
   def tag_commands
-    ["tags #{CMN} [-f format] <id>",
+    ["tags #{CMN} <id>",
      "tag set #{CMN} <id> <tag>...",
      "tag clear #{CMN} <id>",
      "tag add #{CMN} <id> <tag>",
      "tag delete #{CMN} <id> <tag>"]
   end
 
+  # Anything which takes ACLs provides the same interface
+  # @return [Array]
+  #
+  def acl_commands
+    ["acls #{CMN} <id>",
+     "acl #{CMN} clear <id>",
+     "acl #{CMN} grant (view | modify) on <id> to " \
+     '(user | group) <name>...',
+     "acl #{CMN} revoke (view | modify) on <id> from " \
+     '(user | group) <name>...']
+  end
+
   # Inheriting classes must override this method
   # @return [Array]
   #

data/lib/wavefront-cli/commands/cloudintegration.rb

@@ -16,14 +16,14 @@ class WavefrontCommandCloudintegration < WavefrontCommandBase
   end
 
   def _commands
-    ["list #{CMN} [-al] [-O fields] [-f format] [-o offset] [-L limit]",
-     "describe #{CMN} [-f format] <id>",
+    ["list #{CMN} [-al] [-O fields] [-o offset] [-L limit]",
+     "describe #{CMN} <id>",
      "delete #{CMN} <id>",
      "undelete #{CMN} <id>",
      "enable #{CMN} <id>",
      "disable #{CMN} <id>",
      "import #{CMN} <file>",
-     "search #{CMN} [-al] [-f format] [-o offset] [-L limit] <condition>..."]
+     "search #{CMN} [-al] [-o offset] [-L limit] <condition>..."]
   end
 
   def _options

data/lib/wavefront-cli/commands/config.rb

@@ -13,7 +13,8 @@ class WavefrontCommandConfig < WavefrontCommandBase
      'show [-D] [-c file] [<profile>]',
      'setup [-D] [-c file] [<profile>]',
      'delete [-D] [-c file] <profile>',
-     'envvars']
+     'envvars',
+     'about']
   end
 
   def _options

data/lib/wavefront-cli/commands/dashboard.rb

@@ -8,17 +8,19 @@ class WavefrontCommandDashboard < WavefrontCommandBase
   end
 
   def _commands
-    ["list #{CMN} [-alN] [-O fields] [-f format] [-o offset] [-L limit]",
-     "describe #{CMN} [-f format] [-v version] <id>",
-     "import #{CMN} [-f format] <file>",
+    ["list #{CMN} [-alN] [-O fields] [-o offset] [-L limit]",
+     "describe #{CMN} [-v version] <id>",
+     "import #{CMN} <file>",
      "update #{CMN} <key=value> <id>",
      "delete #{CMN} <id>",
      "undelete #{CMN} <id>",
-     "history #{CMN} [-f format] [-o offset] [-L limit] <id>",
-     "search #{CMN} [-al] [-f format] [-o offset] [-L limit] <condition>...",
-     "queries #{CMN} [-f format] [-b] [<id>]",
+     "history #{CMN} [-o offset] [-L limit] <id>",
+     "search #{CMN} [-al] [-o offset] [-L limit] <condition>...",
+     "queries #{CMN} [-b] [<id>]",
+     "favs #{CMN}",
      "fav #{CMN} <id>",
      "unfav #{CMN} <id>",
+     acl_commands,
      tag_commands]
   end
 

data/lib/wavefront-cli/commands/derivedmetric.rb

@@ -16,16 +16,16 @@ class WavefrontCommandDerivedmetric < WavefrontCommandBase
   end
 
   def _commands
-    ["list #{CMN} [-al] [-O fields] [-f format] [-o offset] [-L limit]",
-     "describe #{CMN} [-f format] [-v version] <id>",
+    ["list #{CMN} [-al] [-O fields] [-o offset] [-L limit]",
+     "describe #{CMN} [-v version] <id>",
      "create #{CMN} [-d description] [-T tag...] [-b] [-i interval] " \
      '[-r range] <name> <query>',
-     "import #{CMN} [-f format] <file>",
+     "import #{CMN} <file>",
      "update #{CMN} <key=value> <id>",
      "delete #{CMN} <id>",
      "undelete #{CMN} <id>",
-     "history #{CMN} [-f format] [-o offset] [-L limit] <id>",
-     "search #{CMN} [-al] [-f format] [-o offset] [-L limit] <condition>...",
+     "history #{CMN} [-o offset] [-L limit] <id>",
+     "search #{CMN} [-al] [-o offset] [-L limit] <condition>...",
      tag_commands]
   end