ruby-grafana-reporter 0.1.7 → 0.4.0

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 {QueryMixin#format_columns}
+    #
+    # +replace_values+ - see {QueryMixin#replace_values}
+    #
+    # +filter_columns+ - see {QueryMixin#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']
+          query.merge_hash_variables(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 {QueryMixin#format_columns}
+    #
+    # +replace_values+ - see {QueryMixin#replace_values}
+    #
+    # +filter_columns+ - see {QueryMixin#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']
+          query.merge_hash_variables(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

@@ -1,326 +1,310 @@
-# In this namespace all objects needed for the grafana reporter are collected.
-module GrafanaReporter
-  # Used to store the whole settings, which are necessary to run the reporter.
-  # It can read configuration files, but might also be configured programmatically.
-  #
-  # This class also contains a function {#validate}, which ensures that the
-  # provided settings are set properly.
-  #
-  # Using this class is embedded in the {Application::Application#configure_and_run}.
-  #
-  # TODO add config example
-  class Configuration
-    # @return [AbstractReport] specific report class, which should be used.
-    attr_accessor :report_class
-
-    # Returned by {#mode} if only a connection test shall be executed.
-    MODE_CONNECTION_TEST = 'test'
-    # Returned by {#mode} if only one configured report shall be rendered.
-    MODE_SINGLE_RENDER = 'single-render'
-    # Returned by {#mode} if the default webservice shall be started.
-    MODE_SERVICE = 'webservice'
-
-    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
-    end
-
-    attr_reader :logger
-
-    # @return [String] mode, in which the reporting shall be executed. One of {MODE_CONNECTION_TEST}, {MODE_SINGLE_RENDER} and {MODE_SERVICE}.
-    def mode
-      return MODE_SERVICE if get_config('grafana-reporter:run-mode') != MODE_CONNECTION_TEST and get_config('grafana-reporter:run-mode') != MODE_SINGLE_RENDER
-
-      return get_config('grafana-reporter:run-mode')
-    end
-
-    # @return [String] configured report template. Only needed in {MODE_SINGLE_RENDER}.
-    def template
-      get_config('default-document-attributes:var-template')
-    end
-
-    # @return [String] destination filename for the report in {MODE_SINGLE_RENDER}.
-    def to_file
-      return get_config('to_file') || true if mode == MODE_SINGLE_RENDER
-
-      get_config('to_file')
-    end
-
-    # @return [Array<String>] names of the configured grafana_instances.
-    def grafana_instances
-      instances = get_config('grafana')
-      instances.keys
-    end
-
-    # @param instance [String] grafana instance name, for which the value shall be retrieved.
-    # @return [String] configured 'host' for the requested grafana instance.
-    def grafana_host(instance = 'default')
-      host = get_config("grafana:#{instance}:host")
-      raise GrafanaInstanceWithoutHostError, instance if host.nil?
-
-      host
-    end
-
-    # @param instance [String] grafana instance name, for which the value shall be retrieved.
-    # @return [String] configured 'api_key' for the requested grafana instance.
-    def grafana_api_key(instance = 'default')
-      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
-      result = get_config('grafana-reporter:templates-folder') || '.'
-      result.sub!(%r{[/]*$}, '/') unless result.empty?
-      result
-    end
-
-    # Returns configured folder, in which temporary images during report generation
-    # shall be stored including trailing slash. Folder has to be a subfolder of
-    # {#templates_folder}. By default: current folder.
-    # @return [String] configured folder, in which temporary images shall be stored.
-    def images_folder
-      img_path = templates_folder
-      img_path = img_path.empty? ? get_config('default-document-attributes:imagesdir').to_s : img_path + get_config('default-document-attributes:imagesdir').to_s
-      img_path.empty? ? './' : img_path.sub(%r{[/]*$}, '/')
-    end
-
-    # @return [String] name of grafana instance, against which a test shall be executed
-    def test_instance
-      get_config('grafana-reporter:test-instance')
-    end
-
-    # @return [String] configured folder, in which the reports shall be stored including trailing slash. By default: current folder.
-    def reports_folder
-      result = get_config('grafana-reporter:reports-folder') || '.'
-      result.sub!(%r{[/]*$}, '/') unless result.empty?
-      result
-    end
-
-    # @return [Integer] how many hours a generated report shall be retained, before it shall be deleted. By default: 24.
-    def report_retention
-      get_config('grafana-reporter:report-retention') || 24
-    end
-
-    # @return [Integer] port, on which the webserver shall run. By default: 8815.
-    def webserver_port
-      get_config('grafana-reporter:webservice-port') || 8815
-    end
-
-    # The configuration made with the setting 'default-document-attributes' will
-    # be passed 1:1 to the asciidoctor report service. It can be used to preconfigure
-    # whatever is essential for the needed report renderings.
-    # @return [Hash] configured document attributes
-    def default_document_attributes
-      get_config('default-document-attributes') || {}
-    end
-
-    # Used to load the configuration of a file or a manually created Hash to this
-    # object. To make sure, that the configuration is valid, call {#validate}.
-    #
-    # NOTE: This function overwrites all existing configurations
-    # @param hash [Hash] configuration settings
-    # @return [void]
-    def load_config(hash)
-      @config = hash
-    end
-
-    # Used to do the configuration by a command line call. Therefore also help will
-    # be shown, in case no parameter has been given.
-    # @param params [Array<String>] command line parameters, mainly ARGV can be used.
-    # @return [Integer] 0 if everything is fine, -1 if execution shall be aborted.
-    def configure_by_command_line(params = [])
-      params << '--help' if params.empty?
-
-      parser = OptionParser.new do |opts|
-        opts.banner = "Usage: ruby #{$0} CONFIG_FILE [options]"
-
-        opts.on('-d', '--debug LEVEL', 'Specify detail level: FATAL, ERROR, WARN, INFO, DEBUG.') do |level|
-          @logger.level = Object.const_get("::Logger::Severity::#{level}") if level =~ /(?:FATAL|ERROR|WARN|INFO|DEBUG)/
-        end
-
-        opts.on('--test GRAFANA_INSTANCE', 'test current configuration against given GRAFANA_INSTANCE') do |instance|
-          if get_config('grafana-reporter')
-            @config['grafana-reporter']['run-mode'] = 'test'
-          else
-            @config.merge!({'grafana-reporter' => {'run-mode' => 'test'} })
-	  end
-          @config['grafana-reporter']['test-instance'] = instance
-        end
-
-        opts.on('-t', '--template TEMPLATE', 'Render a single ASCIIDOC template to PDF and exit') do |template|
-          if get_config('grafana-reporter')
-            @config['grafana-reporter']['run-mode'] = 'single-render'
-          else
-            @config.merge!({'grafana-reporter' => {'run-mode' => 'single-render'} })
-	  end
-          @config['default-document-attributes']['var-template'] = template
-        end
-
-        opts.on('-o', '--output FILE', 'Output filename if only a single file is rendered') do |file|
-          @config.merge!({ 'to_file' => file })
-        end
-
-        opts.on('-v', '--version', 'Version information') do
-          puts GRAFANA_REPORTER_VERSION.join('.')
-          return -1
-        end
-
-        opts.on('-h', '--help', 'Show this message') do
-          puts opts
-          return -1
-        end
-      end
-
-      unless params.empty?
-        if File.exist?(params[0])
-          config_file = params.slice!(0)
-          begin
-            load_config(YAML.load_file(config_file))
-          rescue StandardError => e
-            raise ConfigurationError, "Could not read CONFIG_FILE '#{config_file}' (Error: #{e.message})"
-          end
-        end
-      end
-      parser.parse!(params)
-
-      0
-    end
-
-    # 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.
-    # @return [void]
-    def validate
-      validate_schema(schema, @config)
-
-      # check if set folders exist
-      raise FolderDoesNotExistError.new(reports_folder, 'reports-folder') unless File.directory?(reports_folder)
-      raise FolderDoesNotExistError.new(templates - folder, 'templates-folder') unless File.directory?(templates_folder)
-      raise FolderDoesNotExistError.new(images - folder, 'images-folder') unless File.directory?(images_folder)
-    end
-
-    private
-
-    def get_config(path)
-      return if path.nil?
-
-      cur_pos = @config
-      path.split(':').each do |subpath|
-        cur_pos = cur_pos[subpath] if cur_pos
-      end
-      cur_pos
-    end
-
-    def validate_schema(schema, subject)
-      return nil if subject.nil?
-
-      schema.each do |key, config|
-        type, min_occurence, next_level = config
-
-        validate_schema(next_level, subject[key]) if next_level
-
-        if key.nil?
-          # apply to all on this level
-          if 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
-
-          elsif subject.is_a?(Array)
-            if subject.length < min_occurence
-              raise ConfigurationDoesNotMatchSchemaError.new(key, 'occur', min_occurence, subject.length)
-            end
-
-            subject.each_index do |i|
-              sub_scheme = {}
-              sub_scheme[i] = schema[nil]
-              validate_schema(sub_scheme, subject)
-            end
-
-          else
-            raise ConfigurationError, "Unhandled configuration data type '#{subject.class}'."
-          end
-        else
-          # apply to single item
-          if subject.is_a?(Hash)
-            if !subject.key?(key) && (min_occurence > 0)
-              raise ConfigurationDoesNotMatchSchemaError.new(key, 'occur', min_occurence, 0)
-            end
-            if !subject[key].is_a?(type) && subject.key?(key)
-              raise ConfigurationDoesNotMatchSchemaError.new(key, 'be a', type, subject[key].class)
-            end
-
-          elsif subject.is_a?(Array)
-            if (subject.length < key) && (min_occurence > subject.length)
-              raise ConfigurationDoesNotMatchSchemaError.new(key, 'occur', min_occurence, subject.length)
-            end
-            if !subject[key].is_a?(type) && (subject.length >= key)
-              raise ConfigurationDoesNotMatchSchemaError.new(key, 'be a', type, subject[key].class)
-            end
-
-          else
-            raise ConfigurationError, "Unhandled configuration data type '#{subject.class}'."
-          end
-        end
-      end
-
-      # validate also if subject has further configurations, which are not known by the reporter
-      subject.each do |item, subitems|
-        schema_config = schema[item] || schema[nil]
-        if schema_config.nil?
-          logger.warn("Item '#{item}' in configuration is unknown to the reporter and will be ignored")
-        end
-      end
-    end
-
-    def schema
-      {
-        'grafana' =>
-         [
-           Hash, 1,
-           {
-             nil =>
-              [
-                Hash, 1,
-                {
-                  'host' => [String, 1],
-                  'api_key' => [String, 0],
-                  'datasources' => [Hash, 0, { nil => [Integer, 1] }]
-                }
-              ]
-           }
-         ],
-        'default-document-attributes' => [Hash, 0],
-        'grafana-reporter' =>
-        [
-          Hash, 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]
-          }
-        ]
-      }
-    end
-  end
-end
+# frozen_string_literal: true
+
+# In this namespace all objects needed for the grafana reporter are collected.
+module GrafanaReporter
+  # Used to store the whole settings, which are necessary to run the reporter.
+  # It can read configuration files, but might also be configured programmatically.
+  #
+  # This class also contains a function {#validate}, which ensures that the
+  # provided settings are set properly.
+  #
+  # Using this class is embedded in the {Application::Application#configure_and_run}.
+  #
+  class Configuration
+    # @return [AbstractReport] specific report class, which should be used.
+    attr_accessor :report_class
+
+    # Returned by {#mode} if only a connection test shall be executed.
+    MODE_CONNECTION_TEST = 'test'
+    # Returned by {#mode} if only one configured report shall be rendered.
+    MODE_SINGLE_RENDER = 'single-render'
+    # Returned by {#mode} if the default webservice shall be started.
+    MODE_SERVICE = 'webservice'
+
+    # Used to access the configuration hash. To make sure, that the configuration is
+    # valid, call {#validate}.
+    attr_reader :config
+
+    def initialize
+      @config = {}
+      @logger = ::Logger.new($stderr, level: :info)
+    end
+
+    attr_accessor :logger
+
+    # 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}.
+    def mode
+      if (get_config('grafana-reporter:run-mode') != MODE_CONNECTION_TEST) &&
+         (get_config('grafana-reporter:run-mode') != MODE_SINGLE_RENDER)
+        return MODE_SERVICE
+      end
+
+      get_config('grafana-reporter:run-mode')
+    end
+
+    # @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"
+    end
+
+    # @return [String] destination filename for the report in {MODE_SINGLE_RENDER}.
+    def to_file
+      return get_config('to_file') || true if mode == MODE_SINGLE_RENDER
+
+      get_config('to_file')
+    end
+
+    # @return [Array<String>] names of the configured grafana_instances.
+    def grafana_instances
+      instances = get_config('grafana')
+      instances.keys
+    end
+
+    # @param instance [String] grafana instance name, for which the value shall be retrieved.
+    # @return [String] configured 'host' for the requested grafana instance.
+    def grafana_host(instance = 'default')
+      host = get_config("grafana:#{instance}:host")
+      raise GrafanaInstanceWithoutHostError, instance if host.nil?
+
+      host
+    end
+
+    # @param instance [String] grafana instance name, for which the value shall be retrieved.
+    # @return [String] configured 'api_key' for the requested grafana instance.
+    def grafana_api_key(instance = 'default')
+      get_config("grafana:#{instance}:api_key")
+    end
+
+    # @return [String] configured folder, in which the report templates are stored including trailing slash.
+    #   By default: current folder.
+    def templates_folder
+      result = get_config('grafana-reporter:templates-folder') || '.'
+      return result.sub(%r{/*$}, '/') unless result.empty?
+
+      result
+    end
+
+    # Returns configured folder, in which temporary images during report generation
+    # shall be stored including trailing slash. Folder has to be a subfolder of
+    # {#templates_folder}. By default: current folder.
+    # @return [String] configured folder, in which temporary images shall be stored.
+    def images_folder
+      img_path = templates_folder
+      img_path = if img_path.empty?
+                   get_config('default-document-attributes:imagesdir').to_s
+                 else
+                   img_path + get_config('default-document-attributes:imagesdir').to_s
+                 end
+      img_path.empty? ? './' : img_path.sub(%r{/*$}, '/')
+    end
+
+    # @return [String] name of grafana instance, against which a test shall be executed
+    def test_instance
+      get_config('grafana-reporter:test-instance')
+    end
+
+    # @return [String] configured folder, in which the reports shall be stored including trailing slash.
+    #   By default: current folder.
+    def reports_folder
+      result = get_config('grafana-reporter:reports-folder') || '.'
+      return result.sub(%r{/*$}, '/') unless result.empty?
+
+      result
+    end
+
+    # @return [Integer] how many hours a generated report shall be retained, before it shall be deleted.
+    #   By default: 24.
+    def report_retention
+      get_config('grafana-reporter:report-retention') || 24
+    end
+
+    # @return [Integer] port, on which the webserver shall run. By default: 8815.
+    def webserver_port
+      get_config('grafana-reporter:webservice-port') || 8815
+    end
+
+    # The configuration made with the setting 'default-document-attributes' will
+    # be passed 1:1 to the asciidoctor report service. It can be used to preconfigure
+    # whatever is essential for the needed report renderings.
+    # @return [Hash] configured document attributes
+    def default_document_attributes
+      get_config('default-document-attributes') || {}
+    end
+
+    # 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(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)
+      raise FolderDoesNotExistError.new(templates_folder, 'templates-folder') unless File.directory?(templates_folder)
+      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?
+
+      cur_pos = @config
+      path.split(':').each do |subpath|
+        cur_pos = cur_pos[subpath] if cur_pos
+      end
+      cur_pos
+    end
+
+    def validate_schema(schema, subject)
+      return nil if subject.nil?
+
+      schema.each do |key, config|
+        type, min_occurence, next_level = config
+
+        validate_schema(next_level, subject[key]) if next_level
+
+        if key.nil?
+          # apply to all on this level
+          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
+        elsif subject.is_a?(Hash)
+          if !subject.key?(key) && min_occurence.positive?
+            raise ConfigurationDoesNotMatchSchemaError.new(key, 'occur', min_occurence, 0)
+          end
+          if !subject[key].is_a?(type) && subject.key?(key)
+            raise ConfigurationDoesNotMatchSchemaError.new(key, 'be a', type, subject[key].class)
+          end
+
+        else
+          raise ConfigurationError, "Unhandled configuration data type '#{subject.class}'."
+        end
+      end
+
+      # validate also if subject has further configurations, which are not known by the reporter
+      subject.each do |item, _subitems|
+        schema_config = schema[item] || schema[nil]
+        if schema_config.nil?
+          logger.warn("Item '#{item}' in configuration is unknown to the reporter and will be ignored")
+        end
+      end
+    end
+
+    def schema(explicit)
+      {
+        'grafana' =>
+         [
+           Hash, 1,
+           {
+             nil =>
+              [
+                Hash, 1,
+                {
+                  'host' => [String, 1],
+                  'api_key' => [String, 0]
+                }
+              ]
+           }
+         ],
+        'default-document-attributes' => [Hash, explicit ? 1 : 0],
+        'to_file' => [String, 0],
+        'grafana-reporter' =>
+        [
+          Hash, 1,
+          {
+            'debug-level' => [String, 0],
+            'run-mode' => [String, 0],
+            'test-instance' => [String, 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] }]
+          }
+        ]
+      }
+    end
+  end
+end