ruby-grafana-reporter 0.4.2 → 0.5.0

data/lib/grafana_reporter/asciidoctor/panel_image_inline_macro.rb

@@ -7,8 +7,8 @@ module GrafanaReporter
     # Implements the hook
     #   grafana_panel_image:<panel_id>[<options>]
     #
-    # Stores the queried panel as a temporary image file and returns an asciidoctor link
-    # to be included in the report.
+    # Stores the queried panel as a temporary image file and returns a relative asciidoctor link
+    # to the storage location, which can then be included in the report.
     #
     # == Used document parameters
     # +grafana_default_instance+ - name of grafana instance, 'default' if not specified
@@ -20,8 +20,6 @@ module GrafanaReporter
     # +to+ - 'to' time for the sql query
     #
     # == Supported options
-    # +field+ - property to query for, e.g. +description+ or +title+ (*mandatory*)
-    #
     # +instance+ - name of grafana instance, 'default' if not specified
     #
     # +dashboard+ - uid of grafana dashboard to use
@@ -48,10 +46,14 @@ module GrafanaReporter
         begin
           # set alt text to a default, because otherwise asciidoctor fails
           attrs['alt'] = '' unless attrs['alt']
-          query = PanelImageQuery.new(@report.grafana(instance).dashboard(dashboard).panel(target), variables: build_attribute_hash(parent.document.attributes, attrs))
+          query = PanelImageQuery.new(@report.grafana(instance).dashboard(dashboard).panel(target),
+                                      variables: build_attribute_hash(parent.document.attributes, attrs))
 
           image = query.execute
           image_path = @report.save_image_file(image)
+        rescue Grafana::GrafanaError => e
+          @report.logger.error(e.message)
+          return create_inline(parent, :quoted, e.message)
         rescue GrafanaReporterError => e
           @report.logger.error(e.message)
           return create_inline(parent, :quoted, e.message)

data/lib/grafana_reporter/asciidoctor/panel_property_inline_macro.rb

@@ -38,10 +38,14 @@ module GrafanaReporter
                              " panel: #{target}, property: #{attrs[:field]})")
 
         begin
-          query = PanelPropertyQuery.new(@report.grafana(instance).dashboard(dashboard).panel(target), variables: build_attribute_hash(parent.document.attributes, attrs))
+          query = PanelPropertyQuery.new(@report.grafana(instance).dashboard(dashboard).panel(target),
+                                         variables: build_attribute_hash(parent.document.attributes, attrs))
           query.raw_query = { property_name: attrs[:field] }
 
           description = query.execute
+        rescue Grafana::GrafanaError => e
+          @report.logger.error(e.message)
+          return create_inline(parent, :quoted, e.message)
         rescue GrafanaReporterError => e
           @report.logger.error(e.message)
           return create_inline(parent, :quoted, e.message)

data/lib/grafana_reporter/asciidoctor/panel_query_table_include_processor.rb

@@ -59,9 +59,13 @@ module GrafanaReporter
 
         begin
           panel = @report.grafana(instance).dashboard(dashboard).panel(panel_id)
-          query = QueryValueQuery.new(panel, variables: build_attribute_hash(doc.attributes, attrs))
+          vars = { 'table_formatter' => 'adoc_plain' }.merge(build_attribute_hash(doc.attributes, attrs))
+          query = QueryValueQuery.new(panel, variables: vars)
 
-          reader.unshift_lines query.execute
+          reader.unshift_lines query.execute.split("\n")
+        rescue Grafana::GrafanaError => e
+          @report.logger.error(e.message)
+          reader.unshift_line "|#{e.message}"
         rescue GrafanaReporterError => e
           @report.logger.error(e.message)
           reader.unshift_line "|#{e.message}"

data/lib/grafana_reporter/asciidoctor/panel_query_value_inline_macro.rb

@@ -59,6 +59,9 @@ module GrafanaReporter
           query = QueryValueQuery.new(panel, variables: build_attribute_hash(parent.document.attributes, attrs))
 
           create_inline(parent, :quoted, query.execute)
+        rescue Grafana::GrafanaError => e
+          @report.logger.error(e.message)
+          create_inline(parent, :quoted, e.message)
         rescue GrafanaReporterError => e
           @report.logger.error(e.message)
           create_inline(parent, :quoted, e.message)

data/lib/grafana_reporter/asciidoctor/processor_mixin.rb

@@ -38,8 +38,9 @@ module GrafanaReporter
           # TODO: specify accepted options for each processor class individually
           k =~ /^(?:var-|render-)/ ||
           k =~ /^(?:timeout|from|to)$/ ||
-          k =~ /filter_columns|format|replace_values_.*|transpose|column_divider|
-               row_divider|from_timezone|to_timezone|result_type|query/x
+          k =~ /filter_columns|format|replace_values_.*|transpose|from_timezone|
+               to_timezone|result_type|query|table_formatter|include_headline|
+               column_divider|row_divider/x
         end)
 
         result

data/lib/grafana_reporter/asciidoctor/report.rb

@@ -15,7 +15,7 @@ module GrafanaReporter
       # 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)
+      def build
         attrs = { 'convert-backend' => 'pdf' }.merge(@config.default_document_attributes.merge(@custom_attributes))
         logger.debug("Document attributes: #{attrs}")
 
@@ -41,22 +41,14 @@ module GrafanaReporter
         ::Asciidoctor.convert_file(@template, extension_registry: registry, backend: attrs['convert-backend'],
                                               to_file: path, attributes: attrs, header_footer: true)
 
-        @destination_file_or_path.close if @destination_file_or_path.is_a?(File)
-
         # store report including als images as ZIP file, if the result is not a PDF
         if attrs['convert-backend'] != 'pdf'
-          dest_path = if @destination_file_or_path.is_a?(File) || @destination_file_or_path.is_a?(Tempfile)
-                        @destination_file_or_path.path
-                      else
-                        @destination_file_or_path
-                      end
-
           # build zip file
           zip_file = Tempfile.new('gf_zip')
           buffer = Zip::OutputStream.write_buffer do |zipfile|
             # add report file
-            zipfile.put_next_entry("#{dest_path.gsub(@config.reports_folder, '')}.#{attrs['convert-backend']}")
-            zipfile.write File.read(dest_path)
+            zipfile.put_next_entry("#{path.gsub(@config.reports_folder, '')}.#{attrs['convert-backend']}")
+            zipfile.write File.read(path)
 
             # add image files
             @image_files.each do |file|
@@ -71,9 +63,9 @@ module GrafanaReporter
           # replace original file with zip file
           zip_file.rewind
           begin
-            File.write(dest_path, zip_file.read)
+            File.write(path, zip_file.read)
           rescue StandardError => e
-            logger.fatal("Could not overwrite report file '#{dest_path}' with ZIP file. (#{e.message}).")
+            logger.fatal("Could not overwrite report file '#{path}' with ZIP file. (#{e.message}).")
           end
 
           # cleanup temporary zip file
@@ -100,6 +92,16 @@ module GrafanaReporter
         path
       end
 
+      # @see AbstractReport#default_template_extension
+      def self.default_template_extension
+        'adoc'
+      end
+
+      # @see AbstractReport#default_result_extension
+      def self.default_result_extension
+        'pdf'
+      end
+
       # @see AbstractReport#demo_report_classes
       def self.demo_report_classes
         [AlertsTableIncludeProcessor, AnnotationsTableIncludeProcessor, PanelImageBlockMacro, PanelImageInlineMacro,

data/lib/grafana_reporter/asciidoctor/show_environment_include_processor.rb

@@ -13,6 +13,9 @@ module GrafanaReporter
     #
     # == Used document parameters
     # All, to be listed as the available environment.
+    #
+    # == Supported options
+    # +instance+ - grafana instance name, if extended information about the grafana instance shall be printed
     class ShowEnvironmentIncludeProcessor < ::Asciidoctor::Extensions::IncludeProcessor
       include ProcessorMixin
 
@@ -22,19 +25,47 @@ module GrafanaReporter
       end
 
       # :nodoc:
-      def process(doc, reader, _target, _attrs)
+      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 ShowEnvironmentIncludeProcessor')
+        grafana = @report.grafana(instance)
+
+        vars = { 'table_formatter' => 'adoc_plain', 'include_headline' => 'true'}
+        vars = vars.merge(build_attribute_hash(doc.attributes, attrs))
+
+        # query reporter environment
+        result = ['== Reporter', '|===']
+        query = QueryValueQuery.new(grafana, variables: vars.merge({'transpose' => 'true'}))
+        query.datasource = ::GrafanaReporter::ReporterEnvironmentDatasource.new(nil)
+        result += query.execute.split("\n")
+
+        # query grafana environment
+        result += ['|===', '',
+                   '== Grafana Instance', '|===']
+        query = QueryValueQuery.new(grafana, variables: vars.merge({'transpose' => 'true'}))
+        query.raw_query = {grafana: grafana, mode: 'general'}
+        query.datasource = ::Grafana::GrafanaEnvironmentDatasource.new(nil)
+        result += query.execute.split("\n")
+
+        result += ['|===', '',
+                   '== Accessible Dashboards', '|===']
+        query = QueryValueQuery.new(grafana, variables: vars)
+        query.raw_query = {grafana: grafana, mode: 'dashboards'}
+        query.datasource = Grafana::GrafanaEnvironmentDatasource.new(nil)
+        result += query.execute.split("\n")
 
-        vars = ['== Accessible Variables',
-                '|===']
+        result += ['|===', '',
+                   '== Accessible Variables',
+                   '|===']
         doc.attributes.sort.each do |k, v|
-          vars << "| `+{#{k}}+` | #{v}"
+          result << "| `+{#{k}}+` | #{v}"
         end
-        vars << '|==='
+        result << '|==='
 
-        reader.unshift_lines vars
+        reader.unshift_lines result
       end
 
       # @see ProcessorMixin#build_demo_entry

data/lib/grafana_reporter/asciidoctor/show_help_include_processor.rb

@@ -23,7 +23,7 @@ module GrafanaReporter
         @report.next_step
         @report.logger.debug('Processing ShowHelpIncludeProcessor')
 
-        reader.unshift_lines GrafanaReporter::Help.new.asciidoctor.split("\n")
+        reader.unshift_lines Help.new.asciidoctor.split("\n")
       end
 
       # @see ProcessorMixin#build_demo_entry

data/lib/grafana_reporter/asciidoctor/sql_table_include_processor.rb

@@ -51,11 +51,15 @@ module GrafanaReporter
 
         begin
           # catch properly if datasource could not be identified
-          query = QueryValueQuery.new(@report.grafana(instance), variables: build_attribute_hash(doc.attributes, attrs))
+          vars = { 'table_formatter' => 'adoc_plain' }.merge(build_attribute_hash(doc.attributes, attrs))
+          query = QueryValueQuery.new(@report.grafana(instance), variables: vars)
           query.datasource = @report.grafana(instance).datasource_by_id(target.split(':')[1].to_i)
           query.raw_query = attrs['sql']
 
-          reader.unshift_lines query.execute
+          reader.unshift_lines query.execute.split("\n")
+        rescue Grafana::GrafanaError => e
+          @report.logger.error(e.message)
+          reader.unshift_line "|#{e.message}"
         rescue GrafanaReporterError => e
           @report.logger.error(e.message)
           reader.unshift_line "|#{e.message}"

data/lib/grafana_reporter/asciidoctor/sql_value_inline_macro.rb

@@ -49,11 +49,15 @@ module GrafanaReporter
 
         begin
           # catch properly if datasource could not be identified
-          query = QueryValueQuery.new(@report.grafana(instance), variables: build_attribute_hash(parent.document.attributes, attrs))
+          query = QueryValueQuery.new(@report.grafana(instance),
+                                      variables: build_attribute_hash(parent.document.attributes, attrs))
           query.datasource = @report.grafana(instance).datasource_by_id(target)
           query.raw_query = attrs['sql']
 
           create_inline(parent, :quoted, query.execute)
+        rescue Grafana::GrafanaError => e
+          @report.logger.error(e.message)
+          create_inline(parent, :quoted, e.message)
         rescue GrafanaReporterError => e
           @report.logger.error(e.message)
           create_inline(parent, :quoted, e.message)

data/lib/grafana_reporter/asciidoctor/value_as_variable_include_processor.rb

@@ -58,11 +58,6 @@ module GrafanaReporter
           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

data/lib/grafana_reporter/configuration.rb

@@ -152,6 +152,32 @@ module GrafanaReporter
       get_config('default-document-attributes') || {}
     end
 
+    # Checks if this is the latest ruby-grafana-reporter version. If and how often the check if
+    # performed, depends on the configuration setting `check-for-updates`. By default this is
+    # 0 (=disabled). If a number >0 is specified, the checks are performed once every n-days on
+    # report creation or call of overview webpage.
+    # @return [Boolean] true, if is ok, false if a newer version exists
+    def latest_version_check_ok?
+      return false if @newer_version_exists
+
+      value = get_config('grafana-reporter:check-for-updates') || 0
+      return true if value <= 0
+
+      # repeat check only every n-th day
+      if @last_version_check
+        return true if (Time.now - @last_version_check) < (value * 24*60*60)
+      end
+
+      # check for newer version
+      @last_version_check = Time.now
+      url = 'https://github.com/divinity666/ruby-grafana-reporter/releases/latest'
+      response = Grafana::WebRequest.new(url).execute
+      return true if response['location'] =~ /.*[\/v]#{GRAFANA_REPORTER_VERSION.join('.')}$/
+
+      @newer_version_exists = true
+      return false
+    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.
@@ -304,6 +330,7 @@ module GrafanaReporter
         [
           Hash, 1,
           {
+            'check-for-updates' => [Integer, 0],
             'debug-level' => [String, 0],
             'run-mode' => [String, 0],
             'test-instance' => [String, 0],

data/lib/grafana_reporter/console_configuration_wizard.rb

@@ -6,7 +6,6 @@ module GrafanaReporter
   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'
@@ -39,7 +38,7 @@ module GrafanaReporter
       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 "   #{program_call}#{config_param} -t #{demo_report} -o demo_report.#{config.report_class.default_result_extension}"
       puts
       puts 'or run it as a service using the following command:'
       puts
@@ -73,6 +72,9 @@ module GrafanaReporter
 #{grafana}
 
 grafana-reporter:
+# Specifies how often the reporter shall check for newer versions [number of days].
+# You may set check-for-updates to 0 to disable
+  check-for-updates: 1
   report-class: GrafanaReporter::Asciidoctor::Report
   templates-folder: #{templates}
   reports-folder: #{reports}
@@ -120,7 +122,7 @@ default-document-attributes:
       return nil unless create =~ /^(?:y|Y)$/
 
       demo_report = 'demo_report'
-      demo_report_file = "#{config.templates_folder}#{demo_report}.adoc"
+      demo_report_file = "#{config.templates_folder}#{demo_report}.#{config.report_class.default_template_extension}"
 
       # ask to overwrite file
       if File.exist?(demo_report_file)

data/lib/grafana_reporter/csv_table_format_strategy.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module GrafanaReporter
+  # Implements a default table format strategy, which will return tables
+  # as CSV formatted strings.
+  class CsvTableFormatStrategy < AbstractTableFormatStrategy
+    # @see AbstractTableFormatStrategy#abbreviation
+    def self.abbreviation
+      'csv'
+    end
+
+    # @see AbstractTableFormatStrategy#format_rules
+    def format_rules
+      {
+        row_start: '',
+        row_end: "\n",
+        cell_start: '',
+        between_cells: ', ',
+        cell_end: '',
+        replace_string_or_regex: ',',
+        replacement: '\\,'
+      }
+    end
+  end
+end

data/lib/grafana_reporter/demo_report_wizard.rb

@@ -55,12 +55,6 @@ module GrafanaReporter
       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}"
@@ -77,6 +71,9 @@ module GrafanaReporter
             # currently not allowed
           rescue StandardError => e
             puts "#{e.message}\n#{e.backtrace.join("\n")}"
+          rescue NotImplementedError
+            # Ignore these errors, as it only means, that a class does not implement
+            # the demo entry
           end
         end
       end
@@ -84,7 +81,6 @@ module GrafanaReporter
       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('.')}",

data/lib/grafana_reporter/erb/demo_report_builder.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module GrafanaReporter
+  module ERB
+    # This class builds a demo report for ERB templates
+    class DemoReportBuilder
+      # This method is called if a demo report shall be built for the given {Grafana::Panel}.
+      # @param panel [Grafana::Panel] panel object, for which a demo entry shall be created.
+      # @return [String] String containing the entry, or nil if not possible for given panel
+      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
+
+        <<~DEMO_ERB_TEMPLATE
+          <%
+          dashboard = '#{panel.dashboard.id}'
+          instance = 'default'
+          # load the panel object from grafana instance
+          panel = @report.grafana(instance).dashboard(dashboard).panel(#{panel.id})
+          # build a complete attributes hash, including the variables set for this report call
+          # e.g. including command line parameters etc.
+          attrs = @attributes.merge({ 'result_type' => 'panel_table', 'query' => '#{ref_id}' })
+          query = QueryValueQuery.new(panel, variables: attrs)
+          %>
+
+          This is a test table for panel <%= panel.id %>:
+
+          <%= query.execute %>
+
+          For detailed API documentation you may start with:
+            1) the AbstractReport (https://rubydoc.info/gems/ruby-grafana-reporter/GrafanaReporter/AbstractReport), or
+            2) subclasses of the AbstractQuery (https://rubydoc.info/gems/ruby-grafana-reporter/GrafanaReporter/AbstractQuery)
+        DEMO_ERB_TEMPLATE
+      end
+    end
+  end
+end

data/lib/grafana_reporter/erb/report.rb

@@ -10,20 +10,26 @@ module GrafanaReporter
       # 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)
+      def build
+        attrs = @config.default_document_attributes.merge(@custom_attributes).merge({ 'grafana_report_timestamp' => ::Grafana::Variable.new(Time.now.to_s) })
         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))
+        File.write(path, ::ERB.new(File.read(@template)).result(ReportJail.new(self, attrs).bind))
+      end
+
+      # @see AbstractReport#default_template_extension
+      def self.default_template_extension
+        'erb'
+      end
 
-        # 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)
+      # @see AbstractReport#default_result_extension
+      def self.default_result_extension
+        'txt'
       end
 
       # @see AbstractReport#demo_report_classes
       def self.demo_report_classes
-        []
+        [DemoReportBuilder]
       end
     end
   end

data/lib/grafana_reporter/errors.rb

@@ -10,23 +10,25 @@ module GrafanaReporter
 
   # Raised if a datasource shall be queried, which is not (yet) supported by the reporter
   class DatasourceNotSupportedError < GrafanaReporterError
-    def initialize(ds, query)
-      super("The datasource '#{ds.name}' is of type '#{ds.type}' which is currently not supported for "\
-            "the query type '#{query}'.")
+    def initialize(datasource, query)
+      super("The datasource '#{datasource.name}' is of type '#{datasource.type}' which is currently "\
+            "not supported for the query type '#{query}'.")
     end
   end
 
   # Raised if some unhandled exception is raised during a datasource request execution.
   class DatasourceRequestInternalError < GrafanaReporterError
-    def initialize(ds, message)
-      super("The datasource request to '#{ds.name}' (#{ds.class}) failed with an internal error: #{message}")
+    def initialize(datasource, message)
+      super("The datasource request to '#{datasource.name}' (#{datasource.class}) failed with "\
+            "an internal error: #{message}")
     end
   end
 
   # Raised if the return value of a datasource request does not match the expected return hash.
   class DatasourceRequestInvalidReturnValueError < GrafanaReporterError
-    def initialize(ds, message)
-      super("The datasource request to '#{ds.name}' (#{ds.class}) returned an invalid value: '#{message}'")
+    def initialize(datasource, message)
+      super("The datasource request to '#{datasource.name}' (#{datasource.class})"\
+            "returned an invalid value: '#{message}'")
     end
   end
 

data/lib/grafana_reporter/panel_image_query.rb

@@ -5,6 +5,7 @@ module GrafanaReporter
   class PanelImageQuery < AbstractQuery
     # Sets the proper render variables.
     def pre_process
+      # TODO: properly show error, if a (maybe a repeated template) panel can not be rendered
       # TODO: ensure that in case of timezones are specified, that they are also forwarded to the image renderer
       # rename "render-" variables
       @variables = @variables.each_with_object({}) { |(k, v), h| h[k.gsub(/^render-/, '')] = v }
@@ -14,7 +15,6 @@ module GrafanaReporter
     # Returns the body of the http query, which contains the raw image.
     def post_process
       @result = @result[:content].first
-      raise ::Grafana::ImageCouldNotBeRenderedError, @panel if @result.include?('<html')
     end
 
     # @see AbstractQuery#raw_query

data/lib/grafana_reporter/query_value_query.rb

@@ -19,8 +19,14 @@ module GrafanaReporter
       modify_results
 
       case @variables['result_type'].raw_value
+      when 'object'
+
       when /(?:panel_table|sql_table)/
-        @result = format_table_output(@result, row_divider: @variables['row_divider'], column_divider: @variables['column_divider'])
+        @result = format_table_output(@result, row_divider: @variables['row_divider'],
+                                               column_divider: @variables['column_divider'],
+                                               table_formatter: @variables['table_formatter'],
+                                               include_headline: @variables['include_headline'],
+                                               transpose: @variables['transpose'])
 
       when /(?:panel_value|sql_value)/
         tmp = @result[:content] || []

data/lib/grafana_reporter/report_webhook.rb

@@ -12,14 +12,18 @@ module GrafanaReporter
     # Implements the call of the configured webhook.
     # Provides the following report information in JSON format:
     #
-    # +object_id+ - id of the current report
-    # +path+ - file path to the report
-    # +status+ - report status as string, e.g. +cancelled+, +finished+ or +in progress+
-    # +execution_time+ - execution time of the report
-    # +template+ - name of the used template
-    # +start_time+ - time when the report creation started
-    # +end_time+ - time when the report creation ended
-    # +event+ - event, which has happened
+    #   :object_id      - id of the current report
+    #   :path           - file path to the report
+    #   :status         - report status as string, e.g. `cancelled`, `finished` or `in progress`
+    #   :execution_time - execution time in seconds of the report
+    #   :template       - name of the used template
+    #   :start_time     - time when the report creation started
+    #   :end_time       - time when the report creation ended
+    #   :event          - event, which has happened, e.g. `on-before-create`
+    #
+    # Please note that this callback is a non-blocking event, i.e. the report
+    # generation is proceeding, no matter if the callback is successfull and
+    # no matter how long the execution of the callback does take.
     def callback(event, report)
       # build report information as JSON
       data = { object_id: report.object_id, path: report.path, status: report.status,

data/lib/grafana_reporter/reporter_environment_datasource.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module GrafanaReporter
+  # Implements a datasource to return environment related information about the reporter in a tabular format.
+  class ReporterEnvironmentDatasource < ::Grafana::AbstractDatasource
+    # @see AbstractDatasource#request
+    def request(query_description)
+      {
+        header: ['Version', 'Release Date'],
+        content: [[GRAFANA_REPORTER_VERSION.join('.'), GRAFANA_REPORTER_RELEASE_DATE]]
+      }
+    end
+
+    # @see AbstractDatasource#default_variable_format
+    def default_variable_format
+      nil
+    end
+
+    # @see AbstractDatasource#name
+    def name
+      self.class.to_s
+    end
+  end
+end