wavefront-sdk 0.0.1

data/.travis.yml

@@ -0,0 +1,16 @@
+language: ruby
+cache: bundler
+rvm:
+- 2.2.7
+- 2.3.4
+- 2.4.1
+before_install: gem install bundler --no-rdoc --no-ri
+deploy:
+  provider: rubygems
+  api_key:
+    secure: dfmL5JwBn+u3cUmyAaDsApDa7ljGajGNz3GDcKd2J8FOt7+a758/lmL8EQ34sDT1ZFotrxn/y1RbgXlaDxAE1XDfrZbjckmx7a6wa2sqR3kBraJ2tx7CiXodbw3Z8XZf9WLb0kYGmlLtI73GNcuunMt/9f1cobqWISRLHw6b7amlO7GW2ZBZgzRS+N8TSS2dicIvKMo5HoMYU+uWLM4zDFBPnGNcMiWxh8ysLzJoKqA9kbBUyCVEZ03MlV7G71ObvWCLasKnZ3W5U+K1NbgU7mgMYfl9KIcA4y9hQ9hUCijk40SmT7ffy3P2gq8zblC/4x5Eefpau9X/bdLwXoRCIzqk05t4f45wstj2auHGK0HJwOYRtx8apdaLSgyJ5lQpGcbCRu40WR9mDkaM8m9n3u2o6GJmftCg3AN1QtsourmQB84x67LEbHzValMaokrbCol4XeWqlC+dCNLPixemQRBvcNfI3V9C6RqVGfjpoGlSTI+RkQqwm01PcxpeqIVfdMd1wnfUuAOywUO6UpvtK9TZaxg0NnVElXpPseQbtzulLwZ7R5Y3A4Ss8Z7w43c1KHxTkg54FWUOp065ItjAc4lmyORXq/2+F7sMvRN6dtCLaXTUlkYuU3cjFLIPlLGFYgqq4T4xQa+e5NEK1XW7nghv+IRfKfyVeZsB0WpY+uc=
+  gem: wavefront-sdk
+  on:
+    tags: true
+    repo: snltd/wavefront-sdk
+    ruby: 2.3.4

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'                                                                                                  
+gemspec

data/Gemfile.lock

@@ -0,0 +1,58 @@
+PATH
+  remote: .
+  specs:
+    wavefront-sdk (0.0.1)
+      faraday (>= 0.12.1, < 0.13)
+      inifile (>= 3.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.5.1)
+      public_suffix (~> 2.0, >= 2.0.2)
+    ast (2.3.0)
+    crack (0.4.3)
+      safe_yaml (~> 1.0.0)
+    faraday (0.12.1)
+      multipart-post (>= 1.2, < 3)
+    hashdiff (0.3.2)
+    inifile (3.0.0)
+    minitest (5.8.5)
+    multipart-post (2.0.0)
+    parser (2.4.0.0)
+      ast (~> 2.2)
+    powerpack (0.1.1)
+    public_suffix (2.0.5)
+    rainbow (2.2.1)
+    rake (12.0.0)
+    rubocop (0.47.1)
+      parser (>= 2.3.3.1, < 3.0)
+      powerpack (~> 0.1)
+      rainbow (>= 1.99.1, < 3.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.0, >= 1.0.1)
+    ruby-progressbar (1.8.1)
+    safe_yaml (1.0.4)
+    spy (0.4.5)
+    unicode-display_width (1.1.3)
+    webmock (2.3.2)
+      addressable (>= 2.3.6)
+      crack (>= 0.3.2)
+      hashdiff
+    yard (0.9.5)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.3)
+  minitest (~> 5.8, >= 5.8.0)
+  rake (~> 12.0)
+  rubocop (~> 0.47.0)
+  spy (~> 0.4.0)
+  wavefront-sdk!
+  webmock (~> 2.3, >= 2.3.2)
+  yard (~> 0.9.5)
+
+BUNDLED WITH
+   1.14.6

data/LICENSE.txt

@@ -0,0 +1,27 @@
+Copyright (c) 2017, Sysdef Ltd
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+* Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in
+  the documentation and/or other materials provided with the
+  distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,103 @@
+# wavefront-sdk [![Build Status](https://travis-ci.org/snltd/wavefront-sdk.svg?branch=master)](https://travis-ci.org/snltd/wavefront-sdk) [![Code Climate](https://codeclimate.com/github/snltd/wavefront-sdk/badges/gpa.svg)](https://codeclimate.com/github/snltd/wavefront-sdk) [![Issue Count](https://codeclimate.com/github/snltd/wavefront-sdk/badges/issue_count.svg)](https://codeclimate.com/github/snltd/wavefront-sdk) [![Known Vulnerabilities](https://snyk.io/test/github/snltd/wavefront-sdk/badge.svg)](https://snyk.io/test/github/snltd/wavefront-sdk)
+
+This is a Ruby SDK for v2 of
+[Wavefront](https://www.wavefront.com/)'s public API. It supports Ruby >= 2.2.
+
+Note that it currently has major version number `0`. This means *it
+is not finished*. Until version `1` comes out, I reserve the right
+to change, break, and befoul the code and the gem.
+
+## Installation
+
+```
+$ gem install wavefront-sdk
+```
+
+or to build locally,
+
+```
+$ gem build wavefront-sdk.gemspec
+```
+
+## Examples
+
+First, let's list the IDs of the users in our account. The `list()` method
+will return a `Wavefront::Response::User` object with a list of items. Most
+response classes behave this way.
+
+```ruby
+# Define our API endpoint. (This is not a valid token!)
+
+CREDS = { endpoint: 'metrics.wavefront.com',
+          token: 'c7a1ff30-0dd8-fa60-e14d-f58f91bafc0e' }
+
+require 'wavefront-sdk/user'
+
+# You can pass in a Ruby logger object, and tell the SDK to be
+# verbose.
+
+require 'logger'
+log = Logger.new(STDOUT)
+
+wf = Wavefront::User.new(CREDS, verbose: true, logger: log)
+
+wf.list.response.items.each { |user| puts user[:identifier] }
+
+# And delete the user 'lolex@oldplace.com'
+
+wf.delete('lolex@oldplace.com')
+```
+
+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.
+
+
+```ruby
+require 'wavefront-sdk/query'
+
+Wavefront::Query.new(CREDS).query(
+  'ts("prod.www.host.tenant.physicalmem.usage")',
+  :m,
+  (Time.now - 600)
+)
+```
+
+We can write points too, assuming we have a proxy. You can't write points
+directly via the API. Unlike all other classes, this one requires the proxy
+address and port as its credential hash.
+
+```ruby
+require 'wavefront-sdk/write'
+
+W_CREDS = { proxy: 'wavefront.localnet', port: 2878 }
+
+wf = Wavefront::Write.new(W_CREDS, debug: true)
+
+task = wf.write( [{ path: 'dev.test.sdk', value: 10 }])
+
+p task.response
+#<struct sent=1, rejected=0, unsent=0>
+puts task.status.result
+#OK
+```
+
+The SDK also provides a helper class for extracting credentials from a
+configuration file. If you don't supply a file, defaults will be
+used.
+
+```ruby
+require 'wavefront-sdk/credentials'
+
+c = Wavefront::Credentials.new
+
+# Now use that to list the proxies in our account
+
+require 'wavefront-sdk/proxy'
+
+p Wavefront::Proxy.new(c.creds).list
+
+# It works for proxies too:
+
+wf = Wavefront::Write.new(c.proxy)
+```

data/Rakefile

@@ -0,0 +1,18 @@
+require 'yard'
+require 'rake/testtask'
+require 'rubocop/rake_task'
+
+task default: :test
+
+Rake::TestTask.new do |t|
+  t.pattern = 'spec/wavefront-sdk/*_spec.rb'
+  t.warning = false
+end
+
+RuboCop::RakeTask.new(:rubocop) do |t|
+  t.options = ['--display-cop-names']
+end
+
+YARD::Rake::YardocTask.new do |t|
+  t.files = ['lib/wavefront-sdk/*rb']
+end

data/lib/wavefront-sdk/alert.rb

@@ -0,0 +1,195 @@
+require_relative './base'
+
+module Wavefront
+  #
+  # View and manage alerts. Alerts are identified by their millisecond
+  # epoch timestamp. Returns a Wavefront::Response::Alert object.
+  #
+  class Alert < Wavefront::Base
+
+    # GET /api/v2/alert
+    # Get all alerts for a customer
+    #
+    # @param offset [Int] alert at which the list begins
+    # @param limit [Int] the number of alerts to return
+    # @return [Hash]
+    #
+    def list(offset = 0, limit = 100)
+      api_get('', { offset: offset, limit: limit })
+    end
+
+    # POST /api/v2/alert
+    # Create a specific alert. We used to validate input here, but
+    # this couples the SDK too tightly to the API. Now it's just a
+    # generic POST of a hash.
+    #
+    # @param body [Hash] description of alert
+    # @return [Hash]
+    #
+    def create(body)
+      raise ArgumentError unless body.is_a?(Hash)
+      api_post('', body, 'application/json')
+    end
+
+    # DELETE /api/v2/alert/{id}
+    # Delete a specific alert.
+    #
+    # Deleting an active alert moves it to 'trash', from where it can
+    # be restored with an #undelete operation. Deleting an alert in
+    # 'trash' removes it for ever.
+    #
+    # @param id [String] ID of the alert
+    # @return [Hash]
+    #
+    def delete(id)
+      wf_alert_id?(id)
+      api_delete(id)
+    end
+
+    # GET /api/v2/alert/{id}
+    # GET /api/v2/alert/{id}/history/{version}
+    # Get a specific alert / Get a specific historical version of a
+    # specific alert.
+    #
+    # @param id [String] ID of the alert
+    # @param version [Integer] version of alert
+    # @return [Hash]
+    #
+    def describe(id, version = nil)
+      wf_alert_id?(id)
+      wf_version?(version) if version
+      fragments = [id]
+      fragments += ['history', version] if version
+      api_get(fragments.uri_concat)
+    end
+
+    # PUT /api/v2/alert/{id}
+    # Update a specific alert.
+    #
+    # @param id [String] a Wavefront alert ID
+    # @param body [Hash] description of event. See body_desc()
+    # @return [Hash]
+    #
+    def update(id, body)
+      wf_alert_id?(id)
+      raise ArgumentError unless body.is_a?(Hash)
+      api_put(id, body, 'application/json')
+    end
+
+    # GET /api/v2/alert/{id}/history
+    # Get the version history of a specific alert.
+    #
+    # @param id [String] ID of the alert
+    # @return [Hash]
+    #
+    def history(id)
+      wf_alert_id?(id)
+      api_get([id, 'history'].uri_concat)
+    end
+
+    # POST /api/v2/alert/{id}/snooze
+    # Snooze a specific alert for some number of seconds.
+    #
+    # @param id [String] ID of the alert
+    # @param time [Integer] how many seconds to snooze for. Nil is indefinite
+    # @returns [Hash] object describing the alert with status and
+    #   response keys
+    #
+    def snooze(id, seconds = nil)
+      wf_alert_id?(id)
+      qs = seconds ? "?seconds=#{seconds}" : ''
+      api_post([id, "snooze#{qs}"].uri_concat, nil)
+    end
+
+    # GET /api/v2/alert/{id}/tag
+    # Get all tags associated with a specific alert.
+    #
+    # @param id [String] ID of the alert
+    # @returns [Hash] object describing the alert with status and
+    #   response keys
+    #
+    def tags(id)
+      wf_alert_id?(id)
+      api_get([id, 'tag'].uri_concat)
+    end
+
+    # POST /api/v2/alert/{id}/tag
+    # Set all tags associated with a specific alert.
+    #
+    # @param id [String] ID of the alert
+    # @param tags [Array] list of tags to set.
+    # @returns [Hash] object describing the alert with status and
+    #   response keys
+    #
+    def tag_set(id, tags)
+      wf_alert_id?(id)
+      tags = Array(tags)
+      tags.each { |t| wf_string?(t) }
+      api_post([id, 'tag'].uri_concat, tags.to_json, 'application/json')
+    end
+
+    # DELETE /api/v2/alert/{id}/tag/{tagValue}
+    # Remove a tag from a specific alert.
+    #
+    # @param id [String] ID of the alert
+    # @param tag [String] tag to delete
+    # @returns [Hash] object with 'status' key and empty 'repsonse'
+    #
+    def tag_delete(id, tag)
+      wf_alert_id?(id)
+      wf_string?(tag)
+      api_delete([id, 'tag', tag].uri_concat)
+    end
+
+    # PUT /api/v2/alert/{id}/tag/{tagValue}
+    # Add a tag to a specific alert.
+    #
+    # @param id [String] ID of the alert
+    # @param tag [String] tag to set.
+    # @returns [Hash] object with 'status' key and empty 'repsonse'
+    #
+    def tag_add(id, tag)
+      wf_alert_id?(id)
+      wf_string?(tag)
+      api_put([id, 'tag', tag].uri_concat)
+    end
+
+    # POST /api/v2/alert/{id}/undelete
+    # Undelete a specific alert.
+    #
+    # @param id [String] ID of the alert
+    # @return [Hash]
+    #
+    def undelete(id)
+      wf_alert_id?(id)
+      api_post([id, 'undelete'].uri_concat)
+    end
+
+    # POST /api/v2/alert/{id}/unsnooze
+    # Unsnooze a specific alert.
+    #
+    # @param id [String] ID of the alert
+    # @returns [Hash] object describing the alert with status and
+    #   response keys
+    #
+    def unsnooze(id)
+      wf_alert_id?(id)
+      api_post([id, 'unsnooze'].uri_concat)
+    end
+
+    # GET /api/v2/alert/summary
+    # Count alerts of various statuses for a customer
+    #
+    # @return [Hash]
+    #
+    def summary
+      api_get('summary')
+    end
+  end
+
+  # A standard response
+  #
+  class Response
+    class Alert < Base; end
+  end
+end

data/lib/wavefront-sdk/base.rb

@@ -0,0 +1,251 @@
+require 'json'
+require 'time'
+require 'faraday'
+require 'pp'
+require 'ostruct'
+require_relative './exception'
+require_relative './mixins'
+require_relative './response'
+require_relative './validators'
+require_relative './version'
+
+module Wavefront
+  #
+  # Abstract class from which all API classes inherit. When you make
+  # any call to the Wavefront API from this SDK, you are returned an
+  # OpenStruct object.
+  #
+  # @returns a Wavefront::Class::Response object where Class matches
+  # the inheriting class name.
+  #
+  class Base
+    include Wavefront::Validators
+    include Wavefront::Mixins
+    attr_reader :opts, :debug, :noop, :verbose, :net, :api_base, :conn,
+                :update_keys, :logger
+
+    # Create a new API object. This will always be called from a
+    # class which inherits this one. If the inheriting class defines
+    # #post_initialize, that method will be called afterwards, with
+    # the same arguments.
+    #
+    # @param creds [Hash] must contain the keys `endpoint` (the
+    #   Wavefront API server) and `token`, the user token with which
+    #   you wish to access the endpoint. Can optionally contain
+    #   `agent`, which will become the `user-agent` string sent with
+    #   all requests.
+    # @param opts [Hash] options governing class behaviour. Expected
+    #   keys are `debug`, `noop` and `verbose`, all boolean; and
+    #   `logger`, which must be a standard Ruby logger object. You
+    #   can also pass :response_only. If this is true, you will only
+    #   be returned a hash of the 'response' object returned by
+    #   Wavefront.
+    # @return [Nil]
+    #
+    def initialize(creds = {}, opts = {})
+      @opts  = opts
+      @debug = opts[:debug] || false
+      @noop = opts[:noop] || false
+      @verbose = opts[:verbose] || false
+      @logger = opts[:logger] || nil
+      setup_endpoint(creds)
+
+      post_initialize(creds, opts) if respond_to?(:post_initialize)
+    end
+
+    # Convert an epoch timestamp into epoch milliseconds. If the
+    # timestamp looks like it's already epoch milliseconds, return
+    # it as-is.
+    #
+    # @param t [Integer] epoch timestamp
+    # @return [Ingeter] epoch millisecond timestamp
+    #
+    def time_to_ms(t)
+      return false unless t.is_a?(Integer)
+      return t if t.to_s.size == 13
+      (t.to_f * 1000).round
+    end
+
+    # Derive the first part of the API path from the class name. You
+    # can override this in your class if you wish
+    #
+    # @return [String] portion of API URI
+    #
+    def api_base
+      self.class.name.split('::').last.downcase
+    end
+
+    # Create a Faraday connection object. The server comes from the
+    # endpoint passed to the initializer in the 'creds' hash; the
+    # root of the URI is dynamically derived by the #setup_endpoint
+    # method.
+    #
+    # @param headers [Hash] additional headers
+    # @return [URI::HTTPS]
+    #
+    def mk_conn(path, headers = {})
+      Faraday.new(
+        url:     "https://#{net[:endpoint]}" +
+                 [net[:api_base], path].uri_concat,
+        headers: net[:headers].merge(headers)
+      )
+    end
+
+    # Make a GET call to the Wavefront API and return the result as
+    # a Ruby hash. Can optionally perform a verbose noop, if the
+    # #noop class variable is set. If #verbose is set, then prints
+    # the information used to build the URI.
+    #
+    # @param path [String] path to be appended to the
+    #   #net[:api_base] path.
+    # @param qs [String] optional query string
+    # @return [Hash] API response
+    #
+    def api_get(path, query = {})
+      make_call(mk_conn(path), :get, nil, query)
+    end
+
+    # Make a POST call to the Wavefront API and return the result as
+    # a Ruby hash. Can optionally perform a verbose noop, if the
+    # #noop class variable is set. If #verbose is set, then prints
+    # the information used to build the URI.
+    #
+    # @param path [String] path to be appended to the
+    #   #net[:api_base] path.
+    # @param body [String] optional body text to post
+    # @param ctype [String] the content type to use when posting
+    # @return [Hash] API response
+    #
+    def api_post(path, body = nil, ctype = 'text/plain')
+      body = body.to_json unless body.is_a?(String)
+      make_call(mk_conn(path, { 'Content-Type': ctype,
+                                       'Accept': 'application/json'}),
+                :post, nil, body)
+    end
+
+    # Make a PUT call to the Wavefront API and return the result as
+    # a Ruby hash. Can optionally perform a verbose noop, if the
+    # #noop class variable is set. If #verbose is set, then prints
+    # the information used to build the URI.
+    #
+    # @param path [String] path to be appended to the
+    #   #net[:api_base] path.
+    # @param body [String] optional body text to post
+    # @param ctype [String] the content type to use when putting
+    # @return [Hash] API response
+    #
+    def api_put(path, body = nil, ctype = 'application/json')
+      make_call(mk_conn(path, { 'Content-Type': ctype,
+                                      'Accept': 'application/json' }),
+                :put, nil, body.to_json)
+    end
+
+    # Make a DELETE call to the Wavefront API and return the result
+    # as a Ruby hash. Can optionally perform a verbose noop, if the
+    # #noop class variable is set. If #verbose is set, then prints
+    # the information used to build the URI.
+    #
+    # @param path [String] path to be appended to the
+    #   #net[:api_base] path.
+    # @return [Hash] API response
+    #
+    def api_delete(path)
+      make_call(mk_conn(path), :delete)
+    end
+
+    # doing a PUT to update an object requires only a certain subset of
+    # the keys returned by #describe().
+    #
+    # @param body [Hash] a hash of the existing object merged with the
+    #   hash describing the user's change(s).
+    # @param keys [Array, String] the keys(s) the user wishes to update
+    # @return [Hash] a hash containing only the keys which need to be
+    #   sent to the API. Keys will be symbolized.
+    #
+    def hash_for_update(old, new)
+      raise ArgumentError unless old.is_a?(Hash) && new.is_a?(Hash)
+
+      Hash[old.merge(new).map { |k, v| [k.to_sym, v] }].select do |k, _v|
+        update_keys.include?(k)
+      end
+    end
+
+    # Send a message to a Ruby logger object if the user supplied
+    # one, or print to standard out if not.
+    #
+    # @param msg [String] the string to print
+    # @param level [Symbol] the level of the message.
+    #   :verbose messages equate to a standard INFO log level and
+    #   :debug to DEBUG.
+    #
+    def log(msg, level = nil)
+
+      if logger
+        logger.send(level || :info, msg)
+      else
+        # print it unless it's a debug and we're not in debug
+        #
+        return if level == :debug && ! opts[:debug]
+        return if level == :info && ! opts[:verbose]
+
+        puts msg
+      end
+    end
+
+    def respond(resp)
+      response_class.send(:new, resp.body, resp.status || {})
+    end
+
+    private
+
+    # Try to describe the actual HTTP calls we make. There's a bit
+    # of clumsy guesswork here
+    #
+    def verbosity(conn, method, *args)
+      log "uri: #{method.upcase} #{conn.url_prefix}"
+
+      if args.last && ! args.last.empty?
+        puts log method == :get ? "params: #{args.last}" :
+                                  "body: #{args.last}"
+      end
+    end
+
+    # Make the API call, or not, if noop is set.
+    #
+    def make_call(conn, method, *args)
+      verbosity(conn, method, *args) if noop || verbose
+      return if noop
+
+      resp = conn.public_send(method, *args)
+
+      if debug
+        require 'pp'
+        pp resp
+      end
+
+      respond(resp)
+    end
+
+    def response_class
+       Object.const_get(
+        "Wavefront::Response::#{self.class.name.split('::').last}")
+    end
+
+    def setup_endpoint(creds)
+      %w(endpoint token).each do |k|
+        raise "creds must contain #{k}" unless creds.key?(k.to_sym)
+      end
+
+      unless creds.key?(:agent) && creds[:agent]
+        creds[:agent] = "wavefront-sdk #{WF_SDK_VERSION}"
+      end
+
+      @net = {
+        headers:  { 'Authorization': "Bearer #{creds[:token]}",
+                    'user-agent':    creds[:agent] },
+        endpoint: creds[:endpoint],
+        api_base: ['', 'api', 'v2', api_base].uri_concat
+      }
+    end
+  end
+end