ruby-grafana-reporter 0.3.0 → 0.4.4

data/lib/grafana_reporter/demo_report_wizard.rb

@@ -0,0 +1,104 @@
+# 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
+
+    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/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

@@ -0,0 +1,36 @@
+# 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
+        attrs = @config.default_document_attributes.merge(@custom_attributes).merge({ 'grafana_report_timestamp' => ::Grafana::Variable.new(Time.now.to_s) })
+        logger.debug("Document attributes: #{attrs}")
+
+        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
+
+      # @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
+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

data/lib/grafana_reporter/errors.rb

@@ -8,6 +8,30 @@ module GrafanaReporter
     end
   end
 
+  # Raised if a datasource shall be queried, which is not (yet) supported by the reporter
+  class DatasourceNotSupportedError < GrafanaReporterError
+    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(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(datasource, message)
+      super("The datasource request to '#{datasource.name}' (#{datasource.class})"\
+            "returned an invalid value: '#{message}'")
+    end
+  end
+
   # Thrown, if the requested grafana instance does not have the mandatory 'host'
   # setting configured.
   class GrafanaInstanceWithoutHostError < GrafanaReporterError
@@ -45,4 +69,37 @@ module GrafanaReporter
             "but was '#{currently}'.")
     end
   end
+
+  # Thrown, if the value configuration in {AbstractQuery#replace_values} is
+  # invalid.
+  class MalformedReplaceValuesStatementError < GrafanaReporterError
+    def initialize(statement)
+      super("The specified replace_values statement '#{statement}' is invalid. Make sure it contains"\
+            " exactly one not escaped ':' symbol.")
+    end
+  end
+
+  # Thrown, if a configured parameter is malformed.
+  class MalformedAttributeContentError < GrafanaReporterError
+    def initialize(message, attribute, content)
+      super("The content '#{content}' in attribute '#{attribute}' is malformed: #{message}")
+    end
+  end
+
+  # Thrown, if a configured time range is not supported by the reporter.
+  #
+  # If this happens, most likely the reporter has to implement the new
+  # time range definition.
+  class TimeRangeUnknownError < GrafanaReporterError
+    def initialize(time_range)
+      super("The specified time range '#{time_range}' is unknown.")
+    end
+  end
+
+  # Thrown, if a mandatory attribute is not set.
+  class MissingMandatoryAttributeError < GrafanaReporterError
+    def initialize(attribute)
+      super("Missing mandatory attribute '#{attribute}'.")
+    end
+  end
 end

data/lib/grafana_reporter/logger/{two_way_logger.rb → two_way_delegate_logger.rb}

@@ -25,7 +25,7 @@ module GrafanaReporter
       end
 
       # Sets the severity level of the additional logger to the given severity.
-      # @param severity one of {Logger::Severity}
+      # @param severity one of Logger::Severity
       def level=(severity)
         @additional_logger.level = severity
       end

data/lib/grafana_reporter/panel_image_query.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module GrafanaReporter
+  # This class is used to create an image out of a {Grafana::Panel}.
+  class PanelImageQuery < AbstractQuery
+    # Sets the proper render variables.
+    def pre_process
+      # 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 }
+      @datasource = Grafana::ImageRenderingDatasource.new(nil)
+    end
+
+    # 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
+    def raw_query
+      { panel: @panel }
+    end
+  end
+end

data/lib/grafana_reporter/panel_property_query.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module GrafanaReporter
+  # This class is used to query properties from a {Grafana::Panel}, such as +description+,
+  # +title+ etc.
+  class PanelPropertyQuery < AbstractQuery
+    # @see Grafana::AbstractQuery#pre_process
+    def pre_process
+      @datasource = Grafana::GrafanaPropertyDatasource.new(nil)
+    end
+
+    # @see Grafana::AbstractQuery#post_process
+    def post_process
+      @result = @result[:content].first
+    end
+
+    # @see Grafana::AbstractQuery#raw_query
+    def raw_query
+      @raw_query.merge({ panel: @panel })
+    end
+  end
+end

data/lib/grafana_reporter/query_value_query.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module GrafanaReporter
+  # This class provides a general query implementation for any kind of single value and table queries.
+  class QueryValueQuery < AbstractQuery
+    # @see Grafana::AbstractQuery#pre_process
+    def pre_process
+      @datasource = @panel.datasource if @panel
+
+      @variables['result_type'] ||= Variable.new('')
+    end
+
+    # Executes {AbstractQuery#format_columns}, {AbstractQuery#replace_values} and
+    # {AbstractQuery#filter_columns} on the query results.
+    #
+    # Finally the results are formatted as a asciidoctor table.
+    # @see Grafana::AbstractQuery#post_process
+    def post_process
+      modify_results
+
+      case @variables['result_type'].raw_value
+      when /(?:panel_table|sql_table)/
+        @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'])
+
+      when /(?:panel_value|sql_value)/
+        tmp = @result[:content] || []
+        @result = tmp.flatten.first
+
+      else
+        raise StandardError, "Unsupported 'result_type' received: '#{@variables['result_type'].raw_value}'"
+
+      end
+    end
+
+    # @see Grafana::AbstractQuery#raw_query
+    def raw_query
+      return @raw_query if @raw_query
+
+      case @variables['result_type'].raw_value
+      when /(?:panel_table|panel_value)/
+        @variables['query'] ? @panel.query(@variables['query'].raw_value) : @panel.query(nil)
+
+      when /(?:sql_table|sql_value)/
+        nil
+
+      else
+        raise StandardError, "Unsupported 'result_type' received: '#{@variables['result_type'].raw_value}'"
+
+      end
+    end
+
+    private
+
+    def modify_results
+      @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'])
+      @result = transpose(@result, @variables['transpose'])
+    end
+  end
+end

data/lib/grafana_reporter/report_webhook.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module GrafanaReporter
+  # This class provides a default webhook implementation for report events. It sends out
+  # a webrequest to the configured +callback_url+ with all necessary information about the
+  # event and the report.
+  class ReportWebhook
+    def initialize(callback_url)
+      @callback_url = callback_url
+    end
+
+    # 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 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,
+               execution_time: report.execution_time, template: report.template,
+               start_time: report.start_time, end_time: report.end_time, event: event }
+
+      request = { body: JSON.generate(data), accept: nil, content_type: nil }
+      res = ::Grafana::WebRequest.new(@callback_url, request).execute
+
+      "#{res} - Body: #{res.body}"
+    end
+  end
+end

data/lib/ruby_grafana_extension.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative 'ruby_grafana_reporter'
+
+config = GrafanaReporter::Configuration.new
+config.config = GrafanaReporter::Application::Application.load_config
+
+GrafanaReporter::Asciidoctor::Report.new(config).register