ruby-grafana-reporter 0.1.7 → 0.4.0

data/lib/grafana_reporter/console_configuration_wizard.rb

@@ -0,0 +1,319 @@
+# frozen_string_literal: true
+
+module GrafanaReporter
+  # This class provides a console configuration wizard, to reduce the manual efforts that have
+  # to be spent for that action and to reduce mistakes as good as possible.
+  class ConsoleConfigurationWizard
+    # Provides a command line configuration wizard for setting up the necessary configuration
+    # file.
+    # TODO: refactor class
+    def start_wizard(config_file, console_config)
+      action = overwrite_or_use_config_file(config_file)
+      return if action == 'abort'
+
+      config = create_config_wizard(config_file, console_config) if action == 'overwrite'
+      config ||= Configuration.new
+
+      begin
+        config.config = YAML.load_file(config_file)
+      rescue StandardError => e
+        raise ConfigurationError, "Could not read config file '#{config_file}' (Error: #{e.message})\n"\
+              "Source:\n#{File.read(config_file)}"
+      end
+
+      begin
+        config.validate(true)
+        puts 'Configuration file validated successfully.'
+      rescue ConfigurationError => e
+        raise e
+      end
+
+      demo_report = create_demo_report(config)
+
+      demo_report ||= '<<your_report_name>>'
+      config_param = config_file == Application::Application::CONFIG_FILE ? '' : " -c #{config_file}"
+      program_call = "#{Gem.ruby} #{$PROGRAM_NAME}"
+      program_call = ENV['OCRA_EXECUTABLE'].gsub("#{Dir.pwd}/".gsub('/', '\\'), '') if ENV['OCRA_EXECUTABLE']
+
+      puts
+      puts 'Now everything is setup properly. Create your reports as required in the templates '\
+           'folder and run the reporter either standalone with e.g. the following command:'
+      puts
+      puts "   #{program_call}#{config_param} -t #{demo_report} -o demo_report_with_help.pdf"
+      puts
+      puts 'or run it as a service using the following command:'
+      puts
+      puts "   #{program_call}#{config_param}"
+      puts
+      puts "Open 'http://localhost:#{config.webserver_port}/render?var-template=#{demo_report}' in a webbrowser to"\
+           ' test your configuration.'
+    end
+
+    private
+
+    def create_config_wizard(config_file, console_config)
+      config = Configuration.new
+
+      puts 'This wizard will guide you through an initial configuration for'\
+           ' the ruby-grafana-reporter. The configuration file will be created'\
+           ' in the current folder. Please make sure to specify necessary paths'\
+           ' either with a relative or an absolute path properly.'
+      puts
+      puts "Wizard is creating configuration file '#{config_file}'."
+      puts
+      port = ui_config_port
+      grafana = ui_config_grafana(console_config)
+      templates = ui_config_templates_folder
+      reports = ui_config_reports_folder
+      images = ui_config_images_folder(templates)
+      retention = ui_config_retention
+
+      config_yaml = %(# This configuration has been built with the configuration wizard.
+
+#{grafana}
+
+grafana-reporter:
+  report-class: GrafanaReporter::Asciidoctor::Report
+  templates-folder: #{templates}
+  reports-folder: #{reports}
+  report-retention: #{retention}
+  webservice-port: #{port}
+# you may want to configure the following webhook callbacks to get informed on certain events
+#  callbacks:
+#    all:
+#      - <<your_callback_url>>
+#      - ...
+#    on_before_create:
+#      - <<your_callback_url>>
+#      - ...
+#    on_after_cancel:
+#      - <<your_callback_url>>
+#      - ...
+#    on_after_finish:
+#      - <<your_callback_url>>
+#      - ...
+
+default-document-attributes:
+  imagesdir: #{images}
+# feel free to add here additional asciidoctor document attributes which are applied to all your templates
+)
+
+      begin
+        File.write(config_file, config_yaml, mode: 'w')
+        puts 'Configuration file successfully created.'
+      rescue StandardError => e
+        raise e
+      end
+
+      config
+    end
+
+    def create_demo_report(config)
+      unless Dir.exist?(config.templates_folder)
+        puts "Skip creation of DEMO template, as folder '#{config.templates_folder}' does not exist."
+        return nil
+      end
+
+      create = user_input('Shall I create a demo report for your new configuration file? Please note '\
+                          'that this report might contain confidential information, depending on the '\
+                          'confidentiality of the information stored in your dashboard.', 'yN')
+      return nil unless create =~ /^(?:y|Y)$/
+
+      demo_report = 'demo_report'
+      demo_report_file = "#{config.templates_folder}#{demo_report}.adoc"
+
+      # ask to overwrite file
+      if File.exist?(demo_report_file)
+        input = user_input("Demo template '#{demo_report_file}' does already exist. Do you want to "\
+                           'overwrite it?', 'yN')
+
+        case input
+        when /^(?:y|Y)$/
+          puts 'Overwriting existing DEMO template.'
+
+        else
+          puts 'Skip creation of DEMO template.'
+          return demo_report
+        end
+      end
+
+      # TODO: move this to Asciidoctor::Report class
+      classes = [Asciidoctor::AlertsTableIncludeProcessor, Asciidoctor::AnnotationsTableIncludeProcessor,
+                 Asciidoctor::PanelImageBlockMacro, Asciidoctor::PanelImageInlineMacro,
+                 Asciidoctor::PanelPropertyInlineMacro, Asciidoctor::PanelQueryTableIncludeProcessor,
+                 Asciidoctor::PanelQueryValueInlineMacro, Asciidoctor::SqlTableIncludeProcessor,
+                 Asciidoctor::SqlValueInlineMacro, Asciidoctor::ShowHelpIncludeProcessor,
+                 Asciidoctor::ShowEnvironmentIncludeProcessor]
+
+      grafana = ::Grafana::Grafana.new(config.grafana_host, config.grafana_api_key)
+      demo_report_content = DemoReportWizard.new(classes).build(grafana)
+
+      begin
+        File.write(demo_report_file, demo_report_content, mode: 'w')
+        puts "DEMO template '#{demo_report_file}' successfully created."
+      rescue StandardError => e
+        puts e.message
+        return nil
+      end
+
+      demo_report
+    end
+
+    def ui_config_grafana(config)
+      valid = false
+      url = nil
+      api_key = nil
+      until valid
+        url ||= user_input('Specify grafana host', 'http://localhost:3000')
+        print "Testing connection to '#{url}' #{api_key ? '_with_' : '_without_'} API key..."
+        begin
+          res = Grafana::Grafana.new(url,
+                                     api_key,
+                                     logger: config.logger).test_connection
+        rescue StandardError => e
+          puts
+          puts e.message
+        end
+        puts 'done.'
+
+        case res
+        when 'Admin'
+          tmp = user_input('Access to grafana is permitted as Admin, which is a potential security risk.'\
+                ' Do you want to use another [a]pi key, [r]e-enter url key or [i]gnore?', 'aRi')
+
+          case tmp
+          when /(?:i|I)$/
+            valid = true
+
+          when /(?:a|A)$/
+            print 'Enter API key: '
+            api_key = gets.strip
+
+          else
+            url = nil
+            api_key = nil
+
+          end
+
+        when 'NON-Admin'
+          print 'Access to grafana is permitted as NON-Admin.'
+          valid = true
+
+        else
+          tmp = user_input("Grafana could not be accessed at '#{url}'. Do you want to use an [a]pi key,"\
+                ' [r]e-enter url, or [i]gnore and proceed?', 'aRi')
+
+          case tmp
+          when /(?:i|I)$/
+            valid = true
+
+          when /(?:a|A)$/
+            print 'Enter API key: '
+            api_key = gets.strip
+
+          else
+            url = nil
+            api_key = nil
+
+          end
+
+        end
+      end
+      %(grafana:
+  default:
+    host: #{url}#{api_key ? "\n    api_key: #{api_key}" : ''}
+)
+    end
+
+    def ui_config_port
+      input = nil
+      until input
+        input = user_input('Specify port on which reporter shall run', '8815')
+        input = nil unless input =~ /[0-9]+/
+      end
+      input
+    end
+
+    def ui_config_templates_folder
+      input = nil
+      until input
+        input = user_input('Specify path where templates shall be stored', './templates')
+        input = nil unless validate_config_folder(input)
+      end
+      input
+    end
+
+    def ui_config_reports_folder
+      input = nil
+      until input
+        input = user_input('Specify path where created reports shall be stored', './reports')
+        input = nil unless validate_config_folder(input)
+      end
+      input
+    end
+
+    def ui_config_images_folder(parent)
+      input = nil
+      until input
+        input = user_input('Specify path where rendered images shall be stored (relative to templates folder)',
+                           './images')
+        input = nil unless validate_config_folder(File.join(parent, input))
+      end
+      input
+    end
+
+    def ui_config_retention
+      input = nil
+      until input
+        input = user_input('Specify report retention duration in hours', '24')
+        input = nil unless input =~ /[0-9]+/
+      end
+      input
+    end
+
+    def user_input(text, default)
+      print "#{text} [#{default}]: "
+      input = gets.gsub(/\n$/, '')
+      input = default if input.empty?
+      input
+    end
+
+    def validate_config_folder(folder)
+      return true if Dir.exist?(folder)
+
+      print "Directory '#{folder} does not exist: [c]reate, [r]e-enter path or [i]gnore? [cRi]: "
+      case gets
+      when /^(?:c|C)$/
+        begin
+          Dir.mkdir(folder)
+          puts "Directory '#{folder}' successfully created."
+          return true
+        rescue StandardError => e
+          puts "WARN: Directory '#{folder}' could not be created. Please create it manually."
+          puts e.message
+        end
+
+      when /^(?:i|I)$/
+        puts "WARN: Directory '#{folder}' does not exist. Please create manually."
+        return true
+      end
+
+      false
+    end
+
+    def overwrite_or_use_config_file(config_file)
+      return 'overwrite' unless File.exist?(config_file)
+
+      input = nil
+      until input
+        input = user_input("Configuration file '#{config_file}' already exists. Do you want to [o]verwrite it, "\
+                           'use it to for [d]emo report creation only, or [a]bort?', 'odA')
+      end
+
+      return 'demo_report' if input =~ /^(?:d|D)$/
+      return 'abort' if input =~ /^(?:A|a|odA)$/
+
+      'overwrite'
+    end
+  end
+end

data/lib/grafana_reporter/demo_report_wizard.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module GrafanaReporter
+  # This class is used to build a demo report based on a real grafana instance. Therefore
+  # it checks available grafana dashboards and panels and returns a final template file as
+  # string, which can then be used as a template.
+  class DemoReportWizard
+    # @param query_classes [Array] class objects, for which a demo report shall be created
+    def initialize(query_classes)
+      @query_classes = query_classes
+    end
+
+    # Invokes the build process for the given +grafana+ object. Progress is printed to
+    # STDOUT.
+    # @param grafana [Grafana] grafana instance, for which the demo report shall be built
+    # @return [String] demo template as string
+    def build(grafana)
+      results = {}
+
+      grafana.dashboard_ids.sample(15).each do |dashboard_id|
+        print "Evaluating dashboard '#{dashboard_id}' for building a demo report..."
+        dashboard = grafana.dashboard(dashboard_id)
+
+        results = evaluate_dashboard(dashboard, @query_classes - results.keys).merge(results)
+
+        puts "done - #{(@query_classes - results.keys).length} examples to go"
+        break if (@query_classes - results.keys).empty?
+      end
+      puts 'Aborting evaluating further dashboards after 15 samples.' if grafana.dashboard_ids.length > 15 and !(@query_classes - results.keys).empty?
+      puts "For #{(@query_classes - results.keys).length} reporter functionalities no appropriate examples could be found in the configured grafana instance." unless (@query_classes - results.keys).empty?
+
+      format_results(default_result(@query_classes - results.keys).merge(results))
+    end
+
+    private
+
+    def default_result(query_classes)
+      results = {}
+
+      query_classes.each do |query_class|
+        results[query_class] = "No example found for #{query_class.name} in the dashboards."
+      end
+
+      results
+    end
+
+    def evaluate_dashboard(dashboard, query_classes)
+      results = {}
+
+      dashboard.panels.shuffle.each do |panel|
+        query_classes.each do |query_class|
+          unless query_class.public_instance_methods.include?(:build_demo_entry)
+            results[query_class] = "Method 'build_demo_entry' not implemented for #{query_class.name}"
+            next
+          end
+
+          begin
+            result = query_class.new.build_demo_entry(panel)
+            results[query_class] = result if result
+          rescue StandardError => e
+            puts "#{e.message}\n#{e.backtrace.join("\n")}"
+          end
+        end
+      end
+
+      results
+    end
+
+    # TODO: move this method to Asciidoctor::Report
+    def format_results(raw_results)
+      results = ['= Demo report',
+                 "Created by `+ruby-grafana-reporter+` version #{GRAFANA_REPORTER_VERSION.join('.')}",
+                 '== Examples']
+
+      raw_results.each do |k, v|
+        results += if v =~ /^[A-Z]/
+                     ["=== #{k.to_s.gsub(/.*::/, '')}", v.to_s]
+                   else
+                     ["=== #{k.to_s.gsub(/.*::/, '')}", 'Sample call:', " #{v.gsub(/\n/, "\n ")}",
+                      'Result:', v.to_s]
+                   end
+      end
+
+      results.join("\n\n")
+    end
+  end
+end

data/lib/grafana_reporter/errors.rb

@@ -1,38 +1,81 @@
-module GrafanaReporter
-  # General error of the reporter. All other errors will inherit from this class.
-  class GrafanaReporterError < StandardError
-    def initialize(message)
-      super('GrafanaReporterError: ' + message.to_s)
-    end
-  end
-
-  # Thrown, if the requested grafana instance does not have the mandatory 'host'
-  # setting configured.
-  class GrafanaInstanceWithoutHostError < GrafanaReporterError
-    def initialize(instance)
-      super("Grafana instance '#{instance}' has been configured without mandatory 'host' setting.")
-    end
-  end
-
-  # General configuration error. All configuration errors inherit from this class.
-  class ConfigurationError < GrafanaReporterError
-    def initialize(message)
-      super("Configuration error: #{message}")
-    end
-  end
-
-  # Thrown, if a configured path does not exist.
-  class FolderDoesNotExistError < ConfigurationError
-    def initialize(folder, config_item)
-      super("#{config_item} '#{folder}' does not exist.")
-    end
-  end
-
-  # Thrown if the configuration does not match the expected schema.
-  # Details about how to fix that are provided in the message.
-  class ConfigurationDoesNotMatchSchemaError < ConfigurationError
-    def initialize(item, verb, expected, currently)
-      super("Configuration file does not match schema definition. Expected '#{item}' to #{verb} '#{expected}', but was '#{currently}'.")
-    end
-  end
-end
+# frozen_string_literal: true
+
+module GrafanaReporter
+  # General error of the reporter. All other errors will inherit from this class.
+  class GrafanaReporterError < StandardError
+    def initialize(message)
+      super("GrafanaReporterError: #{message}")
+    end
+  end
+
+  # Thrown, if the requested grafana instance does not have the mandatory 'host'
+  # setting configured.
+  class GrafanaInstanceWithoutHostError < GrafanaReporterError
+    def initialize(instance)
+      super("Grafana instance '#{instance}' has been configured without mandatory 'host' setting.")
+    end
+  end
+
+  # General configuration error. All configuration errors inherit from this class.
+  class ConfigurationError < GrafanaReporterError
+    def initialize(message)
+      super("Configuration error: #{message}")
+    end
+  end
+
+  # Thrown if a non existing template has been specified.
+  class MissingTemplateError < ConfigurationError
+    def initialize(template)
+      super("Given report template '#{template}' is not a valid template.")
+    end
+  end
+
+  # Thrown, if a configured path does not exist.
+  class FolderDoesNotExistError < ConfigurationError
+    def initialize(folder, config_item)
+      super("#{config_item} '#{folder}' does not exist.")
+    end
+  end
+
+  # Thrown if the configuration does not match the expected schema.
+  # Details about how to fix that are provided in the message.
+  class ConfigurationDoesNotMatchSchemaError < ConfigurationError
+    def initialize(item, verb, expected, currently)
+      super("Configuration file does not match schema definition. Expected '#{item}' to #{verb} '#{expected}',"\
+            "but was '#{currently}'.")
+    end
+  end
+
+  # Thrown, if the value configuration in {QueryMixin#replace_values} is
+  # invalid.
+  class MalformedReplaceValuesStatementError < GrafanaReporterError
+    def initialize(statement)
+      super("The specified replace_values statement '#{statement}' is invalid. Make sure it contains"\
+            " exactly one not escaped ':' symbol.")
+    end
+  end
+
+  # Thrown, if a configured parameter is malformed.
+  class MalformedAttributeContentError < GrafanaReporterError
+    def initialize(message, attribute, content)
+      super("The content '#{content}' in attribute '#{attribute}' is malformed: #{message}")
+    end
+  end
+
+  # Thrown, if a configured time range is not supported by the reporter.
+  #
+  # If this happens, most likely the reporter has to implement the new
+  # time range definition.
+  class TimeRangeUnknownError < GrafanaReporterError
+    def initialize(time_range)
+      super("The specified time range '#{time_range}' is unknown.")
+    end
+  end
+
+  # Thrown, if a mandatory attribute is not set.
+  class MissingMandatoryAttributeError < GrafanaReporterError
+    def initialize(attribute)
+      super("Missing mandatory attribute '#{attribute}'.")
+    end
+  end
+end