ruby-grafana-reporter 0.2.0 → 0.4.1

data/lib/grafana_reporter/asciidoctor/show_environment_include_processor.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module GrafanaReporter
+  module Asciidoctor
+    # Implements the hook
+    #   include::grafana_environment[]
+    #
+    # Shows all available variables, which are accessible during this run of the asciidoctor
+    # grafana reporter in a asciidoctor readable form.
+    #
+    # This processor is very helpful during report template design, to find out the available
+    # variables, that can be accessed.
+    #
+    # == Used document parameters
+    # All, to be listed as the available environment.
+    class ShowEnvironmentIncludeProcessor < ::Asciidoctor::Extensions::IncludeProcessor
+      include ProcessorMixin
+
+      # :nodoc:
+      def handles?(target)
+        target.start_with? 'grafana_environment'
+      end
+
+      # :nodoc:
+      def process(doc, reader, _target, _attrs)
+        # return if @report.cancel
+        @report.next_step
+        @report.logger.debug('Processing ShowEnvironmentIncludeProcessor')
+
+        vars = ['== Accessible Variables',
+                '|===']
+        doc.attributes.sort.each do |k, v|
+          vars << "| `+{#{k}}+` | #{v}"
+        end
+        vars << '|==='
+
+        reader.unshift_lines vars
+      end
+
+      # @see ProcessorMixin#build_demo_entry
+      def build_demo_entry(_panel)
+        'include::grafana_environment[]'
+      end
+    end
+  end
+end

data/lib/grafana_reporter/asciidoctor/show_help_include_processor.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module GrafanaReporter
+  module Asciidoctor
+    # Implements the hook
+    #   include::grafana_help[]
+    #
+    # Shows all available options for the asciidoctor grafana reporter in a asciidoctor readable form.
+    #
+    # == Used document parameters
+    # None
+    class ShowHelpIncludeProcessor < ::Asciidoctor::Extensions::IncludeProcessor
+      include ProcessorMixin
+
+      # :nodoc:
+      def handles?(target)
+        target.start_with? 'grafana_help'
+      end
+
+      # :nodoc:
+      def process(_doc, reader, _target, _attrs)
+        # return if @report.cancel
+        @report.next_step
+        @report.logger.debug('Processing ShowHelpIncludeProcessor')
+
+        reader.unshift_lines GrafanaReporter::Help.new.asciidoctor.split("\n")
+      end
+
+      # @see ProcessorMixin#build_demo_entry
+      def build_demo_entry(_panel)
+        'include::grafana_help[]'
+      end
+    end
+  end
+end

data/lib/grafana_reporter/asciidoctor/sql_table_include_processor.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module GrafanaReporter
+  module Asciidoctor
+    # Implements the hook
+    #   include::grafana_sql_table:<datasource_id>[<options>]
+    #
+    # Returns the results of the SQL query as a asciidoctor table.
+    #
+    # == Used document parameters
+    # +grafana_default_instance+ - name of grafana instance, 'default' if not specified
+    #
+    # +from+ - 'from' time for the sql query
+    #
+    # +to+ - 'to' time for the sql query
+    #
+    # All other variables starting with +var-+ will be used to replace grafana templating strings
+    # in the given SQL query.
+    #
+    # == Supported options
+    # +sql+ - sql statement (*mandatory*)
+    #
+    # +instance+ - name of grafana instance, 'default' if not specified
+    #
+    # +from+ - 'from' time for the sql query
+    #
+    # +to+ - 'to' time for the sql query
+    #
+    # +format+ - see {AbstractQuery#format_columns}
+    #
+    # +replace_values+ - see {AbstractQuery#replace_values}
+    #
+    # +filter_columns+ - see {AbstractQuery#filter_columns}
+    class SqlTableIncludeProcessor < ::Asciidoctor::Extensions::IncludeProcessor
+      include ProcessorMixin
+
+      # :nodoc:
+      def handles?(target)
+        target.start_with? 'grafana_sql_table:'
+      end
+
+      # :nodoc:
+      def process(doc, reader, target, attrs)
+        return if @report.cancel
+
+        @report.next_step
+        instance = attrs['instance'] || doc.attr('grafana_default_instance') || 'default'
+        attrs['result_type'] = 'sql_table'
+        @report.logger.debug("Processing SqlTableIncludeProcessor (instance: #{instance},"\
+                             " datasource: #{target.split(':')[1]}, sql: #{attrs['sql']})")
+
+        begin
+          # catch properly if datasource could not be identified
+          query = QueryValueQuery.new(@report.grafana(instance))
+          query.datasource = @report.grafana(instance).datasource_by_id(target.split(':')[1].to_i)
+          query.raw_query = attrs['sql']
+          assign_doc_and_item_variables(query, doc.attributes, attrs)
+          @report.logger.debug("from: #{query.from}, to: #{query.to}")
+
+          reader.unshift_lines query.execute
+        rescue GrafanaReporterError => e
+          @report.logger.error(e.message)
+          reader.unshift_line "|#{e.message}"
+        rescue StandardError => e
+          @report.logger.fatal(e.message)
+          reader.unshift_line "|#{e.message}"
+        end
+
+        reader
+      end
+
+      # @see ProcessorMixin#build_demo_entry
+      def build_demo_entry(panel)
+        return nil unless panel
+        return nil unless panel.model['type'].include?('table')
+
+        ref_id = nil
+        panel.model['targets'].each do |item|
+          if !item['hide'] && !panel.query(item['refId']).to_s.empty?
+            ref_id = item['refId']
+            break
+          end
+        end
+        return nil unless ref_id
+
+        "|===\ninclude::grafana_sql_table:#{panel.dashboard.grafana.datasource_by_name(panel.model['datasource']).id}"\
+        "[sql=\"#{panel.query(ref_id).gsub(/"/, '\"').gsub("\n", ' ').gsub(/\\/, '\\\\')}\",filter_columns=\"time\","\
+        "dashboard=\"#{panel.dashboard.id}\",from=\"now-1h\",to=\"now\"]\n|==="
+      end
+    end
+  end
+end

data/lib/grafana_reporter/asciidoctor/sql_value_inline_macro.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module GrafanaReporter
+  module Asciidoctor
+    # Implements the hook
+    #   grafana_sql_value:<datasource_id>[<options>]
+    #
+    # Returns the first value of the resulting SQL query.
+    #
+    # == Used document parameters
+    # +grafana_default_instance+ - name of grafana instance, 'default' if not specified
+    #
+    # +from+ - 'from' time for the sql query
+    #
+    # +to+ - 'to' time for the sql query
+    #
+    # All other variables starting with +var-+ will be used to replace grafana templating strings
+    # in the given SQL query.
+    #
+    # == Supported options
+    # +sql+ - sql statement (*mandatory*)
+    #
+    # +instance+ - name of grafana instance, 'default' if not specified
+    #
+    # +from+ - 'from' time for the sql query
+    #
+    # +to+ - 'to' time for the sql query
+    #
+    # +format+ - see {AbstractQuery#format_columns}
+    #
+    # +replace_values+ - see {AbstractQuery#replace_values}
+    #
+    # +filter_columns+ - see {AbstractQuery#filter_columns}
+    class SqlValueInlineMacro < ::Asciidoctor::Extensions::InlineMacroProcessor
+      include ProcessorMixin
+      use_dsl
+
+      named :grafana_sql_value
+
+      # @see GrafanaReporter::Asciidoctor::SqlFirstValueQuery
+      def process(parent, target, attrs)
+        return if @report.cancel
+
+        @report.next_step
+        instance = attrs['instance'] || parent.document.attr('grafana_default_instance') || 'default'
+        attrs['result_type'] = 'sql_value'
+        @report.logger.debug("Processing SqlValueInlineMacro (instance: #{instance}, datasource: #{target},"\
+                             " sql: #{attrs['sql']})")
+
+        begin
+          # catch properly if datasource could not be identified
+          query = QueryValueQuery.new(@report.grafana(instance))
+          query.datasource = @report.grafana(instance).datasource_by_id(target)
+          query.raw_query = attrs['sql']
+          assign_doc_and_item_variables(query, parent.document.attributes, attrs)
+          @report.logger.debug("from: #{query.from}, to: #{query.to}")
+
+          create_inline(parent, :quoted, query.execute)
+        rescue GrafanaReporterError => e
+          @report.logger.error(e.message)
+          create_inline(parent, :quoted, e.message)
+        rescue StandardError => e
+          @report.logger.fatal(e.message)
+          create_inline(parent, :quoted, e.message)
+        end
+      end
+
+      # @see ProcessorMixin#build_demo_entry
+      def build_demo_entry(panel)
+        return nil unless panel
+        return nil unless panel.model['type'] == 'singlestat'
+
+        ref_id = nil
+        panel.model['targets'].each do |item|
+          if !item['hide'] && !panel.query(item['refId']).to_s.empty?
+            ref_id = item['refId']
+            break
+          end
+        end
+        return nil unless ref_id
+
+        "grafana_sql_value:#{panel.dashboard.grafana.datasource_by_name(panel.model['datasource']).id}"\
+        "[sql=\"#{panel.query(ref_id).gsub(/"/, '\"').gsub("\n", ' ').gsub(/\\/, '\\\\')}\",from=\"now-1h\","\
+        'to="now"]'
+      end
+    end
+  end
+end

data/lib/grafana_reporter/asciidoctor/value_as_variable_include_processor.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative 'processor_mixin'
+
+module GrafanaReporter
+  module Asciidoctor
+    # Implements the hook
+    #   include::grafana_value_as_variable[<options>]
+    #
+    # Returns an attribute definition in asciidoctor format. This is needed if you want to refer to values of
+    # a grafana query within a variable in asciidoctor. As this works without this function for the
+    # `IncludeProcessor`s values, it will not work for all the other processors.
+    #
+    # This method is just a proxy for all other hooks and will forward parameters accordingly.
+    #
+    # Example:
+    #
+    #   include:grafana_value_as_variable[call="grafana_sql_value:1",variable_name="my_variable",sql="SELECT 'looks good'",<any_other_option>]
+    #
+    # This will call the {SqlValueInlineMacro} with `datasource_id` set to `1` and store the result in the
+    # variable. The resulting asciidoctor variable definition will be created as:
+    #
+    #   :my_variable: looks good
+    #
+    # and can be refered to in your document easily as
+    #
+    #   {my_variable}
+    #
+    # == Supported options
+    # +call+ - regular call to the reporter hook (*mandatory*)
+    #
+    # +variable_name+ - name of the variable, to which the result shall be assigned (*mandatory*)
+    class ValueAsVariableIncludeProcessor < ::Asciidoctor::Extensions::IncludeProcessor
+      include ProcessorMixin
+
+      # :nodoc:
+      def handles?(target)
+        target.start_with? 'grafana_value_as_variable'
+      end
+
+      # :nodoc:
+      def process(doc, reader, target, attrs)
+        return if @report.cancel
+
+        # increase step for this processor as well as it is also counted in the step counter
+        @report.next_step
+
+        call_attr = attrs.delete('call')
+        call, target = call_attr.split(':') if call_attr
+        attribute = attrs.delete('variable_name')
+        @report.logger.debug("Processing ValueAsVariableIncludeProcessor (call: #{call}, target: #{target},"\
+                             " variable_name: #{attribute}, attrs: #{attrs})")
+        if !call || !attribute
+          @report.logger.error('ValueAsVariableIncludeProcessor: Missing mandatory attribute \'call\' or '\
+                               '\'variable_name\'.')
+          # increase counter, as error occured and no sub call is being processed
+          @report.next_step
+          return reader
+        end
+
+        # TODO: remove dirty hack to allow the document as parameter for other processors
+        def doc.document
+          self
+        end
+
+        # TODO: properly show error messages also in document
+        ext = doc.extensions.find_inline_macro_extension(call) if doc.extensions.inline_macros?
+        if !ext
+          @report.logger.error('ValueAsVariableIncludeProcessor: Could not find inline macro extension for '\
+                               "'#{call}'.")
+          # increase counter, as error occured and no sub call is being processed
+          @report.next_step
+        else
+          @report.logger.debug('ValueAsVariableIncludeProcessor: Calling sub-method.')
+          item = ext.process_method.call(doc, target, attrs)
+          if !item.text.to_s.empty?
+            result = ":#{attribute}: #{item.text}"
+            @report.logger.debug("ValueAsVariableIncludeProcessor: Adding '#{result}' to document.")
+            reader.unshift_line(result)
+          else
+            @report.logger.debug("ValueAsVariableIncludeProcessor: Not adding variable '#{attribute}'"\
+                                 ' as query result was empty.')
+          end
+        end
+
+        reader
+      end
+    end
+  end
+end

data/lib/grafana_reporter/configuration.rb

@@ -13,6 +13,10 @@ module GrafanaReporter
   class Configuration
     # @return [AbstractReport] specific report class, which should be used.
     attr_accessor :report_class
+    attr_accessor :logger
+
+    # Default file name for grafana reporter configuration file
+    DEFAULT_CONFIG_FILE_NAME = 'grafana_reporter.config'
 
     # Returned by {#mode} if only a connection test shall be executed.
     MODE_CONNECTION_TEST = 'test'
@@ -23,18 +27,28 @@ module GrafanaReporter
 
     # Used to access the configuration hash. To make sure, that the configuration is
     # valid, call {#validate}.
-    #
-    # NOTE: This function overwrites all existing configurations
-    attr_accessor :config
+    attr_reader :config
 
     def initialize
       @config = {}
-      @logger = ::Logger.new($stderr, level: :unknown)
-      # TODO: set report class somewhere else, but make it known here
-      self.report_class = Asciidoctor::Report
+      @logger = ::Logger.new($stderr, level: :info)
     end
 
-    attr_accessor :logger
+    # Reads a given configuration file.
+    # @param config_file [String] path to configuration file, defaults to DEFAULT_CONFIG_FILE_NAME
+    # @return [Hash] configuration hash to be set as {Configuration#config}
+    def load_config_from_file(config_file = nil)
+      config_file ||= DEFAULT_CONFIG_FILE_NAME
+      self.config = YAML.load_file(config_file)
+    rescue StandardError => e
+      raise ConfigurationError, "Could not read config file '#{config_file}' (Error: #{e.message})"
+    end
+
+    # Used to overwrite the current configuration.
+    def config=(new_config)
+      @config = new_config
+      update_configuration
+    end
 
     # @return [String] mode, in which the reporting shall be executed. One of {MODE_CONNECTION_TEST},
     #   {MODE_SINGLE_RENDER} and {MODE_SERVICE}.
@@ -50,7 +64,8 @@ module GrafanaReporter
     # @return [String] full path of configured report template. Only needed in {MODE_SINGLE_RENDER}.
     def template
       return nil if get_config('default-document-attributes:var-template').nil?
-      "#{templates_folder}#{get_config('default-document-attributes:var-template')}.adoc"
+
+      "#{templates_folder}#{get_config('default-document-attributes:var-template')}"
     end
 
     # @return [String] destination filename for the report in {MODE_SINGLE_RENDER}.
@@ -81,16 +96,6 @@ module GrafanaReporter
       get_config("grafana:#{instance}:api_key")
     end
 
-    # @param instance [String] grafana instance name, for which the value shall be retrieved.
-    # @return [Hash<String,Integer>] configured datasources for the requested grafana instance. Name as key,
-    #   ID as value.
-    def grafana_datasources(instance = 'default')
-      hash = get_config("grafana:#{instance}:datasources")
-      return nil if hash.nil?
-
-      hash.map { |k, v| [k, v] }.to_h
-    end
-
     # @return [String] configured folder, in which the report templates are stored including trailing slash.
     #   By default: current folder.
     def templates_folder
@@ -150,9 +155,11 @@ module GrafanaReporter
     # This function shall be called, before the configuration object is used in the
     # {Application::Application#run}. It ensures, that everything is setup properly
     # and all necessary folders exist. Appropriate errors are raised in case of errors.
+    # @param explicit [Boolean] true, if validation shall expect explicit (wizard) configuration file
     # @return [void]
-    def validate
-      validate_schema(schema, @config)
+    def validate(explicit = false)
+      check_deprecation
+      validate_schema(schema(explicit), @config)
 
       # check if set folders exist
       raise FolderDoesNotExistError.new(reports_folder, 'reports-folder') unless File.directory?(reports_folder)
@@ -160,8 +167,66 @@ module GrafanaReporter
       raise FolderDoesNotExistError.new(images_folder, 'images-folder') unless File.directory?(images_folder)
     end
 
+    # Can be used to configure or overwrite single parameters.
+    #
+    # @param path [String] path of the paramter to set, e.g. +grafana-reporter:webservice-port+
+    # @param value [Object] value to set
+    def set_param(path, value)
+      return if path.nil?
+
+      levels = path.split(':')
+      last_level = levels.pop
+
+      cur_pos = @config
+      levels.each do |subpath|
+        cur_pos[subpath] = {} unless cur_pos[subpath]
+        cur_pos = cur_pos[subpath]
+      end
+
+      cur_pos[last_level] = value
+      update_configuration
+    end
+
+    # Merge the given configuration object settings with the current config, i.e. overwrite and add all
+    # settings from the given config, but keep the not specified configs from the current object.
+    #
+    # param other_config [Configuration] other configuration object
+    def merge!(other_config)
+      config.merge!(other_config.config) { |_key, v1, v2| v1.is_a?(Hash) && v2.is_a?(Hash) ? v1.merge(v2) : v2 }
+      update_configuration
+    end
+
     private
 
+    def check_deprecation
+      return if report_class
+
+      logger.warn('DEPRECATION WARNING: Your configuration explicitly needs to specify the '\
+                  '\'grafana-reporter:report-class\' value.  Currently this defaults to '\
+                  '\'GrafanaReporter::Asciidoctor::Report\'. You can get rid of this warning, if you '\
+                  'explicitly set this configuration in your configuration file. Setting this default will be '\
+                  'removed in a future version.')
+      set_param('grafana-reporter:report-class', 'GrafanaReporter::Asciidoctor::Report')
+    end
+
+    def update_configuration
+      debug_level = get_config('grafana-reporter:debug-level')
+      rep_class = get_config('grafana-reporter:report-class')
+
+      @logger.level = Object.const_get("::Logger::Severity::#{debug_level}") if debug_level =~ /DEBUG|INFO|WARN|
+                                                                                                ERROR|FATAL|UNKNOWN/x
+      self.report_class = Object.const_get(rep_class) if rep_class
+      ::Grafana::WebRequest.ssl_cert = get_config('grafana-reporter:ssl-cert')
+
+      # register callbacks
+      callbacks = get_config('grafana-reporter:callbacks')
+      return unless callbacks
+
+      callbacks.each do |url, event|
+        AbstractReport.add_event_listener(event.to_sym, ReportWebhook.new(url))
+      end
+    end
+
     def get_config(path)
       return if path.nil?
 
@@ -182,20 +247,16 @@ module GrafanaReporter
 
         if key.nil?
           # apply to all on this level
-          case
-          when subject.is_a?(Hash)
-            if subject.length < min_occurence
-              raise ConfigurationDoesNotMatchSchemaError.new(key, 'occur', min_occurence, subject.length)
-            end
-
-            subject.each do |k, _v|
-              sub_scheme = {}
-              sub_scheme[k] = schema[nil]
-              validate_schema(sub_scheme, subject)
-            end
-
-          else
-            raise ConfigurationError, "Unhandled configuration data type '#{subject.class}'."
+          raise ConfigurationError, "Unhandled configuration data type '#{subject.class}'." unless subject.is_a?(Hash)
+
+          if subject.length < min_occurence
+            raise ConfigurationDoesNotMatchSchemaError.new(key, 'occur', min_occurence, subject.length)
+          end
+
+          subject.each do |k, _v|
+            sub_scheme = {}
+            sub_scheme[k] = schema[nil]
+            validate_schema(sub_scheme, subject)
           end
 
         # apply to single item
@@ -221,7 +282,7 @@ module GrafanaReporter
       end
     end
 
-    def schema
+    def schema(explicit)
       {
         'grafana' =>
          [
@@ -232,23 +293,27 @@ module GrafanaReporter
                 Hash, 1,
                 {
                   'host' => [String, 1],
-                  'api_key' => [String, 0],
-                  'datasources' => [Hash, 0, { nil => [Integer, 1] }]
+                  'api_key' => [String, 0]
                 }
               ]
            }
          ],
-        'default-document-attributes' => [Hash, 0],
+        'default-document-attributes' => [Hash, explicit ? 1 : 0],
+        'to_file' => [String, 0],
         'grafana-reporter' =>
         [
-          Hash, 0,
+          Hash, 1,
           {
+            'debug-level' => [String, 0],
             'run-mode' => [String, 0],
             'test-instance' => [String, 0],
-            'templates-folder' => [String, 0],
-            'reports-folder' => [String, 0],
-            'report-retention' => [Integer, 0],
-            'webservice-port' => [Integer, 0]
+            'templates-folder' => [String, explicit ? 1 : 0],
+            'report-class' => [String, 1],
+            'reports-folder' => [String, explicit ? 1 : 0],
+            'report-retention' => [Integer, explicit ? 1 : 0],
+            'ssl-cert' => [String, 0],
+            'webservice-port' => [Integer, explicit ? 1 : 0],
+            'callbacks' => [Hash, 0, { nil => [String, 1] }]
           }
         ]
       }