wavefront-client 3.0.0 → 3.1.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    YTkyYWUzNzQ3MTVmYjhlNGI3NWZlZDM5YTBjYTAwMzNkMTQ2MjQ0YQ==
+    MjE5OWM5OWIyYjcxNWI2MGJjNGRiOWI1YjBlMjI1OWFiMzIyMWVjYg==
   data.tar.gz: !binary |-
-    NDNlN2ZiNmYxNDE0NzhlMzdjMTJhNjExZGI4ZjhhY2Q0YWE5YjViMw==
+    OGJkZTg1ZTgwMDdjMmZhZDhiYjIyZDVlYmJlYzMzNGZiZDI4ZWEyOQ==
 SHA512:
   metadata.gz: !binary |-
-    YzQxYzE3NGZmNzkwNWRjYzgxYWM0MDBhNDk5OGM1NGZlMjE4MDA2ZWI2YTNi
-    YTRhNTQxYTIzYzFhNWRlYTgxYzIyNWI1OTgwNTA1ZWE0NjFmMjY0M2Y2ODg3
-    ZmVlOTJmZDk2YTdiYjVkOGEzOTUzYTMwYjk3NTU5NjVkOWRjZjI=
+    YTBhNmI4OWJmOWJlM2I2NDMwYTNhNjIzMGNjZjM0OWVlMjdjMzU1YWUwNjYy
+    MTZjYjIwYjI2MDhlNDU3ZmJjYmZjODk1NmY0ZTM0OGJlMzMzMDJjZmNjN2Jk
+    MDk4N2MxODQzYzQ0MDQxMzRkY2Y2YzMwOWE3ODA3ZGFjZDA2MGM=
   data.tar.gz: !binary |-
-    MDljMjNlYzg3YTJhNjY0YWQ3MDA0Y2M2ZDYyOWVjMzlkOTA5NzEyMjJhMzNl
-    NmFhMjVmMjI4MDAyNjEzNTc1OTlmOWE5ZWYyY2Y4MzY2ZDg5ODAzOTI2OGEw
-    ZTg0NWFiZGQyOTNhZGRkYmEyNmE3ZGNiMzI2NmIxYjBmNjY1NmE=
+    YjJhOGNmOTEyYzE1ZmRlN2JhMjNkMTgwMmVmOGU2YWJhYjY2MGRjMGVmNTFm
+    YjQwZmJhMTRhYTBhYWRmM2ViNGIyZjlhYTQ5Y2JiYzIxOTMyZTQyZDUxNTdl
+    MGNlMWVhMjNlNjkzM2U2MjAwNjdmY2QxYzgyOWExZGQyYTc2ZDE=

data/README.md

@@ -180,16 +180,18 @@ See `<command> --help` for more information on a specific command.
 
 $ wavefront ts --help
 Usage: wavefront COMMAND QUERY (OPTIONS)
-    -d, --days                        Query granularity of days
+    -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
-    -E, --endpoint                    Connect to alternative cluster endpoint (default: metrics.wavefront.com)
-    -S, --seconds                     Query granularity of seconds
-    -s, --start                       Time in UNIX epoch seconds to begin the query from
+    -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, --end                         Time in UNIX epoch seconds to query to
-    -f, --format                      Output format (raw, ruby, graphite, highcharts) (default: raw)
+    -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
@@ -213,6 +215,55 @@ $ wavefront alerts snoozed -t TOKEN -f json --shared ops
    ...
 ```
 
+#### 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.
 
 ## Building and installing
 

data/bin/wavefront

@@ -12,52 +12,94 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 #    limitations under the License.
-
+#
 require 'wavefront/client'
 require 'slop'
+require 'pathname'
+require 'wavefront/cli'
 
+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
+  end
+
   command 'ts' do
     description "Query the timeseries"
-    on 'd', 'days', 'Query granularity of days'
+    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 'E', 'endpoint=', 'Connect to alternative cluster endpoint', default: Wavefront::Client::DEFAULT_HOST.to_s
-    on 'S', 'seconds', 'Query granularity of seconds'
-    on 's', 'start=', 'Time in UNIX epoch seconds to begin the query from'
+    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', 'end=', 'Time in UNIX epoch seconds to query to'
+    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=', 'The number of path elements to treat as a prefix when doing schema manipulations', default: Wavefront::Client::DEFAULT_PREFIX_LENGTH
+    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=', 'Flag to include metrics that have not been reporting for more than 4 weeks,defaults to false', default: Wavefront::Client::DEFAULT_OBSOLETE_METRICS
+    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, arguments)
-      cli.run
+      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
 
   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, arguments)
-      cli.run
+      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
     end
   end
 
+
+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
 end
 
 puts options

data/lib/wavefront/cli/alerts.rb

@@ -17,6 +17,7 @@ require 'wavefront/alerting'
 require 'wavefront/cli'
 require 'json'
 require 'pp'
+require 'time'
 
 class Wavefront::Cli::Alerts < Wavefront::Cli
 
@@ -26,12 +27,18 @@ class Wavefront::Cli::Alerts < Wavefront::Cli
     alerts = Wavefront::Alerting.new(@options[:token])
     queries = alerts.public_methods(false).sort
     queries.delete(:token)
- 
-    if arguments[0]
-      query = arguments[0].to_sym
-    else
-      puts "Your query should be one of: #{ queries.each {|q| q.to_s}.join(', ') }. See --help for more information"
-      exit 1
+
+    raise 'Missing query.' if arguments.empty?
+    query = arguments[0].to_sym
+
+    unless queries.include?(query)
+      raise 'State must be one of: ' + queries.each {|q| q.to_s}.join(', ')
+    end
+
+    unless Wavefront::Client::ALERT_FORMATS.include?(
+                                            @options[:format].to_sym)
+      raise 'Output format must be one of: ' +
+            Wavefront::Client::ALERT_FORMATS.join(', ')
     end
 
     # This isn't especially nice, but if require to
@@ -42,22 +49,20 @@ class Wavefront::Cli::Alerts < Wavefront::Cli
     if @options[:shared]
       options[:shared_tags] = @options[:shared].delete(' ').split(',')
     end
+
     if @options[:private]
       options[:private_tags] = @options[:private].delete(' ').split(',')
     end
 
-    if queries.include?(query)
-      result = alerts.send(query, options)
-    else
-      puts "Your query should be one of: #{ queries.each {|q| q.to_s}.join(', ') }. See --help for more information"
-      exit 1
-    end
+    result = alerts.send(query, options)
 
     case @options[:format].to_sym
     when :ruby
       pp result
     when :json
       puts JSON.pretty_generate(JSON.parse(result))
+    when :human
+      puts humanize(JSON.parse(result))
     else
       puts "Invalid output format, See --help for more detail."
       exit 1
@@ -65,4 +70,79 @@ class Wavefront::Cli::Alerts < Wavefront::Cli
 
     exit 0
   end
+
+  def humanize(alerts)
+    #
+    # Selectively display alert information in an easily
+    # human-readable format. I have chosen not to display certain
+    # fields which I don't think are useful in this context. I also
+    # wish to put the fields in order. Here are the fields I want, in
+    # the order I want them.
+    #
+    row_order = %w(name created severity condition displayExpression
+                   minutes resolveAfterMinutes updated alertStates
+                   metricsUsed hostsUsed additionalInformation)
+
+    # build up an array of lines then turn it into a string and
+    # return it
+    #
+    # Most things get printed with the human_line() method, but some
+    # data needs special handling. To do that, just add a method
+    # called human_line_key() where key is something in row_order,
+    # and it will be found.
+    #
+    x = alerts.map do |alert|
+      row_order.map do |key|
+        lm = "human_line_#{key}"
+        if self.respond_to?(lm)
+          self.method(lm.to_sym).call(key, alert[key])
+        else
+          human_line(key, alert[key])
+        end
+      end
+    end
+  end
+
+  def human_line(k, v)
+    '%-22s%s' % [k, v]
+  end
+
+  def human_line_created(k, v)
+    #
+    # The 'created' and 'updated' timestamps are in epoch
+    # milliseconds
+    #
+    human_line(k, Time.at(v / 1000))
+  end
+
+  def human_line_updated(k, v)
+    human_line_created(k, v)
+  end
+
+  def human_line_hostsUsed(k, v)
+    #
+    # Put each host on its own line, indented.
+    #
+    v.sort!
+    [human_line(k, v.shift)] + v.map {|el| human_line('', el)}
+  end
+
+  def human_line_metricsUsed(k, v)
+    human_line_hostsUsed(k, v)
+  end
+
+  def human_line_alertStates(k, v)
+    human_line(k, v.join(','))
+  end
+
+  def human_line_additionalInformation(k, v)
+    human_line(k, indent_wrap(v))
+  end
+
+  def indent_wrap(line, cols=78, offset=22)
+    #
+    # hanging indent long lines to fit in an 80-column terminal
+    #
+    line.gsub(/(.{1,#{cols - offset}})(\s+|\Z)/, "\\1\n#{' ' * offset}")
+  end
 end

data/lib/wavefront/cli/ts.rb

@@ -17,29 +17,39 @@ require 'wavefront/client'
 require 'wavefront/cli'
 require 'pp'
 require 'json'
+require 'date'
 
 class Wavefront::Cli::Ts < Wavefront::Cli
 
   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]
-    if @options.minutes?
+
+    if @options[:minutes]
       granularity = 'm'
-    elsif @options.hours?
+    elsif @options[:hours]
       granularity = 'h'
-    elsif @options.seconds?
+    elsif @options[:seconds]
       granularity = 's'
-    elsif @options.days?
+    elsif @options[:days]
       granularity = 'd'
     else
-      puts "You must specify a granularity of either --seconds, --minutes --hours or --days. See --help for more information."
-      exit 1
+      raise "You must specify a granularity of either --seconds, --minutes --hours or --days. See --help for more information."
     end
 
     unless Wavefront::Client::FORMATS.include?(@options[:format].to_sym)
-      puts "The output format must be on of #{Wavefront::Client::FORMATS.join(', ')}"
-      exit 1
+      raise "The output format must be one of: #{Wavefront::Client::FORMATS.join(', ')}."
     end
 
     options = Hash.new
@@ -47,11 +57,11 @@ class Wavefront::Cli::Ts < Wavefront::Cli
     options[:prefix_length] = @options[:prefixlength].to_i
 
     if @options[:start]
-      options[:start_time] = Time.at(@options[:start].to_i)
+      options[:start_time] = parse_time(@options[:start])
     end
 
     if @options[:end]
-      options[:end_time] = Time.at(@options[:end].to_i)
+      options[:end_time] = parse_time(@options[:end])
     end
 
     wave = Wavefront::Client.new(@options[:token], @options[:endpoint], @options[:debug])
@@ -60,6 +70,8 @@ class Wavefront::Cli::Ts < Wavefront::Cli
       puts wave.query(query, granularity, options)
     when :graphite
       puts wave.query(query, granularity, options).graphite.to_json
+    when :human
+      puts wave.query(query, granularity, options).human
     else
       pp wave.query(query, granularity, options)
     end

data/lib/wavefront/cli.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.
@@ -14,6 +14,8 @@ See the License for the specific language governing permissions and
 
 =end
 
+require 'inifile'
+
 module Wavefront
   class Cli
 
@@ -23,11 +25,29 @@ module Wavefront
       @options   = options
       @arguments = arguments
 
-      if @options.help?
+      if @options[:help]
         puts @options
         exit 0
       end
     end
 
+    def load_profile
+      cf = Pathname.new(options[:config])
+      pf = options[:profile]
+
+      if cf.exist?
+        raw = IniFile.load(cf)
+        profile = raw[pf]
+
+        unless profile.empty?
+          puts "using #{pf} profile from #{cf}" if options[:debug]
+          return profile.inject({}){|x, (k, v)| x[k.to_sym] = v; x }
+        end
+
+      else
+        puts "no config file at '#{cf}': using options" if options[:debug]
+      end
+    end
+
   end
 end

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.0.0"
+    VERSION = "3.1.0"
   end
 end

data/lib/wavefront/client.rb

@@ -38,7 +38,7 @@ module Wavefront
 
     def query(query, granularity='m', options={})
 
-      options[:end_time] ||= Time.now
+      options[:end_time] ||= Time.now.utc
       options[:start_time] ||= options[:end_time] - DEFAULT_PERIOD_SECONDS
       options[:response_format] ||= DEFAULT_FORMAT
       options[:prefix_length] ||= DEFAULT_PREFIX_LENGTH
@@ -76,6 +76,5 @@ module Wavefront
         RestClient.log = 'stdout'
       end
     end
-
   end
 end

data/lib/wavefront/constants.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.
@@ -22,7 +22,9 @@ module Wavefront
     DEFAULT_PREFIX_LENGTH = 1
     DEFAULT_STRICT = true
     DEFAULT_OBSOLETE_METRICS = false
-    FORMATS = [ :raw, :ruby, :graphite, :highcharts ]
+    FORMATS = [ :raw, :ruby, :graphite, :highcharts, :human ]
+    ALERT_FORMATS = [:ruby, :json, :human]
+    DEFAULT_ALERT_FORMAT = :human
     GRANULARITIES = %w( s m h d )
   end
 end

data/lib/wavefront/response.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.
@@ -39,7 +39,7 @@ module Wavefront
     class Ruby
       include JSON
       attr_reader :response, :options
-      
+
       def initialize(response, options={})
         @response = response
         @options = options
@@ -59,7 +59,7 @@ module Wavefront
       def initialize(response, options={})
         super
         options[:prefix_length] ||= Wavefront::Client::DEFAULT_PREFIX_LENGTH
-        
+
         @graphite = Array.new
         self.timeseries.each do |ts|
 
@@ -72,7 +72,7 @@ module Wavefront
           end
 
           output_timeseries['datapoints'] = datapoints
-          @graphite << output_timeseries 
+          @graphite << output_timeseries
 
         end
       end
@@ -111,5 +111,38 @@ module Wavefront
       end
     end
 
+    class Human < Wavefront::Response::Ruby
+      #
+      # Print "human-readable" (but also easily machine-pareseable)
+      # values.
+      #
+      attr_reader :response, :options, :human
+
+      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
+          end
+        else
+          out = self.warnings
+        end
+
+        @human = out.join("\n")
+      end
+    end
   end
 end

data/wavefront-client.gemspec

@@ -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.
@@ -40,6 +40,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "rest-client", ">= 1.6.7", "<= 1.8"
   spec.add_dependency "slop", ">= 3.4.7", "<= 3.6"
+  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.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Sam Pointer
@@ -13,7 +13,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-05-16 00:00:00.000000000 Z
+date: 2016-05-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -97,6 +97,20 @@ dependencies:
     - - <=
       - !ruby/object:Gem::Version
         version: '3.6'
+- !ruby/object:Gem::Dependency
+  name: inifile
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 3.0.0
 description: A simple abstraction for talking to wavefront in ruby
 email:
 - support@wavefront.com