wavefront-sdk 3.6.0 → 5.0.0

data/lib/wavefront-sdk/api_mixins/user.rb

@@ -25,6 +25,26 @@ module Wavefront
 
         list.each { |id| wf_usergroup_id?(id) }
       end
+
+      # Validate a list of accounts.
+      # @param list [Array[String]] list of account IDs
+      # @raise Wavefront::Exception::InvalidAccount
+      #
+      def validate_account_list(list)
+        raise ArgumentError unless list.is_a?(Array)
+
+        list.each { |id| wf_account_id?(id) }
+      end
+
+      # Validate a list of roles
+      # @param list [Array[String]] list of role IDs
+      # @raise Wavefront::Exception::InvalidRole
+      #
+      def validate_role_list(list)
+        raise ArgumentError unless list.is_a?(Array)
+
+        list.each { |id| wf_role_id?(id) }
+      end
     end
   end
 end

data/lib/wavefront-sdk/core/api_caller.rb

@@ -6,6 +6,7 @@ require 'addressable'
 require_relative 'response'
 require_relative '../defs/version'
 require_relative '../support/mixins'
+require_relative '../stdlib/time'
 
 module Wavefront
   #
@@ -78,14 +79,47 @@ module Wavefront
     # was cleaner to add this method. Parameters are same as #get.
     #
     def get_flat_params(path, query = {})
-      conn = mk_conn(path,
-                     {},
-                     request: {
-                       params_encoder: Faraday::FlatParamsEncoder
-                     },
-                     params: query)
+      make_call(flat_param_conn(path, query), :get)
+    end
+
+    # This is used by the Wavefront::Unstable::Spy methods to stream data.
+    # It prints to standard out.
+    # @param path [String] path to be appended to the net[:api_base] path.
+    # @param query [Hash] optional key-value pairs with will be made into a
+    #   query string
+    # @param opts [Hash] keys:
+    #   timestamp_chunks -- prints a timestamp before each chunk of streamed
+    #     data
+    #   timeout -- after approximately this many seconds, return. It will be
+    #     the first chunk *after* the given time
+    # @return
+    #
+    def get_stream(path, query = {}, opts = {})
+      conn = flat_param_conn(path, query)
+      verbosity(conn, :get, query)
+      stream_connection(conn, query, opts)
+    rescue Faraday::TimeoutError
+      raise Wavefront::Exception::NetworkTimeout
+    rescue StopIteration
+      nil
+    end
+
+    def stream_connection(conn, query, opts)
+      t_end = end_time(opts)
+
+      conn.get do |req|
+        req.params = query
+        req.options.on_data = proc do |chunk, _size|
+          raise StopIteration if t_end && Time.right_now >= t_end
 
-      make_call(conn, :get)
+          puts Time.now if opts[:timestamp_chunks]
+          puts chunk
+        end
+      end
+    end
+
+    def end_time(opts)
+      Time.right_now + opts[:timeout] if opts[:timeout]&.positive?
     end
 
     # Make a POST call to the Wavefront API and return the result as
@@ -240,5 +274,14 @@ module Wavefront
         end
       end
     end
+
+    def flat_param_conn(path, query)
+      mk_conn(path,
+              {},
+              request: {
+                params_encoder: Faraday::FlatParamsEncoder
+              },
+              params: query)
+    end
   end
 end

data/lib/wavefront-sdk/core/exception.rb

@@ -8,6 +8,7 @@ module Wavefront
     class CredentialError < RuntimeError; end
     class EmptyMetricName < RuntimeError; end
     class EnumerableError < RuntimeError; end
+    class InvalidAccountId < RuntimeError; end
     class InvalidAlertId < RuntimeError; end
     class InvalidAlertSeverity < RuntimeError; end
     class InvalidApiTokenId < RuntimeError; end
@@ -23,9 +24,11 @@ module Wavefront
     class InvalidExternalLinkId < RuntimeError; end
     class InvalidGranularity < RuntimeError; end
     class InvalidHostname < RuntimeError; end
+    class InvalidIngestionPolicyId < RuntimeError; end
     class InvalidIntegrationId < RuntimeError; end
     class InvalidLinkTemplate < RuntimeError; end
     class InvalidMaintenanceWindowId < RuntimeError; end
+    class InvalidMonitoredClusterId < RuntimeError; end
     class InvalidMessageId < RuntimeError; end
     class InvalidMetricName < RuntimeError; end
     class InvalidMetricValue < RuntimeError; end
@@ -35,7 +38,9 @@ module Wavefront
     class InvalidPoint < RuntimeError; end
     class InvalidPrefixLength < RuntimeError; end
     class InvalidProxyId < RuntimeError; end
+    class InvalidRoleId < RuntimeError; end
     class InvalidRelativeTime < RuntimeError; end
+    class InvalidSamplingValue < RuntimeError; end
     class InvalidSavedSearchEntity < RuntimeError; end
     class InvalidSavedSearchId < RuntimeError; end
     class InvalidServiceAccountId < RuntimeError; end
@@ -49,6 +54,7 @@ module Wavefront
     class InvalidUserGroupId < RuntimeError; end
     class InvalidVersion < RuntimeError; end
     class InvalidWebhookId < RuntimeError; end
+    class NetworkTimeout < RuntimeError; end
     class NotImplemented < RuntimeError; end
     class SocketError < RuntimeError; end
     class UnparseableResponse < RuntimeError; end

data/lib/wavefront-sdk/core/response.rb

@@ -25,7 +25,8 @@ module Wavefront
   #
   class Response
     include Wavefront::Mixins
-    attr_reader :status, :response, :opts, :logger
+    attr_reader :status, :opts, :logger
+    attr_accessor :response
 
     # Create and return a Wavefront::Response object
     # @param json [String] a raw response body from the Wavefront API

data/lib/wavefront-sdk/defs/version.rb

@@ -1,6 +1,4 @@
 # frozen_string_literal: true
 
-require 'pathname'
-
-WF_SDK_VERSION = '3.6.0'
+WF_SDK_VERSION = '5.0.0'
 WF_SDK_LOCATION = Pathname.new(__dir__).parent.parent.parent

data/lib/wavefront-sdk/ingestionpolicy.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative 'core/api'
+
+module Wavefront
+  #
+  # View and manage Wavefront ingestion policies.
+  #
+  # These use the Usage API path.
+  #
+  class IngestionPolicy < CoreApi
+    def api_base
+      '/usage/ingestionpolicy'
+    end
+
+    # GET /api/v2/usage/ingestionpolicy
+    # Get all ingestion policies for a customer
+    #
+    # @return [Wavefront::Response]
+    #
+    # @param offset [Int] ingestion policy at which the list begins
+    # @param limit [Int] the number of ingestion policies to return
+    # @return [Wavefront::Response]
+    #
+    def list(offset = 0, limit = 100)
+      api.get('', offset: offset, limit: limit)
+    end
+
+    # POST /api/v2/usage/ingestionpolicy
+    # Create a specific ingestion policy
+    #
+    # @param body [Hash] description of ingestion policy
+    # @return [Wavefront::Response]
+    #
+    def create(body)
+      raise ArgumentError unless body.is_a?(Hash)
+
+      api.post('', body, 'application/json')
+    end
+
+    # DELETE /api/v2/usage/ingestionpolicy/{id}
+    # Delete a specific ingestion policy
+    #
+    # @param id [String] ID of the alert
+    # @return [Wavefront::Response]
+    #
+    def delete(id)
+      wf_ingestionpolicy_id?(id)
+      api.delete(id)
+    end
+
+    # GET /api/v2/usage/ingestionpolicy/{id}
+    # Get a specific ingestion policy
+    #
+    # @return [Wavefront::Response]
+    # @param id [String] ID of the proxy
+    # @return [Wavefront::Response]
+    #
+    def describe(id)
+      wf_ingestionpolicy_id?(id)
+      api.get(id)
+    end
+
+    # PUT /api/v2/usage/ingestionpolicy/{id}
+    # Update a specific ingestion policy
+    #
+    # @param id [String] a Wavefront alert ID
+    # @param body [Hash] key-value hash of the parameters you wish
+    #   to change
+    # @param modify [true, false] if true, use {#describe()} to get
+    #   a hash describing the existing object, and modify that with
+    #   the new body. If false, pass the new body straight through.
+    # @return [Wavefront::Response]
+    #
+    def update(id, body, modify = true)
+      wf_ingestionpolicy_id?(id)
+      raise ArgumentError unless body.is_a?(Hash)
+
+      return api.put(id, body, 'application/json') unless modify
+
+      api.put(id, hash_for_update(describe(id).response, body),
+              'application/json')
+    end
+  end
+end

data/lib/wavefront-sdk/paginator/base.rb

@@ -5,23 +5,29 @@ require_relative '../defs/constants'
 module Wavefront
   module Paginator
     #
-    # Automatically handle pagination. This is an abstract class
-    # made concrete by an extension for each HTTP request type.
+    # Automatically handle pagination. This is an abstract class made concrete
+    # by an extension for each HTTP request type.
     #
-    # This class and its children do slightly unpleasant things with
-    # the HTTP request passed to us by the user, extracting and
-    # changing values in the URI, query string, or POST/PUT body.
-    # The POST class is particularly onerous.
+    # This class and its children do slightly unpleasant things with the HTTP
+    # request passed to us by the user, extracting and changing values in the
+    # URI, query string, or POST/PUT body.  The POST class is particularly
+    # onerous.
     #
-    # Automatic pagination works by letting the user override the
-    # limit and offset values in API calls. Setting the limit to
-    # :all iteratively calls the Wavefront API, returning all
-    # requested objects an a standard Wavefront::Response wrapper;
-    # setting limit to :lazy returns a lazy Enumerable. The number
-    # of objects fetched in each API call, whether eager or lazy
-    # defaults to PAGE_SIZE, but the user can override that value by
-    # using the offset argument in conjunction with limit = :lazy |
-    # :all.
+    # Automatic pagination works by letting the user override the limit and
+    # offset values in API calls.
+    #
+    # * Calling with limit = :all iteratively calls the Wavefront API,
+    # returning all requested objects in a standard Wavefront::Response
+    # wrapper.
+    #
+    # * Calling with limit = :lazy returns a lazy Enumerable.
+    #
+    # The number of objects fetched in each API call, eager or lazy, defaults
+    # to PAGE_SIZE, but the user can override that value by using the offset
+    # argument in conjunction with limit = :lazy | :all.
+    #
+    # So, for example, to fetch all objects in blocks of ten (which could
+    # require a lot of API calls) you would use { limit: :all, offset: 10 }
     #
     class Base
       attr_reader :api_caller, :conn, :method, :args, :page_size,

data/lib/wavefront-sdk/query.rb

@@ -43,7 +43,6 @@ module Wavefront
       options[:s] = parse_time(t_start, true)
       options[:e] = parse_time(t_end, true) if t_end
 
-      options.delete_if { |k, v| v == false && k != :i }
       api.get('api', options)
     end
 

data/lib/wavefront-sdk/role.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative 'core/api'
+require_relative 'api_mixins/user'
+
+module Wavefront
+  #
+  # Manage and query Wavefront roles
+  #
+  class Role < CoreApi
+    include Wavefront::Mixin::User
+
+    def update_keys
+      %i[id name description]
+    end
+
+    # GET /api/v2/role
+    # Get all roles for a customer
+    # @param offset [Int] alert at which the list begins
+    # @param limit [Int] the number of alerts to return
+    # @return [Wavefront::Response]
+    #
+    def list(offset = 0, limit = 100)
+      api.get('', offset: offset, limit: limit)
+    end
+
+    # POST /api/v2/role
+    # Create a specific role
+    # @param body [Hash] a hash of parameters describing the role.  Please
+    #   refer to the Wavefront Swagger docs for key:value information
+    # @return [Wavefront::Response]
+    #
+    def create(body)
+      raise ArgumentError unless body.is_a?(Hash)
+
+      api.post('', body, 'application/json')
+    end
+
+    # DELETE /api/v2/role/{id}
+    # Delete a specific role
+    # @param id [String] ID of the role
+    # @return [Wavefront::Response]
+    #
+    def delete(id)
+      wf_role_id?(id)
+      api.delete(id)
+    end
+
+    # GET /api/v2/role/{id}
+    # Get a specific role
+    # @param id [String] ID of the role
+    # @return [Wavefront::Response]
+    #
+    def describe(id)
+      wf_role_id?(id)
+      api.get(id)
+    end
+
+    # PUT /api/v2/role/{id}
+    # Update a specific role
+    # @param id [String] role ID
+    # @param body [Hash] key-value hash of the parameters you wish to change
+    # @param modify [true, false] if true, use {#describe()} to get a hash
+    #   describing the existing object, and modify that with the new body. If
+    #   false, pass the new body straight through.
+    # @return [Wavefront::Response]
+    #
+    def update(id, body, modify = true)
+      wf_role_id?(id)
+      raise ArgumentError unless body.is_a?(Hash)
+
+      return api.put(id, body, 'application/json') unless modify
+
+      api.put(id, hash_for_update(describe(id).response, body),
+              'application/json')
+    end
+
+    # POST /api/v2/role/{id}/addAssignees
+    # Add multiple users and user groups to a specific role
+    # @param id [String] role ID
+    # @param assignees [Array[String]] list of roles or accounts to be added
+    # @return [Wavefront::Response]
+    #
+    def add_assignees(id, assignees)
+      wf_role_id?(id)
+      validate_user_list(assignees)
+      api.post([id, 'addAssignees'].uri_concat, assignees, 'application/json')
+    end
+
+    # POST /api/v2/role/{id}/removeAssignees
+    # Remove multiple users and user groups from a specific role
+    # @param id [String] role ID
+    # @param assignees [Array[String]] list of roles or accounts to be removed
+    # @return [Wavefront::Response]
+    #
+    def remove_assignees(id, assignees)
+      wf_role_id?(id)
+      validate_user_list(assignees)
+      api.post([id, 'removeAssignees'].uri_concat,
+               assignees,
+               'application/json')
+    end
+  end
+end

data/lib/wavefront-sdk/spy.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require_relative 'defs/constants'
+require_relative 'core/api'
+
+module Wavefront
+  #
+  # Spy on data going into Wavefront
+  #
+  class Spy < CoreApi
+    # GET /api/spy/points
+    # Gets new metric data points that are added to existing time series.
+    # @param sampling [Float] the amount of points to sample, from 0
+    #   (none) to 1 (all)
+    # @param filter [Hash] with the following keys:
+    #   :prefix [String] only list points whose metric name begins with this
+    #     case-sensitive string
+    #   :host [Array] only list points if source name begins with this
+    #     case-sensitive string
+    #   :tag_key [String,Array[String]] only list points with one or more of
+    #     the given points tags
+    # @param options [Hash] with the following keys
+    #   :timestamp [Boolean] prefix each block of streamed data with a
+    #     timestamp
+    #   :timeout [Integer] how many seconds to run the spy. After this time
+    #     the method returns
+    # @raise Wavefront::Exception::InvalidSamplingValue
+    # @return [Nil]
+    #
+    def points(sampling = 0.01, filters = {}, options = {})
+      wf_sampling_value?(sampling)
+      api.get_stream('points', points_filter(sampling, filters), options)
+    end
+
+    # GET /api/spy/histograms
+    # Gets new histograms that are added to existing time series.
+    # @param sampling [Float] see #points
+    # @param filter [Hash] see #points
+    # @param options [Hash] see #points
+    # @raise Wavefront::Exception::InvalidSamplingValue
+    # @return [Nil]
+    #
+    def histograms(sampling = 0.01, filters = {}, options = {})
+      wf_sampling_value?(sampling)
+      api.get_stream('histograms',
+                     histograms_filter(sampling, filters),
+                     options)
+    end
+
+    # GET /api/spy/spans
+    # Gets new spans with existing source names and span tags.
+    # @param sampling [Float] see #points
+    # @param filter [Hash] see #points
+    # @param options [Hash] see #points
+    # @raise Wavefront::Exception::InvalidSamplingValue
+    # @return [Nil]
+    #
+    def spans(sampling = 0.01, filters = {}, options = {})
+      wf_sampling_value?(sampling)
+      api.get_stream('spans', spans_filter(sampling, filters), options)
+    end
+
+    # GET /api/spy/ids
+    # Gets newly allocated IDs that correspond to new metric names, source
+    # names, point tags, or span tags. A new ID generally indicates that a
+    # new time series has been introduced.
+    # @param sampling [Float] see #points
+    # @param filter [Hash] with keys:
+    #   :prefix [String] only list assignments whose metric name begins with
+    #     this case-sensitive string
+    #   :type [String] one of METRIC, SPAN, HOST or STRING
+    # @param options [Hash] see #points
+    #
+    def ids(sampling = 0.01, filters = {}, options = {})
+      wf_sampling_value?(sampling)
+      api.get_stream('ids', ids_filter(sampling, filters), options)
+    end
+
+    def api_path
+      '/api/spy'
+    end
+
+    # We have to try to make the response we get from the API look
+    # like the one we get from the public API. To begin with, it's
+    # nothing like it.
+    #
+    # This method must be public because a #respond_to? looks for
+    # it.
+    #
+    def _response_shim(resp, status)
+      { response: parse_response(resp),
+        status: { result: status == 200 ? 'OK' : 'ERROR',
+                  message: extract_api_message(status, resp),
+                  code: status } }.to_json
+    end
+
+    private
+
+    def points_filter(sampling, filters)
+      { metric: filters.fetch(:prefix, nil),
+        host: filters.fetch(:host, nil),
+        sampling: sampling,
+        pointTagKey: filters.fetch(:tag_key, nil) }.compact
+    end
+
+    def histograms_filter(sampling, filters)
+      { histogram: filters.fetch(:prefix, nil),
+        host: filters.fetch(:host, nil),
+        sampling: sampling,
+        histogramTagKey: filters.fetch(:tag_key, nil) }.compact
+    end
+
+    def spans_filter(sampling, filters)
+      { name: filters.fetch(:prefix, nil),
+        host: filters.fetch(:host, nil),
+        sampling: sampling,
+        spanTagKey: filters.fetch(:tag_key, nil) }.compact
+    end
+
+    def ids_filter(sampling, filters)
+      { name: filters.fetch(:prefix, nil),
+        type: filters.fetch(:type, nil),
+        sampling: sampling }.compact
+    end
+  end
+end