ruby-grafana-reporter 0.4.5 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd6bdf1a9856b3c0a663060c4b2ecfc3a094ae230635807398a611d38d74ac90
-  data.tar.gz: 95ac2750e962a67b0d3b71184b5409b88441840f4b08f31284b33f20b0d862a3
+  metadata.gz: '06912db0a0635560dca75c00c01c047deac42741c7c6ba2ee717cbccdf26cb19'
+  data.tar.gz: 8d09e509266737bf1b73c3f6ad5c03255de461c116a6e5ec7b45bfaef56520b7
 SHA512:
-  metadata.gz: 53698b98b33afef1706243cf5c322bd1a9968ec723e18d32ec5d550769117fa9c64c43c9d174752630ac7f8e8015d1394d4f2060fbe6be1b2ce73d7ad8390801
-  data.tar.gz: 5f39c12e056e689ff442f00c175219e6a560e9e38362a5aec9f67dc738b172ebf0b9d288958e312020f8304603e54ff1c4e21ca44d77182342a3df9fe03825ba
+  metadata.gz: 66e81686e253f8e98101f97b0b08db97f955cd1c274f2ed683f597b675c228adf198cd2c66f9ce3df05506a760564643e43b94c40fa952b13748122ecc8d6890
+  data.tar.gz: 916ec07231acf19c20b0f01d7bfe9a47d5825a8e0c3a6c67a9fa615e2b993343d1506fb129cc72b66e2be9b02102c15e338a6e8b5746286494de4164a9678c38

data/README.md

@@ -30,7 +30,7 @@ professional reporting functionality. And this is, where the ruby grafana report
 steps in.
 
 The key functionality of the reporter is to capture data and images from grafana
-dashboards and to use it in your custom templates to finally create reports in PDF
+dashboards and to use it in your custom templates to finally create reports in PDF
 (default), HTML, or any other format.
 
 By default (an extended version of) Asciidoctor is enabled as template language.
@@ -65,7 +65,7 @@ Database                  | Image rendering | Raw queries   | Composed queries
 ------------------------- | :-------------: | :-----------: | :------------:
 all SQL based datasources | supported       | supported     | supported
 Graphite                  | supported       | supported     | supported
-InfluxDB                  | supported       | supported     | not (yet) supported
+InfluxDB                  | supported       | supported     | supported
 Prometheus                | supported       | supported     | n/a in grafana
 other datasources         | supported       | not supported | not supported
 

data/lib/VERSION.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 # Version information
-GRAFANA_REPORTER_VERSION = [0, 4, 5].freeze
+GRAFANA_REPORTER_VERSION = [0, 5, 0].freeze
 # Release date
-GRAFANA_REPORTER_RELEASE_DATE = '2021-08-26'
+GRAFANA_REPORTER_RELEASE_DATE = '2021-11-05'

data/lib/grafana/abstract_datasource.rb

@@ -128,6 +128,9 @@ module Grafana
         repeat_count += 1
 
         variables.each do |name, variable|
+          # do not replace with non grafana variables
+          next unless name =~ /^var-/
+
           # only set ticks if value is string
           var_name = name.gsub(/^var-/, '')
           next unless var_name =~ /^\w+$/

data/lib/grafana/dashboard.rb

@@ -35,6 +35,11 @@ module Grafana
       @model['uid']
     end
 
+    # @return [String] dashboard title
+    def title
+      @model['title']
+    end
+
     # @return [Panel] panel for the specified ID
     def panel(id)
       panels = @panels.select { |item| item.field('id') == id.to_i }
@@ -53,7 +58,7 @@ module Grafana
       list = @model['templating']['list']
       return unless list.is_a? Array
 
-      list.each { |item| @variables << Variable.new(item) }
+      list.each { |item| @variables << Variable.new(item, self) }
     end
 
     # read panels

data/lib/grafana/errors.rb

@@ -53,7 +53,8 @@ module Grafana
   class ImageCouldNotBeRenderedError < GrafanaError
     def initialize(panel)
       super("The specified panel '#{panel.id}' from dashboard '#{panel.dashboard.id}' could not be "\
-        'rendered to an image.')
+        'rendered to an image. Check if rendering is possible manually by selecting "Share" and then '\
+        '"Direct link rendered image" from a panel\'s options menu.')
     end
   end
 

data/lib/grafana/grafana.rb

@@ -25,6 +25,30 @@ module Grafana
       initialize_datasources unless @base_uri.empty?
     end
 
+    # @return [Hash] Information about the current organization
+    def organization
+      return @organization if @organization
+
+      response = prepare_request({ relative_url: '/api/org/' }).execute
+      if response.is_a?(Net::HTTPOK)
+        @organization = JSON.parse(response.body)
+      end
+
+      @organization
+    end
+
+    # @return [String] grafana version
+    def version
+      return @version if @version
+
+      response = prepare_request({ relative_url: '/api/health' }).execute
+      if response.is_a?(Net::HTTPOK)
+        @version = JSON.parse(response.body)['version']
+      end
+
+      @version
+    end
+
     # Used to test a connection to the grafana instance.
     #
     # Running this function also determines, if the API configured here has Admin or NON-Admin privileges,

data/lib/grafana/grafana_environment_datasource.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Grafana
+  # Implements a datasource to return environment related information about the grafana instance in a tabular format.
+  class GrafanaEnvironmentDatasource < ::Grafana::AbstractDatasource
+    # +:raw_query+ needs to contain a Hash with the following structure:
+    #
+    #   {
+    #     grafana:  {Grafana} object to query
+    #     mode:     'general' (default) or 'dashboards' for receiving different environment information
+    #   }
+    # @see AbstractDatasource#request
+    def request(query_description)
+      raise MissingSqlQueryError if query_description[:raw_query].nil?
+      raw_query = {mode: 'general'}.merge(query_description[:raw_query])
+
+      return dashboards_data(raw_query[:grafana]) if raw_query[:mode] == 'dashboards'
+
+      general_data(raw_query[:grafana])
+    end
+
+    # @see AbstractDatasource#default_variable_format
+    def default_variable_format
+      nil
+    end
+
+    # @see AbstractDatasource#name
+    def name
+      self.class.to_s
+    end
+
+    private
+
+    def general_data(grafana)
+      {
+        header: ['Version', 'Organization Name', 'Organization ID', 'Access permissions'],
+        content: [[grafana.version,
+                   grafana.organization['name'],
+                   grafana.organization['id'],
+                   grafana.test_connection]]
+      }
+    end
+
+    def dashboards_data(grafana)
+      content = []
+      grafana.dashboard_ids.each do |id|
+        content << [id, grafana.dashboard(id).title, grafana.dashboard(id).panels.length]
+      end
+
+      {
+        header: ['Dashboard ID', 'Dashboard Name', '# Panels'],
+        content: content
+      }
+    end
+  end
+end

data/lib/grafana/image_rendering_datasource.rb

@@ -10,12 +10,16 @@ module Grafana
     #   }
     # @see AbstractDatasource#request
     def request(query_description)
+      panel = query_description[:raw_query][:panel]
+
       webrequest = query_description[:prepared_request]
-      webrequest.relative_url = query_description[:raw_query][:panel].render_url + url_params(query_description)
+      webrequest.relative_url = panel.render_url + url_params(query_description)
       webrequest.options.merge!({ accept: 'image/png' })
 
       result = webrequest.execute
 
+      raise ImageCouldNotBeRenderedError, panel if result.body.include?('<html')
+
       { header: ['image'], content: [result.body] }
     end
 

data/lib/grafana/influxdb_datasource.rb

@@ -24,8 +24,6 @@ module Grafana
       query = query.gsub(/\$timeFilter(?=\W|$)/, "time >= #{query_description[:from]}ms and time <= #{query_description[:to]}ms")
 
       # replace grafana variables $__interval and $__interval_ms in query
-      # TODO: influx datasource currently uses a fixed values of 1000 width for interval variables specified in a query - it should be possible to calculate this according to grafana
-      # TODO: check where calculation and replacement of interval variable should take place
       query = query.gsub(/\$(?:__)?interval(?=\W|$)/, "#{((query_description[:to].to_i - query_description[:from].to_i) / 1000 / 1000).to_i}s")
       query = query.gsub(/\$(?:__)?interval_ms(?=\W|$)/, "#{((query_description[:to].to_i - query_description[:from].to_i) / 1000).to_i}")
 

data/lib/grafana/sql_datasource.rb

@@ -49,6 +49,8 @@ module Grafana
     def preformat_response(response_body)
       results = {}
       results.default = []
+      results[:header] = []
+      results[:content] = []
 
       JSON.parse(response_body)['results'].each_value do |query_result|
         if query_result.key?('error')

data/lib/grafana/variable.rb

@@ -29,15 +29,14 @@ module Grafana
 
     # @param config_or_value [Hash, Object] configuration hash of a variable out of an {Dashboard} instance
     #  or a value of any kind.
-    def initialize(config_or_value)
+    # @param dashboard [Dashboard] parent dashboard, if applicable; especially needed for query variable
+    #  evaluation.
+    def initialize(config_or_value, dashboard = nil)
       if config_or_value.is_a? Hash
+        @dashboard = dashboard
         @config = config_or_value
         @name = @config['name']
-        # TODO: if a variable uses type 'query' which is never updated, the selected values are stored in 'options'
-        unless @config['current'].nil?
-          @raw_value = @config['current']['value']
-          @text = @config['current']['text']
-        end
+        init_values
       else
         @config = {}
         @raw_value = config_or_value
@@ -68,14 +67,19 @@ module Grafana
       if value == '$__all'
         if !@config['options'].empty?
           # this query contains predefined values, so capture them and format the values accordingly
-          # this happens either if type='custom' or a query, which is never updated
-          value = @config['options'].map { |item| item['value'] }
+          # this happens either for type='custom' or type 'query', if it is never updated
+          value = @config['options'].reject { |item| item['value'] == '$__all' }.map { |item| item['value'] }
 
         elsif @config['type'] == 'query' && !@config['query'].empty?
-          # TODO: replace variables in query, execute it and evaluate the results as if they were normally selected
-          # "multiFormat": contains variable replacement in "query", e.g. 'regex values' or 'glob'
-          # "datasource": contains name of datasource
-          return @config['query']
+          # variables in this configuration are not stored in grafana, i.e. if all is selected here,
+          # the values have to be fetched from the datasource
+          query = ::GrafanaReporter::QueryValueQuery.new(@dashboard)
+          query.datasource = @dashboard.grafana.datasource_by_name(@config['datasource'])
+          query.variables['result_type'] = Variable.new('object')
+          query.raw_query = @config['query']
+          result = query.execute
+
+          value = result[:content].map { |item| item[0].to_s }
 
         else
           # TODO: add support for variable type: 'datasource' and 'adhoc'
@@ -149,8 +153,10 @@ module Grafana
         value.gsub(%r{[" |=/\\]}, '\\\\\0')
 
       when /^date(?::(?<format>.*))?$/
-        # TODO: grafana does not seem to allow multiselection of variables with date format - raise an error if this happens anyway
-        get_date_formatted(value, Regexp.last_match(1))
+        if multi? && value.is_a?(Array)
+          raise GrafanaError, "Date format cannot be specified for a variable containing an array of values"
+        end
+        Variable.format_as_date(value, Regexp.last_match(1))
 
       when ''
         # default
@@ -168,8 +174,9 @@ module Grafana
       end
     end
 
-    # @return [Boolean] true, if the value can contain multiple selections, i.e. can contain an Array
+    # @return [Boolean] true, if the value can contain multiple selections, i.e. can contain an Array or does contain all
     def multi?
+      return true if @raw_value == '$__all'
       return @config['multi'] unless @config['multi'].nil?
 
       @raw_value.is_a? Array
@@ -187,12 +194,13 @@ module Grafana
       @text = new_text
     end
 
-    private
-
-    # Realize time formatting according
+    # Applies the date format according
     # {https://grafana.com/docs/grafana/latest/variables/variable-types/global-variables/#__from-and-__to}
-    # and {https://momentjs.com/docs/#/displaying/}.
-    def get_date_formatted(value, format)
+    # and {https://momentjs.com/docs/#/displaying/} to a given value.
+    # @param value [String] time as milliseconds to be formatted
+    # @param format [String] format string in which the time value shall be returned
+    # @return [String] time converted to the specified time format
+    def self.format_as_date(value, format)
       return (Float(value) / 1000).to_i.to_s if format == 'seconds'
       return Time.at((Float(value) / 1000).to_i).utc.iso8601(3) if !format || (format == 'iso')
 
@@ -203,13 +211,12 @@ module Grafana
         tmp = work_string.scan(/^(?:M{1,4}|D{1,4}|d{1,4}|e|E|w{1,2}|W{1,2}|Y{4}|Y{2}|A|a|H{1,2}|
                                     h{1,2}|k{1,2}|m{1,2}|s{1,2}|S+|X)/x)
 
-        # TODO: add test for sub! and switch to non-modifying frozen string action
         if tmp.empty?
           matches << work_string[0]
-          work_string.sub!(/^#{work_string[0]}/, '')
+          work_string = work_string.sub(/^#{work_string[0]}/, '')
         else
           matches << tmp[0]
-          work_string.sub!(/^#{tmp[0]}/, '')
+          work_string = work_string.sub(/^#{tmp[0]}/, '')
         end
       end
 
@@ -221,5 +228,21 @@ module Grafana
 
       Time.at((Float(value) / 1000).to_i).strftime(format_string)
     end
+
+    private
+
+    def init_values
+      case @config['type']
+      when 'constant'
+        self.raw_value = @config['query']
+
+      else
+        if !@config['current'].nil?
+          self.raw_value = @config['current']['value']
+        else
+          raise GrafanaError.new("Grafana variable with type '#{@config['type']}' and name '#{@config['name']}' could not be handled properly. Please raise a ticket.")
+        end
+      end
+    end
   end
 end

data/lib/grafana/webrequest.rb

@@ -50,6 +50,7 @@ module Grafana
       @logger.debug("Requesting #{uri} with '#{@options[:body]}' and timeout '#{timeout}'")
       response = @http.request(request)
       @logger.debug("Received response #{response}")
+      @logger.debug("HTTP response body: #{response.body}") unless response.code =~ /^2.*/
 
       response
     end

data/lib/grafana_reporter/abstract_query.rb

@@ -44,6 +44,7 @@ module GrafanaReporter
       else
         raise GrafanaReporterError, "Internal error in AbstractQuery: given object is of type #{grafana_obj.class.name}, which is not supported"
       end
+      @logger = @grafana ? @grafana.logger : ::Logger.new($stderr, level: :info)
       @variables = {}
       @variables['from'] = Grafana::Variable.new(nil)
       @variables['to'] = Grafana::Variable.new(nil)
@@ -79,7 +80,7 @@ module GrafanaReporter
       raise DatasourceNotSupportedError.new(@datasource, self) if @datasource.is_a?(Grafana::UnsupportedDatasource)
 
       begin
-        @result = @datasource.request(from: from, to: to, raw_query: raw_query, variables: grafana_variables,
+        @result = @datasource.request(from: from, to: to, raw_query: raw_query, variables: @variables,
                                       prepared_request: @grafana.prepare_request, timeout: timeout)
       rescue ::Grafana::GrafanaError
         # grafana errors will be directly passed through
@@ -143,6 +144,8 @@ module GrafanaReporter
     #
     # Multiple columns may be filtered. Therefore the column titles have to be named in the
     # {Grafana::Variable#raw_value} and have to be separated by +,+ (comma).
+    #
+    # Commas can be used in a format string, but need to be escaped by using +_,+.
     # @param result [Hash] preformatted sql hash, (see {Grafana::AbstractDatasource#request})
     # @param filter_columns_variable [Grafana::Variable] column names, which shall be removed in the query result
     # @return [Hash] filtered query result
@@ -150,8 +153,8 @@ module GrafanaReporter
       return result unless filter_columns_variable
 
       filter_columns = filter_columns_variable.raw_value
-      filter_columns.split(',').each do |filter_column|
-        pos = result[:header].index(filter_column)
+      filter_columns.split(/(?<!_),/).each do |filter_column|
+        pos = result[:header].index(filter_column.gsub("_,", ","))
 
         unless pos.nil?
           result[:header].delete_at(pos)
@@ -167,23 +170,33 @@ module GrafanaReporter
     # The formatting will be applied separately for every column. Therefore the column formats have to be named
     # in the {Grafana::Variable#raw_value} and have to be separated by +,+ (comma). If no value is specified for
     # a column, no change will happen.
+    #
+    # It is also possible to format milliseconds as dates by specifying date formats, e.g. +date:iso+. It is
+    # possible to use any date format according
+    # {https://grafana.com/docs/grafana/latest/variables/variable-types/global-variables/#from-and-to}
+    #
+    # Commas can be used in a format string, but need to be escaped by using +_,+.
     # @param result [Hash] preformatted sql hash, (see {Grafana::AbstractDatasource#request})
     # @param formats [Grafana::Variable] formats, which shall be applied to the columns in the query result
     # @return [Hash] formatted query result
     def format_columns(result, formats)
       return result unless formats
 
-      formats.text.split(',').each_index do |i|
-        format = formats.text.split(',')[i]
+      formats.text.split(/(?<!_),/).each_index do |i|
+        format = formats.text.split(/(?<!_),/)[i].gsub("_,", ",")
         next if format.empty?
 
         result[:content].map do |row|
           next unless row.length > i
 
           begin
-            row[i] = format % row[i] if row[i]
+            if format =~ /^date:/
+              row[i] = ::Grafana::Variable.format_as_date(row[i], format.sub(/^date:/, '')) if row[i]
+            else
+              row[i] = format % row[i] if row[i]
+            end
           rescue StandardError => e
-            @grafana.logger.error(e.message)
+            @logger.error(e.message)
             row[i] = e.message
           end
         end
@@ -248,7 +261,7 @@ module GrafanaReporter
                   begin
                     row[i] = row[i].to_s.gsub(/#{k}/, v) if row[i].to_s =~ /#{k}/
                   rescue StandardError => e
-                    @grafana.logger.error(e.message)
+                    @logger.error(e.message)
                     row[i] = e.message
                   end
 
@@ -273,7 +286,7 @@ module GrafanaReporter
                                  end
                       end
                     rescue StandardError => e
-                      @grafana.logger.error(e.message)
+                      @logger.error(e.message)
                       row[i] = e.message
                     end
                   end
@@ -298,17 +311,19 @@ module GrafanaReporter
     # @option opts [Grafana::Variable] :column_divider requested row divider for the result table, only to be used with table_formatter `adoc_deprecated`
     # @option opts [Grafana::Variable] :include_headline specifies if table should contain headline, defaults to false
     # @option opts [Grafana::Variable] :table_formatter specifies which formatter shall be used, defaults to 'csv'
+    # @option opts [Grafana::Variable] :transposed specifies whether the result table is transposed
     # @return [String] table in custom output format
     def format_table_output(result, opts)
       opts = { include_headline: Grafana::Variable.new('false'),
                table_formatter: Grafana::Variable.new('csv'),
                row_divider: Grafana::Variable.new('| '),
-               column_divider: Grafana::Variable.new(' | ') }.merge(opts.delete_if {|_k, v| v.nil? })
+               column_divider: Grafana::Variable.new(' | '),
+               transpose: Grafana::Variable.new('false') }.merge(opts.delete_if {|_k, v| v.nil? })
 
       if opts[:table_formatter].raw_value == 'adoc_deprecated'
-        @grafana.logger.warn("You are using deprecated 'table_formatter' named 'adoc_deprecated', which will be "\
-                             "removed in a future version. Start using 'adoc_plain' or register your own "\
-                             "implementation of AbstractTableFormatStrategy.")
+        @logger.warn("You are using deprecated 'table_formatter' named 'adoc_deprecated', which will be "\
+                     "removed in a future version. Start using 'adoc_plain' or register your own "\
+                     "implementation of AbstractTableFormatStrategy.")
         return result[:content].map do |row|
           opts[:row_divider].raw_value + row.map do |item|
             item.to_s.gsub('|', '\\|')
@@ -316,7 +331,7 @@ module GrafanaReporter
         end.join("\n")
       end
 
-      AbstractTableFormatStrategy.get(opts[:table_formatter].raw_value).format(result, opts[:include_headline].raw_value.downcase == 'true')
+      AbstractTableFormatStrategy.get(opts[:table_formatter].raw_value).format(result, opts[:include_headline].raw_value.downcase == 'true', opts[:transpose].raw_value.downcase == 'true')
     end
 
     # Used to translate the relative date strings used by grafana, e.g. +now-5d/w+ to the
@@ -334,7 +349,7 @@ module GrafanaReporter
     # @param timezone [Grafana::Variable] timezone to use, if not system timezone
     # @return [String] translated date as timestamp string
     def translate_date(orig_date, report_time, is_to_time, timezone = nil)
-      @grafana.logger.warn("#translate_date has been called without 'report_time' - using current time as fallback.") unless report_time
+      @logger.warn("#translate_date has been called without 'report_time' - using current time as fallback.") unless report_time
       report_time ||= ::Grafana::Variable.new(Time.now.to_s)
       orig_date = orig_date.raw_value if orig_date.is_a?(Grafana::Variable)
 
@@ -405,8 +420,7 @@ module GrafanaReporter
     def datasource_response_valid?
       return false if @result.nil?
       return false unless @result.is_a?(Hash)
-      # TODO: compare how empty valid responses look like in grafana
-      return true if @result.empty?
+      return false if @result.empty?
       return false unless @result.key?(:header)
       return false unless @result.key?(:content)
       return false unless @result[:header].is_a?(Array)
@@ -415,12 +429,6 @@ module GrafanaReporter
       true
     end
 
-    # @return [Hash<String, Variable>] all grafana variables stored in this query, i.e. the variable name
-    #  is prefixed with +var-+
-    def grafana_variables
-      @variables.select { |k, _v| k =~ /^var-.+/ }
-    end
-
     def delta_date(date, delta_count, time_letter)
       # substract specified time
       case time_letter

data/lib/grafana_reporter/abstract_report.rb

@@ -143,6 +143,8 @@ module GrafanaReporter
       notify(:on_before_create)
       @start_time = Time.new
       logger.info("Report started at #{@start_time}")
+      logger.info("You are running ruby-grafana-reporter version #{GRAFANA_REPORTER_VERSION.join('.')}.")
+      logger.info("A newer version is released. Check out https://github.com/divinity666/ruby-grafana-reporter/releases/latest") unless @config.latest_version_check_ok?
       build
     rescue MissingTemplateError => e
       @logger.error(e.message)

data/lib/grafana_reporter/abstract_table_format_strategy.rb

@@ -23,12 +23,52 @@ module GrafanaReporter
       raise NotImplementedError
     end
 
-    # @abstract
-    # @param column [Array] datasource table result
+    # Used to format a given content array to the desired output format. The default
+    # implementation applies the {#format_rules} to create a custom string export. If
+    # this is not sufficient for a desired table format, you may simply overwrite this
+    # function to have full freedom about the desired output.
+    # @param content [Hash] datasource table result
     # @param include_headline [Boolean] true, if headline should be included in result
+    # @param transposed [Boolean] true, if result array is in transposed format
     # @return [String] formatted in table format
-    def format(content, include_headline)
-      raise NotImplementedError
+    def format(content, include_headline, transposed)
+      result = content[:content]
+
+      # add the headline at the correct position to the content array
+      if include_headline
+        if transposed
+          result.each_index do |i|
+            result[i] = [content[:header][i]] + result[i]
+          end
+        else
+          result = result.unshift(content[:header])
+        end
+      end
+
+      # translate the content to a table
+      result.map do |row|
+        format_rules[:row_start] + row.map do |item|
+          value = item.to_s
+          if format_rules[:replace_string_or_regex]
+            value = value.gsub(format_rules[:replace_string_or_regex], format_rules[:replacement])
+          end
+
+          format_rules[:cell_start] + value + format_rules[:cell_end]
+        end.join(format_rules[:between_cells])
+      end.join(format_rules[:row_end])
+    end
+
+    # Formatting rules, which are applied to build the table output format.
+    def format_rules
+      {
+        row_start: '',
+        row_end: '',
+        cell_start: '',
+        between_cells: '',
+        cell_end: '',
+        replace_string_or_regex: nil,
+        replacement: ''
+      }
     end
   end
 end

data/lib/grafana_reporter/alerts_table_query.rb

@@ -37,7 +37,8 @@ module GrafanaReporter
                                     row_divider: @variables['row_divider'],
                                     column_divider: @variables['column_divider'],
                                     table_formatter: @variables['table_formatter'],
-                                    include_headline: @variables['include_headline'])
+                                    include_headline: @variables['include_headline'],
+                                    transpose: @variables['transpose'])
     end
   end
 end

data/lib/grafana_reporter/annotations_table_query.rb

@@ -36,7 +36,8 @@ module GrafanaReporter
                                     row_divider: @variables['row_divider'],
                                     column_divider: @variables['column_divider'],
                                     table_formatter: @variables['table_formatter'],
-                                    include_headline: @variables['include_headline'])
+                                    include_headline: @variables['include_headline'],
+                                    transpose: @variables['transpose'])
     end
   end
 end

data/lib/grafana_reporter/application/webservice.rb

@@ -26,7 +26,13 @@ module GrafanaReporter
         @progress_reporter = Thread.new {}
 
         @status = :running
-        accept_requests_loop
+        begin
+          accept_requests_loop
+        rescue SystemExit, Interrupt
+          @logger.info("Server shutting down.")
+          stop!
+          retry
+        end
         @status = :stopped
       end
 
@@ -57,8 +63,6 @@ module GrafanaReporter
           # step 1) accept incoming connection
           socket = @server.accept
 
-          # TODO: shutdown properly on SIGINT/SIGHUB
-
           # stop webservice properly, if shall be shutdown
           if @status == :stopping
             socket.close
@@ -252,7 +256,7 @@ module GrafanaReporter
             <% end.join('') %>
             <tbody>
           </table>
-          <p style="font-size: small; color:grey">You are running ruby-grafana-reporter version <%= GRAFANA_REPORTER_VERSION.join('.') %>.</p>
+          <p style="font-size: small; color:grey">You are running ruby-grafana-reporter version <%= GRAFANA_REPORTER_VERSION.join('.') %>.<%= @config.latest_version_check_ok? ? '' : ' Check out the latest version <a href="https://github.com/divinity666/ruby-grafana-reporter/releases/latest">here</a>.' %></p>
           </body>
           </html>
         HTML_TEMPLATE

data/lib/grafana_reporter/asciidoctor/adoc_plain_table_format_strategy.rb

@@ -10,15 +10,17 @@ module GrafanaReporter
         'adoc_plain'
       end
 
-      # @see AbstractTableFormatStrategy#format
-      def format(result, include_headline)
-        headline = '| ' + result[:header].map { |item| item.to_s.gsub(' | ', '\\|') }.join(' | ')
-
-        content = result[:content].map do |row|
-          '| ' + row.map { |item| item.to_s.gsub(' | ', '\\|') }.join(' | ')
-        end.join("\n")
-
-        "#{"#{headline}\n" if include_headline}#{content}"
+      # @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/asciidoctor/help.rb

@@ -82,7 +82,7 @@ Usage: #{opts[:code_begin]}#{v[:call]}#{opts[:code_end]}
 #{v[:description]}#{"\n\nSee also: #{v[:see]}" if v[:see]}#{unless v[:options].empty?
 %(
 #{opts[:table_begin]}| Option | Description#{"\n#{opts[:head_postfix_col] * 2}" if opts[:head_postfix_col]}
-#{v[:options].sort.map { |_opt_k, opt_v| "| #{opts[:code_begin]}#{opt_v[:call]}#{opts[:code_end]} | #{opt_v[:description].gsub('|', '\|')}" }.join("\n") }#{opts[:table_end]})
+#{v[:options].sort.map { |_opt_k, opt_v| "| #{opts[:code_begin]}#{opt_v[:call]}#{opts[:code_end]} | #{opt_v[:description].gsub('|', '\|')}#{"\nSee also: #{opt_v[:see]}" if opt_v[:see]}" }.join("\n") }#{opts[:table_end]})
 end}
 )
         end
@@ -109,12 +109,12 @@ end}
           res_item[:description] = item['description']
           res_item[:see] = item['see']
 
-          opts = ((item['options'] ? item['options'].keys : [])
+          opts = ((item['options'] ? item['options'].keys : []) +
                   (item['standard_options'] ? item['standard_options'].keys : [])).sort
           opts.each do |opt_key|
             res_item[:options][opt_key] = {}
 
-            if item['standard_options'].key?(opt_key)
+            if std_opts.key?(opt_key)
               res_item[:options][opt_key][:call] = std_opts[opt_key]['call']
               res_item[:options][opt_key][:description] = "#{std_opts[opt_key]['description']} "\
                                                           "#{item['standard_options'][opt_key]}".chop
@@ -196,8 +196,12 @@ end}
             format:
               call: format="<format_col1>,<format_col2>,..."
               description: >-
-                Specify format in which the results shall be returned, e.g. `%.2f` for only two digit decimals of a
-                float. Several columns are separated by `,`. Execution is applied in the following order `format`,
+                Specify format in which the results in a specific column shall be returned, e.g. `%.2f` for only
+                two digit decimals of a float. Several column formats are separated by `,`, i.e. `%.2f,%.3f` would
+                apply `%.2f` to the first column and `%.3f` to the second column. All other columns would not be
+                formatted. You may also format time in milliseconds to a time format by specifying e.g. `date:iso`.
+                Commas in format strings are supported, but have to be escaped by useing `_,`.
+                Execution of related functions is applied in the following order `format`,
                 `replace_values`, `filter_columns`, `transpose`.
               see: 'https://ruby-doc.org/core/Kernel.html#method-i-sprintf'
 
@@ -207,21 +211,24 @@ end}
                 Specify result values which shall be replaced, e.g. `2:OK` will replace query values `2` with value `OK`.
                 Replacing several values is possible by separating by `,`. Matches with regular expressions are also
                 supported, but must be full matches, i.e. have to start with `^` and end with `$`, e.g. `^[012]$:OK`.
-                Number replacements can also be performed, e.g. `<8.2` or `<>3`. Execution is applied in the following order `format`,
+                Number replacements can also be performed, e.g. `<8.2` or `<>3`. Execution of related functions is
+                applied in the following order `format`,
                 `replace_values`, `filter_columns`, `transpose`.
               see: https://ruby-doc.org/core/Regexp.html#class-Regexp-label-Character+Classes
 
             filter_columns:
               call: filter_columns="<column_name_1>,<column_name_2>,..."
               description: >-
-                Removes specified columns from result. Execution is applied in the following order `format`, `replace_values`,
-                `filter_columns`, `transpose`.
+                Removes specified columns from result.  Commas in format strings are supported, but have to be
+                escaped by useing `_,`. Execution of related functions is applied in the following order
+                `format`, `replace_values`, `filter_columns`, `transpose`.
 
             transpose:
               call: transpose="true"
               description: >-
-                Transposes the query result, i.e. columns become rows and rows become columnns. Execution is applied in the
-                following order `format`, `replace_values`, `filter_columns`, `transpose`.
+                Transposes the query result, i.e. columns become rows and rows become columnns. Execution of related
+                functions is applied in the following order `format`, `replace_values`, `filter_columns`,
+                `transpose`.
 
             column_divider:
               call: column_divider="<divider>"
@@ -234,7 +241,7 @@ end}
               call: row_divider="<divider>"
               description: >-
                 Replace the default row divider with another one, when used in conjunction with `table_formatter` set to
-                `adoc_deprecated`. . Defaults to `| ` for being interpreted as a asciidoctor row. DEPRECATED: switch to
+                `adoc_deprecated`. Defaults to `| ` for being interpreted as a asciidoctor row. DEPRECATED: switch to
                 `table_formatter` named `adoc_plain`, or implement a custom table formatter.
 
             table_formatter:
@@ -258,8 +265,13 @@ end}
             call: 'include::grafana_help[]'
 
           grafana_environment:
-            description: Shows all available variables in the rendering context which can be used in the asciidoctor template.
+            description: >-
+              Shows all available variables in the rendering context which can be used in the asciidoctor template.
+              If optional `instance` is specified, additional information about the configured grafana instance will be provided.
+              This is especially helpful for debugging.
             call: 'include::grafana_environment[]'
+            standard_options:
+              instance:
 
           grafana_alerts:
             description: >-

data/lib/grafana_reporter/asciidoctor/panel_image_block_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

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

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/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'
@@ -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}

data/lib/grafana_reporter/csv_table_format_strategy.rb

@@ -9,15 +9,17 @@ module GrafanaReporter
       'csv'
     end
 
-    # @see AbstractTableFormatStrategy#format
-    def format(result, include_headline)
-      headline = result[:header].map { |item| item.to_s.gsub(',', '\\,') }.join(',')
-
-      content = result[:content].map do |row|
-        row.map { |item| item.to_s.gsub(',', '\,') }.join(',')
-      end.join("\n")
-
-      "#{"#{headline}\n" if include_headline}#{content}"
+    # @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

data/lib/grafana_reporter/panel_image_query.rb

@@ -15,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'], table_formatter: @variables['table_formatter'], include_headline: @variables['include_headline'])
+        @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/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

data/lib/ruby_grafana_reporter.rb

@@ -18,17 +18,6 @@ require 'asciidoctor-pdf'
 require 'zip'
 require_relative 'VERSION'
 
-# TODO: add test to see if datasource default formats are applied
-# TODO: add test for render-height and render-width, as they are not forwarded
-# TODO: show convert-backend, template language and all variables in webservice overview
-# TODO: add automated test against grafana playground before building a new release
-# TODO: allow registration of files to be defined in config file
-# TODO: PRIO: check in cloud - variables fetched from queries are replaced with SQL query instead of the resolved values, which can lead to issues, e.g. when using that in a function as SUBSTRING
-# TODO: PRIO: allow multiple report classes in configuration file including possibility to decide for the individual class for each rendering call
-# TODO: add configuration example to README
-# TODO: find a way, how to automatically update test grafana responses with _real_ grafana responses
-# TODO: append necessary variables on demo report creation for plain SQL queries, as they are lacking the grafana reference
-
 folders = [
   %w[grafana],
   %w[grafana_reporter logger],

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-grafana-reporter
 version: !ruby/object:Gem::Version
-  version: 0.4.5
+  version: 0.5.0
 platform: ruby
 authors:
 - Christian Kohlmeyer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-08-26 00:00:00.000000000 Z
+date: 2021-11-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor
@@ -118,6 +118,7 @@ files:
 - "./lib/grafana/grafana.rb"
 - "./lib/grafana/grafana_alerts_datasource.rb"
 - "./lib/grafana/grafana_annotations_datasource.rb"
+- "./lib/grafana/grafana_environment_datasource.rb"
 - "./lib/grafana/grafana_property_datasource.rb"
 - "./lib/grafana/graphite_datasource.rb"
 - "./lib/grafana/image_rendering_datasource.rb"
@@ -165,6 +166,7 @@ files:
 - "./lib/grafana_reporter/panel_property_query.rb"
 - "./lib/grafana_reporter/query_value_query.rb"
 - "./lib/grafana_reporter/report_webhook.rb"
+- "./lib/grafana_reporter/reporter_environment_datasource.rb"
 - "./lib/ruby_grafana_extension.rb"
 - "./lib/ruby_grafana_reporter.rb"
 - LICENSE