wavefront-sdk 1.6.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a51f123acf9e28be6fde5916a80976858fe958f13cb7bfd2d1be6b97b201dde
-  data.tar.gz: 2aa03e1e185c801dda9d56f9643578ba2f9692973f0bbab4dd728b93cdb44fee
+  metadata.gz: 78759a49a05aded24a69a8759c648c10c7e8f52857597a51ce73c3703d24b42a
+  data.tar.gz: cb66061865a11ecef526e726cb804ca2ab1f2a75ba72224be1c6c20ca2dabfc9
 SHA512:
-  metadata.gz: 6b8921cec2fdf37e6451605d76895d2f538a04128c6e6217e28be58e7e0387cc95c74a37abc21f71f07bf87051ed587b0e2f10e33b703bc7c028085c383e8383
-  data.tar.gz: 6a83ce8d88d17b4a494579bbf8a9602581a4684eeb8c29458710cba2a9d5797c693e36738c79cb852098494b7c4e9c6360158147aac6664460e826b27603e758
+  metadata.gz: 6be149c21dd32ce4a6f8dd56843331fe08f8b508fd0894139bf6d09279a0061fbb280553cdb35f33e546c3124f4d4ebfa4eca7bedfa26ef1489a4d5f178ca238
+  data.tar.gz: 41c617f4c39afd7e21965afe89521f17c2e8713c402c18259ca907b7dab09c29ba053f4497c14cbba5ec0601874a6aa37e18a81c5f26178dd85d737ef4d5df08

data/.rubocop.yml

@@ -13,3 +13,9 @@ Metrics/ClassLength:
 
 Metrics/MethodLength:
   Max: 13
+
+Style/DoubleNegation:
+  Enabled: false
+
+Style/NumericLiterals:
+  Enabled: false

data/HISTORY.md

@@ -1,10 +1,48 @@
 # Changelog
 
+## 2.0.0
+* Remove `#everything` method from all classes. (Breaking change.)
+* Calling any method which takes the `limit` argument with  `limit`
+  set to `:all` will automatically handle pagination, fetching all
+  matching objects.
+* Calling with `limit` set to `:lazy` returns a lazy `Enumerable`
+  over which you can iterate. Every element is an object,
+* Added one-word methods like `#snoozed`, `#active` and so-on to the
+  `Wavefront::Alert` class. These replicate the behaviour of similarly
+  named methods in the v1 SDK. (Though they use different underlying
+  API calls, as the alerts API has changed significantly.)
+* Added `#pending` and `#ongoing` methods to
+  `Wavefront::MaintenanceWindow`.
+* Added `MaintenanceWindow#summary` method, replicating the behaviour
+  of the `summary` v1 API call.
+* Added `#ids`, `#names` and `#empty?` helper methods to
+  `Wavefront::Response`.
+* Add `Distribution` class to help you write [Histogram
+  distributions](https://docs.wavefront.com/proxies_histograms.html).
+* Writing points or distributions (or reporting points) shows the
+  wire-format point being sent if in `debug` or `verbose` mode.
+* Broke up old write classes, moving the transport mechanism
+  into a separate class. The interface is backward-compatible,
+  though a new `:writer` constructor option  lets you select the
+  transport mechanism.
+* New transport mechanism class allows points to be HTTP POSTed to a
+  proxy rather than being written to a socket.
+* The summary object returned when writing points is now a
+  standalone class.
+* Use `wavefront` rather than `graphite_v2` as the `report` data
+  type.
+* `Wavefront::Report` is now a shim around `Wavefront::Write`, left
+  in for backward-compatability. The "correct" way to send data via
+  the API is using `Wavefront::Write`, specifying the `:api` writer.
+* `Wavefront::Credentials` object has new `all` method, which gives
+  a hash of proxy *and* API credentials. This is useful for passing
+  to `Wavefront::Write` as it means all writers will work without
+  modifying your code.
+
 ## 1.6.2 (22/08/2018)
 * Drop log priority of write class messages.
 
 ## 1.6.1 (22/08/2018)
-
 * Fix Ruby 2.2 bugs
 * Improve unit test separation
 * Allow updating of all external link parameters
@@ -15,27 +53,22 @@
 * Improve README.
 
 ## 1.5.0 (25/06/2018)
-
 * Add [derived
   metric](https://docs.wavefront.com/derived_metrics.html) support.
 * Add this changelog.
 
 ## 1.4.0 (10/04/2018)
-
 * Add support for [direct
   ingestion](https://docs.wavefront.com/direct_ingestion.html).
 
 ## 1.3.2 (03/04/2018)
-
 * Fix regression in write class.
 
 ## 1.3.1 (03/04/2018)
-
 * Fix Ruby 2.2 support.
 * Code tidy and linting improvements.
 
 ## 1.3.0 (29/03/2018)
-
 * Add support for delta metrics.
 * Add automatic pagination support for long lists of objects.
   Such lists can be treated as Ruby enumerables.
@@ -46,33 +79,26 @@
 * Support Ruby 2.5.
 
 ## 1.2.1 (12/10/2017)
-
 * Fix bug in relative time support.
 * Fix Ruby 2.4 support.
 
 ## 1.2.0 (12/10/2017)
-
 * Support relative times through mixin methods.
 
 ## 1.1.0 (09/10/2017)
-
 * Add support for notificant (alert target) API path.
 * Add support for integration API path.
 * Support new source description set/delete API endpoint.
 
 ## 1.0.3 (20/09/2017)
-
 * Gracefully handle tags with `nil` values.
 * Bump dependencies.
 
 ## 1.0.2 (04/08/2017)
-
 * Maintenance window bugfixes.
 
 ## 1.0.1 (31/07/2017)
-
 * Fix message ID validator.
 
 ## 1.0.0 (11/06/2017)
-
 First official release.

data/README.md

@@ -9,7 +9,8 @@ auto-generated SDK.
 As well as complete API coverage, `wavefront-sdk` includes methods
 which facilitate various common tasks, and provides non-API
 features such as credential management, and writing points through a
-proxy.
+proxy. It also has methods mimicking the behaviour of useful v1 API
+calls which did not make it into v2.
 
 ## Installation
 
@@ -35,7 +36,7 @@ rubydoc.info](http://www.rubydoc.info/gems/wavefront-sdk/).
 
 ## Examples
 
-First, let's list the IDs of the users in our account. The `list()`
+First, let's list the Wavefront proxies in our account. The `list()`
 method will return a `Wavefront::Response` object. This object has
 `status` and `response` methods. `status` always yields a structure
 containing `result`, `message` and `code` fields which can be
@@ -53,7 +54,7 @@ you to the same place.
 CREDS = { endpoint: 'metrics.wavefront.com',
           token: 'c7a1ff30-0dd8-fa60-e14d-f58f91bafc0e' }
 
-require 'wavefront-sdk/user'
+require 'wavefront-sdk/proxy'
 
 # You can pass in a Ruby logger object, and tell the SDK to be
 # verbose.
@@ -62,35 +63,62 @@ require 'logger'
 log = Logger.new(STDOUT)
 
 wf = Wavefront::User.new(CREDS, verbose: true, logger: log)
+proxies = wf.list
+
+puts proxies.class
+# Wavefront::Response
 
-# See how things went:
+# See how things went. How specific do you want to be?
 
-p wf.status
-#<Wavefront::Type::Status:0x007feb99185538 @result="OK", @message="", @code=200>
+puts proxies.ok?
+# true
+puts proxies.empty?
+# false
+puts proxies.status
+# {:result=>"OK", :message=>"", :code=>200}
+puts proxies.status.code
+# 200
 
-# And print each user's ID
+# Now print the proxy IDs
 
-wf.list.response.items.each { |user| puts user[:identifier] }
+puts proxies.ids
+# 1439acb2-ab07-4cf9-8397-2f2d758e52a0
+# 87eca9df-fc47-4a24-88cf-6dd0bae245a9
+# df77bd37-8f32-4e0c-b578-51eb42f22b6f
 
-# Now delete the user 'lolex@oldplace.com', disregarding the
-# response.
+# Delete the first one.
 
-wf.delete('lolex@oldplace.com')
+result = wf.delete('1439acb2-ab07-4cf9-8397-2f2d758e52a0')
+puts result.ok?
+# true
 ```
 
-All API classes expect `user` support pagination and will only
-return blocks of results. The `everything()` method returns a lazy
-enumerator to make dealing with pagination simpler.
+By default (because it's the default behaviour of the API),
+all API classes (except `user`) will only return blocks of results
+when you ask for a list of objects.
+
+You can set an offset and a limit when you list, but setting the
+limit to the magic value `:all` will return all items, without you
+having to deal with pagination.
+
+Calling a method with the limit set to `:lazy` returns a lazy
+enumerable.
 
 ```ruby
-Wavefront::Alert.new(c.creds).everything.each_with_index do |m, i|
-  puts "#{i} #{m.id}"
-end
+wf = Wavefront::Alert.new(creds.all)
+
+# The first argument is how many object to get with each API call,
+# the second gets us a lazy #Enumerable
+wf.list(99, :lazy).each { |alert| puts alert.name }
+# Point Rate
+# Disk Error
+# ...
 ```
 
-Retrieve a timeseries over the last 10 minutes, with one minute bucket
-granularity. We will describe the time as a Ruby object, but could also use
-an epoch timestamp. The SDK happily converts between the two.
+We can easily write queries. Let's retrieve a timeseries over the
+last 10 minutes, with one minute bucket granularity. We will
+describe the time as a Ruby object, but could also use an epoch
+timestamp. The SDK happily converts between the two.
 
 
 ```ruby
@@ -115,20 +143,39 @@ require 'wavefront-sdk/write'
 
 W_CREDS = { proxy: 'wavefront.localnet', port: 2878 }
 
-wf = Wavefront::Write.new(W_CREDS, debug: true)
+wf = Wavefront::Write.new(W_CREDS, verbose:true)
 
 task = wf.write( [{ path: 'dev.test.sdk', value: 10 }])
-
-p task.response
-#{"sent"=>1, "rejected"=>0, "unsent"=>0}
-puts task.status.result
-#OK
+# SDK DEBUG: Connecting to wavefront.localnet:2878.
+# SDK INFO: dev.test.sdk 10 source=box
+# SDK DEBUG: Closing connection to proxy.
+puts task.response
+# {"sent"=>1, "rejected"=>0, "unsent"=>0}
+puts task.ok?
+# true
 ```
 
 You can send delta metrics either by manually prefixing your metric
-path with a delta symbol, or by using the `write_delta()` method
+path with a delta symbol, or by using the `write_delta()` method.
+There is even a class to help you write Wavefront distributions.
+
+You can also send points to a local proxy over HTTP. Just specify
+`:http` as the `writer` option when you create your write object.
+
+```ruby
+wf = Wavefront::Write.new(W_CREDS, writer: :http, verbose: true)
+
+task = wf.write( [{ path: 'dev.test.sdk', value: 10 }])
+# SDK INFO: dev.test.sdk 10 source=box
+# SDK INFO: uri: POST http://wavefront.localnet:2878/
+# SDK INFO: body: dev.test.sdk 10 source=box
+p task.response
+# {"sent"=>1, "rejected"=>0, "unsent"=>0}
+puts task.ok?
+# true
+```
 
-The SDK also provides a helper class for extracting credentials from a
+The SDK provides a helper class for extracting credentials from a
 configuration file. If you don't supply a file, defaults will be
 used. You can even override things with environment variables.
 

data/Rakefile

@@ -5,7 +5,7 @@ require 'rubocop/rake_task'
 task default: %i[rubocop test]
 
 Rake::TestTask.new do |t|
-  t.pattern = 'spec/wavefront-sdk/*_spec.rb'
+  t.pattern = 'spec/**/*_spec.rb'
   t.warning = false
 end
 

data/lib/wavefront-sdk/alert.rb

@@ -1,11 +1,12 @@
-require_relative 'base'
+require_relative 'defs/constants'
+require_relative 'core/api'
 
 module Wavefront
   #
   # View and manage alerts. Alerts are identified by their millisecond
   # epoch timestamp. Returns a Wavefront::Response::Alert object.
   #
-  class Alert < Base
+  class Alert < CoreApi
     def update_keys
       %i[id name target condition displayExpression minutes
          resolveAfterMinutes severity additionalInformation]
@@ -19,7 +20,7 @@ module Wavefront
     # @return [Hash]
     #
     def list(offset = 0, limit = 100)
-      api_get('', offset: offset, limit: limit)
+      api.get('', offset: offset, limit: limit)
     end
 
     # POST /api/v2/alert
@@ -32,7 +33,7 @@ module Wavefront
     #
     def create(body)
       raise ArgumentError unless body.is_a?(Hash)
-      api_post('', body, 'application/json')
+      api.post('', body, 'application/json')
     end
 
     # DELETE /api/v2/alert/id
@@ -47,7 +48,7 @@ module Wavefront
     #
     def delete(id)
       wf_alert_id?(id)
-      api_delete(id)
+      api.delete(id)
     end
 
     # GET /api/v2/alert/id
@@ -64,7 +65,7 @@ module Wavefront
       wf_version?(version) if version
       fragments = [id]
       fragments += ['history', version] if version
-      api_get(fragments.uri_concat)
+      api.get(fragments.uri_concat)
     end
 
     # PUT /api/v2/alert/id
@@ -82,9 +83,9 @@ module Wavefront
       wf_alert_id?(id)
       raise ArgumentError unless body.is_a?(Hash)
 
-      return api_put(id, body, 'application/json') unless modify
+      return api.put(id, body, 'application/json') unless modify
 
-      api_put(id, hash_for_update(describe(id).response, body),
+      api.put(id, hash_for_update(describe(id).response, body),
               'application/json')
     end
 
@@ -100,7 +101,7 @@ module Wavefront
       qs[:offset] = offset if offset
       qs[:limit] = limit if limit
 
-      api_get([id, 'history'].uri_concat, qs)
+      api.get([id, 'history'].uri_concat, qs)
     end
 
     # POST /api/v2/alert/id/snooze
@@ -114,7 +115,7 @@ module Wavefront
     def snooze(id, seconds = nil)
       wf_alert_id?(id)
       qs = seconds ? "?seconds=#{seconds}" : ''
-      api_post([id, "snooze#{qs}"].uri_concat, nil)
+      api.post([id, "snooze#{qs}"].uri_concat, nil)
     end
 
     # GET /api/v2/alert/id/tag
@@ -125,7 +126,7 @@ module Wavefront
     #
     def tags(id)
       wf_alert_id?(id)
-      api_get([id, 'tag'].uri_concat)
+      api.get([id, 'tag'].uri_concat)
     end
 
     # POST /api/v2/alert/id/tag
@@ -139,7 +140,7 @@ module Wavefront
       wf_alert_id?(id)
       tags = Array(tags)
       tags.each { |t| wf_string?(t) }
-      api_post([id, 'tag'].uri_concat, tags.to_json, 'application/json')
+      api.post([id, 'tag'].uri_concat, tags.to_json, 'application/json')
     end
 
     # DELETE /api/v2/alert/id/tag/tagValue
@@ -152,7 +153,7 @@ module Wavefront
     def tag_delete(id, tag)
       wf_alert_id?(id)
       wf_string?(tag)
-      api_delete([id, 'tag', tag].uri_concat)
+      api.delete([id, 'tag', tag].uri_concat)
     end
 
     # PUT /api/v2/alert/id/tag/tagValue
@@ -165,7 +166,7 @@ module Wavefront
     def tag_add(id, tag)
       wf_alert_id?(id)
       wf_string?(tag)
-      api_put([id, 'tag', tag].uri_concat)
+      api.put([id, 'tag', tag].uri_concat)
     end
 
     # POST /api/v2/alert/id/undelete
@@ -176,7 +177,7 @@ module Wavefront
     #
     def undelete(id)
       wf_alert_id?(id)
-      api_post([id, 'undelete'].uri_concat)
+      api.post([id, 'undelete'].uri_concat)
     end
 
     # POST /api/v2/alert/id/unsnooze
@@ -187,7 +188,7 @@ module Wavefront
     #
     def unsnooze(id)
       wf_alert_id?(id)
-      api_post([id, 'unsnooze'].uri_concat)
+      api.post([id, 'unsnooze'].uri_concat)
     end
 
     # GET /api/v2/alert/summary
@@ -196,7 +197,102 @@ module Wavefront
     # @return [Wavefront::Response]
     #
     def summary
-      api_get('summary')
+      api.get('summary')
+    end
+
+    # The following methods replicate similarly named ones in the v1
+    # SDK. The v2 API does not provide the level of alert-querying
+    # convenience v1 did, but we can still give our users those
+    # lovely simple methods. Note that these are constructions of
+    # the SDK and do not actually correspond to the underlying API.
+
+    # @return [Wavefront::Response] all currently firing alerts
+    #
+    def active
+      firing
+    end
+
+    # @return [Wavefront::Response] all alerts currently in a
+    #   maintenance window.
+    #
+    def affected_by__maintenance
+      in_maintenance
+    end
+
+    # @return [Wavefront::Response] all alerts which have an invalid
+    #   query.
+    #
+    def invalid
+      alerts_in_state(:invalid)
+    end
+
+    # For completeness, one-word methods like those above for all
+    # possible alert states.
+
+    # @return [Wavefront::Response] all alerts currently snoozed
+    #
+    def snoozed
+      alerts_in_state(:snoozed)
+    end
+
+    # @return [Wavefront::Response] all currently firing alerts.
+    #
+    def firing
+      alerts_in_state(:firing)
+    end
+
+    # @return [Wavefront::Response] all alerts currently in a
+    #   maintenance window.
+    #
+    def in_maintenance
+      alerts_in_state(:in_maintenance)
+    end
+
+    # @return [Wavefront::Response] I honestly don't know what the
+    #   NONE state denotes, but this will fetch alerts which have
+    #   it.
+    #
+    def none
+      alerts_in_state(:none)
+    end
+
+    # @return [Wavefront::Response] all alerts being checked.
+    #
+    def checking
+      alerts_in_state(:checking)
+    end
+
+    # @return [Wavefront::Response] all alerts in the trash.
+    #
+    def trash
+      alerts_in_state(:trash)
+    end
+
+    # @return [Wavefront::Response] all alerts reporting NO_DATA.
+    #
+    def no_data
+      alerts_in_state(:no_data)
+    end
+
+    # @return [Wavefront::Response] all your alerts
+    #
+    def all
+      list(PAGE_SIZE, :all)
+    end
+
+    # Use a search to get all alerts in the given state. You would
+    # be better to use one of the wrapper methods like #firing,
+    # #snoozed etc, but I've left this method public in case new
+    # states are added before the SDK supports them.
+    # @param state [Symbol] state such as :firing, :snoozed etc. See
+    #   the Alert Swagger documentation for a full list
+    # @return [Wavfront::Response]
+    #
+    def alerts_in_state(state)
+      require_relative 'search'
+      wfs = Wavefront::Search.new(creds, opts)
+      query = { key: 'status', value: state, matchingMethod: 'EXACT' }
+      wfs.search(:alert, query, limit: :all, offset: PAGE_SIZE)
     end
   end
 end