ruby-grafana-reporter 0.1.6

data/lib/grafana/dashboard.rb

@@ -0,0 +1,66 @@
+module Grafana
+  # Representation of one specific dashboard in a {Grafana} instance.
+  class Dashboard
+    # @return [Grafana] parent {Grafana} object
+    attr_reader :grafana
+    attr_reader :panels, :variables
+
+    # @param model [Hash] converted JSON Hash of the grafana dashboard
+    # @param grafana [Grafana] parent {Grafana} object
+    def initialize(model, grafana)
+      @grafana = grafana
+      @model = model
+
+      # read panels
+      @panels = []
+      if @model.key?('panels')
+        @model['panels'].each do |panel|
+          if panel.key?('panels')
+            panel['panels'].each do |subpanel|
+              @panels << Panel.new(subpanel, self)
+            end
+          else
+            @panels << Panel.new(panel, self)
+          end
+        end
+      end
+
+      # store variables in array as objects of type Variable
+      @variables = []
+      return unless @model.key?('templating')
+
+      list = @model['templating']['list']
+      return unless list.is_a? Array
+
+      list.each do |item|
+        @variables << Variable.new(item)
+      end
+    end
+
+    # @return [String] +from+ time configured in the dashboard.
+    def from_time
+      return @model['time']['from'] if @model['time']
+
+      nil
+    end
+
+    # @return [String] +to+ time configured in the dashboard.
+    def to_time
+      @model['time']['to'] if @model['time']
+      nil
+    end
+
+    # @return [String] dashboard UID
+    def id
+      @model['uid']
+    end
+
+    # @return [Panel] panel for the specified ID
+    def panel(id)
+      panels = @panels.select { |item| item.field('id') == id.to_i }
+      raise PanelDoesNotExistError.new(id, self) if panels.empty?
+
+      panels.first
+    end
+  end
+end

data/lib/grafana/errors.rb

@@ -0,0 +1,61 @@
+module Grafana
+  # A top level alarm for all other errors in current module.
+  class GrafanaError < StandardError
+    def initialize(message)
+      super("GrafanaError: #{message} (#{self.class})")
+    end
+  end
+
+  # Raised if a given dashboard does not exist in a specific {Grafana} instance.
+  class DashboardDoesNotExistError < GrafanaError
+    # @param dashboard_uid [String] dashboard uid, which could not be found
+    def initialize(dashboard_uid)
+      super("The specified dashboard '#{dashboard_uid}' does not exist.")
+    end
+  end
+
+  # Raised if a given panel does not exist on a specific {Dashboard} in the current {Grafana} instance.
+  class PanelDoesNotExistError < GrafanaError
+    # @param panel_id [String] panel id, which could not be found on the dashboard
+    # @param dashboard [Dashboard] dashboard object on which the panel could not be found
+    def initialize(panel_id, dashboard)
+      super("The specified panel id '#{panel_id}' does not exist on the dashboard '#{dashboard.id}'.")
+    end
+  end
+
+  # Raised if a given query letter does not exist on a specific {Panel}.
+  class QueryLetterDoesNotExistError < GrafanaError
+    # @param query_letter [String] query letter name, which could not be found on the panel
+    # @param panel [Panel] panel object on which the query could not be found
+    def initialize(query_letter, panel)
+      super("The specified query '#{query_letter}' does not exist in the panel '#{panel.id}' in dashboard '#{panel.dashboard}'.")
+    end
+  end
+
+  # Raised if a given datasource does not exist in a specific {Grafana} instance.
+  class DatasourceDoesNotExistError < GrafanaError
+    # @param field [String] specifies, how the datasource has been searched, e.g. 'id' or 'name'
+    # @param datasource_identifier [String] identifier of the datasource, which could not be found, e.g. the specifiy id or name
+    def initialize(field, datasource_identifier)
+      super("Datasource with #{field} '#{datasource_identifier}' does not exist.")
+    end
+  end
+
+  # Raised if a {Panel} could not be rendered as an image.
+  #
+  # Most likely this happens, because the image renderer is not configures properly in grafana,
+  # or the panel rendering ran into a timeout.
+  class ImageCouldNotBeRenderedError < GrafanaError
+    # @param panel [Panel] panel object, which could not be rendered
+    def initialize(panel)
+      super("The specified panel '#{panel.id}' from dashboard '#{panel.dashboard.id} could not be rendered to an image.")
+    end
+  end
+
+  # Raised if no SQL query is specified in a {AbstractSqlQuery} object.
+  class MissingSqlQueryError < GrafanaError
+    def initialize
+      super('No SQL statement has been specified.')
+    end
+  end
+end

data/lib/grafana/grafana.rb

@@ -0,0 +1,131 @@
+# Contains all objects for creating structured objects for interfacing grafana.
+#
+# The intention is, that these represent the business logic contained within grafana in an appropriate object model for the reporter to work with.
+#
+# For details, see also {https://grafana.com/docs/grafana/latest/http_api Grafana API}.
+module Grafana
+  # Main class for handling the interaction with one specific Grafana instance.
+  class Grafana
+    # @param base_uri [String] full URI pointing to the specific grafana instance without trailing slash, e.g. +https://localhost:3000+.
+    # @param key [String] API key for the grafana instance, if required
+    # @param opts [Hash] additional options.
+    #   Currently supporting +:logger+ and +:datasources+.
+    #   +:datasources+ need to be an Hash with datasource name as key and datasource id as value.
+    #   If not specified, the datasources will be queried from the grafana interface.
+    #   Specifying +:datasources+> here can be used, so that the interface can be used without grafana Admin privileges.
+    def initialize(base_uri, key = nil, opts = {})
+      @base_uri = base_uri
+      @key = key
+      @dashboards = {}
+      @logger = opts[:logger] || ::Logger.new(nil)
+      @datasources = opts[:datasources]
+    end
+
+    # Used to test a connection to the grafana instance.
+    #
+    # Running this function also determines, if the API configured here has Admin or NON-Admin privileges,
+    # or even fails on connecting to grafana.
+    #
+    # @return [String] +Admin+, +NON-Admin+ or +Failed+ is returned, depending on the test results
+    def test_connection
+      res = execute_http_request('/api/datasources')
+      if res.is_a?(Net::HTTPOK)
+        # we have admin rights
+        @logger.info('Reporter is running with Admin privileges on grafana.')
+        return 'Admin'
+      else
+        # check if we have lower rights
+        res = execute_http_request('/api/dashboards/home')
+        if res.is_a?(Net::HTTPOK)
+          @logger.warn('Reporter is running with NON-Admin privileges on grafana. Make sure that necessary datasources are specified in CONFIG_FILE, otherwise operation will fail')
+          return 'NON-Admin'
+        end
+      end
+
+      'Failed'
+    end
+
+    # Returns the ID of a datasource, which has been queried by the datasource name.
+    #
+    # @return [Integer] ID for the specified datasource name
+    def datasource_id(datasource_name)
+      id = datasources[datasource_name]
+      raise DatasourceDoesNotExistError.new('name', datasource_name) unless id
+
+      id
+    end
+
+    # Returns if the given datasource ID exists for the grafana instance.
+    #
+    # @return [Boolean] true if exists, false otherwise
+    def datasource_id_exists?(datasource_id)
+      datasources.value?(datasource_id)
+    end
+
+    # @param dashboard_uid [String] UID of the searched {Dashboard}
+    # @return [Dashboard] dashboard object, if it has been found
+    def dashboard(dashboard_uid)
+      return @dashboards[dashboard_uid] unless @dashboards[dashboard_uid].nil?
+
+      response = execute_http_request('/api/dashboards/uid/' + dashboard_uid)
+      model = JSON.parse(response.body)['dashboard']
+
+      raise DashboardDoesNotExistError, dashboard_uid if model.nil?
+
+      # cache dashboard for reuse
+      @dashboards[dashboard_uid] = Dashboard.new(model, self)
+
+      @dashboards[dashboard_uid]
+    end
+
+    # Runs a specific HTTP request against the current grafana instance.
+    #
+    # Default (can be overridden, by specifying the options Hash):
+    #   accept: 'application/json'
+    #   request: Net::HTTP::Get
+    #   content_type: 'application/json'
+    #
+    # @param relative_uri [String] relative URL with a leading slash, which shall be queried
+    # @param options [Hash] options, which shall be merged to the request.
+    # @param timeout [Integer] number of seconds to wait, before the http request is cancelled, defaults to 60 seconds
+    def execute_http_request(relative_uri, options = {}, timeout = nil)
+      uri = URI.parse(@base_uri + relative_uri)
+      default_options = { accept: 'application/json', request: Net::HTTP::Get, content_type: 'application/json' }
+      options = default_options.merge(options)
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      if @base_uri =~ /^https/
+        http.use_ssl = true
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+      end
+      http.read_timeout = timeout.to_i if timeout
+
+      request = options[:request].new(uri.request_uri)
+      request['Accept'] = options[:accept]
+      request['Content-Type'] = options[:content_type]
+      request['Authorization'] = 'Bearer ' + @key unless @key.nil?
+      request.body = options[:body]
+
+      @logger.debug("Requesting #{relative_uri} with '#{options[:body]}' and timeout '#{http.read_timeout}'")
+      resp = http.request(request)
+      resp
+    end
+
+    private
+
+    def datasources
+      if @datasources.nil?
+        # load datasources from grafana directly, if allowed
+        response = execute_http_request('/api/datasources')
+        if response['message'].nil?
+          json = JSON.parse(response.body)
+          # only store needed values
+          @datasources = json.map { |item| [item['name'], item['id']] }.to_h
+        else
+          @datasources = {}
+        end
+      end
+      @datasources
+    end
+  end
+end

data/lib/grafana/panel.rb

@@ -0,0 +1,39 @@
+module Grafana
+  # Representation of one specific panel in a {Dashboard} instance.
+  class Panel
+    # @return [Dashboard] parent {Dashboard} object
+    attr_reader :dashboard
+
+    # @param model [Hash] converted JSON Hash of the panel
+    # @param dashboard [Dashboard] parent {Dashboard} object
+    def initialize(model, dashboard)
+      @model = model
+      @dashboard = dashboard
+    end
+
+    # @return [String] content of the requested field or +''+ if not found
+    def field(field)
+      return @model[field] if @model.key?(field)
+
+      ''
+    end
+
+    # @return [String] panel ID
+    def id
+      @model['id']
+    end
+
+    # @return [String] SQL query string for the requested query letter
+    def query(query_letter)
+      query_item = @model['targets'].select { |item| item['refId'].to_s == query_letter.to_s }.first
+      raise QueryLetterDoesNotExistError.new(query_letter, self) if query_item.nil?
+
+      query_item['rawSql']
+    end
+
+    # @return [String] relative rendering URL for the panel, to create an image out of it
+    def render_url
+      "/render/d-solo/#{@dashboard.id}?panelId=#{@model['id']}"
+    end
+  end
+end

data/lib/grafana/panel_image_query.rb

@@ -0,0 +1,49 @@
+module Grafana
+  # Query, which allows to render a {Panel} as a PNG image.
+  class PanelImageQuery < AbstractPanelQuery
+    # Returns the URL for rendering the panel. Uses {Panel#render_url} and sets additional url parameters according {https://grafana.com/docs/grafana/latest/reference/share_panel Grafana Share Panel}.
+    #
+    # @see AbstractQuery#url
+    # @return [String] string for rendering the panel
+    def url
+      @panel.render_url + url_parameters
+    end
+
+    # Changes the result of the request to be of type +image/png+.
+    #
+    # @see AbstractQuery#request
+    def request
+      { accept: 'image/png' }
+    end
+
+    # Adds default variables for querying the image.
+    #
+    # @see AbstractQuery#pre_process
+    def pre_process(_grafana)
+      @variables['fullscreen'] = Variable.new(true)
+      @variables['theme'] = Variable.new('light')
+      @variables['timeout'] = Variable.new(timeout) if timeout
+      @variables['timeout'] ||= Variable.new(60)
+    end
+
+    # Checks if the rendering has been performed properly.
+    # If so, the resulting image is stored in the @result variable, otherwise an error is raised.
+    #
+    # @see AbstractQuery#post_process
+    def post_process
+      raise ImageCouldNotBeRenderedError, @panel if @result.body.include?('<html')
+    end
+
+    private
+
+    def url_parameters
+      url_vars = variables.select { |k, _v| k =~ /^(?:timeout|height|width|theme|fullscreen)/ || k =~ /^var-.+/ }
+      url_vars['from'] = Variable.new(@from) if @from
+      url_vars['to'] = Variable.new(@to) if @to
+      url_params = URI.encode_www_form(url_vars.map { |k, v| [k, v.raw_value.to_s] })
+      return '' if url_params.empty?
+
+      '&' + url_params
+    end
+  end
+end

data/lib/grafana/variable.rb

@@ -0,0 +1,259 @@
+module Grafana
+  # This class contains a representation of
+  # {https://grafana.com/docs/grafana/latest/variables/templates-and-variables grafana variables},
+  # aka grafana templates.
+  #
+  # The main need therefore rises in order to replace variables properly in different
+  # texts, e.g. SQL statements or results.
+  class Variable
+    attr_reader :name, :text, :raw_value
+
+    # @param config_or_value [Hash, Object] configuration hash of a variable out of an {Dashboard} instance or a value of any kind.
+    def initialize(config_or_value)
+      if config_or_value.is_a? Hash
+        @config = config_or_value
+        @name = @config['name']
+        unless @config['current'].nil?
+          @raw_value = @config['current']['value']
+          @text = @config['current']['text']
+        end
+      else
+        @config = {}
+        @raw_value = config_or_value
+        @text = config_or_value.to_s
+      end
+    end
+
+    # Returns the stored value formatted according the given format.
+    #
+    # Supported formats are: +csv+, +distributed+, +doublequote+, +json+, +percentencode+, +pipe+, +raw+, +regex+, +singlequote+, +sqlstring+, +lucene+, +date+ or +glob+ (default)
+    #
+    # For details see {https://grafana.com/docs/grafana/latest/variables/advanced-variable-format-options Grafana Advanced variable format options}.
+    #
+    # For details of +date+ format, see {https://grafana.com/docs/grafana/latest/variables/variable-types/global-variables/#__from-and-__to}. Please note that input for +date+ format is unixtime in milliseconds.
+    #
+    # @param format [String] desired format
+    # @return [String] value of stored variable according the specified format
+    def value_formatted(format = '')
+      value = @raw_value
+
+      # handle value 'All' properly
+      # TODO fix check for selection of All properly
+      if value == 'All' or @text == 'All'
+        if !@config['options'].empty?
+          value = @config['options'].map { |item| item['value'] }
+        elsif !@config['query'].empty?
+          # TODO: replace variables in this query, too
+          return @config['query']
+          # TODO handle 'All' value properly for query attributes
+        else
+          # TODO how to handle All selection properly at this point?
+        end
+      end
+
+      case format
+      when 'csv'
+        return value.join(',').to_s if multi?
+
+        value.to_s
+
+      when 'distributed'
+        return value.join(",#{name}=") if multi?
+
+        value
+      when 'doublequote'
+        if multi?
+          value = value.map { |item| "\"#{item.gsub(/[\\]/, '\\\\').gsub(/"/, '\\"')}\"" }
+          return value.join(',')
+        end
+        "\"#{value.gsub(/"/, '\\"')}\""
+
+      when 'json'
+        if multi?
+          value = value.map { |item| "\"#{item.gsub(/["\\]/, '\\\\' + '\0')}\"" }
+          return "[#{value.join(',')}]"
+        end
+        "\"#{value.gsub(/"/, '\\"')}\""
+
+      when 'percentencode'
+        value = "{#{value.join(',')}}" if multi?
+        ERB::Util.url_encode(value)
+
+      when 'pipe'
+        return value.join('|') if multi?
+
+        value
+
+      when 'raw'
+        return "{#{value.join(',')}}" if multi?
+
+        value
+
+      when 'regex'
+        if multi?
+          value = value.map { |item| item.gsub(%r{[/$\.\|\\]}, '\\\\' + '\0') }
+          return "(#{value.join('|')})"
+        end
+        value.gsub(%r{[/$\.\|\\]}, '\\\\' + '\0')
+
+      when 'singlequote'
+        if multi?
+          value = value.map { |item| "'#{item.gsub(/[']/, '\\\\' + '\0')}'" }
+          return value.join(',')
+        end
+        "'#{value.gsub(/[']/, '\\\\' + '\0')}'"
+
+      when 'sqlstring'
+        if multi?
+          value = value.map { |item| "'#{item.gsub(/'/, "''")}'" }
+          return value.join(',')
+        end
+        "'#{value.gsub(/'/, "''")}'"
+
+      when 'lucene'
+        if multi?
+          value = value.map { |item| "\"#{item.gsub(%r{[" |=/\\]}, '\\\\' + '\0')}\"" }
+          return "(#{value.join(' OR ')})"
+        end
+        value.gsub(%r{[" |=/\\]}, '\\\\' + '\0')
+
+      when /^date(?:[:](?<format>.*))?$/
+        #TODO validate how grafana handles multivariables with date format
+        get_date_formatted(value, $1)
+
+      when ''
+        # default
+        if multi?
+          value = value.map { |item| "'#{item.gsub(/'/, "''")}'" }
+          return value.join(',')
+        end
+        value.gsub(/'/, "''")
+
+      else
+        # glob and all unknown
+	#TODO add check for array value properly for all cases
+        return "{#{value.join(',')}}" if multi? and value.is_a?(Array)
+
+        value
+      end
+    end
+
+    # @return [Boolean] true, if the value can contain multiple selections, i.e. is an Array
+    def multi?
+      return @config['multi'] unless @config['multi'].nil?
+
+      @raw_value.is_a? Array
+    end
+
+    # @return [Object] raw value of the variable
+    def raw_value=(new_val)
+      @raw_value = new_val
+      @raw_value = @raw_value.to_s unless @raw_value.is_a?(Array)
+      new_text = @raw_value
+      if @config['options']
+        val = @config['options'].select { |item| item['value'] == @raw_value }
+        new_text = val.first['text'] unless val.empty?
+      end
+      @text = new_text
+    end
+
+    private
+
+    # Realize time formatting according
+    # {https://grafana.com/docs/grafana/latest/variables/variable-types/global-variables/#__from-and-__to}
+    # and {https://momentjs.com/docs/#/displaying/}.
+    def get_date_formatted(value, format)
+      return (Float(value) / 1000).to_i.to_s if format == 'seconds'
+      return Time.at((Float(value) / 1000).to_i).utc.iso8601(3) if !format or format == 'iso'
+
+      # build array of known matches
+      matches = []
+      work_string = format
+      while work_string.length > 0
+        tmp = work_string.scan(/^(?:M{1,4}|D{1,4}|d{1,4}|e|E|w{1,2}|W{1,2}|Y{4}|Y{2}|A|a|H{1,2}|h{1,2}|k{1,2}|m{1,2}|s{1,2}|S+|X)/)
+        unless tmp.empty?
+          matches << tmp[0]
+          work_string.delete_prefix!(tmp[0])
+        else
+          matches << work_string[0]
+          work_string.delete_prefix!(work_string[0])
+        end
+      end
+
+      #TODO move case when to hash
+      format_string = ""
+      matches.each do |match|
+        format_string += case match
+          when 'M'
+            '%-m'
+          when 'MM'
+            '%m'
+          when 'MMM'
+            '%b'
+          when 'MMMM'
+            '%B'
+          when 'D'
+            '%-d'
+          when 'DD'
+            '%d'
+          when 'DDD'
+            '%-j'
+          when 'DDDD'
+            '%j'
+          when 'YY'
+            '%y'
+          when 'YYYY'
+            '%Y'
+          when 'd'
+            '%w'
+          when 'ddd'
+            '%a'
+          when 'dddd'
+            '%A'
+          when 'e'
+            '%w'
+          when 'E'
+            '%u'
+          when 'w'
+            '%-U'
+          when 'ww'
+            '%U'
+          when 'W'
+            '%-V'
+          when 'WW'
+            '%V'
+          when 'YY'
+            '%y'
+          when 'YYYY'
+            '%Y'
+          when 'A'
+            '%p'
+          when 'a'
+            '%P'
+          when 'H'
+            '%-H'
+          when 'HH'
+            '%H'
+          when 'h'
+            '%-I'
+          when 'hh'
+            '%I'
+          when 'm'
+            '%-M'
+          when 'mm'
+            '%M'
+          when 's'
+            '%-S'
+          when 'ss'
+            '%S'
+          when 'X'
+            '%s'
+          else
+            match
+          end
+      end
+
+      Time.at((Float(value) / 1000).to_i).strftime(format_string)
+    end
+  end
+end