ruby-grafana-reporter 0.2.1 → 0.4.2

data/lib/grafana_reporter/console_configuration_wizard.rb

@@ -0,0 +1,311 @@
+# 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 == Configuration::DEFAULT_CONFIG_FILE_NAME ? '' : " -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
+
+      grafana = ::Grafana::Grafana.new(config.grafana_host, config.grafana_api_key)
+      demo_report_content = DemoReportWizard.new(config.report_class.demo_report_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,105 @@
+# 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
+
+      if grafana.dashboard_ids.length > 15 && !(@query_classes - results.keys).empty?
+        puts 'Aborting evaluating further dashboards after 15 samples.'
+      end
+
+      unless (@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.'
+      end
+
+      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|
+        begin
+          next if panel.datasource.is_a?(Grafana::UnsupportedDatasource)
+        rescue Grafana::DatasourceDoesNotExistError
+          next
+        end
+
+        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 Grafana::DatasourceDoesNotExistError
+            # properly catch DatasourceDoesNotExist errors here, as they don't lead to a real issue
+            # during demo report creation
+            # This may e.g. happen if a panel asks e.g. for datasource '-- Dashboard --' which is
+            # currently not allowed
+          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/erb/report.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'erb'
+
+module GrafanaReporter
+  module ERB
+    # Implementation of a specific {AbstractReport}. It is used to
+    # build reports specifically for erb templates.
+    class Report < ::GrafanaReporter::AbstractReport
+      # Starts to create an asciidoctor report. It utilizes all extensions in the {GrafanaReporter::Asciidoctor}
+      # namespace to realize the conversion.
+      # @see AbstractReport#build
+      def build(template, destination_file_or_path, custom_attributes)
+        attrs = @config.default_document_attributes.merge(@custom_attributes)
+        logger.debug("Document attributes: #{attrs}")
+
+        # TODO: if path is true, a default filename has to be generated. check if this should be a general function instead
+        File.write(path, ::ERB.new(File.read(template)).result(ReportJail.new(self, attrs).bind))
+
+        # TODO: check if closing output file is correct here, or maybe can be moved to AbstractReport.done!
+        @destination_file_or_path.close if @destination_file_or_path.is_a?(File)
+      end
+
+      # @see AbstractReport#demo_report_classes
+      def self.demo_report_classes
+        []
+      end
+    end
+  end
+end

data/lib/grafana_reporter/erb/report_jail.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module GrafanaReporter
+  module ERB
+    # An instance of this class is used as binding for the ERB execution, i.e.
+    # this class contains everything known within the ERB template
+    class ReportJail
+      attr_reader :report, :attributes
+
+      def initialize(report, attributes)
+        @report = report
+        @attributes = attributes
+      end
+
+      # @return binding to this object
+      def bind
+        binding
+      end
+    end
+  end
+end