wavefront-client 3.5.4 → 3.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5c289e188276ac63035e6acd3ea84ab59721e63b
-  data.tar.gz: eb9d96bae403aa21ed775bf37bb5ad85d8c078c3
+  metadata.gz: 27196556716ec832044c8587e6d395caddc4c39f
+  data.tar.gz: b8acc4e5aa6ce54130fd6abc143d3f2f8fffe44b
 SHA512:
-  metadata.gz: 18b87b4ff437336b124a353fb982bdea69c0a34ed32314a0fad69db6f636cb33c0b529cad6dffa95137ef18a952b1ad0d1066959e01fa25e652bceb04e78b5e8
-  data.tar.gz: c926ec0a4245bba66b92f64daa28cbb300c8abad127d3a2f302b6c05b14e234e0109b6986678bb220c6651886125a716e96a154e75ac5c7ee81fc9a25d0564e1
+  metadata.gz: 656b1215fe52afbdcfeb62212e458f900807edf84621e2968c50f44ff23b60b1f2424d2a32753d3f19e14de3894c0f8d479dd6320d55e3fa3307c7117ee5936d
+  data.tar.gz: c8c9741dfc418ba90aab20f6b4b3d898e978dd98677baae33ec506b42c0c377ce77dc0a31291210b99e556c071af542a19e42dcd3702e84206ecd8099188b251

data/README-cli.md

@@ -102,23 +102,37 @@ $ ./wavefront  ts -f human -m --start=18:00 --end=20:00 'events()'
 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
+## `alerts` Mode: Retrieving and Importing 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.
+The `alerts` command lets you view, export, and import alerts. It
+does not currently modification removal, or reacting to alerts, as
+these actions are not supported by the v1 API.
+
+Alerts 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`, `yaml` or `json` formatters.
 
 ```
 Usage:
-  wavefront alerts [-D] [-c file] [-P profile] [-E endpoint] [-t token] [-V]
+  wavefront alerts [-DnV] [-c file] [-P profile] [-E endpoint] [-t token]
             [-f format] [-p tag] [ -s tag] <state>
+  wavefront alerts export [-DnV] [-c file] [-P profile] [-E endpoint] [-t token]
+            [-f format] <timestamp>
+  wavefront alerts import [-DnV] [-c file] [-P profile] [-E endpoint] [-t token]
+            <file>
+
+Global options:
+  -c, --config=FILE    path to configuration file [/home/rob/.wavefront]
+  -P, --profile=NAME   profile in configuration file [default]
+  -D, --debug          enable debug mode
+  -n, --noop           don't perform API calls
+  -V, --verbose        be verbose
+  -h, --help           show this message
 
 Options:
   -E, --endpoint=URI       cluster endpoint [metrics.wavefront.com]
   -t, --token=TOKEN        Wavefront authentication token
-  -f, --alertformat=STRING output format (ruby, json, human)
+  -f, --alertformat=STRING output format (ruby, json, human, yaml)
                            []
   -p, --private=TAG        retrieve only alerts with named private tags,
                            comma delimited.
@@ -126,6 +140,17 @@ Options:
                            comma delimited.
 ```
 
+When exporting an alert, you must refer to it my its millisecond
+timestamp. This value is in the `created` field when you view an
+alert as `json` or `YAML`, and it is shown in brackets on the
+`created` line if you use `human` output.
+
+Due to v1 API limitations, not all an alert's properties will
+survive the import/export process.
+
+Imports can only be alerted from a file. Importing from stdin is
+currently unsupported.
+
 ### Examples
 
 List all alerts in human-readable format. Alerts are separated by a
@@ -157,10 +182,23 @@ severity              WARN
 Show alerts currently firing, in JSON format:
 
 ```
-$ wavefront alerts -P sysdef --format ruby active
+$ wavefront alerts -P sysdef --format json 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}]"
 ```
 
+Export an alert from your default account, in JSON format:
+
+```
+$ wavefront alerts export -f json 1488995981076 >my_alert.json
+```
+
+and re-import it:
+
+```
+$ wavefront alerts import my_alert.json
+Alert imported.
+```
+
 ## `event` Mode: Opening and Closing Events
 
 The `event` command is used to open and close Wavefront events.
@@ -473,6 +511,121 @@ physical                 10
 zone                     363
 ```
 
+## `dashboard` Mode:
+
+The `dashboard` command implements all of the v1 API's `dashboard`
+paths.
+
+```
+Usage:
+  wavefront dashboard list [-DnV] [-c file] [-P profile] [-E endpoint]
+           [-f format] [-t token] [-T tag...] [-p tag...] [-a]
+  wavefront dashboard import [-DnV] [-c file] [-P profile] [-E endpoint]
+           [-f format] [-F] <file>
+  wavefront dashboard export [-DnV] [-c file] [-P profile] [-E endpoint]
+           [-f format] [-v version] <dashboard_id>
+  wavefront dashboard create [-DnV] [-c file] [-P profile] [-E endpoint]
+           <dashboard_id> <name>
+  wavefront dashboard clone [-DnV] [-c file] [-P profile] [-E endpoint]
+           [-v version] -s source_id <new_id> <new_name>
+  wavefront dashboard delete [-DnV] [-c file] [-P profile] [-E endpoint]
+           <dashboard_id>
+  wavefront dashboard undelete [-DnV] [-c file] [-P profile] [-E endpoint]
+           <dashboard_id>
+  wavefront dashboard history [-DnV] [-c file] [-P profile] [-E endpoint]
+           [-f format] [-S version] [-L limit] <dashboard_id>
+```
+
+Dashboard IDs are the same as their `url` fields when listed or exported.
+
+Deleting a dashboard once will move it to "trash". Deleting a second
+time removes it for ever. Dashboards can be recovered from the trash
+with the `undelete` command.
+
+Listing dashboards with `-f human` will not ordinarily display
+dashboards in the trash. Supplying the `-a` option will list all
+dashboards, and trashed ones will have `(in trash)` appended to
+their name field. Listing dashboards in a machine-parseable format
+does not do this filtering.
+
+When cloning a dashboard you may use the `-v` flag to clone from a
+specific version. Without `-v` the current dashboard is cloned.
+
+If your dashboard output format, defined either by the `-f` flag or
+the `dashformat` config-file setting is `human`, and you use
+`dashboard export`, the output format will silently switch to JSON
+for that one command.
+
+Importing a dashboard will fail if a dashboard with the same url
+already exists. If  you supply the `-F` flag, the existing dashboard
+will be overwritten.
+
+Dashboards can be imported from YAML or JSON files, but not
+currently from standard in. The file format is automatically
+detected.
+
+### Examples
+
+List active dashboards in a human-readable form:
+
+```
+$ wavefront dashboard list -f human
+ID                               NAME
+S3                               S3
+box                              how busy is box?
+discogs                          discogs data
+internal_metrics                 Internal Metrics
+intro-anomaly-detection-series-1 Intro: Use Case: Anomaly Detection
+Series - Part 1
+intro-code-push-example          Intro: Use Case: Code Push Event
+...
+```
+
+Show the modification history of a dashboard, in human-readable
+form:
+
+```
+$ wavefront dashboard history shark-overview
+25  2016-10-01 16:08:29 +0100 (slackboy@gmail.com)
+      Dashboard Section: Incoming Chart added
+      Chart: swapping events in Section: Memory updated
+24  2016-10-01 16:06:25 +0100 (slackboy@gmail.com)
+      Chart: swapping events in Section: Memory updated
+23  2016-10-01 15:35:39 +0100 (slackboy@gmail.com)
+      Chart: SMF services added to Section: System Health
+      Chart: ZFS ARC in Section: ZFS updated
+22  2016-10-01 15:31:18 +0100 (slackboy@gmail.com)
+      Chart: ZFS ARC in Section: ZFS updated
+21  2016-10-01 15:30:57 +0100 (slackboy@gmail.com)
+      Dashboard Section: Incoming Chart removed
+      Dashboard Section: Memory added
+      Dashboard Section: Memory added
+20  2016-10-01 15:30:07 +0100 (slackboy@gmail.com)
+      Chart: swapping events added to Section: Incoming Chart
+19  2016-10-01 15:25:40 +0100 (slackboy@gmail.com)
+      Dashboard Section: Incoming Chart added
+      Chart: ZFS ARC in Section: ZFS updated
+...
+```
+
+The first column is the version of the dashboard.
+
+Export a dashboard to a JSON file
+
+```
+$ wavefront dashboard export -f json shark-overview >shark_overview.json
+```
+
+And import it back in
+```
+$ wavefront dashboard import shark_overview.json
+```
+
+### Caveats
+
+It is not currently possible to delete the example dashboards
+supplied by Wavefront. This is not the fault of the CLI or SDK.
+
 ## Notes on Options
 
 ### Times

data/bin/wavefront

@@ -17,7 +17,7 @@
 require 'pathname'
 
 # uncomment for development
-$LOAD_PATH.<< Pathname.new(__FILE__).dirname.realpath.parent + 'lib'
+# $LOAD_PATH.<< Pathname.new(__FILE__).dirname.realpath.parent + 'lib'
 
 require 'wavefront/client'
 require 'wavefront/client/version'
@@ -87,6 +87,10 @@ alerts: %(
 Usage:
   #{ME} alerts [-DnV] [-c file] [-P profile] [-E endpoint] [-t token]
             [-f format] [-p tag] [ -s tag] <state>
+  #{ME} alerts export [-DnV] [-c file] [-P profile] [-E endpoint] [-t token]
+            [-f format] <timestamp>
+  #{ME} alerts import [-DnV] [-c file] [-P profile] [-E endpoint] [-t token]
+            <file>
 #{global_opts}
 Options:
   -E, --endpoint=URI       cluster endpoint [#{DEFAULT_OPTS[:endpoint]}]
@@ -180,6 +184,38 @@ Options:
   -H, --host=STRING          source to manipulate
   -f, --sourceformat=STRING  output format (#{SOURCE_FORMATS.join(', ')}) [#{DEFAULT_OPTS[:sourceformat]}]
 ),
+dashboard: %(
+Usage:
+  #{ME} dashboard list [-DnV] [-c file] [-P profile] [-E endpoint]
+           [-t token] [-f format] [-a] [-T tag...] [-p tag...]
+  #{ME} dashboard import [-DnV] [-c file] [-P profile] [-E endpoint]
+           [-t token] [-f format] [-F] <file>
+  #{ME} dashboard export [-DnV] [-c file] [-P profile] [-E endpoint]
+           [-t token] [-f format] [-v version] <dashboard_id>
+  #{ME} dashboard create [-DnV] [-c file] [-P profile] [-E endpoint]
+           [-t token] <dashboard_id> <name>
+  #{ME} dashboard clone [-DnV] [-c file] [-P profile] [-E endpoint]
+           [-t token] [-v version] <source_id> <new_id> <new_name>
+  #{ME} dashboard delete [-DnV] [-c file] [-P profile] [-E endpoint]
+           [-t token] <dashboard_id>
+  #{ME} dashboard undelete [-DnV] [-c file] [-P profile] [-E endpoint]
+           [-t token] <dashboard_id>
+  #{ME} dashboard history [-DnV] [-c file] [-P profile] [-E endpoint]
+           [-t token] [-f format] [-S version] [-L limit] <dashboard_id>
+  #{ME} dashboard --help
+#{global_opts}
+Options:
+  -E, --endpoint=URI       cluster endpoint [#{DEFAULT_OPTS[:endpoint]}]
+  -t, --token=TOKEN        Wavefront authentication token
+  -a, --all                in human output mode, list all dashboards
+  -T, --sharedtag=TAG      only select dashboards with this shared tag
+  -p, --privatetag=TAG     only select dashboards with this private tag
+  -S, --start=VERSION      highest version number from which to descend
+  -L, --limit=COUNT        number of versions to report
+  -v, --version=INTEGER    version of dashboard to clone
+  -F, --force              import dashboard even if it already exists
+  -f, --dashformat=STRING  output format (#{DASH_FORMATS.join(', ')}) [#{DEFAULT_OPTS[:dashformat]}]
+),
 default: %(
 Wavefront CLI
 
@@ -191,6 +227,7 @@ Usage:
 Commands:
   ts          view timeseries data
   alerts      view alerts
+  dashboard   view and manage dashboards
   event       open and close events
   source      view and manage source tags and descriptions
   write       send data points to a Wavefront proxy
@@ -247,6 +284,9 @@ when :write
     require 'wavefront/cli/write'
     cli = Wavefront::Cli::Write.new(opts, [opts[:'<state>']])
   end
+when :dashboard
+  require 'wavefront/cli/dashboards'
+  cli = Wavefront::Cli::Dashboards.new(opts, [opts[:'<state>']])
 end
 
 begin

data/lib/wavefront/alerting.rb

@@ -29,7 +29,7 @@ module Wavefront
     include Wavefront::Mixins
     DEFAULT_PATH = '/api/alert/'
 
-    attr_reader :token, :noop, :verbose, :endpoint
+    attr_reader :token, :noop, :verbose, :endpoint, :headers, :options
 
     def initialize(token, host = DEFAULT_HOST, debug=false, options = {})
       #
@@ -41,26 +41,108 @@ module Wavefront
       debug(debug)
       @noop = options[:noop]
       @verbose = options[:verbose]
+      @options = options
+    end
+
+    def import_to_create(raw)
+      #
+      # Take a previously exported alert, and construct a hash which
+      # create_alert() can use to re-create it.
+      #
+      ret = {
+        name:          raw['name'],
+        condition:     raw['condition'],
+        minutes:       raw['minutes'],
+        notifications: raw['target'].split(','),
+        severity:      raw['severity'],
+      }
+
+      if raw.key?('displayExpression')
+        ret[:displayExpression] = raw['displayExpression']
+      end
+
+      if raw.key?('resolveAfterMinutes')
+        ret[:resolveMinutes] = raw['resolveAfterMinutes']
+      end
+
+      if raw.key?('customerTagsWithCounts')
+        ret[:sharedTags] = raw['customerTagsWithCounts'].keys
+      end
+
+      if raw.key?('additionalInformation')
+        ret[:additionalInformation] = raw['additionalInformation']
+      end
+
+      ret
+    end
+
+    def create_alert(alert={})
+      #
+      # Create an alert. Expects you to provide it with a hash of
+      # the form:
+      #
+      # {
+      #   name:                 string
+      #   condition:            string
+      #   displayExpression:    string     (optional)
+      #   minutes:              int
+      #   resolveMinutes:       int        (optional)
+      #   notifications:        array
+      #   severity:             INFO | SMOKE | WARN | SEVERE
+      #   privateTags:          array      (optional)
+      #   sharedTags:           array      (optional)
+      #   additionalInformation string     (optional)
+      # }
+      #
+      %w(name condition minutes notifications severity).each do |f|
+        raise "missing field: #{f}" unless alert.key?(f.to_sym)
+      end
+
+      unless %w(INFO SMOKE WARN SEVERE).include?(alert[:severity])
+        raise 'invalid severity'
+      end
+
+      %w(notifications privateTags sharedTags).each do |f|
+        f = f.to_sym
+        alert[f] = alert[f].join(',') if alert[f] && alert[f].is_a?(Array)
+      end
+
+      call_post(create_uri(path: 'create'),
+                hash_to_qs(alert), 'application/x-www-form-urlencoded')
+    end
+
+    def get_alert(id, options = {})
+      #
+      # Alerts are identified by the timestamp at which they were
+      # created. Returns a hash. Exceptions are just passed on
+      # through. You get a 500 if the alert doesn't exist.
+      #
+      resp = call_get(create_uri(path: id)) || '{}'
+      return JSON.parse(resp)
     end
 
     def active(options={})
-      get_alerts('active', options)
+      call_get(create_uri(options.merge(path: 'active',
+                                        qs: mk_qs(options))))
     end
 
     def all(options={})
-      get_alerts('all', options)
+      call_get(create_uri(options.merge(path: 'all', qs: mk_qs(options))))
     end
 
     def invalid(options={})
-      get_alerts('invalid', options)
+      call_get(create_uri(options.merge(path: 'invalid',
+                                        qs: mk_qs(options))))
     end
 
     def snoozed(options={})
-      get_alerts('snoozed', options)
+      call_get(create_uri(options.merge(path: 'snoozed',
+                                        qs: mk_qs(options))))
     end
 
     def affected_by_maintenance(options={})
-      get_alerts('affected_by_maintenance', options)
+      call_get(create_uri(options.merge(path: 'affected_by_maintenance',
+                                        qs: mk_qs(options))))
     end
 
     private
@@ -70,33 +152,38 @@ module Wavefront
     end
 
     def mk_qs(options)
-      query = "t=#{token}"
+      query = []
 
-      query += '&' + list_of_tags(options[:shared_tags]).map do |t|
-        "customerTag=#{t}"
-      end.join('&') if options[:shared_tags]
+      if options[:shared_tags]
+        query.push(list_of_tags(options[:shared_tags]).map do |t|
+          "customerTag=#{t}"
+        end.join('&'))
+      end
 
-      query += '&' + list_of_tags(options[:private_tags]).map do |t|
-        "userTag=#{t}"
-      end.join('&') if options[:private_tags]
+      if options[:private_tags]
+        query.push(list_of_tags(options[:private_tags]).map do |t|
+          "userTag=#{t}"
+        end.join('&'))
+      end
 
-      query
+      query.join('&')
     end
 
-    def get_alerts(path, options={})
+    def create_uri(options = {})
+      #
+      # Build the URI we use to send a 'create' request.
+      #
       options[:host] ||= endpoint
-      options[:path] ||= DEFAULT_PATH
+      options[:path] ||= ''
+      options[:qs]   ||= nil
+
+      options[:qs] = nil if options[:qs] && options[:qs].empty?
 
-      uri = URI::HTTPS.build(
+      URI::HTTPS.build(
         host:  options[:host],
-        path:  uri_concat(options[:path], path),
-	      query: mk_qs(options),
+        path:  uri_concat(DEFAULT_PATH, options[:path]),
+        query: options[:qs],
       )
-
-      puts "GET #{uri.to_s}" if (verbose || noop)
-      return if noop
-
-      RestClient.get(uri.to_s)
     end
 
     def debug(enabled)