wavefront-sdk 1.6.2 → 2.0.0

data/lib/wavefront-sdk/{mixins.rb → support/mixins.rb}

@@ -1,7 +1,9 @@
 require 'date'
-require_relative 'exception'
 require_relative 'parse_time'
-require_relative 'stdlib'
+require_relative '../core/exception'
+require_relative '../stdlib/string'
+require_relative '../stdlib/array'
+require_relative '../stdlib/hash'
 
 module Wavefront
   #
@@ -85,5 +87,9 @@ module Wavefront
       return u[suffix.to_sym] if u.key?(suffix.to_sym)
       raise Wavefront::Exception::InvalidTimeUnit
     end
+
+    def log(message, severity = :info)
+      logger.log(message, severity)
+    end
   end
 end

data/lib/wavefront-sdk/{parse_time.rb → support/parse_time.rb}

@@ -1,3 +1,5 @@
+require 'time'
+
 module Wavefront
   #
   # Parse various times into integers. This class is not for direct

data/lib/wavefront-sdk/types/status.rb

@@ -0,0 +1,52 @@
+module Wavefront
+  #
+  # Status types are used by the Wavefront::Response class. They
+  # represent the success or failure of an API call.
+  #
+  #
+  module Type
+    #
+    # An object which provides information about whether the request
+    # was successful or not. Ordinarily this is easy to construct
+    # from the API's JSON response, but some classes, for instance
+    # Wavefront::Write fake it by constructing their own.
+    #
+    # @!attribute [r] result
+    #   @return [OK, ERROR] a string telling us how the request went
+    # @!attribute [r] message
+    #   @return [String] Any informational message from the API
+    # @!attribute [r] code
+    #   @return [Integer] the HTTP response code from the API
+    #     request
+    #
+    class Status
+      attr_reader :obj, :status
+
+      # @param response [Hash] the API response, turned into a hash
+      # @param status [Integer] HTTP status code
+      #
+      def initialize(response, status)
+        @obj = response.fetch(:status, response)
+        @status = status
+      end
+
+      def to_s
+        obj.inspect.to_s
+      end
+
+      def message
+        obj[:message] || nil
+      end
+
+      def code
+        obj[:code] || status
+      end
+
+      def result
+        return obj[:result] if obj[:result]
+        return 'OK' if status.between?(200, 299)
+        'ERROR'
+      end
+    end
+  end
+end

data/lib/wavefront-sdk/user.rb

@@ -1,15 +1,15 @@
-require_relative 'base'
+require_relative 'core/api'
 
 module Wavefront
   #
   # Manage and query Wavefront users
   #
-  class User < Base
+  class User < CoreApi
     # GET /api/v2/user
     # Get all users.
     #
     def list
-      api_get('')
+      api.get('')
     end
 
     # POST /api/v2/user
@@ -22,7 +22,7 @@ module Wavefront
     #
     def create(body, send_email = false)
       raise ArgumentError unless body.is_a?(Hash)
-      api_post("?sendEmail=#{send_email}", body, 'application/json')
+      api.post("?sendEmail=#{send_email}", body, 'application/json')
     end
 
     # DELETE /api/v2/user/id
@@ -33,7 +33,7 @@ module Wavefront
     #
     def delete(id)
       wf_user_id?(id)
-      api_delete(id)
+      api.delete(id)
     end
 
     # GET /api/v2/user/id
@@ -44,7 +44,7 @@ module Wavefront
     #
     def describe(id)
       wf_user_id?(id)
-      api_get(id)
+      api.get(id)
     end
 
     # PUT /api/v2/user/id/grant
@@ -63,7 +63,7 @@ module Wavefront
     def grant(id, group)
       wf_user_id?(id)
       raise ArgumentError unless group.is_a?(String)
-      api_post([id, 'grant'].uri_concat, "group=#{group}",
+      api.post([id, 'grant'].uri_concat, "group=#{group}",
                'application/x-www-form-urlencoded')
     end
 
@@ -79,7 +79,7 @@ module Wavefront
     def revoke(id, group)
       wf_user_id?(id)
       raise ArgumentError unless group.is_a?(String)
-      api_post([id, 'revoke'].uri_concat, "group=#{group}",
+      api.post([id, 'revoke'].uri_concat, "group=#{group}",
                'application/x-www-form-urlencoded')
     end
 

data/lib/wavefront-sdk/validators.rb

@@ -1,5 +1,5 @@
-require_relative 'constants'
-require_relative 'exception'
+require_relative 'defs/constants'
+require_relative 'core/exception'
 
 module Wavefront
   #
@@ -409,7 +409,7 @@ module Wavefront
     # https://community.wavefront.com/docs/DOC-1031
     #
     # @param point [Hash] description of point
-    # @return true if valie
+    # @return true if valid
     # @raise whichever exception is thrown first when validating
     #   each component of the point.
     #
@@ -422,6 +422,35 @@ module Wavefront
       true
     end
 
+    # Validate a distribution description
+    # @param dist [Hash] description of distribution
+    # @return true if valid
+    # @raise whichever exception is thrown first when validating
+    #   each component of the distribution.
+    #
+    def wf_distribution?(dist)
+      wf_metric_name?(dist[:path])
+      wf_distribution_values?(dist[:value])
+      wf_epoch?(dist[:ts]) if dist[:ts]
+      wf_source_id?(dist[:source]) if dist[:source]
+      wf_point_tags?(dist[:tags]) if dist[:tags]
+      true
+    end
+
+    # Validate an array of distribution values
+    # @param vals [Array[Array]] [count, value]
+    # @return true if valid
+    # @raise whichever exception is thrown first when validating
+    #   each component of the distribution.
+    #
+    def wf_distribution_values?(vals)
+      vals.each do |times, val|
+        wf_distribution_count?(times)
+        wf_value?(val)
+      end
+      true
+    end
+
     # Ensure the given argument is a valid Wavefront notificant ID.
     #
     # @param id [String] the notificant ID to validate
@@ -446,6 +475,26 @@ module Wavefront
       return true if id.is_a?(String) && id =~ /^[a-z0-9]+$/
       raise Wavefront::Exception::InvalidIntegrationId
     end
+
+    # Ensure the given argument is a valid distribution interval.
+    # @param interval [Symbol]
+    # @raise Wavefront::Exception::InvalidDistributionInterval if the
+    #   interval is not valid
+    #
+    def wf_distribution_interval?(interval)
+      return true if %i[m h d].include?(interval)
+      raise Wavefront::Exception::InvalidDistributionInterval
+    end
+
+    # Ensure the given argument is a valid distribution count.
+    # @param count [Numeric]
+    # @raise Wavefront::Exception::InvalidDistributionCount if the
+    #   count is not valid
+    #
+    def wf_distribution_count?(count)
+      return true if count.is_a?(Integer) && count > 0
+      raise Wavefront::Exception::InvalidDistributionCount
+    end
   end
   # rubocop:enable Metrics/ModuleLength
 end

data/lib/wavefront-sdk/webhook.rb

@@ -1,10 +1,10 @@
-require_relative 'base'
+require_relative 'core/api'
 
 module Wavefront
   #
   # Manage and query Wavefront webhooks
   #
-  class Webhook < Base
+  class Webhook < CoreApi
     def update_keys
       %i[title description template title triggers recipient]
     end
@@ -16,7 +16,7 @@ module Wavefront
     # @param limit [Integer] the number of webhooks to return
     #
     def list(offset = 0, limit = 100)
-      api_get('', offset: offset, limit: limit)
+      api.get('', offset: offset, limit: limit)
     end
 
     # POST /api/v2/webhook
@@ -29,7 +29,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/webhook/id
@@ -40,7 +40,7 @@ module Wavefront
     #
     def delete(id)
       wf_webhook_id?(id)
-      api_delete(id)
+      api.delete(id)
     end
 
     # GET /api/v2/webhook/id
@@ -51,7 +51,7 @@ module Wavefront
     #
     def describe(id)
       wf_webhook_id?(id)
-      api_get(id)
+      api.get(id)
     end
 
     # PUT /api/v2/webhook/id
@@ -69,9 +69,9 @@ module Wavefront
       wf_webhook_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
   end

data/lib/wavefront-sdk/write.rb

@@ -1,66 +1,127 @@
-require_relative 'base_write'
+require 'socket'
+require_relative 'core/exception'
+require_relative 'core/logger'
+require_relative 'defs/constants'
+require_relative 'validators'
+require 'spy'
+require 'spy/integration'
+
+HOSTNAME = Socket.gethostname.freeze
 
 module Wavefront
   #
-  # This class helps you send points to a Wavefront proxy in native
-  # format. Usually this is done on port 2878.
-  #
-  # The points are prepped in the BaseWrite class, which this
-  # extends. This class provides the transport mechanism.
+  # This class helps you send points to Wavefront. It is extended by
+  # the Write and Report classes, which respectively handle point
+  # ingestion by a proxy and directly to the API.
   #
-  class Write < BaseWrite
-    def really_send_point(point)
-      begin
-        sock.puts(point)
-      rescue StandardError => e
-        summary[:unsent] += 1
-        log('WARNING: failed to send point.')
-        log(e.to_s, :debug)
-        return false
-      end
+  class Write
+    attr_reader :creds, :opts, :writer, :logger
+
+    include Wavefront::Validators
+
+    # Construct an object which gives the user an interface for
+    # writing points to Wavefront. The actual writing is handled by
+    # a Wavefront::Writer:: subclass.
+    #
+    # @param creds [Hash] credentials
+    #   signature.
+    # @param options [Hash] can contain the following keys:
+    #   proxy [String] the address of the Wavefront proxy. ('wavefront')
+    #   port [Integer] the port of the Wavefront proxy
+    #   tags [Hash] point tags which will be applied to every point
+    #   noop [Bool] if true, no proxy connection will be made, and
+    #     instead of sending the points, they will be printed in
+    #     Wavefront wire format.
+    #   novalidate [Bool] if true, points will not be validated.
+    #     This might make things go marginally quicker if you have
+    #     done point validation higher up in the chain. Invalid
+    #     points are dropped, logged, and reported in the summary.
+    #   verbose [Bool]
+    #   debug [Bool]
+    #   writer [Symbol, String] the name of the writer class to use.
+    #     Defaults to :socket
+    #
+    def initialize(creds = {}, opts = {})
+      defaults = { tags:       nil,
+                   writer:     :socket,
+                   noop:       false,
+                   novalidate: false,
+                   verbose:    false,
+                   debug:      false }
+
+      @opts = setup_options(opts, defaults)
+      @creds = creds
+      wf_point_tags?(opts[:tags]) if opts[:tags]
+      @logger = Wavefront::Logger.new(opts)
+      @writer = setup_writer
+    end
 
-      summary[:sent] += 1
-      true
+    def setup_options(user, defaults)
+      defaults.merge(user)
     end
 
-    # Open a socket to a Wavefront proxy, putting the descriptor
-    # in instance variable @sock.
+    # Wrapper to the writer class's #open method. Using this you can
+    # manually open a connection and re-use it.
     #
     def open
-      if opts[:noop]
-        log('No-op requested. Not opening connection to proxy.')
-        return true
-      end
+      writer.open
+    end
 
-      port = net[:port] || 2878
-      log("Connecting to #{net[:proxy]}:#{port}.", :debug)
+    # Wrapper to the writer class's #close method.
+    #
+    def close
+      writer.close
+    end
 
-      begin
-        @sock = TCPSocket.new(net[:proxy], port)
-      rescue StandardError => e
-        log(e, :error)
-        raise Wavefront::Exception::InvalidEndpoint
-      end
+    # A wrapper to the writer class's #write method.
+    # Writers implement this method differently, Check the
+    # appropriate class documentation for @return information etc.
+    # The signature is always the same.
+    #
+    def write(points = [], openclose = true, prefix = nil)
+      writer.write(points, openclose, prefix)
     end
 
-    # Close the socket described by the @sock instance variable.
+    # A wrapper method around #write() which guarantees all points
+    # will be sent as deltas. You can still manually prefix any
+    # metric with a delta symbol and use #write(), but depending on
+    # your use-case, this method may be safer. It's easy to forget
+    # the delta.
     #
-    def close
-      return if opts[:noop]
-      log('Closing connection to proxy.', :debug)
-      sock.close
+    # @param points [Array[Hash]] see #write()
+    # @param openclose [Bool] see #write()
+    #
+    def write_delta(points, openclose = true)
+      write(paths_to_deltas(points), openclose)
+    end
+
+    # Prefix all paths in a points array (as passed to
+    # #write_delta() with a delta symbol
+    #
+    # @param points [Array[Hash]] see #write()
+    # @return [Array[Hash]]
+    #
+    def paths_to_deltas(points)
+      [points].flatten.map { |p| p.tap { p[:path] = DELTA + p[:path] } }
     end
 
-    # Overload the method which sets an API endpoint. A proxy
-    # endpoint has an address and a port, rather than an address and
-    # a token.
+    # Wrapper for the writer class's #send_point method
+    # @param point [String] a point description, probably from
+    #   #hash_to_wf()
     #
-    def setup_endpoint(creds)
-      @net = creds
+    def send_point(point)
+      if opts[:noop]
+        logger.log "Would send: #{point}"
+        return
+      end
+
+      logger.log("Sending: #{point}", :debug)
+      writer.send_point(point)
     end
 
-    # Send raw data to a Wavefront proxy, automatically opening and
-    # closing a socket.
+    # Send raw data to a Wavefront proxy, optionally automatically
+    # opening and closing the connection. (Or not, if that does not
+    # make sense in the context of the writer.)
     #
     # @param points [Array[String]] an array of points in native
     #   Wavefront wire format, as described in
@@ -71,22 +132,62 @@ module Wavefront
     #   afterwards, close it.
     #
     def raw(points, openclose = true)
-      open if openclose
+      writer.open if openclose && writer.respond_to?(:open)
 
       begin
-        [points].flatten.each { |p| send_point(p) }
+        [points].flatten.each { |p| writer.send_point(p) }
       ensure
-        close if openclose
+        writer.close if openclose && writer.respond_to?(:close)
       end
     end
 
+    # The method used to validate the data we wish to write.
+    #
+    def validation
+      :wf_point?
+    end
+
+    # Convert a validated point to a string conforming to
+    # https://community.wavefront.com/docs/DOC-1031.  No validation
+    # is done here.
+    #
+    # @param point [Hash] a hash describing a point. See #write() for
+    #   the format.
+    #
+    def hash_to_wf(point)
+      format('%s %s %s source=%s %s %s',
+             *point_array(point)).squeeze(' ').strip
+    rescue StandardError
+      raise Wavefront::Exception::InvalidPoint
+    end
+
+    # Make an array which can be used by #hash_to_wf.
+    # @param point [Hash] a hash describing a point. See #write() for
+    #   the format.
+    # @raise
+    #
+    def point_array(point)
+      [point[:path] || raise,
+       point[:value] || raise,
+       point.fetch(:ts, nil),
+       point.fetch(:source, HOSTNAME),
+       point[:tags] && point[:tags].to_wf_tag,
+       opts[:tags] && opts[:tags].to_wf_tag]
+    end
+
     private
 
-    def _write_loop(points)
-      points.each do |p|
-        p[:ts] = p[:ts].to_i if p[:ts].is_a?(Time)
-        send_point(hash_to_wf(p))
-      end
+    # @return [Object] appropriate subclass of Wavefront::Writer
+    # @raise [Wavefront::Exception::UnsupportedWriter] if requested
+    #   writer cannot be loaded
+    #
+    def setup_writer
+      writer = opts[:writer].to_s
+      require_relative File.join('writers', writer)
+      Object.const_get(format('Wavefront::Writer::%s',
+                              writer.capitalize)).new(self)
+    rescue LoadError
+      raise(Wavefront::Exception::UnsupportedWriter, writer)
     end
   end
 end