ruby-grafana-reporter 0.2.0 → 0.4.1

data/lib/grafana_reporter/abstract_report.rb

@@ -9,6 +9,13 @@ module GrafanaReporter
   # Objects of this class are also stored in {Application::Application}, unless
   # the retention time is over.
   class AbstractReport
+    # Array of supported event callback symbols
+    EVENT_CALLBACKS = %i[all on_before_create on_after_cancel on_after_finish].freeze
+
+    # Class variable for storing event listeners
+    @@event_listeners = {}
+    @@event_listeners.default = []
+
     # @return [String] path to the template
     attr_reader :template
 
@@ -28,21 +35,38 @@ module GrafanaReporter
     attr_reader :done
 
     # @param config [Configuration] configuration object
-    # @param template [String] path to the template to be used
-    # @param destination_file_or_path [String or File] path to the destination report or file object to use
-    # @param custom_attributes [Hash] custom attributes, which shall be merged with priority over the configuration
-    def initialize(config, template, destination_file_or_path = nil, custom_attributes = {})
+    def initialize(config)
       @config = config
       @logger = Logger::TwoWayDelegateLogger.new
       @logger.additional_logger = @config.logger
-      @done = false
-      @template = template
-      @destination_file_or_path = destination_file_or_path
-      @custom_attributes = custom_attributes
-      @start_time = nil
-      @end_time = nil
-      @cancel = false
-      raise MissingTemplateError, @template.to_s unless File.exist?(@template.to_s)
+      @grafana_instances = {}
+
+      init_before_create
+    end
+
+    # Registers a new event listener object.
+    # @param event [Symbol] one of EVENT_CALLBACKS
+    # @param listener [Object] object responding to #callback(event_symbol, object)
+    def self.add_event_listener(event, listener)
+      @@event_listeners[event] = [] if @@event_listeners[event] == []
+      @@event_listeners[event].push(listener)
+    end
+
+    # Removes all registeres event listener objects
+    def self.clear_event_listeners
+      @@event_listeners = {}
+      @@event_listeners.default = []
+    end
+
+    # @param instance [String] requested grafana instance
+    # @return [Grafana::Grafana] the requested grafana instance.
+    def grafana(instance)
+      unless @grafana_instances[instance]
+        @grafana_instances[instance] = ::Grafana::Grafana.new(@config.grafana_host(instance),
+                                                              @config.grafana_api_key(instance),
+                                                              logger: @logger)
+      end
+      @grafana_instances[instance]
     end
 
     # Call to request cancelling the report generation.
@@ -50,6 +74,7 @@ module GrafanaReporter
     def cancel!
       @cancel = true
       logger.info('Cancelling report generation invoked.')
+      notify(:on_after_cancel)
     end
 
     # @return [String] path to the report destination file
@@ -81,9 +106,12 @@ module GrafanaReporter
       @error || []
     end
 
-    # @return [String] status of the report, one of 'in progress', 'cancelled', 'died' or 'finished'.
+    # @return [String] status of the report as string, either 'not started', 'in progress', 'cancelling',
+    #   'cancelled', 'died' or 'finished'.
     def status
+      return 'not started' unless @start_time
       return 'cancelled' if done && cancel
+      return 'cancelling' if !done && cancel
       return 'finished' if done && error.empty?
       return 'died' if done && !error.empty?
 
@@ -96,17 +124,91 @@ module GrafanaReporter
       logger.internal_messages
     end
 
-    # @abstract
     # Is being called to start the report generation.
+    # @param template [String] path to the template to be used, trailing +.adoc+ extension may be omitted
+    # @param destination_file_or_path [String or File] path to the destination report or file object to use
+    # @param custom_attributes [Hash] custom attributes, which shall be merged with priority over the configuration
     # @return [void]
-    def create_report
-      raise NotImplementedError
+    def create_report(template, destination_file_or_path = nil, custom_attributes = {})
+      init_before_create
+      @template = template
+      @destination_file_or_path = destination_file_or_path
+      @custom_attributes = custom_attributes
+
+      # automatically add extension, if a file with adoc extension exists
+      @template = "#{@template}.adoc" if File.file?("#{@template}.adoc") && !File.file?(@template.to_s)
+      raise MissingTemplateError, @template.to_s unless File.file?(@template.to_s)
+
+      notify(:on_before_create)
+      @start_time = Time.new
+      logger.info("Report started at #{@start_time}")
     end
 
-    # @abstract
+    # Used to calculate the progress of a report. By default expects +@total_steps+ to contain the total
+    # number of steps, which will be processed with each call of {#next_step}.
     # @return [Integer] number between 0 and 100, representing the current progress of the report creation.
     def progress
+      return @current_pos.to_i if @total_steps.to_i.zero?
+
+      @current_pos.to_f / @total_steps
+    end
+
+    # Increments the progress.
+    # @return [Integer] number of the current progress position.
+    def next_step
+      @current_pos += 1
+      @current_pos
+    end
+
+    # @abstract
+    # Provided class objects need to implement a method +build_demo_entry(panel)+.
+    # @return [Array<Class>] array of class objects, which shall be included in a demo report
+    def self.demo_report_classes
       raise NotImplementedError
     end
+
+    private
+
+    # Called, if the report generation has died with an error.
+    # @param error [StandardError] occured error
+    # @return [void]
+    def died_with_error(error)
+      @error = [error.message] << [error.backtrace]
+      done!
+    end
+
+    def init_before_create
+      @done = false
+      @start_time = nil
+      @end_time = nil
+      @cancel = false
+      @current_pos = 0
+    end
+
+    def done!
+      return if @done
+
+      @done = true
+      @end_time = Time.new
+      @start_time ||= @end_time
+      logger.info("Report creation ended after #{@end_time.to_i - @start_time.to_i} seconds with status '#{status}'")
+      notify(:on_after_finish)
+    end
+
+    def notify(event)
+      (@@event_listeners[:all] + @@event_listeners[event]).each do |listener|
+        logger.debug("Informing event listener '#{listener.class}' about event '#{event}' for report '#{object_id}'.")
+        begin
+          res = listener.callback(event, self)
+          logger.debug("Event listener '#{listener.class}' for event '#{event}' and report '#{object_id}' returned "\
+                       "with result '#{res}'.")
+        rescue StandardError => e
+          msg = "Event listener '#{listener.class}' for event '#{event}' and report '#{object_id}' returned with "\
+                "error: #{e.message} - #{e.backtrace}."
+          puts msg
+          logger.error(msg)
+        end
+      end
+    end
   end
 end

data/lib/grafana_reporter/alerts_table_query.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module GrafanaReporter
+  # This class is used to query alerts from grafana.
+  class AlertsTableQuery < AbstractQuery
+    # Check if mandatory {Grafana::Variable} +columns+ is specified in variables.
+    #
+    # The value of the +columns+ variable has to be a comma separated list of column titles, which
+    # need to be included in the following list:
+    # - limit
+    # - dashboardId
+    # - panelId
+    # - query
+    # - state
+    # - folderId
+    # - dashboardQuery
+    # - dashboardTag
+    # @return [void]
+    def pre_process
+      raise MissingMandatoryAttributeError, 'columns' unless @raw_query['columns']
+
+      @from = translate_date(@from, @variables['grafana_report_timestamp'], false, @variables['from_timezone'] ||
+                             @variables['grafana_default_from_timezone'])
+      @to = translate_date(@to, @variables['grafana_report_timestamp'], true, @variables['to_timezone'] ||
+                           @variables['grafana_default_to_timezone'])
+      @datasource = Grafana::GrafanaAlertsDatasource.new(nil)
+    end
+
+    # Filter the query result for the given columns and sets the result in the preformatted SQL
+    # result stlye.
+    #
+    # Additionally it applies {AbstractQuery#format_columns}, {AbstractQuery#replace_values} and
+    # {AbstractQuery#filter_columns}.
+    # @return [void]
+    def post_process
+      @result = format_columns(@result, @variables['format'])
+      @result = replace_values(@result, @variables.select { |k, _v| k =~ /^replace_values_\d+/ })
+      @result = filter_columns(@result, @variables['filter_columns'])
+
+      # TODO: move formatting to Asciidoctor namespace
+      @result = @result[:content].map { |row| "| #{row.map { |item| item.to_s.gsub('|', '\\|') }.join(' | ')}" }
+    end
+  end
+end

data/lib/grafana_reporter/annotations_table_query.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module GrafanaReporter
+  # This class is used to query annotations from grafana.
+  class AnnotationsTableQuery < AbstractQuery
+    # Check if mandatory {Grafana::Variable} +columns+ is specified in variables.
+    #
+    # The value of the +columns+ variable has to be a comma separated list of column titles, which
+    # need to be included in the following list:
+    # - limit
+    # - alertId
+    # - userId
+    # - type
+    # - tags
+    # - dashboardId
+    # - panelId
+    # @return [void]
+    def pre_process
+      raise MissingMandatoryAttributeError, 'columns' unless @raw_query['columns']
+
+      @from = translate_date(@from, @variables['grafana_report_timestamp'], false, @variables['from_timezone'] ||
+                             @variables['grafana_default_from_timezone'])
+      @to = translate_date(@to, @variables['grafana_report_timestamp'], true, @variables['to_timezone'] ||
+                           @variables['grafana_default_to_timezone'])
+      @datasource = Grafana::GrafanaAnnotationsDatasource.new(nil)
+    end
+
+    # Filters the query result for the given columns and sets the result
+    # in the preformatted SQL result style.
+    #
+    # Additionally it applies {AbstractQuery#format_columns}, {AbstractQuery#replace_values} and
+    # {AbstractQuery#filter_columns}.
+    # @return [void]
+    def post_process
+      @result = format_columns(@result, @variables['format'])
+      @result = replace_values(@result, @variables.select { |k, _v| k =~ /^replace_values_\d+/ })
+      @result = filter_columns(@result, @variables['filter_columns'])
+
+      # TODO: move formatting to Asciidoctor namespace
+      @result = result[:content].map { |row| "| #{row.map { |item| item.to_s.gsub('|', '\\|') }.join(' | ')}" }
+    end
+  end
+end

data/lib/grafana_reporter/application/application.rb

@@ -13,61 +13,79 @@ module GrafanaReporter
     # It can be run to test the grafana connection, render a single template
     # or run as a service.
     class Application
-      # Default file name for grafana reporter configuration file
-      CONFIG_FILE = 'grafana_reporter.config'
-
-      def initialize
-        @logger = ::Logger.new($stdout, level: :unknown)
-      end
 
       # Contains the {Configuration} object of the application.
       attr_accessor :config
 
+      # Stores the {Webservice} object of the application
+      attr_reader :webservice
+
+      def initialize
+        @config = Configuration.new
+        @webservice = Webservice.new
+      end
+
       # This is the main method, which is called, if the application is
       # run in standalone mode.
       # @param params [Array<String>] command line parameters, mainly ARGV can be used.
       # @return [Integer] 0 if everything is fine, -1 if execution aborted.
       def configure_and_run(params = [])
-        config_file = CONFIG_FILE
-        cli_config = {}
-        cli_config ['grafana-reporter'] = {}
-        cli_config ['default-document-attributes'] = {}
+        config_file = Configuration::DEFAULT_CONFIG_FILE_NAME
+        tmp_config = Configuration.new
+        action_wizard = false
 
         parser = OptionParser.new do |opts|
-          opts.banner = "Usage: ruby #{$PROGRAM_NAME} [options]"
+          opts.banner = if ENV['OCRA_EXECUTABLE']
+                          "Usage: #{ENV['OCRA_EXECUTABLE'].gsub("#{Dir.pwd}/".gsub('/', '\\'), '')} [options]"
+                        else
+                          "Usage: #{Gem.ruby} #{$PROGRAM_NAME} [options]"
+                        end
 
           opts.on('-c', '--config CONFIG_FILE_NAME', 'Specify custom configuration file,'\
-                  " instead of #{CONFIG_FILE}.") do |file_name|
+                  " instead of #{Configuration::DEFAULT_CONFIG_FILE_NAME}.") do |file_name|
             config_file = file_name
           end
 
+          opts.on('-r', '--register FILE', 'Register a custom plugin, e.g. your own Datasource implementation') do |plugin|
+            require plugin
+          end
+
           opts.on('-d', '--debug LEVEL', 'Specify detail level: FATAL, ERROR, WARN, INFO, DEBUG.') do |level|
-            if level =~ /(?:FATAL|ERROR|WARN|INFO|DEBUG)/
-              @logger.level = Object.const_get("::Logger::Severity::#{level}")
-            end
+            tmp_config.set_param('grafana-reporter:debug-level', level)
           end
 
           opts.on('-o', '--output FILE', 'Output filename if only a single file is rendered') do |file|
-            cli_config['to_file'] = file
+            tmp_config.set_param('to_file', file)
           end
 
-          opts.on('-s', '--set VARIABLE,VALUE', Array, 'Set a variable value, which will be passed to the rendering') do |list|
-            raise ParameterValueError.new(list.length) unless list.length == 2
-            cli_config['default-document-attributes'][list[0]] = list[1]
+          opts.on('-s', '--set VARIABLE,VALUE', Array, 'Set a variable value, which will be passed to the '\
+                  'rendering') do |list|
+            raise ParameterValueError, list.length unless list.length == 2
+
+            tmp_config.set_param("default-document-attributes:#{list[0]}", list[1])
+          end
+
+          opts.on('--ssl-cert FILE', 'Manually specify a SSL cert file for HTTPS connection to grafana. Only '\
+                  'needed if not working properly otherwise.') do |file|
+            if File.file?(file)
+              tmp_config.set_param('grafana-reporter:ssl-cert', file)
+            else
+              config.logger.warn("SSL certificate file #{file} does not exist. Setting will be ignored.")
+            end
           end
 
           opts.on('--test GRAFANA_INSTANCE', 'test current configuration against given GRAFANA_INSTANCE') do |instance|
-            cli_config['grafana-reporter']['run-mode'] = 'test'
-            cli_config['grafana-reporter']['test-instance'] = instance
+            tmp_config.set_param('grafana-reporter:run-mode', 'test')
+            tmp_config.set_param('grafana-reporter:test-instance', instance)
           end
 
           opts.on('-t', '--template TEMPLATE', 'Render a single ASCIIDOC template to PDF and exit') do |template|
-            cli_config['grafana-reporter']['run-mode'] = 'single-render'
-            cli_config['default-document-attributes']['var-template'] = template
+            tmp_config.set_param('grafana-reporter:run-mode', 'single-render')
+            tmp_config.set_param('default-document-attributes:var-template', template)
           end
 
           opts.on('-w', '--wizard', 'Configuration wizard to prepare environment for the reporter.') do
-            return config_wizard
+            action_wizard = true
           end
 
           opts.on('-v', '--version', 'Version information') do
@@ -83,31 +101,22 @@ module GrafanaReporter
 
         begin
           parser.parse!(params)
+          return ConsoleConfigurationWizard.new.start_wizard(config_file, tmp_config) if action_wizard
         rescue ApplicationError => e
           puts e.message
           return -1
         end
 
         # abort if config file does not exist
-        unless File.exist?(config_file)
+        unless File.file?(config_file)
           puts "Config file '#{config_file}' does not exist. Consider calling the configuration wizard"\
                ' with option \'-w\' or use \'-h\' to see help message. Aborting.'
           return -1
         end
 
-        # read config file
-        @config = GrafanaReporter::Configuration.new
-        config.logger = @logger
-        config_hash = nil
-        begin
-          config_hash = YAML.load_file(config_file)
-        rescue StandardError => e
-          raise ConfigurationError, "Could not read config file '#{config_file}' (Error: #{e.message})"
-        end
-
         # merge command line configuration with read config file
-        config_hash.merge!(cli_config) { |_key, v1, v2| Hash === v1 && Hash === v2 ? v1.merge(v2) : v2 }
-        config.config = config_hash
+        @config.load_config_from_file(config_file)
+        @config.merge!(tmp_config)
 
         run
       end
@@ -131,274 +140,17 @@ module GrafanaReporter
 
         when Configuration::MODE_SINGLE_RENDER
           begin
-            config.report_class.new(config, config.template, config.to_file).create_report
+            config.report_class.new(config).create_report(config.template, config.to_file)
           rescue StandardError => e
-            puts e.message
+            puts "#{e.message}\n#{e.backtrace.join("\n")}"
           end
 
         when Configuration::MODE_SERVICE
-          Webservice.new(config).run
+          @webservice.run(config)
         end
 
         0
       end
-
-      private
-
-      # Provides a command line configuration wizard for setting up the necessary configuration
-      # file.
-      def config_wizard
-        if File.exist?(CONFIG_FILE)
-          input = nil
-          until input
-            input = user_input("Configuration file '#{CONFIG_FILE}' already exists. Do you want to overwrite it?", 'yN')
-            return if input =~ /^(?:n|N|yN)$/
-          end
-        end
-
-        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
-        port = ui_config_port
-        grafana = ui_config_grafana
-        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:
-  templates-folder: #{templates}
-  reports-folder: #{reports}
-  report-retention: #{retention}
-  webservice-port: #{port}
-
-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 = Configuration.new
-        begin
-          config.config = YAML.load_file(CONFIG_FILE)
-          puts 'Configuration file validated successfully.'
-        rescue StandardError => e
-          raise ConfigurationError, "Could not read config file '#{CONFIG_FILE}' (Error: #{e.message})\n"\
-                "Source:\n#{File.read(CONFIG_FILE)}"
-        end
-
-        # create a demo report
-        unless Dir.exist?(config.templates_folder)
-          puts "Skip creation of DEMO template, as folder '#{config.templates_folder}' does not exist."
-          return
-        end
-        demo_report = %(= First Grafana Report Template
-
-include::grafana_help[]
-
-include::grafana_environment[])
-
-        demo_report_file = "#{config.templates_folder}demo_report.adoc"
-        if File.exist?(demo_report_file)
-          puts "Skip creation of DEMO template, as file '#{demo_report_file}' already exists."
-        else
-          begin
-            File.write(demo_report_file, demo_report, mode: 'w')
-            puts "DEMO template '#{demo_report_file}' successfully created."
-          rescue StandardError => e
-            raise e
-          end
-        end
-
-        puts
-        puts 'Now everything is setup properly. Run the grafana reporter without any command to start the service.'
-        puts
-        puts '   ruby-grafana-reporter'
-        puts
-        puts "Open 'http://localhost:#{config.webserver_port}/render?var-template=demo_report' in a webbrowser to"
-        puts 'verify your configuration.'
-      end
-
-      def ui_config_grafana
-        valid = false
-        url = nil
-        api_key = nil
-        datasources = ''
-        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: @logger).test_connection
-          rescue StandardError => e
-            puts
-            puts e.message
-          end
-          puts 'done.'
-
-          case res
-          when 'Admin'
-            valid = true
-
-          when 'NON-Admin'
-            print 'Access to grafana is permitted as NON-Admin. Do you want to use an [a]pi key,'\
-                  ' configure [d]atasource manually, [r]e-enter api key or [i]gnore? [adRi]: '
-
-            case gets
-            when /(?:i|I)$/
-              valid = true
-
-            when /(?:a|A)$/
-              print 'Enter API key: '
-              api_key = gets.sub(/\n$/, '')
-
-            when /(?:r|R|adRi)$/
-              api_key = nil
-
-            when /(?:d|D)$/
-              valid = true
-              datasources = ui_config_datasources
-
-            end
-
-          else
-            print "Grafana could not be accessed at '#{url}'. Do you want do [r]e-enter url, or"\
-                 ' [i]gnore and proceed? [Ri]: '
-
-            case gets
-            when /(?:i|I)$/
-              valid = true
-
-            else
-              url = nil
-              api_key = nil
-
-            end
-
-          end
-        end
-        %(grafana:
-  default:
-    host: #{url}#{api_key ? "\n    api_key: #{api_key}" : ''}#{datasources ? "\n#{datasources}" : ''}
-)
-      end
-
-      def ui_config_datasources
-        finished = false
-        datasources = []
-        until finished
-          item = {}
-          print "Datasource ###{datasources.length + 1}) Enter datasource name as configured in grafana: "
-          item[:ds_name] = gets.sub(/\n$/, '')
-          print "Datasource ###{datasources.length + 1}) Enter datasource id: "
-          item[:ds_id] = gets.sub(/\n$/, '')
-
-          puts
-          selection = user_input("Datasource name: '#{item[:ds_name]}', Datasource id: '#{item[:ds_id]}'."\
-                                 ' [A]ccept, [r]etry or [c]ancel?', 'Arc')
-
-          case selection
-          when /(?:Arc|A|a)$/
-            datasources << item
-            another = user_input('Add [a]nother datasource or [d]one?', 'aD')
-            finished = true if another =~ /(?:d|D)$/
-
-          when /(?:c|C)$/
-            finished = true
-
-          end
-        end
-        "    datasources:\n#{datasources.collect { |el| "      #{el[:ds_name]}: #{el[:ds_id]}" }.join('\n')}"
-      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
     end
   end
 end