ruby-grafana-reporter 0.3.0 → 0.4.4

data/lib/grafana_reporter/asciidoctor/panel_image_block_macro.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative 'processor_mixin'
+
+module GrafanaReporter
+  module Asciidoctor
+    # 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.
+    #
+    # == Used document parameters
+    # +grafana_default_instance+ - name of grafana instance, 'default' if not specified
+    #
+    # +grafana_default_dashboard+ - uid of grafana default dashboard to use
+    #
+    # +from+ - 'from' time for the sql query
+    #
+    # +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
+    #
+    # +from+ - 'from' time for the sql query
+    #
+    # +to+ - 'to' time for the sql query
+    class PanelImageBlockMacro < ::Asciidoctor::Extensions::BlockMacroProcessor
+      include ProcessorMixin
+      use_dsl
+
+      named :grafana_panel_image
+
+      # :nodoc:
+      def process(parent, target, attrs)
+        return if @report.cancel
+
+        @report.next_step
+        instance = attrs['instance'] || parent.document.attr('grafana_default_instance') || 'default'
+        dashboard = attrs['dashboard'] || parent.document.attr('grafana_default_dashboard')
+        @report.logger.debug("Processing PanelImageBlockMacro (instance: #{instance}, dashboard: #{dashboard},"\
+                             " panel: #{target})")
+
+        begin
+          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 GrafanaError => e
+          @report.logger.error(e.message)
+          return create_paragraph(parent, e.message, attrs)
+        rescue GrafanaReporterError => e
+          @report.logger.error(e.message)
+          return create_paragraph(parent, e.message, attrs)
+        rescue StandardError => e
+          @report.logger.fatal(e.message)
+          return create_paragraph(parent, e.message, attrs)
+        end
+
+        attrs['target'] = image_path
+        create_image_block(parent, attrs)
+      end
+
+      # @see ProcessorMixin#build_demo_entry
+      def build_demo_entry(panel)
+        return nil unless panel
+        return nil unless panel.model['type'] == 'graph'
+
+        "grafana_panel_image::#{panel.id}[dashboard=\"#{panel.dashboard.id}\",width=\"50%\"]"
+      end
+    end
+  end
+end

data/lib/grafana_reporter/asciidoctor/panel_image_inline_macro.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative 'processor_mixin'
+
+module GrafanaReporter
+  module Asciidoctor
+    # 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.
+    #
+    # == Used document parameters
+    # +grafana_default_instance+ - name of grafana instance, 'default' if not specified
+    #
+    # +grafana_default_dashboard+ - uid of grafana default dashboard to use
+    #
+    # +from+ - 'from' time for the sql query
+    #
+    # +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
+    #
+    # +from+ - 'from' time for the sql query
+    #
+    # +to+ - 'to' time for the sql query
+    class PanelImageInlineMacro < ::Asciidoctor::Extensions::InlineMacroProcessor
+      include ProcessorMixin
+      use_dsl
+
+      named :grafana_panel_image
+
+      # :nodoc:
+      def process(parent, target, attrs)
+        return if @report.cancel
+
+        @report.next_step
+        instance = attrs['instance'] || parent.document.attr('grafana_default_instance') || 'default'
+        dashboard = attrs['dashboard'] || parent.document.attr('grafana_default_dashboard')
+        @report.logger.debug("Processing PanelImageInlineMacro (instance: #{instance}, dashboard: #{dashboard},"\
+                             " panel: #{target})")
+
+        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))
+
+          image = query.execute
+          image_path = @report.save_image_file(image)
+        rescue 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)
+        rescue StandardError => e
+          @report.logger.fatal(e.message)
+          return create_inline(parent, :quoted, e.message)
+        end
+
+        create_inline(parent, :image, nil, { target: image_path, attributes: attrs })
+      end
+
+      # @see ProcessorMixin#build_demo_entry
+      def build_demo_entry(panel)
+        return nil unless panel
+        return nil unless panel.model['type'] == 'graph'
+
+        "see here: grafana_panel_image:#{panel.id}[dashboard=\"#{panel.dashboard.id}\","\
+        'width="90%"] - a working inline image'
+      end
+    end
+  end
+end

data/lib/grafana_reporter/asciidoctor/panel_property_inline_macro.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative 'processor_mixin'
+
+module GrafanaReporter
+  module Asciidoctor
+    # Implements the hook
+    #   grafana_panel_property:<panel_id>[<options>]
+    #
+    # Returns the requested panel property.
+    #
+    # == Used document parameters
+    # +grafana_default_instance+ - name of grafana instance, 'default' if not specified
+    #
+    # +grafana_default_dashboard+ - uid of grafana default dashboard to use
+    #
+    # == 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
+    class PanelPropertyInlineMacro < ::Asciidoctor::Extensions::InlineMacroProcessor
+      include ProcessorMixin
+      use_dsl
+
+      named :grafana_panel_property
+      name_positional_attributes :field
+
+      # :nodoc:
+      def process(parent, target, attrs)
+        return if @report.cancel
+
+        @report.next_step
+        instance = attrs['instance'] || parent.document.attr('grafana_default_instance') || 'default'
+        dashboard = attrs['dashboard'] || parent.document.attr('grafana_default_dashboard')
+        @report.logger.debug("Processing PanelPropertyInlineMacro (instance: #{instance}, dashboard: #{dashboard},"\
+                             " 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.raw_query = { property_name: attrs[:field] }
+
+          description = query.execute
+        rescue 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)
+        rescue StandardError => e
+          @report.logger.fatal(e.message)
+          return create_inline(parent, :quoted, e.message)
+        end
+
+        # translate linebreaks to asciidoctor syntax
+        # and HTML encode to make sure, that HTML formattings are respected
+        create_inline(parent, :quoted, CGI.escapeHTML(description.gsub(%r{//[^\n]*(?:\n)?}, '').gsub(/\n/, " +\n")))
+      end
+
+      # @see ProcessorMixin#build_demo_entry
+      def build_demo_entry(panel)
+        return nil unless panel
+        return nil unless panel.model['title']
+        return nil if panel.model['title'].strip == ''
+        return nil if panel.model['title'].strip == 'Panel Title'
+
+        "this text includes the panel with title grafana_panel_property:#{panel.id}[\"title\","\
+        "dashboard=\"#{panel.dashboard.id}\"]"
+      end
+    end
+  end
+end

data/lib/grafana_reporter/asciidoctor/panel_query_table_include_processor.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative 'processor_mixin'
+
+module GrafanaReporter
+  module Asciidoctor
+    # Implements the hook
+    #   include::grafana_panel_query_table:<panel_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
+    #
+    # +grafana_default_dashboard+ - uid of grafana default dashboard to use
+    #
+    # +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
+    # +query+ - query letter, which shall be used, e.g. +C+ (*mandatory*)
+    #
+    # +instance+ - name of grafana instance, 'default' if not specified
+    #
+    # +dashboard+ - uid of grafana dashboard to use
+    #
+    # +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 PanelQueryTableIncludeProcessor < ::Asciidoctor::Extensions::IncludeProcessor
+      include ProcessorMixin
+
+      # :nodoc:
+      def handles?(target)
+        target.start_with? 'grafana_panel_query_table:'
+      end
+
+      # :nodoc:
+      def process(doc, reader, target, attrs)
+        return if @report.cancel
+
+        @report.next_step
+        panel_id = target.split(':')[1]
+        instance = attrs['instance'] || doc.attr('grafana_default_instance') || 'default'
+        dashboard = attrs['dashboard'] || doc.attr('grafana_default_dashboard')
+        attrs['result_type'] = 'panel_table'
+        @report.logger.debug("Processing PanelQueryTableIncludeProcessor (instance: #{instance}, "\
+                             "dashboard: #{dashboard}, panel: #{panel_id}, query: #{attrs['query']})")
+
+        begin
+          panel = @report.grafana(instance).dashboard(dashboard).panel(panel_id)
+          vars = { 'table_formatter' => 'adoc_plain' }.merge(build_attribute_hash(doc.attributes, attrs))
+          query = QueryValueQuery.new(panel, variables: vars)
+
+          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_panel_query_table:#{panel.id}[query=\"#{ref_id}\",filter_columns=\"time\","\
+        "dashboard=\"#{panel.dashboard.id}\"]\n|==="
+      end
+    end
+  end
+end

data/lib/grafana_reporter/asciidoctor/panel_query_value_inline_macro.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative 'processor_mixin'
+
+module GrafanaReporter
+  module Asciidoctor
+    # Implements the hook
+    #   grafana_panel_query_value:<panel_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
+    #
+    # +grafana_default_dashboard+ - uid of grafana default dashboard to use
+    #
+    # +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
+    # +query+ - query letter, which shall be used, e.g. +C+ (*mandatory*)
+    #
+    # +instance+ - name of grafana instance, 'default' if not specified
+    #
+    # +dashboard+ - uid of grafana dashboard to use
+    #
+    # +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 PanelQueryValueInlineMacro < ::Asciidoctor::Extensions::InlineMacroProcessor
+      include ProcessorMixin
+      use_dsl
+
+      named :grafana_panel_query_value
+
+      # :nodoc:
+      def process(parent, target, attrs)
+        return if @report.cancel
+
+        @report.next_step
+        instance = attrs['instance'] || parent.document.attr('grafana_default_instance') || 'default'
+        dashboard = attrs['dashboard'] || parent.document.attr('grafana_default_dashboard')
+        attrs['result_type'] = 'panel_value'
+        @report.logger.debug("Processing PanelQueryValueInlineMacro (instance: #{instance}, dashboard: #{dashboard},"\
+                             " panel: #{target}, query: #{attrs['query']})")
+
+        begin
+          panel = @report.grafana(instance).dashboard(dashboard).panel(target)
+          query = QueryValueQuery.new(panel, variables: build_attribute_hash(parent.document.attributes, attrs))
+
+          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
+
+        "it's easily possible to include the query value: grafana_panel_query_value:#{panel.id}[query=\"#{ref_id}\""\
+        ",dashboard=\"#{panel.dashboard.id}\"] - just within this text."
+      end
+    end
+  end
+end

data/lib/grafana_reporter/asciidoctor/processor_mixin.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module GrafanaReporter
+  module Asciidoctor
+    # This module contains common methods for all asciidoctor extensions.
+    module ProcessorMixin
+      # Used when initializing a object instance, to set the report object, which is currently in progress.
+      # @param report [GrafanaReporter::Asciidoctor::Report] current report
+      # @return [::Asciidoctor::Extensions::Processor] self
+      def current_report(report)
+        @report = report
+        self
+      end
+
+      # 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)
+        raise NotImplementedError
+      end
+
+      # Merges the given hashes to a common attribute Hash. It respects the priorities of the hashes and the
+      # object and allows only valid variables to be used.
+      # @param document_hash [Hash] variables from report template level
+      # @param item_hash [Hash] variables from item configuration level, i.e. specific call, which may override document
+      # @return [Hash] containing accepted variable names including values
+      def build_attribute_hash(document_hash, item_hash)
+        result = {}
+
+        result['grafana_report_timestamp'] = document_hash['localdatetime']
+        result.merge!(document_hash.select do |k, _v|
+          k =~ /^var-/ ||
+          k =~ /^(?:from|to)$/ ||
+          k =~ /^grafana_default_(?:from_timezone|to_timezone|timeout)$/
+        end)
+
+        result.merge!(item_hash.select do |k, _v|
+          # TODO: specify accepted options for each processor class individually
+          k =~ /^(?:var-|render-)/ ||
+          k =~ /^(?:timeout|from|to)$/ ||
+          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
+      end
+    end
+  end
+end