wavefront-client 3.4.0 → 3.5.1

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    ZDFjYTkzZTY4OGIzM2JlYTJiYmZmMGU0NjQzYjVmYTY1Y2MyZTBlOA==
-  data.tar.gz: !binary |-
-    MjBhZjI0MzA5NjdhNDhlZmU4OTBkN2E1MjVmNmYxZDA2MWNhN2YwMA==
+SHA1:
+  metadata.gz: eb93397040acca02ee9271182b09bf0d1e34a57e
+  data.tar.gz: 324e62b59979579b09b750398d53257142cab2a0
 SHA512:
-  metadata.gz: !binary |-
-    Nzc4MWJhMzNiYjAzZmYzYTYyYWRlNTQ4OTBjNzI2ZDg0YmVkMTdhYjNlYjNj
-    MjM2MjEzMmQzNzFiYjI3YjQ1Y2FjZTlhYTFlODlhODg4Yjk5NjFhNTI4NzU1
-    YjBhMWU3ODA4M2EzZTZiNWYyZTMwNWRhMTY4NDM4MzE2OGE1YzY=
-  data.tar.gz: !binary |-
-    MjQ3MDIzNzRhZTYwZGMwM2FlMjM3N2FjN2UzODg3OGQxNWYxMGY3ZDM3ZDc5
-    OGQ0NGRjYjY1NmUxZDYxODJkYjg5NmU3MzQ3NTRkNzY5NzYxY2YyNDdmMzRj
-    NDlmZGM3YWM5ZmU2YTMxOGFiMzk3MzRkM2E2MmE5MzA4MzZkYjU=
+  metadata.gz: b6093581d6aa9403fe3de7cbf683bc2698460093ba623651a3b2e75d243d5ea8745cdd13b8c87d73ee073cd07704f46eaee33f95417d65a1fc13a5f55eea023a
+  data.tar.gz: 03fad5a006ac5a881ef03db7dd859a54afa3eb57a25933c2c0ce3a18eb4ff862930ab8a032f6aa50dd93cecdb1647b699fc70dc4618c3f4948bc641d84f08124

data/.gitignore

@@ -3,3 +3,5 @@ Gemfile.lock
 pkg
 rdoc
 spec/reports
+.yardoc/
+doc

data/.travis.yml

@@ -3,9 +3,9 @@ cache: bundler
 rvm:
 - 1.9.3
 - 2.0.0
-- 2.1.0
-- 2.2.2
-- 2.3.0
+- 2.1.10
+- 2.2.5
+- 2.3.1
 deploy:
   provider: rubygems
   api_key:

data/README-cli.md

@@ -357,6 +357,103 @@ second. Plot the parabola in Wavefront.
 $ parabola.rb | wavefront write file -F tv -m cli.demo.parabola -
 ```
 
+## `sources` Mode: Tagging and Describing
+
+This command is used to add tags and descriptions to Wavefront
+sources. Note that source tags are not the same as point tags.
+
+```
+Usage:
+  wavefront source list [-c file] [-P profile] [-E endpoint] [-t token]
+           [-f format] [-T tag ...] [-at] [-s source] [-l limit] <pattern>
+  wavefront source show [-c file] [-P profile] [-E endpoint] [-t token]
+           [-f format] <host> ...
+  wavefront source describe [-c file] [-P profile] [-E endpoint] [-t token]
+           [-H host ... ] <description>
+  wavefront source undescribe [-c file] [-P profile] [-E endpoint] [-t token]
+           [<host>] ...
+  wavefront source tag add [-c file] [-P profile] [-E endpoint] [-t token]
+           [-H host ... ] <tag> ...
+  wavefront source tag delete [-c file] [-P profile] [-E endpoint] [-t token]
+           [-H host ... ] <tag> ...
+  wavefront source untag [-c file] [-P profile] [-E endpoint] [-t token]
+           [<host>] ...
+  wavefront source --help
+
+Global options:
+  -c, --config=FILE    path to configuration file [default: /home/rob/.wavefront]
+  -P, --profile=NAME   profile in configuration file [default: default]
+  -D, --debug          enable debug mode
+  -h, --help           show this message
+
+Options:
+  -a, --all            including hidden sources in 'human' output
+  -t, --tags           show tag counts in 'human' output
+  -T, --tagged=STRING  only list sources with this tag in 'human' output
+  -s, --start=STRING   start the list after the named source
+  -l, --limit=NUMBER   only list NUMBER sources
+  -H, --host=STRING    source to manipulate
+  -f, --format=STRING  output format (ruby, json, human)
+                       [default: human]
+```
+
+Tags and descriptions can be applied to multiple sources by repeated
+`-H` options. If no source name is supplied, `wavefront` will use
+the name of the local machine, as supplied by Ruby's
+`Socket.gethostname` method.
+
+The `<pattern>` argument in to the `source list` works as a
+substring match. So `pie` will match `pie`, `pier`, `timepieces`,
+etc. Regular expressions will not work.
+
+### Examples
+
+List, in human-readable format, all active (non-hidden) sources whose name
+contains `cassandra`, which are tagged with `prod` and `eu-west-1`.
+
+```
+$ wavefront source list -T prod -T eu-west-1 -f human cassandra
+```
+
+Tag this host with `dev` and the kernel version:
+
+```
+$ wavefront tag add dev $(uname -r)
+```
+
+Remove all the tags from `i-123456` and `i-abcdef`
+
+```
+$ wavefront source untag i-123456 i-abcdef
+```
+
+Get the description and tags for the host `build-001`, in JSON format.
+
+```
+$ wavefront source show -f json build-001 | json
+{
+  "hostname": "build-001",
+  "userTags": [
+    "JPC",
+    "SmartOS",
+    "dev"
+  ],
+  "description": "build server"
+}
+```
+
+Get a human-readable summary of all the source tags in Wavefront. This works by giving a source name pattern that won't match anything.
+
+```
+$ wavefront source list -t '^$'
+HOSTNAME                  DESCRIPTION                    TAGS
+
+TAG                      COUNT
+hidden                   339
+physical                 10
+zone                     363
+```
+
 ## Notes on Options
 
 ### Times
@@ -406,3 +503,6 @@ 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.
+
+If an option is defined by a command-line switch, and in the
+configuration file, the config file will win.

data/README.md

@@ -4,6 +4,20 @@ Wavefront [![Build Status](https://travis-ci.org/wavefrontHQ/ruby-client.svg?bra
 This is a ruby gem for speaking to the [Wavefront][1] monitoring and graphing system.
 
 ## Usage
+
+To build API documentation with [YARD](https://github.com/lsegal/yard)
+run
+
+```
+$ rake yard
+...
+$ cd doc
+$ yard server
+```
+
+and documentation will be available at
+[http://localhost:8808](http://localhost:8808).
+
 Within your own ruby code:
 
 ### Writer
@@ -164,13 +178,13 @@ response.highcharts[0]['data'].first  # [1436849460000, 517160277.3333333]
 ```
 
 ### Command-line client
-A command line client is included too. Please see [README-cli.md]
-for details.
+A command line client is included too. Please see
+[README-cli.md](README-cli.md) for details.
 
 ## Building and installing
 
 ```bash
-gem build ./wavefront-client.gemspec && gem install ./wavefront*.gem --no-rdoc --no-ri
+rake build
 ```
 
 or

data/Rakefile

@@ -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.
@@ -16,6 +16,7 @@ See the License for the specific language governing permissions and
 
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
+require 'yard'
 
 RSpec::Core::RakeTask.new(:spec)
 
@@ -26,3 +27,7 @@ task :install  do
   sh 'gem install wavefront-client-*.gem --no-rdoc --no-ri'
   sh 'rm wavefront-client-*.gem'
 end
+
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb']
+end

data/bin/wavefront

@@ -39,7 +39,6 @@ DEF_CF = if ENV['HOME']
            Pathname.new('/etc/wavefront/client.conf')
          end
 
-
 # The global_opts are available in every command.
 #
 global_opts = %(
@@ -146,6 +145,34 @@ Files are whitespace separated, and fields can be defined with the -F
 option.  Use 't' for timestamp; 'm' for metric name; 'v' for value
 and 'T' for tags. Put 'T' last.
 ),
+source: %(
+Usage:
+  #{ME} source list [-c file] [-P profile] [-E endpoint] [-t token]
+           [-f format] [-T tag ...] [-at] [-s source] [-l limit] <pattern>
+  #{ME} source show [-c file] [-P profile] [-E endpoint] [-t token]
+           [-f format] <host> ...
+  #{ME} source describe [-c file] [-P profile] [-E endpoint] [-t token]
+           [-H host ... ] <description>
+  #{ME} source undescribe [-c file] [-P profile] [-E endpoint] [-t token]
+           [<host>] ...
+  #{ME} source tag add [-c file] [-P profile] [-E endpoint] [-t token]
+           [-H host ... ] <tag> ...
+  #{ME} source tag delete [-c file] [-P profile] [-E endpoint] [-t token]
+           [-H host ... ] <tag> ...
+  #{ME} source untag [-c file] [-P profile] [-E endpoint] [-t token]
+           [<host>] ...
+  #{ME} source --help
+#{global_opts}
+Options:
+  -a, --all            including hidden sources in 'human' output
+  -t, --tags           show tag counts in 'human' output
+  -T, --tagged=STRING  only list sources with this tag in 'human' output
+  -s, --start=STRING   start the list after the named source
+  -l, --limit=NUMBER   only list NUMBER sources
+  -H, --host=STRING    source to manipulate
+  -f, --format=STRING  output format (#{ALERT_FORMATS.join(', ')})
+                       [default: #{DEFAULT_ALERT_FORMAT}]
+),
 default: %(
 Wavefront CLI
 
@@ -158,6 +185,7 @@ Commands:
   ts          view timeseries data
   alerts      view alerts
   event       open and close events
+  source      view and manage source tags and descriptions
   write       send data points to a Wavefront proxy
 
 Use '#{ME} <command> --help' for further information.)
@@ -182,8 +210,8 @@ rescue Docopt::Exit => e
   end
 end
 
-# Load the config file. Values in there take priority. Probably
-# should be the other way round.
+# Load the config file. Values in there take priority, otherwise
+# default (unset) options will win.
 #
 opts.merge!(Wavefront::Cli.new(opts, nil).load_profile || {})
 
@@ -197,6 +225,9 @@ when :event
 when :alerts
   require 'wavefront/cli/alerts'
   cli = Wavefront::Cli::Alerts.new(opts, [opts[:'<state>']])
+when :source
+  require 'wavefront/cli/sources'
+  cli = Wavefront::Cli::Sources.new(opts, [opts[:'<state>']])
 when :write
   if opts[:file]
     require 'wavefront/cli/batch_write'

data/lib/wavefront/alerting.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.
@@ -15,8 +15,8 @@ See the License for the specific language governing permissions and
 =end
 
 require "wavefront/client/version"
-require "wavefront/exception"
 require "wavefront/constants"
+require 'wavefront/mixins'
 require 'rest_client'
 require 'uri'
 require 'logger'
@@ -24,6 +24,8 @@ require 'logger'
 module Wavefront
   class Alerting
     include Wavefront::Constants
+    include Wavefront::Validators
+    include Wavefront::Mixins
     DEFAULT_PATH = '/api/alert/'
 
     attr_reader :token
@@ -55,35 +57,39 @@ module Wavefront
 
     private
 
-    def get_alerts(path, options={})
-      options[:host] ||= DEFAULT_HOST
-      options[:path] ||= DEFAULT_PATH
+    def list_of_tags(t)
+      t.is_a?(Array) ? t : [t]
+    end
+
+    def mk_qs(options)
+      query = "t=#{token}"
+
+      query += '&' + list_of_tags(options[:shared_tags]).map do |t|
+        "customerTag=#{t}"
+      end.join('&') if options[:shared_tags]
 
-      query = "t=#{@token}"
+      query += '&' + list_of_tags(options[:private_tags]).map do |t|
+        "userTag=#{t}"
+      end.join('&') if options[:private_tags]
 
-      if options[:shared_tags]
-        tags = options[:shared_tags].class == Array ? options[:shared_tags] : [ options[:shared_tags] ] # Force an array, even if string given
-        query += "&#{tags.map{|t| "customerTag=#{t}"}.join('&')}"
-      end
+      query
+    end
 
-      if options[:private_tags]
-        tags = options[:private_tags].class == Array ? options[:private_tags] : [ options[:private_tags] ] # Force an array, even if string given
-        query += "&#{tags.map{|t| "userTag=#{t}"}.join('&')}"
-      end
+    def get_alerts(path, options={})
+      options[:host] ||= DEFAULT_HOST
+      options[:path] ||= DEFAULT_PATH
 
       uri = URI::HTTPS.build(
-        host: options[:host],
-	path: File.join(options[:path], path),
-	query: query
+        host:  options[:host],
+        path:  uri_concat(options[:path], path),
+	      query: mk_qs(options),
       )
+
       RestClient.get(uri.to_s)
     end
 
     def debug(enabled)
-      if enabled
-        RestClient.log = 'stdout'
-      end
+      RestClient.log = 'stdout' if enabled
     end
-
   end
 end

data/lib/wavefront/batch_writer.rb

@@ -1,6 +1,7 @@
 require 'wavefront/client/version'
 require 'wavefront/exception'
 require 'wavefront/constants'
+require 'wavefront/validators'
 require 'uri'
 require 'socket'
 
@@ -27,6 +28,7 @@ module Wavefront
   class BatchWriter
     attr_reader :sock, :opts, :summary
     include Wavefront::Constants
+    include Wavefront::Validators
 
     def initialize(options = {})
       #
@@ -117,7 +119,7 @@ module Wavefront
 
         send_point(hash_to_wf(p))
       end
-      return summary[:rejected] == 0 ? true : false
+      summary[:rejected] == 0 ? true : false
     end
 
     def valid_point?(point)
@@ -134,41 +136,6 @@ module Wavefront
       true
     end
 
-    def valid_path?(path)
-      fail Wavefront::Exception::InvalidMetricName unless \
-        path.is_a?(String) && path.match(/^[a-z0-9\-_\.]+$/) &&
-        path.length < 1024
-      true
-    end
-
-    def valid_value?(value)
-      fail Wavefront::Exception::InvalidMetricValue unless value.is_a?(Numeric)
-      true
-    end
-
-    def valid_ts?(ts)
-      unless ts.is_a?(Time) || ts.is_a?(Date)
-        fail Wavefront::Exception::InvalidTimestamp
-      end
-      true
-    end
-
-    def valid_source?(path)
-      unless path.is_a?(String) && path.match(/^[a-z0-9\-_\.]+$/) &&
-             path.length < 1024
-        fail Wavefront::Exception::InvalidSource
-      end
-      true
-    end
-
-    def valid_tags?(tags)
-      tags.each do |k, v|
-        fail Wavefront::Exception::InvalidTag unless (k.length +
-             v.length < 254) && k.match(/^[a-z0-9\-_\.]+$/)
-      end
-      true
-    end
-
     def hash_to_wf(p)
       #
       # Convert the hash received by the write() method to a string

data/lib/wavefront/cli/events.rb

@@ -65,10 +65,9 @@ class Wavefront::Cli::Events < Wavefront::Cli
     end
 
     begin
-      response = wf_event.delete({
-        startTime: options[:'<timestamp>'],
-        name: options[:'<event>'],
-      })
+      wf_event.delete(startTime: options[:'<timestamp>'],
+                      name: options[:'<event>']
+                     )
     rescue RestClient::Unauthorized
       raise 'Cannot connect to Wavefront API.'
     rescue RestClient::ResourceNotFound
@@ -78,7 +77,7 @@ class Wavefront::Cli::Events < Wavefront::Cli
       raise 'Cannot delete event.'
     end
 
-    puts "Deleted event."
+    puts 'Deleted event.'
   end
 
   def prep_time(t)

data/lib/wavefront/cli/sources.rb

@@ -0,0 +1,193 @@
+require 'wavefront/cli'
+require 'wavefront/metadata'
+require 'json'
+require 'pp'
+
+#
+# Turn CLI input, from the 'sources' command, into metadata API calls
+#
+class Wavefront::Cli::Sources < Wavefront::Cli
+  attr_accessor :wf, :out_format, :show_hidden, :show_tags
+
+  def setup_wf
+    @wf = Wavefront::Metadata.new(options[:token])
+  end
+
+  def run
+    setup_wf
+    @out_format = options[:format]
+    @show_hidden = options[:all]
+    @show_tags = options[:tags]
+
+    begin
+      if options[:list]
+        list_source_handler(options[:'<pattern>'], options[:start],
+                            options[:limit])
+      elsif options[:show]
+        show_source_handler(options[:'<host>'])
+      elsif options[:tag] && options[:add]
+        add_tag_handler(options[:host], options[:'<tag>'])
+      elsif options[:tag] && options[:delete]
+        delete_tag_handler(options[:host], options[:'<tag>'])
+      elsif options[:describe]
+        describe_handler(options[:host], options[:'<description>'])
+      elsif options[:undescribe]
+        describe_handler(options[:'<host>'], '')
+      elsif options[:untag]
+        untag_handler(options[:'<host>'])
+      else
+        fail 'undefined sources error'
+      end
+    rescue Wavefront::Exception::InvalidSource
+      abort 'ERROR: invalid source name.'
+    end
+  end
+
+  def list_source_handler(pattern, start = false, limit = false)
+    limit ||= 100
+
+    q = {
+      desc:         false,
+      limit:        limit,
+      pattern:      pattern
+    }
+
+    q[:lastEntityId] = start if start
+
+    display_data(JSON.parse(wf.show_sources(q)), 'list_source')
+  end
+
+  def describe_handler(hosts, desc)
+    hosts = [Socket.gethostname] if hosts.empty?
+
+    hosts.each do |h|
+      if desc.empty?
+        puts "clearing description of '#{h}'"
+      else
+        puts "setting '#{h}' description to '#{desc}'"
+      end
+
+      begin
+        wf.set_description(h, desc)
+      rescue Wavefront::Exception::InvalidString
+        puts 'ERROR: description contains invalid characters.'
+      end
+    end
+  end
+
+  def untag_handler(hosts)
+    hosts ||= [Socket.gethostname]
+
+    hosts.each do |h|
+      puts "Removing all tags from '#{h}'"
+      wf.delete_tags(h)
+    end
+  end
+
+  def add_tag_handler(hosts, tags)
+    hosts ||= [Socket.gethostname]
+
+    hosts.each do |h|
+      tags.each do |t|
+        puts "Tagging '#{h}' with '#{t}'"
+        begin
+          wf.set_tag(h, t)
+        rescue Wavefront::Exception::InvalidString
+          puts 'ERROR: tag contains invalid characters.'
+        end
+      end
+    end
+  end
+
+  def delete_tag_handler(hosts, tags)
+    hosts ||= [Socket.gethostname]
+
+    hosts.each do |h|
+      tags.each do |t|
+        puts "Removing tag '#{t}' from '#{h}'"
+        wf.delete_tag(h, t)
+      end
+    end
+  end
+
+  def show_source_handler(sources)
+    sources.each do |s|
+      begin
+        result = JSON.parse(wf.show_source(s))
+      rescue RestClient::ResourceNotFound
+        puts "Source '#{s}' not found."
+        next
+      end
+
+      display_data(result, 'show_source')
+    end
+  end
+
+  def display_data(result, method)
+    if out_format == 'human'
+      puts public_send('humanize_' + method, result)
+    elsif out_format == 'json'
+      puts result.to_json
+    else
+      pp result
+    end
+  end
+
+  def humanize_list_source(result)
+    hdr = format('%-25s %-30s %s', 'HOSTNAME', 'DESCRIPTION', 'TAGS')
+
+    ret = result['sources'].each_with_object([hdr]) do |s, aggr|
+      if s.include?('userTags') && s['userTags'].include?('hidden') &&
+         !show_hidden
+        next
+      end
+
+      if options[:tagged]
+        skip = false
+        options[:tagged].each do |t|
+          unless s['userTags'].include?(t)
+            skip = true
+            break
+          end
+        end
+        next if skip
+      end
+
+      if s['description']
+        desc = s['description']
+        desc = desc[0..27] + '...' if desc.length > 30
+      else
+        desc = ''
+      end
+
+      tags = s['userTags'] ? s['userTags'].join(', ') : ''
+
+      aggr.<< format('%-25s %-30s %s', s['hostname'], desc, tags)
+    end
+
+    if show_tags
+      ret.<< ['', format('%-25s%s', 'TAG', 'COUNT')]
+
+      result['counts'].each do |tag, count|
+        ret.<< format('%-25s%s', tag, count)
+      end
+    end
+
+    ret.join("\n")
+  end
+
+  def humanize_show_source(data)
+    ret = [data['hostname']]
+
+    if data['description']
+      ret.<< format('  %-15s%s', 'description', data['description'])
+    end
+
+    if data['userTags']
+      ret.<< format('  %-15s%s', 'tags', data['userTags'].shift)
+      data['userTags'].each { |t| ret.<< format('  %-15s%s', '', t) }
+    end
+
+    ret.join("\n")
+  end
+end