ruby-grafana-reporter 0.3.0 → 0.4.4

data/bin/ruby-grafana-reporter

@@ -1,5 +1,5 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require_relative '../lib/ruby-grafana-reporter'
-GrafanaReporter::Application::Application.new.configure_and_run(ARGV) unless defined?(Ocra)
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/ruby_grafana_reporter'
+GrafanaReporter::Application::Application.new.configure_and_run(ARGV) unless defined?(Ocra)

data/lib/VERSION.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 # Version information
-GRAFANA_REPORTER_VERSION = [0, 3, 0].freeze
-GRAFANA_REPORTER_RELEASE_DATE = '2021-03-02'
+GRAFANA_REPORTER_VERSION = [0, 4, 4].freeze
+# Release date
+GRAFANA_REPORTER_RELEASE_DATE = '2021-07-12'

data/lib/grafana/abstract_datasource.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Grafana
+  # This abstract class defines the base functionalities for the common datasource implementations.
+  # Additionally it provides a factory method to build a real datasource from a given specification.
+  class AbstractDatasource
+    attr_reader :model
+
+    @@subclasses = []
+
+    # Registers the subclass as datasource.
+    # @param subclass [Class] class inheriting from this abstract class
+    def self.inherited(subclass)
+      @@subclasses << subclass
+    end
+
+    # Overwrite this method, to specify if the current datasource implementation handles the given model.
+    # This method is called by {build_instance} to determine, if the current datasource implementation
+    # can handle the given grafana model. By default this method returns false.
+    # @param model [Hash] grafana specification of the datasource to check
+    # @return [Boolean] True if fits, false otherwise
+    def self.handles?(model)
+      false
+    end
+
+    # Factory method to build a datasource from a given datasource Hash description.
+    # @param ds_model [Hash] grafana specification of a single datasource
+    # @return [AbstractDatasource] instance of a fitting datasource implementation
+    def self.build_instance(ds_model)
+      raise InvalidDatasourceQueryProvidedError, ds_model unless ds_model.is_a?(Hash)
+
+      raise InvalidDatasourceQueryProvidedError, ds_model unless ds_model['meta'].is_a?(Hash)
+
+      @@subclasses.each do |datasource_class|
+        return datasource_class.new(ds_model) if datasource_class.handles?(ds_model)
+      end
+
+      UnsupportedDatasource.new(ds_model)
+    end
+
+    def initialize(model)
+      @model = model
+    end
+
+    # @return [String] category of the datasource, e.g. +tsdb+ or +sql+
+    def category
+      @model['meta']['category']
+    end
+
+    # @return [String] type of the datasource, e.g. +mysql+
+    def type
+      @model['type'] || @model['meta']['id']
+    end
+
+    # @return [String] name of the datasource
+    def name
+      @model['name']
+    end
+
+    # @return [Integer] ID of the datasource
+    def id
+      @model['id'].to_i
+    end
+
+    # @abstract
+    #
+    # Executes a request for the current database with the given options.
+    #
+    # Used format of the response will always be the following:
+    #
+    #   {
+    #     :header => [column_title_1, column_title_2],
+    #     :content => [
+    #                   [row_1_column_1, row_1_column_2],
+    #                   [row_2_column_1, row_2_column_2]
+    #                 ]
+    #   }
+    #
+    # @param query_description [Hash] query description, which will requested:
+    # @option query_description [String] :from +from+ timestamp
+    # @option query_description [String] :to +to+ timestamp
+    # @option query_description [Integer] :timeout expected timeout for the request
+    # @option query_description [WebRequest] :prepared_request prepared web request for relevant {Grafana} instance, if this is needed by datasource
+    # @option query_description [String] :raw_query raw query, which shall be executed. May include variables, which will be replaced before execution
+    # @option query_description [Hash<Variable>] :variables hash of variables, which can potentially be replaced in the given +:raw_query+
+    # @return [Hash] sql result formatted as stated above
+    def request(query_description)
+      raise NotImplementedError
+    end
+
+    # @abstract
+    #
+    # The different datasources supported by grafana use different ways to store the query in the
+    # panel's JSON model. This method extracts a query from that description, that can be used
+    # by the {AbstractDatasource} implementation of the datasource.
+    #
+    # @param panel_query_target [Hash] grafana panel target, which contains the query description
+    # @return [String] query string, which can be used as +raw_query+ in a {#request}
+    def raw_query_from_panel_model(panel_query_target)
+      raise NotImplementedError
+    end
+
+    # @abstract
+    #
+    # Overwrite in subclass, to specify the default variable format during replacement of variables.
+    # @return [String] default {Variable#value_formatted} format
+    def default_variable_format
+      raise NotImplementedError
+    end
+
+    private
+
+    # Replaces the grafana variables in the given string with their replacement value.
+    #
+    # @param string [String] string in which the variables shall be replaced
+    # @param variables [Hash<String,Variable>] Hash containing the variables, which shall be replaced in the
+    #  given string
+    # @return [String] string in which all variables are properly replaced
+    def replace_variables(string, variables = {})
+      res = string
+      repeat = true
+      repeat_count = 0
+
+      # TODO: find a proper way to replace variables recursively instead of over and over again
+      # TODO: add tests for recursive replacement of variable
+      while repeat && (repeat_count < 3)
+        repeat = false
+        repeat_count += 1
+
+        variables.each do |name, variable|
+          # only set ticks if value is string
+          var_name = name.gsub(/^var-/, '')
+          next unless var_name =~ /^\w+$/
+
+          res = res.gsub(/(?:\$\{#{var_name}(?::(?<format>\w+))?\}|\$#{var_name}(?!\w))/) do
+            format = default_variable_format
+            if $LAST_MATCH_INFO
+              format = $LAST_MATCH_INFO[:format] if $LAST_MATCH_INFO[:format]
+            end
+            variable.value_formatted(format)
+          end
+        end
+        repeat = true if res.include?('$')
+      end
+
+      res
+    end
+  end
+end

data/lib/grafana/dashboard.rb

@@ -53,9 +53,7 @@ module Grafana
       list = @model['templating']['list']
       return unless list.is_a? Array
 
-      list.each do |item|
-        @variables << Variable.new(item)
-      end
+      list.each { |item| @variables << Variable.new(item) }
     end
 
     # read panels

data/lib/grafana/errors.rb

@@ -37,9 +37,9 @@ module Grafana
 
   # 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 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
+    #   e.g. the specified id or name
     def initialize(field, datasource_identifier)
       super("Datasource with #{field} '#{datasource_identifier}' does not exist.")
     end
@@ -49,18 +49,33 @@ module Grafana
   #
   # Most likely this happens, because the image renderer is not configures properly in grafana,
   # or the panel rendering ran into a timeout.
+  # @param panel [Panel] panel object, which could not be rendered
   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 "\
+      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.
+  # Raised if no SQL query is specified.
   class MissingSqlQueryError < GrafanaError
     def initialize
       super('No SQL statement has been specified.')
     end
   end
+
+  # Raised if a datasource shall be queried, which is not (yet) supported by the reporter
+  class InvalidDatasourceQueryProvidedError < GrafanaError
+    def initialize(query)
+      super("The datasource query provided, does not look like a grafana datasource target (received: #{query}).")
+    end
+  end
+
+  # Raised if a datasource implementation cannot handle a query, which is composed
+  # in the grafana visual editor.
+  class ComposedQueryNotSupportedError < GrafanaError
+    def initialize(class_obj)
+      super("Composed queries are not yet supported for datasource '#{class_obj}'.")
+    end
+  end
 end

data/lib/grafana/grafana.rb

@@ -9,16 +9,17 @@
 module Grafana
   # Main class for handling the interaction with one specific Grafana instance.
   class Grafana
+    attr_reader :logger
+
     # @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 +:ssl_cert+.
+    #   Currently supporting +:logger+.
     def initialize(base_uri, key = nil, opts = {})
       @base_uri = base_uri
       @key = key
       @dashboards = {}
-      @ssl_cert = opts[:ssl_cert]
       @logger = opts[:logger] || ::Logger.new(nil)
 
       initialize_datasources unless @base_uri.empty?
@@ -31,33 +32,54 @@ module Grafana
     #
     # @return [String] +Admin+, +NON-Admin+ or +Failed+ is returned, depending on the test results
     def test_connection
-      if execute_http_request('/api/datasources').is_a?(Net::HTTPOK)
+      if prepare_request({ relative_url: '/api/datasources' }).execute.is_a?(Net::HTTPOK)
         # we have admin rights
         @logger.warn('Reporter is running with Admin privileges on grafana. This is a potential security risk.')
         return 'Admin'
       end
       # check if we have lower rights
-      return 'Failed' unless execute_http_request('/api/dashboards/home').is_a?(Net::HTTPOK)
+      return 'Failed' unless prepare_request({ relative_url: '/api/dashboards/home' }).execute.is_a?(Net::HTTPOK)
 
       @logger.info('Reporter is running with NON-Admin privileges on grafana.')
       'NON-Admin'
     end
 
-    # Returns the ID of a datasource, which has been queried by the datasource name.
+    # Returns the datasource, which has been queried by the datasource name.
     #
-    # @return [Integer] ID for the specified datasource name
-    def datasource_id(datasource_name)
-      datasource_name ||= 'default'
-      return @datasources[datasource_name] if @datasources[datasource_name]
-
-      raise DatasourceDoesNotExistError.new('name', datasource_name)
+    # @param datasource_name [String] name of the searched datasource
+    # @return [Datasource] Datasource for the specified datasource name
+    def datasource_by_name(datasource_name)
+      datasource_name = 'default' if datasource_name.to_s.empty?
+      # TODO: add support for grafana builtin datasource types
+      return UnsupportedDatasource.new(nil) if datasource_name.to_s =~ /-- (?:Mixed|Dashboard|Grafana) --/
+      raise DatasourceDoesNotExistError.new('name', datasource_name) unless @datasources[datasource_name]
+
+      @datasources[datasource_name]
     end
 
-    # Returns if the given datasource ID exists for the grafana instance.
+    # Returns the datasource, which has been queried by the datasource id.
     #
-    # @return [Boolean] true if exists, false otherwise
-    def datasource_id_exists?(datasource_id)
-      @datasources.value?(datasource_id)
+    # @param datasource_id [Integer] id of the searched datasource
+    # @return [Datasource] Datasource for the specified datasource id
+    def datasource_by_id(datasource_id)
+      datasource = @datasources.select { |_name, ds| ds.id == datasource_id.to_i }.values.first
+      raise DatasourceDoesNotExistError.new('id', datasource_id) unless datasource
+
+      datasource
+    end
+
+    # @return [Array] Array of dashboard uids within the current grafana object
+    def dashboard_ids
+      response = prepare_request({ relative_url: '/api/search' }).execute
+      return [] unless response.is_a?(Net::HTTPOK)
+
+      dashboards = JSON.parse(response.body)
+
+      dashboards.each do |dashboard|
+        @dashboards[dashboard['uid']] = nil unless @dashboards[dashboard['uid']]
+      end
+
+      @dashboards.keys
     end
 
     # @param dashboard_uid [String] UID of the searched {Dashboard}
@@ -65,54 +87,27 @@ module Grafana
     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?
+      response = prepare_request({ relative_url: "/api/dashboards/uid/#{dashboard_uid}" }).execute
+      raise DashboardDoesNotExistError, dashboard_uid unless response.is_a?(Net::HTTPOK)
 
       # cache dashboard for reuse
+      model = JSON.parse(response.body)['dashboard']
       @dashboards[dashboard_uid] = Dashboard.new(model, self)
 
       @dashboards[dashboard_uid]
     end
 
-    # Runs a specific HTTP request against the current grafana instance.
+    # Prepares a {WebRequest} object for the current {Grafana} instance, which may be enriched
+    # with further properties and can then run {WebRequest#execute}.
     #
-    # 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
-        if @ssl_cert && !File.exist?(@ssl_cert)
-          @logger.warn('SSL certificate file does not exist.')
-        elsif @ssl_cert
-          http.cert_store = OpenSSL::X509::Store.new
-          http.cert_store.set_default_paths
-          http.cert_store.add_file(@ssl_cert)
-        end
-      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}'")
-      http.request(request)
+    # @option options [Hash] :relative_url relative URL with a leading slash, which shall be queried
+    # @option options [Hash] :accept
+    # @option options [Hash] :body
+    # @option options [Hash] :content_type
+    # @return [WebRequest] webrequest prepared for execution
+    def prepare_request(options = {})
+      auth = @key ? { authorization: "Bearer #{@key}" } : {}
+      WebRequest.new(@base_uri, auth.merge({ logger: @logger }).merge(options))
     end
 
     private
@@ -120,12 +115,12 @@ module Grafana
     def initialize_datasources
       @datasources = {}
 
-      settings = execute_http_request('/api/frontend/settings')
+      settings = prepare_request({ relative_url: '/api/frontend/settings' }).execute
       return unless settings.is_a?(Net::HTTPOK)
 
       json = JSON.parse(settings.body)
       json['datasources'].select { |_k, v| v['id'].to_i.positive? }.each do |ds_name, ds_value|
-        @datasources[ds_name] = ds_value['id'].to_i
+        @datasources[ds_name] = AbstractDatasource.build_instance(ds_value)
       end
       @datasources['default'] = @datasources[json['defaultDatasource']]
     end

data/lib/grafana/grafana_alerts_datasource.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Grafana
+  # Implements the datasource interface to grafana alerts.
+  class GrafanaAlertsDatasource < AbstractDatasource
+    # +:raw_query+ needs to contain a Hash with the following structure:
+    #
+    #   {
+    #     dashboardId: Dashboard ID as String or nil
+    #     panelId:     Panel ID as String or nil
+    #     columns:
+    #     limit:
+    #     query:
+    #     state:
+    #     folderId:
+    #     dashboardQuery:
+    #     dashboardTag:
+    #   }
+    # @see AbstractDatasource#request
+    def request(query_description)
+      webrequest = query_description[:prepared_request]
+      webrequest.relative_url = "/api/alerts#{url_parameters(query_description)}"
+
+      result = webrequest.execute(query_description[:timeout])
+
+      json = JSON.parse(result.body)
+
+      content = []
+      begin
+        json.each { |item| content << item.fetch_values(*query_description[:raw_query]['columns'].split(',')) }
+      rescue KeyError => e
+        raise MalformedAttributeContentError.new(e.message, 'columns', query_description[:raw_query]['columns'])
+      end
+
+      result = {}
+      result[:header] = [query_description[:raw_query]['columns'].split(',')]
+      result[:content] = content
+
+      result
+    end
+
+    private
+
+    def url_parameters(query_desc)
+      url_vars = {}
+      url_vars.merge!(query_desc[:raw_query].select do |k, _v|
+        k =~ /^(?:limit|dashboardId|panelId|query|state|folderId|dashboardQuery|dashboardTag)/
+      end)
+      url_vars['from'] = query_desc[:from] if query_desc[:from]
+      url_vars['to'] = query_desc[:to] if query_desc[:to]
+      url_params = URI.encode_www_form(url_vars.map { |k, v| [k, v.to_s] })
+      return '' if url_params.empty?
+
+      "?#{url_params}"
+    end
+  end
+end