ruby-grafana-reporter 0.3.0 → 0.4.4

data/lib/grafana_reporter/application/webservice.rb

@@ -6,21 +6,48 @@ module GrafanaReporter
     # make use of `webrick` or similar, so that it can be used without futher dependencies
     # in conjunction with the standard asciidoctor docker container.
     class Webservice
-      def initialize(config)
+      # Array of possible webservice running states
+      STATUS = %I[stopped running stopping].freeze
+
+      def initialize
         @reports = []
+        @status = :stopped
+      end
+
+      # Runs the webservice with the given {Configuration} object.
+      def run(config)
         @config = config
         @logger = config.logger
-      end
 
-      # Runs the webservice with the current set {Configuration} object.
-      def run
         # start webserver
         @server = TCPServer.new(@config.webserver_port)
         @logger.info("Server listening on port #{@config.webserver_port}...")
 
         @progress_reporter = Thread.new {}
 
+        @status = :running
         accept_requests_loop
+        @status = :stopped
+      end
+
+      # @return True, if webservice is stopped, false otherwise
+      def stopped?
+        @status == :stopped
+      end
+
+      # @return True, if webservice is up and running, false otherwise
+      def running?
+        @status == :running
+      end
+
+      # Forces stopping the webservice.
+      def stop!
+        @status = :stopping
+
+        # invoke a new request, so that the webservice stops.
+        socket = TCPSocket.new('localhost', @config.webserver_port)
+        socket.send '', 0
+        socket.close
       end
 
       private
@@ -30,6 +57,14 @@ 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
+            break
+          end
+
           # step 2) print the request headers (separated by a blank line e.g. \r\n)
           request = ''
           line = ''
@@ -48,11 +83,8 @@ module GrafanaReporter
           rescue WebserviceUnknownPathError => e
             @logger.debug(e.message)
             socket.write http_response(404, '', e.message)
-          rescue MissingTemplateError => e
-            @logger.error(e.message)
-            socket.write http_response(400, 'Bad Request', e.message)
           rescue WebserviceGeneralRenderingError => e
-            @logger.fatal(e.message)
+            @logger.error(e.message)
             socket.write http_response(400, 'Bad Request', e.message)
           rescue StandardError => e
             @logger.fatal(e.message)
@@ -164,12 +196,13 @@ module GrafanaReporter
         return http_response(200, 'OK', content, "Content-Type": 'application/pdf') if content.start_with?('%PDF')
 
         http_response(200, 'OK', content, "Content-Type": 'application/octet-stream',
-                                          "Content-Disposition": "attachment; filename=report_#{attrs['report_id']}.zip")
+                                          "Content-Disposition": 'attachment; '\
+                                                                 "filename=report_#{attrs['report_id']}.zip")
       end
 
       def render_report(attrs)
         # build report
-        template_file = "#{@config.templates_folder}#{attrs['var-template']}.adoc"
+        template_file = "#{@config.templates_folder}#{attrs['var-template']}"
 
         file = Tempfile.new('gf_pdf_', @config.reports_folder)
         begin
@@ -178,9 +211,10 @@ module GrafanaReporter
           @logger.debug("File permissions could not be set for #{file.path}: #{e.message}")
         end
 
-        report = @config.report_class.new(@config, template_file, file, attrs)
+        report = @config.report_class.new(@config)
+        Thread.report_on_exception = false
         Thread.new do
-          report.create_report
+          report.create_report(template_file, file, attrs)
         end
         @reports << report
 
@@ -190,33 +224,40 @@ module GrafanaReporter
       def get_reports_status_as_html(reports)
         i = reports.length
 
-        content = '<html>'\
-                  '<head></head>'\
-                  '<body>'\
-                  '<table>'\
-                  '<thead>'\
-                  '<th>#</th>'\
-                  '<th>Start Time</th>'\
-                  '<th>End Time</th>'\
-                  '<th>Template</th>'\
-                  '<th>Execution time</th>'\
-                  '<th>Status</th>'\
-                  '<th>Error</th>'\
-                  '<th>Action</th>'\
-                  '</thead>' +
-                  reports.reverse.map do |report|
-                    '<tr>'\
-                    "<td>#{i -= 1}</td>"\
-                    "<td>#{report.start_time}</td>"\
-                    "<td>#{report.end_time}</td>"\
-                    "<td>#{report.template}</td>"\
-                    "<td>#{report.execution_time.to_i} secs</td><td>#{report.status} (#{(report.progress * 100).to_i}%)</td><td>#{report.error.join('<br>')}</td>"\
-                    "<td>#{!report.done && !report.cancel ? "<a href=\"/cancel_report?report_id=#{report.object_id}\">Cancel</a>&nbsp;" : ''}"\
-                    "#{(report.status == 'finished') || (report.status == 'cancelled') ? "<a href=\"/view_report?report_id=#{report.object_id}\">View</a>&nbsp;" : '&nbsp;'}"\
-                    "<a href=\"/view_log?report_id=#{report.object_id}\">Log</a></td>"\
-                    '</tr>'
-                  end.join('') +
-                  '</table></body></html>'
+        # TODO: make reporter HTML results customizable
+        template = <<~HTML_TEMPLATE
+          <html>
+          <head></head>
+          <body>
+          <table>
+            <thead>
+              <th>#</th><th>Start Time</th><th>End Time</th><th>Template</th><th>Execution time</th>
+              <th>Status</th><th>Error</th><th>Action</th>
+            </thead>
+            <tbody>
+            <% reports.reverse.map do |report| %>
+              <tr><td><%= i-= 1 %></td><td><%= report.start_time %></td><td><%= report.end_time %></td>
+              <td><%= report.template %></td><td><%= report.execution_time.to_i %> secs</td>
+              <td><%= report.status %> (<%= (report.progress * 100).to_i %>%)</td>
+              <td><%= report.error.join('<br>') %></td>
+              <td><% if !report.done && !report.cancel %>
+                <a href="/cancel_report?report_id=<%= report.object_id %>">Cancel</a>
+              <% end %>
+              &nbsp;
+              <% if (report.status == 'finished') || (report.status == 'cancelled') %>
+                <a href="/view_report?report_id=<%= report.object_id %>">View</a>
+              <% end %>
+              &nbsp;
+              <a href="/view_log?report_id=<%= report.object_id %>">Log</a></td></tr>
+            <% end.join('') %>
+            <tbody>
+          </table>
+          <p style="font-size: small; color:grey">You are running ruby-grafana-reporter version <%= GRAFANA_REPORTER_VERSION.join('.') %>.</p>
+          </body>
+          </html>
+        HTML_TEMPLATE
+
+        content = ::ERB.new(template).result(binding)
 
         http_response(200, 'OK', content, "Content-Type": 'text/html')
       end

data/lib/grafana_reporter/asciidoctor/adoc_plain_table_format_strategy.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module GrafanaReporter
+  module Asciidoctor
+    # Implements a default table format strategy, which will return tables
+    # as asciidoctor formatted table.
+    class AdocPlainTableFormatStrategy < AbstractTableFormatStrategy
+      # @see AbstractTableFormatStrategy#abbreviation
+      def self.abbreviation
+        '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}"
+      end
+    end
+  end
+end

data/lib/grafana_reporter/asciidoctor/alerts_table_include_processor.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative 'processor_mixin'
+
+module GrafanaReporter
+  module Asciidoctor
+    # Implements the hook
+    #   include::grafana_alerts[<options>]
+    #
+    # Returns the results of alerts 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
+    #
+    # == Supported options
+    # +columns+ - see {AlertsTableQuery#pre_process} (*mandatory*)
+    #
+    # +instance+ - name of grafana instance, 'default' if not specified
+    #
+    # +dashboard+ - uid of grafana dashboard to query for, empty string if no filter is wanted
+    #
+    # +panel+ - id of the panel to query for
+    #
+    # +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 AlertsTableIncludeProcessor < ::Asciidoctor::Extensions::IncludeProcessor
+      include ProcessorMixin
+
+      # :nodoc:
+      def handles?(target)
+        target.start_with? 'grafana_alerts'
+      end
+
+      # :nodoc:
+      def process(doc, reader, _target, attrs)
+        return if @report.cancel
+
+        @report.next_step
+        instance = attrs['instance'] || doc.attr('grafana_default_instance') || 'default'
+        dashboard_id = attrs['dashboard'] || doc.attr('grafana_default_dashboard')
+        panel_id = attrs['panel']
+        @report.logger.debug("Processing AlertsTableIncludeProcessor (instance: #{instance},"\
+                             " dashboard: #{dashboard_id}, panel: #{panel_id})")
+
+        grafana_obj = @report.grafana(instance)
+        grafana_obj = @report.grafana(instance).dashboard(dashboard_id) if dashboard_id
+        grafana_obj = grafana_obj.panel(panel_id) if panel_id
+
+        vars = { 'table_formatter' => 'adoc_plain' }.merge(build_attribute_hash(doc.attributes, attrs))
+        query = AlertsTableQuery.new(grafana_obj, variables: vars)
+        defaults = {}
+        defaults['dashboardId'] = dashboard_id if dashboard_id
+        defaults['panelId'] = panel_id if panel_id
+
+        selected_attrs = attrs.select do |k, _v|
+          k =~ /(?:columns|limit|folderId|dashboardId|panelId|dahboardTag|dashboardQuery|state|query)/x
+        end
+        query.raw_query = defaults.merge(selected_attrs.each_with_object({}) { |(k, v), h| h[k] = v })
+
+        begin
+          reader.unshift_lines query.execute
+        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)
+        "|===\ninclude::grafana_alerts[columns=\"panelId,name,state\"]\n|==="
+      end
+    end
+  end
+end

data/lib/grafana_reporter/asciidoctor/annotations_table_include_processor.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative 'processor_mixin'
+
+module GrafanaReporter
+  module Asciidoctor
+    # Implements the hook
+    #   include::grafana_annotations[<options>]
+    #
+    # Returns the results of alerts 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
+    #
+    # == Supported options
+    # +columns+ - see {AnnotationsTableQuery#pre_process} (*mandatory*)
+    #
+    # +instance+ - name of grafana instance, 'default' if not specified
+    #
+    # +dashboard+ - uid of grafana dashboard to query for, empty string if no filter is wanted
+    #
+    # +panel+ - id of the panel to query for
+    #
+    # +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 AnnotationsTableIncludeProcessor < ::Asciidoctor::Extensions::IncludeProcessor
+      include ProcessorMixin
+
+      # :nodoc:
+      def handles?(target)
+        target.start_with? 'grafana_annotations'
+      end
+
+      # :nodoc:
+      def process(doc, reader, _target, attrs)
+        return if @report.cancel
+
+        @report.next_step
+        instance = attrs['instance'] || doc.attr('grafana_default_instance') || 'default'
+        dashboard_id = attrs['dashboard'] || doc.attr('grafana_default_dashboard')
+        panel_id = attrs['panel']
+        @report.logger.debug("Processing AnnotationsTableIncludeProcessor (instance: #{instance})")
+
+        grafana_obj = @report.grafana(instance)
+        grafana_obj = @report.grafana(instance).dashboard(dashboard_id) if dashboard_id
+        grafana_obj = grafana_obj.panel(panel_id) if panel_id
+
+        vars = { 'table_formatter' => 'adoc_plain' }.merge(build_attribute_hash(doc.attributes, attrs))
+        query = AnnotationsTableQuery.new(grafana_obj, variables: vars)
+        defaults = {}
+        defaults['dashboardId'] = dashboard_id if dashboard_id
+        defaults['panelId'] = panel_id if panel_id
+
+        selected_attrs = attrs.select do |k, _v|
+          k =~ /(?:columns|limit|alertId|dashboardId|panelId|userId|type|tags)/
+        end
+        query.raw_query = defaults.merge(selected_attrs.each_with_object({}) { |(k, v), h| h[k] = v })
+
+        begin
+          reader.unshift_lines query.execute
+        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)
+        "|===\ninclude::grafana_annotations[columns=\"time,panelId,newState,prevState,text\"]\n|==="
+      end
+    end
+  end
+end

data/lib/grafana_reporter/asciidoctor/help.rb

@@ -4,11 +4,17 @@ require 'yaml'
 
 module GrafanaReporter
   module Asciidoctor
+    # This class generates the functional help documentation for the asciidoctor report.
+    # It can create the documentation for github markdown, as well as in asciidoctor syntax.
     class Help
+      # @param headline_level [Integer] top level of headline
+      # @return [String] asciidoctor compatible documentation
       def asciidoctor(headline_level = 2)
         help_text(asciidoctor_options.merge(level: headline_level))
       end
 
+      # @param headline_level [Integer] top level of headline
+      # @return [String] github markdown compatible documentation
       def github(headline_level = 2)
         "#{toc}\n\n#{help_text(github_options.merge(level: headline_level))}"
       end
@@ -20,7 +26,8 @@ module GrafanaReporter
       end
 
       def asciidoctor_options
-        { headline_separator: '=', code_begin: '`+', code_end: '+`', table_begin: "\n[%autowidth.stretch, options=\"header\"]\n|===\n", table_end: "\n|===" }
+        { headline_separator: '=', code_begin: '`+', code_end: '+`', table_begin: "\n[%autowidth.stretch, "\
+          "options=\"header\"]\n|===\n", table_end: "\n|===" }
       end
 
       def help_text(opts)
@@ -33,13 +40,13 @@ module GrafanaReporter
       def toc
         result = []
 
-        result << "Table of contents"
-        result << "* [Global options](#global-options)"
+        result << 'Table of contents'
+        result << '* [Global options](#global-options)'
         prepared_help[:global_options].sort.map do |k, _v|
           result << "  * [#{k}](##{k.downcase})"
         end
 
-        result << "* [Functions](#functions)"
+        result << '* [Functions](#functions)'
         prepared_help[:functions].sort.map do |k, _v|
           result << "  * [#{k}](##{k.downcase})"
         end
@@ -102,13 +109,15 @@ end}
           res_item[:description] = item['description']
           res_item[:see] = item['see']
 
-          opts = ((item['options'] ? item['options'].keys : []) + (item['standard_options'] ? item['standard_options'].keys : [])).sort
+          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)
               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
+              res_item[:options][opt_key][:description] = "#{std_opts[opt_key]['description']} "\
+                                                          "#{item['standard_options'][opt_key]}".chop
               res_item[:options][opt_key][:see] = std_opts[opt_key]['see'] if std_opts[opt_key]['see']
             else
               res_item[:options][opt_key][:call] = item['options'][opt_key]['call']
@@ -122,313 +131,327 @@ end}
       end
 
       def raw_help_yaml
-        <<YAML_HELP
-global_options:
-  grafana_default_instance:
-    call: ":grafana_default_instance: <instance_name>"
-    description: >-
-      Specifies which grafana instance shall be used. If not set, the grafana instance names `default`
-      will be used.
-
-  grafana_default_dashboard:
-    call: ":grafana_default_dashboard: <dashboard_uid>"
-    description: >-
-      Specifies to which dashboard the queries shall be targeted by default.
-
-  grafana_default_from_timezone:
-    call: ":grafana_default_from_timezone: <timezone>"
-    description: Specifies which timezone shall be used for the `from` time, e.g. `CET` or `CEST`.
-
-  grafana_default_to_timezone:
-    call: ":grafana_default_to_timezone: <timezone>"
-    description: Specifies which timezone shall be used for the `to` time, e.g. `CET` or `CEST`.
-
-  from:
-    call: ":from: <from_timestamp>"
-    description: >-
-      Overrides the time setting from grafana. It may contain dates as `now-1M/M`, which will be translated
-      properly to timestamps relative to the called time.
-
-  to:
-    call: ":to: <to_timestamp>"
-    description: >-
-      Overrides the time setting from grafana. It may contain dates as `now-1M/M`, which will be translated
-      properly to timestamps relative to the called time.
-
-standard_options:
-  instance:
-    call: instance="<instance_name>"
-    description: >-
-      can be used to override global grafana instance, set in the report with `grafana_default_instance`.
-      If nothing is set, the configured grafana instance with name `default` will be used.
-
-  dashboard:
-    call: dashboard="<dashboard_uid>"
-    description: >-
-      Specifies the dashboard to be used. If `grafana_default_dashboard` is specified in the report template,
-      this value can be overridden with this option.
-
-  from:
-    call: from="<timestamp>"
-    description: can be used to override default `from` time
-
-  from_timezone:
-    call: from_timezone="<timezone>"
-    description: can be used to override system timezone for `from` time and will also override `grafana_default_from_timezone` option
-
-  to_timezone:
-    call: to_timezone="<timezone>"
-    description: can be used to override system timezone for `to` time and will also override `grafana_default_to_timezone` option
-
-  to:
-    call: to="<timestamp>"
-    description: can be used to override default `to` time
-
-  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`,
-      `replace_values`, `filter_columns`, `transpose`.
-    see: 'https://ruby-doc.org/core-2.4.0/Kernel.html#method-i-sprintf'
-
-  replace_values:
-    call: replace_values="<replace_1>:<with_1>,<replace_2>:<with_2>,..."
-    description: >-
-      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`,
-      `replace_values`, `filter_columns`, `transpose`.
-    see: https://ruby-doc.org/core-2.7.1/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`.
-
-  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`.
-
-  column_divider:
-    call: column_divider="<divider>"
-    description: >-
-      Replace the default column divider with another one. Defaults to ` | ` for being interpreted as a asciidoctor column.
-
-  row_divider:
-    call: row_divider="<divider>"
-    description: >-
-      Replace the default row divider with another one. Defaults to `| ` for being interpreted as a asciidoctor row.
-
-  timeout:
-    call: timeout="<timeout_in_seconds>"
-    description: >-
-      Set a timeout for the current query. If not overridden with `grafana-default-timeout` in the report template,
-      this defaults to 60 seconds.
-
-# ----------------------------------
-# FUNCTION DOCUMENTATION STARTS HERE
-# ----------------------------------
-
-grafana_help:
-  description: Show all available grafana calls within the asciidoctor templates, including available options.
-  call: 'include::grafana_help[]'
-
-grafana_environment:
-  description: Shows all available variables in the rendering context which can be used in the asciidoctor template.
-  call: 'include::grafana_environment[]'
-
-grafana_alerts:
-  description: >-
-    Returns a table of active alert states including the specified columns and the connected information. Supports
-    all query parameters from the Grafana Alerting API, such as `query`, `state`, `limit`, `folderId` and others.
-  call: grafana_alerts[columns="<column_name_1>,<column_name_2>,...",options]
-  see: https://grafana.com/docs/grafana/latest/http_api/alerting/#get-alerts
-  options:
-    columns:
-      description: >-
-        Specifies columns that shall be returned. Valid columns are `id`, `dashboardId`, `dashboardUId`, `dashboardSlug`,
-        `panelId`, `name`, `state`, `newStateDate`, `evalDate`, `evalData` and `executionError`.
-      call: columns="<column_name_1>,<columns_name_2>,..."
-    panel:
-      description: >-
-        If specified, the resulting alerts are filtered for this panel. This option will only work, if a `dashboard`
-        or `grafana_default_dashboard` is set.
-      call: panel="<panel_id>"
-  standard_options:
-    column_divider:
-    dashboard: >-
-      If this option, or the global option `grafana_default_dashboard` is set, the resulting alerts will be limited to
-      this dashboard. To show all alerts in this case, specify `dashboard=""` as option.
-    filter_columns:
-    format:
-    from:
-    instance:
-    replace_values:
-    row_divider:
-    timeout:
-    to:
-    transpose:
-    from_timezone:
-    to_timezone:
-
-grafana_annotations:
-  description: >-
-    Returns a table of all annotations, matching the specified filter criteria and the specified columns. Supports all
-    query parameters from the Grafana Alerting API, such as `limit`, `alertId`, `panelId` and others.
-  call: grafana_annotations[columns="<column_name_1>,<column_name_2>,...",options]
-  see: https://grafana.com/docs/grafana/latest/http_api/annotations/#find_annotations
-  options:
-    columns:
-      description: >-
-        Specified the columns that shall be returned. Valid columns are `id`, `alertId`, `dashboardId`, `panelId`, `userId`,
-        `userName`, `newState`, `prevState, `time`, `timeEnd`, `text`, `metric` and `type`.
-      call: columns="<column_name_1>,<columns_name_2>,..."
-    panel:
-      description: >-
-        If specified, the resulting alerts are filtered for this panel. This option will only work, if a `dashboard` or
-        `grafana_default_dashboard` is set.
-      call: panel="<panel_id>"
-  standard_options:
-    column_divider:
-    dashboard: >-
-      If this option, or the global option `grafana_default_dashboard` is set, the resulting alerts will be limited to this
-      dashboard. To show all alerts in this case, specify `dashboard=""` as option.
-    filter_columns:
-    format:
-    from:
-    instance:
-    replace_values:
-    row_divider:
-    timeout:
-    to:
-    transpose:
-    from_timezone:
-    to_timezone:
-
-grafana_panel_description:
-  description: >-
-    Returns a description field for the specified panel. `<type>` can either be `title` or `description`.
-    Grafana variables will be replaced in the returned value.
-  call: 'grafana_panel_description:<panel_id>["<type>",options]'
-  see: https://grafana.com/docs/grafana/latest/variables/templates-and-variables/#variable-syntax
-  standard_options:
-    dashboard:
-    instance:
-
-grafana_panel_image:
-  description: Includes a panel image as an image in the document. Can be called for inline-images as well as for blocks.
-  call: 'grafana_panel_image:<panel_id>[options] or grafana_panel_image::<panel_id>[options]'
-  options:
-    render-height:
-      description: can be used to override default `height` in which the panel shall be rendered
-      call: render-height="<height>"
-    render-width:
-      description: can be used to override default `width` in which the panel shall be rendered
-      call: render-width="<width>"
-    render-theme:
-      description: can be used to override default `theme` in which the panel shall be rendered (light by default)
-      call: render-theme="<theme>"
-    render-timeout:
-      description: can be used to override default `timeout` in which the panel shall be rendered (60 seconds by default)
-      call: render-timeout="<timeout>"
-  standard_options:
-    dashboard:
-    from:
-    instance:
-    timeout:
-    to:
-    from_timezone:
-    to_timezone:
-
-grafana_panel_query_table:
-  description: >-
-    Returns the results of a query, which is configured in a grafana panel, as a table in asciidoctor.
-    Grafana variables will be replaced in the panel's SQL statement.
-  call: 'include::grafana_panel_query_table:<panel_id>[query="<query_letter>",options]'
-  see: https://grafana.com/docs/grafana/latest/variables/templates-and-variables/#variable-syntax
-  options:
-    query:
-      call: query="<query_letter>"
-      description: +<query_letter>+ needs to point to the grafana query which shall be evaluated, e.g. +A+ or +B+.
-  standard_options:
-    column_divider:
-    dashboard:
-    filter_columns:
-    format:
-    from:
-    instance:
-    replace_values:
-    row_divider:
-    timeout:
-    to:
-    transpose:
-    from_timezone:
-    to_timezone:
-
-grafana_panel_query_value:
-  call: 'grafana_panel_query_value:<panel_id>[query="<query_letter>",options]'
-  description: >-
-    Returns the value in the first column and the first row of a query, which is configured in a grafana panel.
-    Grafana variables will be replaced in the panel's SQL statement.
-  see: https://grafana.com/docs/grafana/latest/variables/templates-and-variables/#variable-syntax
-  options:
-    query:
-      call: query="<query_letter>"
-      description: +<query_letter>+ needs to point to the grafana query which shall be evaluated, e.g. +A+ or +B+.
-  standard_options:
-    dashboard:
-    filter_columns:
-    format:
-    from:
-    instance:
-    replace_values:
-    timeout:
-    to:
-    from_timezone:
-    to_timezone:
-
-grafana_sql_table:
-  call: 'include::grafana_sql_table:<datasource_id>[sql="<sql_query>",options]'
-  description: >-
-    Returns a table with all results of the given query.
-    Grafana variables will be replaced in the SQL statement.
-  see: https://grafana.com/docs/grafana/latest/variables/templates-and-variables/#variable-syntax
-  standard_options:
-    column_divider:
-    filter_columns:
-    format:
-    from:
-    instance:
-    replace_values:
-    row_divider:
-    timeout:
-    to:
-    transpose:
-    from_timezone:
-    to_timezone:
-
-grafana_sql_value:
-  call: 'grafana_sql_value:<datasource_id>[sql="<sql_query>",options]'
-  description: >-
-    Returns the value in the first column and the first row of the given query.
-    Grafana variables will be replaced in the SQL statement.
-  see: https://grafana.com/docs/grafana/latest/variables/templates-and-variables/#variable-syntax
-  standard_options:
-    filter_columns:
-    format:
-    from:
-    instance:
-    replace_values:
-    timeout:
-    to:
-    from_timezone:
-    to_timezone:
-YAML_HELP
+        <<~YAML_HELP
+          global_options:
+            grafana_default_instance:
+              call: ":grafana_default_instance: <instance_name>"
+              description: >-
+                Specifies which grafana instance shall be used. If not set, the grafana instance names `default`
+                will be used.
+
+            grafana_default_dashboard:
+              call: ":grafana_default_dashboard: <dashboard_uid>"
+              description: >-
+                Specifies to which dashboard the queries shall be targeted by default.
+
+            grafana_default_from_timezone:
+              call: ":grafana_default_from_timezone: <timezone>"
+              description: Specifies which timezone shall be used for the `from` time, e.g. `CET` or `CEST`.
+
+            grafana_default_to_timezone:
+              call: ":grafana_default_to_timezone: <timezone>"
+              description: Specifies which timezone shall be used for the `to` time, e.g. `CET` or `CEST`.
+
+            from:
+              call: ":from: <from_timestamp>"
+              description: >-
+                Overrides the time setting from grafana. It may contain dates as `now-1M/M`, which will be translated
+                properly to timestamps relative to the called time.
+
+            to:
+              call: ":to: <to_timestamp>"
+              description: >-
+                Overrides the time setting from grafana. It may contain dates as `now-1M/M`, which will be translated
+                properly to timestamps relative to the called time.
+
+          standard_options:
+            instance:
+              call: instance="<instance_name>"
+              description: >-
+                can be used to override global grafana instance, set in the report with `grafana_default_instance`.
+                If nothing is set, the configured grafana instance with name `default` will be used.
+
+            dashboard:
+              call: dashboard="<dashboard_uid>"
+              description: >-
+                Specifies the dashboard to be used. If `grafana_default_dashboard` is specified in the report template,
+                this value can be overridden with this option.
+
+            from:
+              call: from="<timestamp>"
+              description: can be used to override default `from` time
+
+            from_timezone:
+              call: from_timezone="<timezone>"
+              description: can be used to override system timezone for `from` time and will also override `grafana_default_from_timezone` option
+
+            to_timezone:
+              call: to_timezone="<timezone>"
+              description: can be used to override system timezone for `to` time and will also override `grafana_default_to_timezone` option
+
+            to:
+              call: to="<timestamp>"
+              description: can be used to override default `to` time
+
+            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`,
+                `replace_values`, `filter_columns`, `transpose`.
+              see: 'https://ruby-doc.org/core/Kernel.html#method-i-sprintf'
+
+            replace_values:
+              call: replace_values="<replace_1>:<with_1>,<replace_2>:<with_2>,..."
+              description: >-
+                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`,
+                `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`.
+
+            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`.
+
+            column_divider:
+              call: column_divider="<divider>"
+              description: >-
+                Replace the default column divider with another one, when used in conjunction with `table_formatter` set to
+                `adoc_deprecated`. Defaults to ` | ` for being interpreted as a asciidoctor column. DEPRECATED: switch to
+                `table_formatter` named `adoc_plain`, or implement a custom table formatter.
+
+            row_divider:
+              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
+                `table_formatter` named `adoc_plain`, or implement a custom table formatter.
+
+            table_formatter:
+              call: table_formatter="<formatter>"
+              description: >-
+                Specify a table formatter fitting for your expected target format. It defaults to `adoc_plain` for asciidoctor
+                templates and to `csv` for all other templates, e.g. ERB.
+
+            timeout:
+              call: timeout="<timeout_in_seconds>"
+              description: >-
+                Set a timeout for the current query. If not overridden with `grafana_default_timeout` in the report template,
+                this defaults to 60 seconds.
+
+          # ----------------------------------
+          # FUNCTION DOCUMENTATION STARTS HERE
+          # ----------------------------------
+
+          grafana_help:
+            description: Show all available grafana calls within the asciidoctor templates, including available options.
+            call: 'include::grafana_help[]'
+
+          grafana_environment:
+            description: Shows all available variables in the rendering context which can be used in the asciidoctor template.
+            call: 'include::grafana_environment[]'
+
+          grafana_alerts:
+            description: >-
+              Returns a table of active alert states including the specified columns and the connected information. Supports
+              all query parameters from the Grafana Alerting API, such as `query`, `state`, `limit`, `folderId` and others.
+            call: 'include::grafana_alerts[columns="<column_name_1>,<column_name_2>,...",options]'
+            see: https://grafana.com/docs/grafana/latest/http_api/alerting/#get-alerts
+            options:
+              columns:
+                description: >-
+                  Specifies columns that shall be returned. Valid columns are `id`, `dashboardId`, `dashboardUId`, `dashboardSlug`,
+                  `panelId`, `name`, `state`, `newStateDate`, `evalDate`, `evalData` and `executionError`.
+                call: columns="<column_name_1>,<columns_name_2>,..."
+              panel:
+                description: >-
+                  If specified, the resulting alerts are filtered for this panel. This option will only work, if a `dashboard`
+                  or `grafana_default_dashboard` is set.
+                call: panel="<panel_id>"
+            standard_options:
+              column_divider:
+              dashboard: >-
+                If this option, or the global option `grafana_default_dashboard` is set, the resulting alerts will be limited to
+                this dashboard. To show all alerts in this case, specify `dashboard=""` as option.
+              filter_columns:
+              format:
+              from:
+              instance:
+              replace_values:
+              row_divider:
+              table_formatter:
+              timeout:
+              to:
+              transpose:
+              from_timezone:
+              to_timezone:
+
+          grafana_annotations:
+            description: >-
+              Returns a table of all annotations, matching the specified filter criteria and the specified columns. Supports all
+              query parameters from the Grafana Alerting API, such as `limit`, `alertId`, `panelId` and others.
+            call: 'include::grafana_annotations[columns="<column_name_1>,<column_name_2>,...",options]'
+            see: https://grafana.com/docs/grafana/latest/http_api/annotations/#find-annotations
+            options:
+              columns:
+                description: >-
+                  Specified the columns that shall be returned. Valid columns are `id`, `alertId`, `dashboardId`, `panelId`, `userId`,
+                  `userName`, `newState`, `prevState`, `time`, `timeEnd`, `text`, `metric` and `type`.
+                call: columns="<column_name_1>,<columns_name_2>,..."
+              panel:
+                description: >-
+                  If specified, the resulting alerts are filtered for this panel. This option will only work, if a `dashboard` or
+                  `grafana_default_dashboard` is set.
+                call: panel="<panel_id>"
+            standard_options:
+              column_divider:
+              dashboard: >-
+                If this option, or the global option `grafana_default_dashboard` is set, the resulting alerts will be limited to this
+                dashboard. To show all alerts in this case, specify `dashboard=""` as option.
+              filter_columns:
+              format:
+              from:
+              instance:
+              replace_values:
+              row_divider:
+              table_formatter:
+              timeout:
+              to:
+              transpose:
+              from_timezone:
+              to_timezone:
+
+          grafana_panel_property:
+            description: >-
+              Returns a property field for the specified panel. `<type>` can either be `title` or `description`.
+              Grafana variables will be replaced in the returned value.
+            call: 'grafana_panel_property:<panel_id>["<type>",options]'
+            see: https://grafana.com/docs/grafana/latest/variables/syntax/
+            standard_options:
+              dashboard:
+              instance:
+
+          grafana_panel_image:
+            description: Includes a panel image as an image in the document. Can be called for inline-images as well as for blocks.
+            call: 'grafana_panel_image:<panel_id>[options] or grafana_panel_image::<panel_id>[options]'
+            options:
+              render-height:
+                description: can be used to override default `height` in which the panel shall be rendered
+                call: render-height="<height>"
+              render-width:
+                description: can be used to override default `width` in which the panel shall be rendered
+                call: render-width="<width>"
+              render-theme:
+                description: can be used to override default `theme` in which the panel shall be rendered (light by default)
+                call: render-theme="<theme>"
+              render-timeout:
+                description: can be used to override default `timeout` in which the panel shall be rendered (60 seconds by default)
+                call: render-timeout="<timeout>"
+            standard_options:
+              dashboard:
+              from:
+              instance:
+              timeout:
+              to:
+              from_timezone:
+              to_timezone:
+
+          grafana_panel_query_table:
+            description: >-
+              Returns the results of a query, which is configured in a grafana panel, as a table in asciidoctor.
+              Grafana variables will be replaced in the panel's SQL statement.
+            call: 'include::grafana_panel_query_table:<panel_id>[query="<query_letter>",options]'
+            see: https://grafana.com/docs/grafana/latest/variables/syntax/
+            options:
+              query:
+                call: query="<query_letter>"
+                description: +<query_letter>+ needs to point to the grafana query which shall be evaluated, e.g. +A+ or +B+.
+            standard_options:
+              column_divider:
+              dashboard:
+              filter_columns:
+              format:
+              from:
+              instance:
+              replace_values:
+              row_divider:
+              table_formatter:
+              timeout:
+              to:
+              transpose:
+              from_timezone:
+              to_timezone:
+
+          grafana_panel_query_value:
+            call: 'grafana_panel_query_value:<panel_id>[query="<query_letter>",options]'
+            description: >-
+              Returns the value in the first column and the first row of a query, which is configured in a grafana panel.
+              Grafana variables will be replaced in the panel's SQL statement.
+            see: https://grafana.com/docs/grafana/latest/variables/syntax/
+            options:
+              query:
+                call: query="<query_letter>"
+                description: +<query_letter>+ needs to point to the grafana query which shall be evaluated, e.g. +A+ or +B+.
+            standard_options:
+              dashboard:
+              filter_columns:
+              format:
+              from:
+              instance:
+              replace_values:
+              timeout:
+              to:
+              from_timezone:
+              to_timezone:
+
+          grafana_sql_table:
+            call: 'include::grafana_sql_table:<datasource_id>[sql="<sql_query>",options]'
+            description: >-
+              Returns a table with all results of the given query.
+              Grafana variables will be replaced in the SQL statement.
+            see: https://grafana.com/docs/grafana/latest/variables/syntax/
+            standard_options:
+              column_divider:
+              filter_columns:
+              format:
+              from:
+              instance:
+              replace_values:
+              row_divider:
+              table_formatter:
+              timeout:
+              to:
+              transpose:
+              from_timezone:
+              to_timezone:
+
+          grafana_sql_value:
+            call: 'grafana_sql_value:<datasource_id>[sql="<sql_query>",options]'
+            description: >-
+              Returns the value in the first column and the first row of the given query.
+              Grafana variables will be replaced in the SQL statement.
+            see: https://grafana.com/docs/grafana/latest/variables/syntax/
+            standard_options:
+              filter_columns:
+              format:
+              from:
+              instance:
+              replace_values:
+              timeout:
+              to:
+              from_timezone:
+              to_timezone:
+        YAML_HELP
       end
     end
   end