ruby-grafana-reporter 0.3.0 → 0.4.4

data/lib/grafana_reporter/asciidoctor/report.rb

@@ -1,27 +1,22 @@
 # frozen_string_literal: true
 
 module GrafanaReporter
+  # This module contains all classes, which are necessary to use the reporter in conjunction with asciidoctor.
   module Asciidoctor
     # Implementation of a specific {AbstractReport}. It is used to
     # build reports specifically for asciidoctor results.
-    class Report < GrafanaReporter::AbstractReport
-      # (see AbstractReport#initialize)
-      def initialize(config, template, destination_file_or_path = nil, custom_attributes = {})
+    class Report < ::GrafanaReporter::AbstractReport
+      # @see AbstractReport#initialize
+      def initialize(config)
         super
-        @current_pos = 0
         @image_files = []
-        @grafana_instances = {}
       end
 
-      # Starts to create an asciidoctor report. It utilizes all {Extensions} to
-      # realize the conversion.
-      # @see AbstractReport#create_report
-      # @return [void]
-      def create_report
-        @start_time = Time.now
+      # Starts to create an asciidoctor report. It utilizes all extensions in the {GrafanaReporter::Asciidoctor}
+      # namespace to realize the conversion.
+      # @see AbstractReport#build
+      def build
         attrs = { 'convert-backend' => 'pdf' }.merge(@config.default_document_attributes.merge(@custom_attributes))
-        attrs['grafana-report-timestamp'] = @start_time.to_s
-        logger.info("Report started at #{@start_time}")
         logger.debug("Document attributes: #{attrs}")
 
         initialize_step_counter
@@ -30,43 +25,30 @@ module GrafanaReporter
         ::Asciidoctor::LoggerManager.logger = logger
 
         registry = ::Asciidoctor::Extensions::Registry.new
-        # TODO: dynamically register macros, which is also needed when supporting custom macros
-        registry.inline_macro Extensions::PanelImageInlineMacro.new.current_report(self)
-        registry.inline_macro Extensions::PanelQueryValueInlineMacro.new.current_report(self)
-        registry.inline_macro Extensions::PanelPropertyInlineMacro.new.current_report(self)
-        registry.inline_macro Extensions::SqlValueInlineMacro.new.current_report(self)
-        registry.block_macro Extensions::PanelImageBlockMacro.new.current_report(self)
-        registry.include_processor Extensions::ValueAsVariableIncludeProcessor.new.current_report(self)
-        registry.include_processor Extensions::PanelQueryTableIncludeProcessor.new.current_report(self)
-        registry.include_processor Extensions::SqlTableIncludeProcessor.new.current_report(self)
-        registry.include_processor Extensions::ShowEnvironmentIncludeProcessor.new.current_report(self)
-        registry.include_processor Extensions::ShowHelpIncludeProcessor.new.current_report(self)
-        registry.include_processor Extensions::AnnotationsTableIncludeProcessor.new.current_report(self)
-        registry.include_processor Extensions::AlertsTableIncludeProcessor.new.current_report(self)
+        registry.inline_macro PanelImageInlineMacro.new.current_report(self)
+        registry.inline_macro PanelQueryValueInlineMacro.new.current_report(self)
+        registry.inline_macro PanelPropertyInlineMacro.new.current_report(self)
+        registry.inline_macro SqlValueInlineMacro.new.current_report(self)
+        registry.block_macro PanelImageBlockMacro.new.current_report(self)
+        registry.include_processor ValueAsVariableIncludeProcessor.new.current_report(self)
+        registry.include_processor PanelQueryTableIncludeProcessor.new.current_report(self)
+        registry.include_processor SqlTableIncludeProcessor.new.current_report(self)
+        registry.include_processor ShowEnvironmentIncludeProcessor.new.current_report(self)
+        registry.include_processor ShowHelpIncludeProcessor.new.current_report(self)
+        registry.include_processor AnnotationsTableIncludeProcessor.new.current_report(self)
+        registry.include_processor AlertsTableIncludeProcessor.new.current_report(self)
 
         ::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 = nil
-          case
-          when @destination_file_or_path.is_a?(File)
-            dest_path = @destination_file_or_path.path
-          when @destination_file_or_path.is_a?(Tempfile)
-            dest_path = @destination_file_or_path.path
-          else
-            dest_path = @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|
@@ -81,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
@@ -92,39 +74,6 @@ module GrafanaReporter
         end
 
         clean_image_files
-        @end_time = Time.now
-        logger.info("Report finished after #{@end_time - @start_time} seconds.")
-        @done = true
-      rescue StandardError => e
-        # catch all errors during execution
-        died_with_error(e)
-        raise e
-      end
-
-      # @see AbstractReport#progress
-      # @return [Float] number between 0 and 1 reflecting the current progress.
-      def progress
-        return 0 if @total_steps.to_i.zero?
-
-        @current_pos.to_f / @total_steps
-      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, ssl_cert: @config.ssl_cert)
-        end
-        @grafana_instances[instance]
-      end
-
-      # Increments the progress.
-      # @return [Integer] number of the current progress position.
-      def next_step
-        @current_pos += 1
-        @current_pos
       end
 
       # Called to save a temporary image file. After the final generation of the
@@ -133,6 +82,7 @@ module GrafanaReporter
       # @return [String] path to the temporary file.
       def save_image_file(img_data)
         file = Tempfile.new(['gf_image_', '.png'], @config.images_folder.to_s)
+        file.binmode
         file.write(img_data)
         path = file.path.gsub(/#{@config.images_folder}/, '')
 
@@ -142,13 +92,21 @@ module GrafanaReporter
         path
       end
 
-      # 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]
-        @end_time = Time.now
-        @done = true
+      # @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,
+         PanelPropertyInlineMacro, PanelQueryTableIncludeProcessor, PanelQueryValueInlineMacro,
+         SqlTableIncludeProcessor, SqlValueInlineMacro, ShowHelpIncludeProcessor, ShowEnvironmentIncludeProcessor]
       end
 
       private
@@ -162,6 +120,7 @@ module GrafanaReporter
         @total_steps = 0
         File.readlines(@template).each do |line|
           begin
+            # TODO: move these calls to the specific processors to ensure all are counted properly
             @total_steps += line.gsub(%r{//.*}, '').scan(/(?:grafana_panel_image|grafana_panel_query_value|
                                                          grafana_panel_query_table|grafana_sql_value|
                                                          grafana_sql_table|grafana_environment|grafana_help|

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 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,94 @@
+# 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 {AbstractQuery#format_columns}
+    #
+    # +replace_values+ - see {AbstractQuery#replace_values}
+    #
+    # +filter_columns+ - see {AbstractQuery#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
+          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
+        rescue 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}"
+        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,90 @@
+# 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 {AbstractQuery#format_columns}
+    #
+    # +replace_values+ - see {AbstractQuery#replace_values}
+    #
+    # +filter_columns+ - see {AbstractQuery#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),
+                                      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 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)
+        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