wavefront-cli 2.7.0 → 2.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6829c82ead73104270f19e4f3c06084719720afdc64233f25683940155cef12
-  data.tar.gz: 40530d75b0b5ceb505a5afe9268bcb26036c92cc25114f664ba97662a5639506
+  metadata.gz: 397350925432eb596a2268652590b0690ee115d0f351f4406e807eec465db61c
+  data.tar.gz: e85b47160b148fc9067ea9d14b6265c8fa27004661a65a62dd4bdca67645c4e1
 SHA512:
-  metadata.gz: 072f0f0bbd20bce99729bf3ff4e1a0a64fa34599677be8972b00c7ce48c8ac0fa88c6e0eb45f95b8f17e7e77039d1c70c4e03aff37f0354e1e587063a5ae4bbb
-  data.tar.gz: 88c1dcd21de080393d131c381c28d98da6624c4a866e4d84ee4694e16ff555f067df52c5993ac33599088015d8e8d70506fd1dbcd59d4095a6a7a38947c5a060
+  metadata.gz: 0f9d17a9f4ceebbadc18e41813b6766b86c07f6a881a1b30814ab747e82782f67ef97d6a5f876d28719c8182b8b6e1ae14b514cfc649efe80f265bdefc623c0f
+  data.tar.gz: 7071d861a7da1bad3322fac62601cc05ed773898b04833384d16178ce67d260861603d36ff669f36dff43d333e9805608d0c6e520513fdf179f9ae074286b93d

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 command-line interface to
-[Wavefront](https://www.wavefront.com/)'s API. Each API path
-is covered by a different command keyword.
+This package provides a complete command-line interface to
+[Wavefront](https://www.wavefront.com/)'s API. It also provides easy
+ways to write data through a proxy.
 
 The gem is hosted [on
 Rubygems](https://rubygems.org/gems/wavefront-cli) and can be
@@ -13,12 +13,12 @@ installed with
 $ gem install wavefront-cli
 ```
 
-It is built on [the Wavefront Ruby
+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.
 
-I also maintain [a reasonably thorough
-tutorial](http://sysdef.xyz/post/2017-07-26-wavefront-cli).
+For a far more comprehensive overview/tutorial, please read [this
+article](http://sysdef.xyz/post/2017-07-26-wavefront-cli).
 
 ```
 $ wf --help
@@ -30,21 +30,25 @@ Usage:
   wf --help
 
 Commands:
-  alert         view and manage alerts
-  integration   view and manage cloud integrations
-  dashboard     view and manage dashboards
-  event         view, manage, open, and close events
-  link          view and manage external links
-  message       view and mark as read user messages
-  metric        view metric details
-  proxy         view and manage Wavefront proxies
-  query         run timeseries queries
-  savedsearch   view and manage saved searches
-  source        view and manage source tags and descriptions
-  user          view and manage Wavefront users
-  window        view and manage maintenance windows
-  webhook       view and manage webhooks
-  write         send data points to a Wavefront proxy
+  alert              view and manage alerts
+  cloudintegration   view and manage cloud integrations
+  dashboard          view and manage dashboards
+  derivedmetric      view and manage derived metrics
+  event              open, close, view, and manage events
+  integration        view and manage Wavefront integrations
+  link               view and manage external links
+  message            read and mark user messages
+  metric             view metrics
+  notificant         view and manage Wavefront notification 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
+  webhook            view and manage webhooks
+  window             view and manage maintenance windows
+  write              send data to a Wavefront proxy
 
 Use 'wf <command> --help' for further information.
 ```
@@ -55,10 +59,10 @@ Use 'wf <command> --help' for further information.
 
 You can pass in your Wavefront API and token with command-line
 options `-E` and `-t`; with the environment variables
-`WAVEFRONT_ENDPOINT` and `WAVEFRONT_TOKEN`,
-or by putting them in a configuration file at `${HOME}/.wavefront`. This is an
-ini-style file, with a section for each Wavefront account you wish to use. (None
-of the tokens shown here are real, of course!)
+`WAVEFRONT_ENDPOINT` and `WAVEFRONT_TOKEN`, or by putting them in a
+configuration file at `${HOME}/.wavefront`. This is an ini-style
+file, with a section for each Wavefront account you wish to use.
+(None of the tokens shown here are real, of course!)
 
 ```
 [default]
@@ -73,14 +77,15 @@ endpoint = company.wavefront.com
 format = yaml
 ```
 
-You can override the config file location with `-c`, and select a profile with
-`-P`. If you don't supply `-P`, the `default` profile is used.
+You can override the config file location with `-c`, and select a
+profile with `-P`. If you don't supply `-P`, the `default` profile
+is used.
 
 ### Listing Things
 
 Most commands have a `list` subcommand, which will produce brief
-"one thing per line" output. The unique ID  of the "thing" is in the first
-column.
+"one thing per line" output. The unique ID  of the "thing" is in the
+first column.
 
 ```
 $ wf proxy list
@@ -114,23 +119,30 @@ ephemeral                false
 deleted                  false
 ```
 
-Most timestamps come back from the API as epoch seconds or epoch milliseconds.
-The CLI, in its human-readable descriptions, will convert those to
-`YYYY-MM-DD HH:mm:ss` when it `describe`s something.
+Most timestamps come back from the API as epoch seconds or epoch
+milliseconds.  The CLI, in its human-readable descriptions, will
+convert those to `YYYY-MM-DD HH:mm:ss` when it `describe`s
+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`.)
+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.
 
-Human output can be selective. As well as the time formatting mentioned above,
-human-readable listings and desctiptions may omit data which is not likely to be
-useful, or which is extremely hard to present in a readable way.
+Human output can be selective. As well as the time formatting
+mentioned above, human-readable listings and desctiptions may omit
+data which is not likely to be useful, or which is extremely hard to
+present in a readable way.
 
-If you `describe` an object like a dashboard, user, webhook etc as `json` or
-`yaml`, and send the output to a file, you can re-import that data. The format of the file to be imported is automatically detected.
+If you `describe` an object like a dashboard, user, webhook etc as
+`json` or `yaml`, and send the output to a file, you can re-import
+that data. The format of the file to be imported is automatically
+detected.
 
 ```
 $ wf user list
@@ -213,11 +225,12 @@ or force a timestamp:
 $ wf write point -t 16:53:14 cli.example 8
 ```
 
-More usefully, you can write from a file. Your file must contain multiple
-columns: metric name (`m`), metric value (`v`), timestamp(`t`), and point tags
-(`T`). `v` is mandatory, `m` can be filled in with the `-m` flag, `t` can be
-filled in with the current timestamp, and `T` is optional, but if used, must be
-last. You then tell the CLI what order your fields are in.
+More usefully, you can write from a file. Your file must contain
+multiple columns: metric name (`m`), metric value (`v`),
+timestamp(`t`), and point tags (`T`). `v` is mandatory, `m` can be
+filled in with the `-m` flag, `t` can be filled in with the current
+timestamp, and `T` is optional, but if used, must be last. You then
+tell the CLI what order your fields are in.
 
 ```
 $ cat datafile
@@ -233,6 +246,9 @@ If you set the file to `-`, you can read from standard in:
 $ 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`.
+
 Due to limitations in [docopt](https://github.com/docopt/docopt.rb),
 writing negative values is a bit of a mess.
 

data/lib/wavefront-cli/base.rb

@@ -240,7 +240,10 @@ module WavefrontCli
                               format.to_s.capitalize))
       oclass.new(resp, options).run
     rescue LoadError
-      raise "Unsupported output format '#{format}'."
+      raise WavefrontCli::Exception::UnsupportedOutput.new(
+        format("The '%s' command does not support '%s' output.",
+               options[:class], format)
+      )
     end
 
     def hcl_fields

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

@@ -3,9 +3,11 @@ require_relative 'base'
 # Define the Alert command
 #
 class WavefrontCommandAlert < WavefrontCommandBase
+
   def description
     'view and manage alerts'
   end
+
   def _commands
     ["list #{CMN} [-l] [-f format] [-o offset] [-L limit]",
      "firing #{CMN} [-o offset] [-L limit]",

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

@@ -34,4 +34,10 @@ class WavefrontCommandQuery < WavefrontCommandBase
      '-k, --nospark             do not show sparkline',
      '-W, --nowarn              do not show API warning messages']
   end
+
+  def postscript
+    'The query command has an additional output format. Using ' \
+    "'-f wavefront' produces output suitable for feeding back into a " \
+    'proxy.'.cmd_fold(TW, 0)
+  end
 end

data/lib/wavefront-cli/controller.rb

@@ -92,6 +92,8 @@ class WavefrontCliController
   def run_command(hook)
     hook.validate_opts
     hook.run
+  rescue WavefrontCli::Exception::UnsupportedOutput => e
+    abort e.message
   rescue StandardError => e
     $stderr.puts "general error: #{e}"
     $stderr.puts "re-run with '-D' for stack trace." unless opts[:debug]

data/lib/wavefront-cli/exception.rb

@@ -1,5 +1,6 @@
 module WavefrontCli
   class Exception
     class UnhandledCommand < RuntimeError; end
+    class UnsupportedOutput < RuntimeError; end
   end
 end

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

@@ -1,10 +1,51 @@
 module WavefrontOutput
+  #
+  # WavefrontCli::Base looks for a class WavefrontOutput::Format
+  # where 'Format' is something like 'Json', or 'Yaml'. If it finds
+  # that class it creates a new instance, passing through the
+  # response object (@resp) and options hash (@options), then  calls
+  # the #run method.
+  #
+  # All those classes are an extension of this one. Some, like Json
+  # or Yaml, are generic, and dump a straight translation of the
+  # response object. Others, like Hcl or Wavefront, have subclasses
+  # which deal with the output of specific commands.
+  #
   class Base
-    attr_reader :resp, :options
+    attr_reader :resp, :options, :cmd
 
-    def initialize(resp, options)
+    def initialize(resp = {}, options = {})
+      @cmd = options[:class]
       @resp = resp
       @options = options
     end
+
+    # We used to call #run directly, but now we use this wrapper to
+    # make it easier to test the #_run methods.
+    #
+    def run
+      puts _run
+    end
+
+    def _run
+      command_class.run
+    end
+
+    def my_format
+      self.class.name.split('::').last.downcase
+    end
+
+    def command_class_name
+      format('Wavefront%sOutput::%s', my_format.capitalize, cmd.capitalize)
+    end
+
+    def command_file
+      File.join(my_format, cmd)
+    end
+
+    def command_class
+      require_relative command_file
+      Object.const_get(command_class_name).new(resp, options)
+    end
   end
 end

data/lib/wavefront-cli/output/hcl.rb

@@ -7,14 +7,5 @@ module WavefrontOutput
   # different resource types need various amounts of massaging. Args
   # are passed through to the child class.
   #
-  class Hcl < Base
-    def run
-      require_relative File.join('hcl', options[:class])
-      oclass = Object.const_get(format('WavefrontHclOutput::%s',
-                              options[:class].to_s.capitalize))
-      oclass.new(resp, options).run
-    rescue LoadError
-      abort "no HCL output for #{options[:class]}."
-    end
-  end
+  class Hcl < Base; end
 end

data/lib/wavefront-cli/output/json.rb

@@ -5,8 +5,8 @@ module WavefrontOutput
   # Display as JSON
   #
   class Json < Base
-    def run
-      puts resp.to_json
+    def _run
+      resp.to_json
     end
   end
 end

data/lib/wavefront-cli/output/ruby.rb

@@ -6,7 +6,11 @@ module WavefrontOutput
   #
   class Ruby < Base
     def run
-      p resp
+      p _run
+    end
+
+    def _run
+      resp
     end
   end
 end

data/lib/wavefront-cli/output/wavefront.rb

@@ -0,0 +1,10 @@
+require_relative 'base'
+
+module WavefrontOutput
+  #
+  # Display query results in native Wavefront format. The idea is
+  # that timeseries can be extracted, modified, and fed back in via
+  # a proxy.
+  #
+  class Wavefront < Base; end
+end

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

@@ -0,0 +1,14 @@
+module WavefrontWavefrontOutput
+  class Base
+    attr_reader :resp, :options
+
+    def initialize(resp, options)
+      @resp = resp
+      @options = options
+    end
+
+    def run
+      puts _run
+    end
+  end
+end

data/lib/wavefront-cli/output/wavefront/query.rb

@@ -0,0 +1,48 @@
+require 'wavefront-sdk/stdlib/hash'
+require_relative 'base'
+
+module WavefrontWavefrontOutput
+  #
+  # Display query results in Wavefront wire format. We have to
+  # handle raw and normal output in different ways.
+  #
+  class Query < Base
+    def _run
+      if options[:raw]
+        raw_output
+      else
+        query_output
+      end
+    end
+
+    def raw_output
+      resp.each_with_object('') do |point, a|
+        point[:points].each do |p|
+          a.<< wavefront_format(options[:'<metric>'],
+                                p[:value],
+                                p[:timestamp],
+                                options[:host],
+                                point[:tags]) + "\n"
+        end
+      end
+    end
+
+    def query_output
+      resp[:timeseries].each_with_object('') do |ts, a|
+        ts[:data].each do |point|
+          a.<< wavefront_format(ts[:label],
+                                point[1],
+                                point[0],
+                                ts[:host],
+                                ts[:tags]) + "\n"
+        end
+      end
+    end
+
+    def wavefront_format(path, value, ts, source, tags = nil)
+      arr = [path, value, ts, format('source=%s', source)]
+      arr.<< tags.to_wf_tag if tags && !tags.empty?
+      arr.join(' ')
+    end
+  end
+end

data/lib/wavefront-cli/output/yaml.rb

@@ -8,8 +8,8 @@ module WavefrontOutput
     # We don't want the YAML keys to be symbols, so we load it as
     # JSON and turn *that* into YAML.
     #
-    def run
-      puts JSON.parse(resp.to_json).to_yaml
+    def _run
+      JSON.parse(resp.to_json).to_yaml
     end
   end
 end

data/lib/wavefront-cli/version.rb

@@ -1 +1 @@
-WF_CLI_VERSION = '2.7.0'.freeze
+WF_CLI_VERSION = '2.8.0'.freeze

data/spec/spec_helper.rb

@@ -7,6 +7,13 @@ require 'minitest/spec'
 require 'pathname'
 require_relative '../lib/wavefront-cli/controller'
 
+def all_commands
+  (Pathname.new(__FILE__).dirname.parent + 'lib' + 'wavefront-cli' +
+   'commands').children.each.with_object([]) do |c, a|
+    a.<< c.basename.to_s.chomp('.rb') unless c.basename.to_s == 'base.rb'
+  end
+end
+
 unless defined?(CMD)
   CMD = 'wavefront'.freeze
   ENDPOINT = 'metrics.wavefront.com'.freeze
@@ -17,10 +24,7 @@ unless defined?(CMD)
   JSON_POST_HEADERS = {
     'Content-Type': 'application/json', Accept: 'application/json'
   }.freeze
-
-  CMDS = %w[alert integration dashboard event link message metric
-            proxy query savedsearch source user window webhook write].freeze
-
+  CMDS = all_commands.freeze
   BAD_TAG = '*BAD_TAG*'.freeze
   TW = 80
 end
@@ -188,6 +192,18 @@ def tag_tests(cmd, id, bad_id, pth = nil, k = nil)
   invalid_tags(cmd, ["tag add #{id} #{BAD_TAG}", "tag delete #{id} #{BAD_TAG}"])
 end
 
+# Load in a canned query response
+#
+def load_query_response
+  JSON.parse(IO.read(RES_DIR + 'sample_query_response.json'),
+             symbolize_names: true)
+end
+
+def load_raw_query_response
+  JSON.parse(IO.read(RES_DIR + 'sample_raw_query_response.json'),
+             symbolize_names: true)
+end
+
 # stdlib extensions
 #
 class Hash