add a cadvisor class

Author: yaacov

examples/authentication_proxy.rb

@@ -0,0 +1,39 @@
+require 'prometheus/api_client'
+
+# returns a client, with authentication proxy support
+prometheus = Prometheus::ApiClient.client('https://example.com:443',
+                                          credentials: { token: 'TopSecret' })
+
+prometheus.query(
+  query: 'container_cpu_usage_seconds_total{id="/"}',
+  time: '2017-08-07T06:10:30.781Z',
+)
+
+# will result in a hash containing the results data struct:
+#
+# {"resultType"=>"vector",
+# "result"=>
+#  [{"metric"=>
+#     {"__name__"=>"container_cpu_usage_seconds_total",
+#      "beta_kubernetes_io_arch"=>"amd64",
+#      "beta_kubernetes_io_os"=>"linux",
+#      "cpu"=>"cpu00",
+#      "id"=>"/",
+#      "instance"=>"example.com",
+#      "job"=>"kubernetes-cadvisor",
+#      "kubernetes_io_hostname"=>"example.com",
+#      "region"=>"infra",
+#      "zone"=>"default"},
+#    "value"=>[1502089057.125, "51412.007276689"]},
+#   {"metric"=>
+#     {"__name__"=>"container_cpu_usage_seconds_total",
+#      "beta_kubernetes_io_arch"=>"amd64",
+#      "beta_kubernetes_io_os"=>"linux",
+#      "cpu"=>"cpu01",
+#      "id"=>"/",
+#      "instance"=>"example.com",
+#      "job"=>"kubernetes-cadvisor",
+#      "kubernetes_io_hostname"=>"example.com",
+#      "region"=>"infra",
+#      "zone"=>"default"},
+#    "value"=>[1502089057.125, "54034.698666487"]}]}

examples/get_labels.rb

@@ -0,0 +1,11 @@
+require 'prometheus/api_client'
+
+# returns a client
+prometheus = Prometheus::ApiClient.client('http://example.com:8080')
+
+prometheus.label('job')
+
+# will result in an array containing the results data struct:
+#
+# ["kubernetes-apiservers", "kubernetes-cadvisor", "kubernetes-nodes",
+#  "kubernetes-service-endpoints"]

examples/get_metrics.rb

@@ -1,12 +1,42 @@
 require 'prometheus/api_client'
 
-# returns a default client
-prometheus = Prometheus::ApiClient.client
+# returns a client
+prometheus = Prometheus::ApiClient.client('http://example.com:8080')
 
-prometheus.get(
-  'query_range',
-  query: 'sum(container_cpu_usage_seconds_total{job="kubernetes-cadvisor"})',
-  start: '2015-07-01T20:10:30.781Z',
-  end:   '2015-07-02T20:10:30.781Z',
+prometheus.query_range(
+  query: 'container_cpu_usage_seconds_total{id="/"}',
+  start: '2017-08-07T06:10:30.781Z',
+  end:   '2017-08-07T06:14:30.781Z',
   step:  '120s',
 )
+
+# will result in a hash containing the results data struct:
+#
+# {"resultType"=>"matrix",
+# "result"=>
+#  [{"metric"=>
+#     {"__name__"=>"container_cpu_usage_seconds_total",
+#      "beta_kubernetes_io_arch"=>"amd64",
+#      "beta_kubernetes_io_os"=>"linux",
+#      "cpu"=>"cpu00",
+#      "id"=>"/",
+#      "instance"=>"example.com",
+#      "job"=>"kubernetes-cadvisor",
+#      "kubernetes_io_hostname"=>"example.com",
+#      "region"=>"infra",
+#      "zone"=>"default"},
+#    "values"=>[[1502086230.781, "51264.830099022"],
+#               [1502086470.781, "51277.367732154"]]},
+#   {"metric"=>
+#     {"__name__"=>"container_cpu_usage_seconds_total",
+#      "beta_kubernetes_io_arch"=>"amd64",
+#      "beta_kubernetes_io_os"=>"linux",
+#      "cpu"=>"cpu01",
+#      "id"=>"/",
+#      "instance"=>"example.com",
+#      "job"=>"kubernetes-cadvisor",
+#      "kubernetes_io_hostname"=>"example.com",
+#      "region"=>"infra",
+#      "zone"=>"default"},
+#    "values"=>[[1502086230.781, "53879.644934689"],
+#               [1502086470.781, "53892.665282065"]]}]}

examples/low_level.rb

@@ -0,0 +1,21 @@
+require 'prometheus/api_client'
+
+# returns a default client
+prometheus = Prometheus::ApiClient.client
+
+prometheus.get(
+  'query_range',
+  query: 'sum(container_cpu_usage_seconds_total{job="kubernetes-cadvisor"})',
+  start: '2015-07-01T20:10:30.781Z',
+  end:   '2015-07-02T20:10:30.781Z',
+  step:  '120s',
+)
+
+# will result in a low level Response object:
+#
+# <Faraday::Response:0x0055d24b49b998
+# @env=
+#  #<struct Faraday::Env
+#   method=:get,
+#   body=
+# ...

lib/prometheus/api_client.rb

@@ -5,8 +5,9 @@
 require 'prometheus/api_client/client'
 
 module Prometheus
-  # Client is a ruby implementation for a Prometheus compatible api_client.
+  # Api Client is a ruby implementation for a Prometheus compatible api_client.
   module ApiClient
+    # Default paramters for creating default client
     DEFAULT_ENTRYPOINT = 'http://localhost:9090'.freeze
     DEFAULT_ARGS = {
       path: '/api/v1/',
@@ -17,19 +18,33 @@ module ApiClient
       },
     }.freeze
 
-    # Returns a default client object
-    def self.client(entrypoint = DEFAULT_ENTRYPOINT, args = {})
-      args = DEFAULT_ARGS.merge(args)
+    # Create a Prometheus API client:
+    #
+    # @param [String] entrypoint The Prometheus server url.
+    #
+    # @param [Hash] options
+    # @option options [Hash] :url String base URL.
+    # @option options [Hash] :params URI query unencoded key/value pairs.
+    # @option options [Hash] :headers Unencoded HTTP header key/value pairs.
+    # @option options [Hash] :request Request options.
+    # @option options [Hash] :ssl SSL options.
+    # @option options [Hash] :proxy Proxy options.
+    #
+    # A default client is created if options is omitted.
+    def self.client(entrypoint = DEFAULT_ENTRYPOINT, options = {})
+      options = DEFAULT_ARGS.merge(options)
 
       Client.new(
-        prometheus_args(entrypoint, args),
+        prometheus_args(entrypoint, options),
       )
     end
 
+    # Helper function to evalueate the low level proxy option
     def self.prometheus_proxy(options)
       options[:http_proxy_uri] if options[:http_proxy_uri]
     end
 
+    # Helper function to evalueate the low level ssl option
     def self.prometheus_verify_ssl(options)
       return unless options[:verify_ssl]
 
@@ -39,6 +54,7 @@ def self.prometheus_verify_ssl(options)
       }
     end
 
+    # Helper function to evalueate the low level headers option
     def self.prometheus_headers(credentials)
       return unless credentials[:token]
 
@@ -47,6 +63,7 @@ def self.prometheus_headers(credentials)
       }
     end
 
+    # Helper function to create the args for the low level client
     def self.prometheus_args(entrypoint, args = {})
       {
         url: entrypoint + args[:path],

lib/prometheus/api_client/cadvisor.rb

@@ -0,0 +1,88 @@
+# encoding: UTF-8
+
+require 'prometheus/api_client/client'
+
+module Prometheus
+  # Client is a ruby implementation for a Prometheus compatible api_client.
+  module ApiClient
+    # Client contains the implementation for a Prometheus compatible api_client,
+    # With special labels for the cadvisor job.
+    module Cadvisor
+      # Add labels to simple query variables.
+      #
+      # Example:
+      #     "cpu_usage" => "cpu_usage{labels...}"
+      #     "sum(cpu_usage)" => "sum(cpu_usage{labels...})"
+      #     "rate(cpu_usage[5m])" => "rate(cpu_usage{labels...}[5m])"
+      #
+      # Note:
+      #     Not supporting more complex queries.
+      def self.update_query(query, labels)
+        query.sub(/(?<r>\[.+\])?(?<f>[)])?$/, "{#{labels}}\\k<r>\\k<f>")
+      end
+
+      # A client with special labels for node cadvisor metrics
+      class Node < Client
+        def initialize(instance, region = 'infra', zone = 'default', args = {})
+          @labels = "job=\"kubernetes-cadvisor\",region=\"#{region}\"," \
+            "zone=\"#{zone}\",instance=\"#{instance}\""
+          super(args)
+        end
+
+        def query(options)
+          options[:query] = update_query(options[:query], @labels)
+          super(options)
+        end
+
+        def query_range(options)
+          options[:query] = update_query(options[:query], @labels)
+          super(options)
+        end
+      end
+
+      # A client with special labels for pod cadvisor metrics
+      class Pod < Client
+        def initialize(pod_name, namespace = 'default', region = 'infra',
+                       zone = 'default', args = {})
+
+          @labels = "job=\"kubernetes-cadvisor\",region=\"#{region}\"," \
+            "zone=\"#{zone}\",namespace=\"#{namespace}\"," \
+            "pod_name=\"#{pod_name}\",container_name=\"POD\""
+          super(args)
+        end
+
+        def query(options)
+          options[:query] = update_query(options[:query], @labels)
+          super(options)
+        end
+
+        def query_range(options)
+          options[:query] = update_query(options[:query], @labels)
+          super(options)
+        end
+      end
+
+      # A client with special labels for container cadvisor metrics
+      class Container < Client
+        def initialize(container_name, pod_name, namespace = 'default',
+                       region = 'infra', args = {})
+
+          @labels = "job=\"kubernetes-cadvisor\",region=\"#{region}\"," \
+            "namespace=\"#{namespace}\"," \
+            "pod_name=\"#{pod_name}\",container_name=\"#{container_name}\""
+          super(args)
+        end
+
+        def query(options)
+          options[:query] = update_query(options[:query], @labels)
+          super(options)
+        end
+
+        def query_range(options)
+          options[:query] = update_query(options[:query], @labels)
+          super(options)
+        end
+      end
+    end
+  end
+end

lib/prometheus/api_client/client.rb

@@ -10,26 +10,78 @@ module ApiClient
     class Client
       class RequestError < StandardError; end
 
-      def initialize(args)
-        @client = Faraday.new(args)
+      # Create a Prometheus API client:
+      #
+      # @param [Hash] options
+      # @option options [Hash] :url String base URL.
+      # @option options [Hash] :params URI query unencoded key/value pairs.
+      # @option options [Hash] :headers Unencoded HTTP header key/value pairs.
+      # @option options [Hash] :request Request options.
+      # @option options [Hash] :ssl SSL options.
+      # @option options [Hash] :proxy Proxy options.
+      #
+      # A default client is created if options is omitted.
+      def initialize(options)
+        @client = Faraday.new(options)
       end
 
+      # Evaluates an instant query at a single point in time:
+      #
+      # @param [Hash] options
+      # @option options [String] :query Prometheus expression query string.
+      # @option options [String] :time  <rfc3339 | unix_timestamp> Evaluation
+      #   timestamp. Optional.
+      # @option options [String] :timeout Evaluation timeout. Optional.
+      #   Defaults to and is capped by the value of the -query.timeout flag.
+      #
+      # The current server time is used if the time parameter is omitted.
       def query(options)
         run_command('query', options)
       end
 
+      # Evaluates an expression query over a range of time:
+      #
+      # @param [Hash] options
+      # @option options [String] :query Prometheus expression query string.
+      # @option options [String] :start  <rfc3339 | unix_timestamp> Start
+      #   timestamp.
+      # @option options [String] :end  <rfc3339 | unix_timestamp> End timestamp.
+      # @option options [String] :step  <duration> Query resolution step width.
+      # @option options [String] :timeout Evaluation timeout. Optional.
+      #   Defaults to and is capped by the value of the -query.timeout flag.
+      #
+      # The current server time is used if the time parameter is omitted.
       def query_range(options)
         run_command('query_range', options)
       end
 
-      def label(tag, options = {})
-        run_command("label/#{tag}/values", options)
+      # Returns an overview of the current state of the Prometheus target
+      # discovery:
+      #
+      # @param [Hash] options
+      #
+      # No options used.
+      def targets(options)
+        run_command('targets', options)
       end
 
+      # Returns a list of label values for a provided label name:
+      #
+      # @param [String] label Label name
+      # @param [Hash] options
+      #
+      # No options used.
+      def label(label, options = {})
+        run_command("label/#{label}/values", options)
+      end
+
+      # Issues a get request to the low level client.
       def get(command, options)
         @client.get(command, options)
       end
 
+      # Issues a get request to the low level client, and evalueate the
+      # response JSON.
       def run_command(command, options)
         response = get(command, options)
 

lib/prometheus/api_client/version.rb

@@ -2,6 +2,6 @@
 
 module Prometheus
   module ApiClient
-    VERSION = '0.1.1'
+    VERSION = '0.2.1'
   end
 end