wavefront-sdk 0.0.1

data/lib/wavefront-sdk/exception.rb

@@ -0,0 +1,39 @@
+module Wavefront
+  #
+  # Simple exception classes
+  #
+  class Exception
+    class EmptyMetricName < ::Exception; end
+    class InvalidAlertId < ::Exception; end
+    class InvalidAlertSeverity < ::Exception; end
+    class InvalidCloudIntegrationId < ::Exception; end
+    class InvalidDashboardId < ::Exception; end
+    class InvalidEndpoint < ::Exception; end
+    class InvalidEventId < ::Exception; end
+    class InvalidExternalLinkId < ::Exception; end
+    class InvalidGranularity < ::Exception; end
+    class InvalidHostname < ::Exception; end
+    class InvalidMaintenanceWindowId < ::Exception; end
+    class InvalidMessageId < ::Exception; end
+    class InvalidMetricName < ::Exception; end
+    class InvalidMetricValue < ::Exception; end
+    class InvalidName < ::Exception; end
+    class InvalidPoint < ::Exception; end
+    class InvalidPrefixLength < ::Exception; end
+    class InvalidProxyId < ::Exception; end
+    class InvalidResponse < ::Exception; end
+    class InvalidSavedSearchId < ::Exception; end
+    class InvalidSavedSearchEntity < ::Exception; end
+    class InvalidSourceId < ::Exception; end
+    class InvalidString < ::Exception; end
+    class InvalidTag < ::Exception; end
+    class InvalidLinkTemplate < ::Exception; end
+    class InvalidTimeFormat < ::Exception; end
+    class InvalidTimestamp < ::Exception; end
+    class InvalidUserId < ::Exception; end
+    class InvalidWebhookId < ::Exception; end
+    class InvalidVersion < ::Exception; end
+    class NotImplemented < ::Exception; end
+    class ValueOutOfRange < ::Exception; end
+  end
+end

data/lib/wavefront-sdk/externallink.rb

@@ -0,0 +1,77 @@
+require_relative './base'
+
+module Wavefront
+  #
+  # Manage and query Wavefront external links.
+  #
+  class ExternalLink < Wavefront::Base
+    def api_base
+      '/extlink'
+    end
+
+    # GET /api/v2/extlink
+    # Get all external links for a customer
+    #
+    # @param offset [Int] link at which the list begins
+    # @param limit [Int] the number of link to return
+    #
+    def list(offset = 0, limit = 100)
+      api_get('', { offset: offset, limit: limit })
+    end
+
+    # POST /api/v2/extlink
+    # Create a specific external link.
+    #
+    # @param name [String] a plaintext name for the link
+    # @param template [String] a mustache template for the link target
+    # @param description [String] a plaintext description of the link
+    # @return [Hash]
+    #
+    def create(body)
+      raise ArgumentError unless body.is_a?(Hash)
+      api_post('', body, 'application/json')
+    end
+
+    # DELETE /api/v2/extlink/{id}
+    # Delete a specific external link.
+    #
+    # @param id [String] ID of the link
+    # @return [Hash]
+    #
+    def delete(id)
+      wf_link_id?(id)
+      api_delete(id)
+    end
+
+    # GET /api/v2/extlink/{id}
+    # Get a specific external link.
+    #
+    # @param id [String] ID of the limnk
+    # @return [Hash]
+    #
+    def describe(id)
+      wf_link_id?(id)
+      api_get(id)
+    end
+
+    # PUT /api/v2/extlink/{id}
+    # Update a specific external link.
+    #
+    # @param id [String] ID of the link
+    # @param payload [Hash] a key:value hash where the key is the
+    #   property to change and the value is its desired value
+    # @return [Hash]
+    #
+    def update(id, body)
+      wf_link_id?(id)
+      raise ArgumentError unless body.is_a?(Hash)
+      api_put(id, body)
+    end
+  end
+
+  # A standard response.
+  #
+  class Response
+    class ExternalLink < Base; end
+  end
+end

data/lib/wavefront-sdk/maintenancewindow.rb

@@ -0,0 +1,75 @@
+require_relative './base'
+
+module Wavefront
+  #
+  # Manage and query Wavefront maintenance windows
+  #
+  class MaintenanceWindow < Wavefront::Base
+
+    # GET /api/v2/maintenancewindow
+    # Get all maintenance windows for a customer.
+    #
+    # @param offset [Integer] window at which the list begins
+    # @param limit [Integer] the number of window to return
+    #
+    def list(offset = 0, limit = 100)
+      api_get('', { offset: offset, limit: limit })
+    end
+
+    # POST /api/v2/maintenancewindow
+    # Create a maintenance window.
+    #
+    # We used to validate input here but do not any more.
+    #
+    # @param body [Hash] a hash of parameters describing the window.
+    #   Please refer to the Wavefront Swagger docs for key:value
+    #   information
+    # @return [Hash]
+    #
+    def create(body)
+      raise ArgumentError unless body.is_a?(Hash)
+      api_post('', body, 'application/json')
+    end
+
+    # DELETE /api/v2/maintenancewindow/{id}
+    # Delete a specific maintenance window.
+    #
+    # @param id [String, Integer] ID of the maintenance window
+    # @return [Hash]
+    #
+    def delete(id)
+      wf_maintenance_window_id?(id)
+      api_delete(id)
+    end
+
+    # GET /api/v2/maintenancewindow/{id}
+    # Get a specific maintenance window.
+    #
+    # @param id [String, Integer] ID of the maintenance window
+    # @return [Hash]
+    #
+    def describe(id)
+      wf_maintenance_window_id?(id)
+      api_get(id)
+    end
+
+    # PUT /api/v2/maintenancewindow/{id}
+    # Update a specific maintenance window.
+    #
+    # @param body [Hash] a hash of parameters describing the window.
+    # @return [Hash]
+    # @raise any validation errors from body
+    #
+    def update(id, body)
+      wf_maintenance_window_id?(id)
+      raise ArgumentError unless body.is_a?(Hash)
+      api_put(id, body)
+    end
+  end
+
+  # A standard response.
+  #
+  class Response
+    class MaintenanceWindow < Base; end
+  end
+end

data/lib/wavefront-sdk/message.rb

@@ -0,0 +1,36 @@
+require_relative './base'
+
+module Wavefront
+  #
+  # Manage and query Wavefront messages.
+  #
+  class Message < Wavefront::Base
+
+    # GET /api/v2/message
+    # Gets messages applicable to the current user, i.e. within time
+    # range and distribution scope
+    #
+    # @param offset [Int] agent at which the list begins
+    # @param limit [Int] the number of agents to return
+    #
+    def list(offset = 0, limit = 100, unread_only = true)
+      api_get('', { offset: offset, limit: limit, unreadOnly: unread_only })
+    end
+
+    # POST /api/v2/message/{id}/read
+    # Mark a specific message as read
+    #
+    # @param [id] message ID to mark as read
+    #
+    def read(id)
+      wf_message_id?(id)
+      api_post([id, 'read'].uri_concat)
+    end
+  end
+
+  # A standard response.
+  #
+  class Response
+    class Message < Base; end
+  end
+end

data/lib/wavefront-sdk/metric.rb

@@ -0,0 +1,52 @@
+require_relative './base'
+
+module Wavefront
+  #
+  # Query Wavefront metrics.
+  #
+  class Metric < Wavefront::Base
+    def api_base
+      'chart/metric'
+    end
+
+    # GET /api/v2/chart/metric/detail
+    # Get more details on a metric, including reporting sources and
+    # approximate last time reported
+    #
+    # @param offset [Int] agent at which the list begins
+    # @param limit [Int] the number of agents to return
+    #
+    def detail(metric, sources = [], cursor = nil)
+      raise ArgumentError unless metric.is_a?(String)
+      raise ArgumentError unless sources.is_a?(Array)
+
+      q = [[:m, metric]]
+
+      if cursor
+        raise ArgumentError unless cursor.is_a?(String)
+        q.<< [:c, cursor]
+      end
+
+      sources.each { |s| q.<< [:h, s] }
+
+      api_get('detail', q)
+    end
+  end
+
+  class Response
+
+    # The Metric response forges status and response methods to look
+    # like other classes and create a more consistent interface.
+    #
+    class Metric < Base
+      def populate(raw, status)
+        @response = Struct.new(*raw.keys).new(*raw.values).freeze
+
+        result = status == 200 ? 'OK' : 'ERROR'
+
+        @status = Struct.new(:result, :message, :code).
+          new(result, raw[:message] || raw[:error], status)
+      end
+    end
+  end
+end

data/lib/wavefront-sdk/mixins.rb

@@ -0,0 +1,60 @@
+require_relative './exception'
+
+module Wavefront
+  module Mixins
+    # Return a time as an integer, however it might come in.
+    #
+    # @param t [Integer, String, Time] timestamp
+    # @param ms [Boolean] whether to return epoch milliseconds
+    # @return [Integer] epoch time in seconds
+    # @raise Wavefront::InvalidTimestamp
+    #
+    def parse_time(t, ms = false)
+      #
+      # Numbers, or things that look like numbers, pass straight
+      # through. No validation, because maybe the user means one
+      # second past the epoch, or the year 2525.
+      #
+      return t if t.is_a?(Integer)
+
+      if t.is_a?(String)
+        return t.to_i if t.match(/^\d+$/)
+        begin
+          t = DateTime.parse("#{t} #{Time.now.getlocal.zone}")
+        rescue
+          raise Wavefront::Exception::InvalidTimestamp
+        end
+      end
+
+      ms ? t.to_datetime.strftime('%Q').to_i : t.strftime('%s').to_i
+    end
+  end
+end
+
+# Extensions to the Hash class
+#
+class Hash
+
+  # Convert a tag hash into a string. The quoting is recommended in
+  # the WF wire-format guide. No validation is performed here.
+  #
+  def to_wf_tag
+    self.map { |k, v| "#{k}=\"#{v}\"" }.join(' ')
+  end
+end
+
+# Extensions to stdlib Array
+#
+class Array
+
+  # Join strings together to make a URI path in a way that is more
+  # flexible than URI::Join.  Removes multiple and trailing
+  # separators. Does not have to produce fully qualified paths. Has
+  # no concept of protocols, hostnames, or query strings.
+  #
+  # @return [String] a URI path
+  #
+  def uri_concat
+    self.join('/').squeeze('/').sub(/\/$/, '').sub(/\/\?/, '?')
+  end
+end

data/lib/wavefront-sdk/proxy.rb

@@ -0,0 +1,95 @@
+require_relative './base'
+
+module Wavefront
+  #
+  # Manage and query Wavefront proxies.
+  #
+  class Proxy < Wavefront::Base
+
+    # GET /api/v2/proxy
+    # Get all proxies for a customer
+    #
+    # @param offset [Int] proxy at which the list begins
+    # @param limit [Int] the number of proxies to return
+    #
+    def list(offset = 0, limit = 100)
+      api_get('', { offset: offset, limit: limit })
+    end
+
+    # DELETE /api/v2/proxy/{id}
+    # Delete a specific proxy
+    #
+    # Deleting an active proxy moves it to 'trash', from where it
+    # can be restored with an #undelete operation. Deleting an proxy
+    # in 'trash' removes it for ever.
+    #
+    # @param id [String] ID of the proxy
+    # @return [Hash]
+    #
+    def delete(id)
+      wf_proxy_id?(id)
+      api_delete(id)
+    end
+
+    # GET /api/v2/proxy/{id}
+    # Get a specific proxy
+    #
+    # @param id [String] ID of the proxy
+    # @return [Hash]
+    #
+    def describe(id)
+      wf_proxy_id?(id)
+      api_get(id)
+    end
+
+    # POST /api/v2/proxy/{id}/undelete
+    # Undelete a specific proxy
+    #
+    # Move an proxy from 'trash' back into active service.
+    #
+    # @param id [String] ID of the proxy
+    # @return [Hash]
+    #
+    def undelete(id)
+      wf_proxy_id?(id)
+      api_post([id, 'undelete'].uri_concat)
+    end
+
+    # PUT /api/v2/proxy/{id}
+    # Update the name of a specific proxy
+    #
+    # Rename an proxy. This changes the human-readable name, not the
+    # unique identifier.
+    #
+    # @param id [String] ID of the proxy
+    # @param name [String] new name
+    # @return [Hash]
+    #
+    def rename(id, name)
+      wf_proxy_id?(id)
+      wf_string?(name)
+      update(id, {name: name})
+    end
+
+    # A generic function to change properties of an proxy. So far as I
+    # know, only the 'name' property can currently be changed, and we
+    # supply a dedicated #rename method for that.
+    #
+    # @param id [String] ID of the proxy
+    # @param payload [Hash] a key: value hash, where the key is the
+    #   property to change and the value is its desired value. No
+    #   validation is performed on any part of the payload.
+    # @return [Hash]
+    #
+    def update(id, payload)
+      wf_proxy_id?(id)
+      api_put(id, payload)
+    end
+  end
+
+  # A standard response
+  #
+  class Response
+    class Proxy < Base; end
+  end
+end

data/lib/wavefront-sdk/query.rb

@@ -0,0 +1,96 @@
+require_relative './base'
+
+module Wavefront
+  #
+  # Query Wavefront metrics.
+  #
+  class Query < Wavefront::Base
+    def api_base
+      'chart'
+    end
+
+    # GET /api/v2/chart/api
+    # Perform a charting query against Wavefront servers that
+    # returns the appropriate points in the specified time window
+    # and granularity. Any options can be pased through in the
+    # options hash. This means the SDK does not have to closely
+    # track the API, but also means the burden of data validation is
+    # down to the user.
+    #
+    # @param query [String] Wavefront query to run
+    # @param granularity [String] the required granularity for the
+    #   reported data
+    # @param t_start [Time, Integer] The start of the query window.
+    #   May be a Ruby Time object, or epoch milliseconds
+    # @param t_end [Time, Integer] The end of the query window.
+    #   May be a Ruby Time object, or epoch milliseconds.
+    # @param options [Hash] any other options defined in the API
+    #
+    def query(query, granularity = nil, t_start = nil, t_end = nil,
+               options = {})
+
+      raise ArgumentError unless query.is_a?(String)
+      wf_granularity?(granularity)
+      raise Wavefront::Exception::InvalidTimestamp if t_start.nil?
+
+      options[:q] = query
+      options[:g] = granularity
+      options[:s] = parse_time(t_start, true)
+      options[:e] = parse_time(t_end, true) if t_end
+
+      options.delete_if do |k, v|
+        v == false && k != :i
+      end
+
+      api_get('api', options)
+    end
+
+    # GET /api/v2/chart/raw
+    # Perform a raw data query against Wavefront servers that
+    # returns second granularity points grouped by tags
+    #
+    # @param metric [String]  metric to query ingested points for
+    #   (cannot contain wildcards)
+    # @param source [String] source to query ingested points for
+    #   (cannot contain wildcards).
+    # @param t_start [Time, Integer] start time of window: defaults
+    #   to one hour before t_end
+    # @param t_start [Time, Integer] start time of window: defaults
+    #   to now
+    #
+    def raw(metric, source = nil, t_start = nil, t_end = nil)
+      raise ArgumentError unless metric.is_a?(String)
+
+      options = { metric: metric, }
+
+      if source
+        wf_source_id?(source)
+        options[:source] = source
+      end
+
+      options[:startTime] = parse_time(t_start, true) if t_start
+      options[:endTime] = parse_time(t_end, true) if t_end
+
+      api_get('raw', options)
+    end
+  end
+
+  class Response
+
+    # The Query response forges status and response methods to look
+    # like other classes and create a more consistent interface
+    #
+    class Query < Base
+      def populate(raw, status)
+        @response = Struct.new(*raw.keys).new(*raw.values).freeze
+
+        result = status == 200 ? 'OK' : 'ERROR'
+
+        if raw.key?(:warnings) || raw.key?(:error)
+          @status = Struct.new(:result, :message, :code).
+            new(result, raw[:message] || raw[:error], status)
+        end
+      end
+    end
+  end
+end