ruby-grafana-reporter 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f95b8d5f6221cb369bf0d11671823394683a60299dff0e688da9c5f0eab3246
-  data.tar.gz: 245804ca1843422b29a8bf8866dfaf75ec916a329f2de05739436e580c32b6e8
+  metadata.gz: 0aff73969c807020f8c39fe5a9c4095a3a8ee093e5fe94982a12f0899c057d44
+  data.tar.gz: 179f0d922e2a2a477c04cb91d4fffc692c99fdf394f78fef8ff6bfed0a0b5817
 SHA512:
-  metadata.gz: 84d7265803d6cfedec4f63b9a2938ed181bfdd9f9865bafbd3953c5a208de129e4029dd1bd8855c38ceefb9b215ea071a69242bb8ba6bfacd3f38c14e5a72e5e
-  data.tar.gz: a28e456174baae970bbe0d2abc76675e6900ce3e821b6e35a215f5ee81ff760a61ccf757bc1c5c5d7b79e8e5ac8488f7edde5d1c7f3d708399a60dade839c9dc
+  metadata.gz: e2d4730cbac1a089b9bb23eff305f5e6f9b189c66129370ab16400ec0edf993b8f5350305eccce29d4ffb1472d3e80d548be640ef4ac529babb14b3a8066e957
+  data.tar.gz: 74dfd8961382f3a9e0e35db3557a46762df27843f67cb17be6d0a3b530ff05de4ea09384a4beebfc40716f07b357ffa6eab1fbe0868c63140eeb7de6e2d3c5a1

data/README.md

@@ -35,6 +35,9 @@ The report may also be returned in any other format that asciidoctor supports.
 The reporter can run standalone or as a webservice. It is built to
 integrate without further dependencies with the asciidoctor docker image.
 
+Can't wait to see, what functions the reporter provides within the asciidoctor
+templates? Have a look at the [function documentation](FUNCTION_CALLS.md).
+
 The complete
 [API documentation](https://rubydoc.info/gems/ruby-grafana-reporter) can be
 found here.

data/lib/VERSION.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 # Version information
-GRAFANA_REPORTER_VERSION = [0, 2, 1].freeze
-GRAFANA_REPORTER_RELEASE_DATE = '2020-12-20'
+GRAFANA_REPORTER_VERSION = [0, 2, 2].freeze
+GRAFANA_REPORTER_RELEASE_DATE = '2021-01-30'

data/lib/grafana/dashboard.rb

@@ -13,8 +13,8 @@ module Grafana
       @grafana = grafana
       @model = model
 
-      initialize_panels
-      initialize_variables
+      init_panels
+      init_variables
     end
 
     # @return [String] +from+ time configured in the dashboard.
@@ -42,35 +42,35 @@ module Grafana
 
       panels.first
     end
-  end
 
-  private
+    private
 
-  # store variables in array as objects of type Variable
-  def initialize_variables
-    @variables = []
-    return unless @model.key?('templating')
+    # store variables in array as objects of type Variable
+    def init_variables
+      @variables = []
+      return unless @model.key?('templating')
 
-    list = @model['templating']['list']
-    return unless list.is_a? Array
+      list = @model['templating']['list']
+      return unless list.is_a? Array
 
-    list.each do |item|
-      @variables << Variable.new(item)
+      list.each do |item|
+        @variables << Variable.new(item)
+      end
     end
-  end
 
-  # read panels
-  def initialize_panels
-    @panels = []
-    return unless @model.key?('panels')
+    # read panels
+    def init_panels
+      @panels = []
+      return unless @model.key?('panels')
 
-    @model['panels'].each do |panel|
-      if panel.key?('panels')
-        panel['panels'].each do |subpanel|
-          @panels << Panel.new(subpanel, self)
+      @model['panels'].each do |panel|
+        if panel.key?('panels')
+          panel['panels'].each do |subpanel|
+            @panels << Panel.new(subpanel, self)
+          end
+        else
+          @panels << Panel.new(panel, self)
         end
-      else
-        @panels << Panel.new(panel, self)
       end
     end
   end

data/lib/grafana_reporter/asciidoctor/alerts_table_query.rb

@@ -46,8 +46,8 @@ module GrafanaReporter
       def pre_process(_grafana)
         raise MissingMandatoryAttributeError, 'columns' unless @variables['columns']
 
-        @from = translate_date(@from, @variables['grafana-report-timestamp'], false)
-        @to = translate_date(@to, @variables['grafana-report-timestamp'], true)
+        @from = translate_date(@from, @variables['grafana-report-timestamp'], false, @variables['from_timezone'] || @variables['grafana_default_from_timezone'])
+        @to = translate_date(@to, @variables['grafana-report-timestamp'], true, @variables['to_timezone'] || @variables['grafana_default_to_timezone'])
       end
 
       # Filter the query result for the given columns and sets the result in the preformatted SQL

data/lib/grafana_reporter/asciidoctor/annotations_table_query.rb

@@ -43,8 +43,8 @@ module GrafanaReporter
       def pre_process(_grafana)
         raise MissingMandatoryAttributeError, 'columns' unless @variables['columns']
 
-        @from = translate_date(@from, @variables['grafana-report-timestamp'], false)
-        @to = translate_date(@to, @variables['grafana-report-timestamp'], true)
+        @from = translate_date(@from, @variables['grafana-report-timestamp'], false, @variables['from_timezone'] || @variables['grafana_default_from_timezone'])
+        @to = translate_date(@to, @variables['grafana-report-timestamp'], true, @variables['to_timezone'] || @variables['grafana_default_to_timezone'])
       end
 
       # Filters the query result for the given columns and sets the result

data/lib/grafana_reporter/asciidoctor/extensions/show_help_include_processor.rb

@@ -1,228 +1,30 @@
-module GrafanaReporter
-  module Asciidoctor
-    module Extensions
-      # Implements the hook
-      #   include::grafana_help[]
-      #
-      # Shows all available options for the asciidoctor grafana reporter in a asciidoctor readable form.
-      #
-      # == Used document parameters
-      # None
-      class ShowHelpIncludeProcessor < ::Asciidoctor::Extensions::IncludeProcessor
-        include ProcessorMixin
-
-        # :nodoc:
-        def handles?(target)
-          target.start_with? 'grafana_help'
-        end
-
-        # :nodoc:
-        def replaces_variables(where = nil)
-          "https://grafana.com/docs/grafana/latest/variables/templates-and-variables/#variable-syntax[Grafana variables] will be replaced#{' ' + where.to_s if where}."
-        end
-
-        # :nodoc:
-        def process(_doc, reader, _target, _attrs)
-          # return if @report.cancel
-          @report.next_step
-          @report.logger.debug('Processing ShowHelpIncludeProcessor')
-          exec_order = 'Execution is applied in the following order: `format`, `replace_values`, `filter_columns`, `transpose`.'
-
-          param_instance = '| `instance="<instance_name>"` | 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.'
-          param_dashboard = '| `dashboard="<dashboard_uid>"` | Specifies the dashboard to be used. If `grafana_default_dashboard` is specified in the report template, this value can be overridden with this option.'
-          param_from = '| `from="<from_timestamp>"` | can be used to override default `from` time'
-          param_to = '| `to="<to_timestamp>"` | can be used to override default `to` time'
-  
-          param_format = '| `format="<format_col1>,<format_col2>,..."` | 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 `,`. For details see https://ruby-doc.org/core-2.4.0/Kernel.html#method-i-sprintf[Ruby documentation].'
-          param_replace_values = "| `replace_values=\"<replace_1>:<with_1>,<replace_2>:<with_2>,...\"` | 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`. For details see https://ruby-doc.org/core-2.7.1/Regexp.html#class-Regexp-label-Character+Classes[Ruby Regexp class]. Number replacements can also be performed, e.g. `<8.2` or `<>3`. #{exec_order}"
-          param_filter_columns = '| `filter_columns="<column_name_1>,<column_name_2>,..."` | Removes specified columns from result.'
-          param_transpose = '| `transpose="true"` | Transposes the query result, i.e. columns become rows and rows become columnns.'
-          param_column_divider = '| `column_divider="<divider>"` | Replace the default column divider with another one. Defaults to ` | ` for being interpreted as a asciidoctor column.'
-          param_row_divider = '| `row_divider="<divider>"` | Replace the default row divider with another one. Defaults to `| ` for being interpreted as a asciidoctor row.'
-          param_timeout = '| `timeout="<timeout_in_seconds>" | Set a timeout for the current query. If not overridden with `grafana-default-timeout` in the report template, this defaults to 60 seconds.'
-
-          help = "
-== Grafana Reporter Functions
-=== `grafana_help`
-[cols=\"~,80\"]
-|===
-| Call | `+include::grafana_help[]+`
-| Description | Shows this information.
-|===
-
-=== `grafana_environment`
-[cols=\"~,80\"]
-|===
-| Call | `+include::grafana_environment[]+`
-| Description | Shows all available variables in the rendering context which can be used in the document.
-|===
-
-=== `grafana_alerts`
-[cols=\"~,80\"]
-|===
-| Call | `+grafana_alerts[columns=\"<column_name_1>,<column_name_2>,...\",options]+`
-| Description | Returns a table of active alert states with the specified columns. Valid colums are `id`, `dashboardId`, `dashboardUId`, `dashboardSlug`, `panelId`, `name`, `state`, `newStateDate`, `evalDate`, `evalData` and `executionError` (for details see https://grafana.com/docs/grafana/latest/http_api/alerting/#get-alerts[Grafana Alerting API]).
-|===
-[%autowidth.stretch, options=\"header\"]
-|===
-| Option | Description
-#{param_column_divider}
-#{param_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.
-#{param_filter_columns} #{exec_order}
-#{param_format} #{exec_order}
-#{param_from}
-#{param_instance}
-| `panel=\"<panel_id>\"` | If specified, the resulting alerts are filtered for this panel. This option will only work, if a `dashboard` or `grafana_default_dashboard` is set.
-#{param_replace_values} #{exec_order}
-#{param_row_divider}
-#{param_timeout}
-#{param_to}
-#{param_transpose} #{exec_order}
-|===
-Additionally all query parameters from the https://grafana.com/docs/grafana/latest/http_api/alerting/#get-alerts[Grafana Alerting API], such as `query`, `state`, `limit`, `folderId` and others are supported.
-
-=== `grafana_annotations`
-[cols=\"~,80\"]
-|===
-| Call | `+grafana_annotations[columns=\"<column_name_1>,<column_name_2>,...\",options]+`
-| Description | Returns a table of all annotations, matching the specified filter criteria and the specified columns. Valid colums are `id`, `alertId`, `dashboardId`, `panelId`, `userId`, `userName`, `newState`, `prevState, `time`, `timeEnd`, `text`, `metric` and `type` (for details see https://grafana.com/docs/grafana/latest/http_api/annotations/#find_annotations[Grafana Annotations API]).
-|===
-[%autowidth.stretch, options=\"header\"]
-|===
-| Option | Description
-#{param_column_divider}
-#{param_dashboard} If this option, or the global option `grafana_default_dashboard` is set, the resulting annotations will be limited to this dashboard. To show all annotations in this case, specify `dashboard=\"\"` as option.
-#{param_filter_columns} #{exec_order}
-#{param_format} #{exec_order}
-#{param_from}
-#{param_instance}
-| `panel=\"<panel_id>\"` | If specified, the resulting annotations are filtered for this panel. This option will only work, if a `dashboard` or `grafana_default_dashboard` is set.
-#{param_replace_values} #{exec_order}
-#{param_row_divider}
-#{param_timeout}
-#{param_to}
-#{param_transpose} #{exec_order}
-|===
-Additionally all quer parameters from the https://grafana.com/docs/grafana/latest/http_api/annotations/#find_annotations[Grafana Alerting API], such as `limit`, `alertId`, `panelId` and others are supported.
-
-=== `grafana_panel_description`
-[cols=\"~,80\"]
-|===
-| Call | `+grafana_panel_description:<panel_id>[\"<type>\",options]+`
-| Description | Returns a description field for the specified panel. `+<type>+` can either be `title` or `description`. #{replaces_variables('in the returned value')}
-|===
-[%autowidth.stretch, options=\"header\"]
-|===
-| Option | Description
-#{param_dashboard}
-#{param_instance}
-|===
-
-=== `grafana_panel_image`
-[cols=\"~,80\"]
-|===
-| Call Inline | `+grafana_panel_image:<panel_id>[options]+`
-| Call Block | `+grafana_panel_image::<panel_id>[options]+`
-| Description | Includes a panel image as an image in the document. Can be calles for inline-images as well as for blocks.
-|===
-[%autowidth.stretch, options=\"header\"]
-|===
-| Option | Description
-#{param_dashboard}
-#{param_from}
-#{param_instance}
-#{param_timeout}
-#{param_to}
-| `render-height=\"<height>\"` | can be used to override default `height` in which the panel shall be rendered
-| `render-width=\"<width>\"` | can be used to override default `width` in which the panel shall be rendered
-| `render-theme=\"<theme>\"` | can be used to override default `theme` in which the panel shall be rendered (`light` by default)
-| `render-timeout=\"<timeout>\"` | can be used to override default `timeout` in which the panel shall be rendered (60 seconds by default)
-|===
-
-=== `grafana_panel_query_table`
-[cols=\"~,80\"]
-|===
-| Call | `+include:grafana_panel_query_table:<panel_id>[query=\"<query_letter>\",options]+`
-| Description | Returns the results of a query, which is configured in a grafana panel, as a table in asciidoc. `+<query_letter>+` needs to point to the grafana query which shall be evaluated, e.g. `A` or `B`. #{replaces_variables("in the panel's SQL statement")}
-|===
-[%autowidth.stretch, options=\"header\"]
-|===
-| Option | Description
-#{param_column_divider}
-#{param_dashboard}
-#{param_filter_columns} #{exec_order}
-#{param_format} #{exec_order}
-#{param_from}
-#{param_instance}
-#{param_replace_values} #{exec_order}
-#{param_row_divider}
-#{param_timeout}
-#{param_to}
-#{param_transpose} #{exec_order}
-|===
-
-=== `grafana_panel_query_value`
-[cols=\"~,80\"]
-|===
-| Call | `+grafana_panel_query_value:<panel_id>[query=\"<query_letter>\",options]+`
-| Description | Returns the first returned value of in the first column of  a query, which is configured in a grafana panel. `+<query_letter>+` needs to point to the grafana query which shall be evaluated, e.g. `A` or `B`. #{replaces_variables("in the panel's SQL statement")}
-|===
-[%autowidth.stretch, options=\"header\"]
-|===
-| Option | Description
-#{param_dashboard}
-#{param_filter_columns} #{exec_order}
-#{param_format} #{exec_order}
-#{param_from}
-#{param_instance}
-#{param_replace_values} #{exec_order}
-#{param_row_divider}
-#{param_timeout}
-#{param_to}
-|===
-
-=== `grafana_sql_table`
-[cols=\"~,80\"]
-|===
-| Call | `+include::grafana_sql_table:<datasource_id>[sql=\"<sql_query>\",options]+`
-| Description | Returns a table with all results of the given query. #{replaces_variables('in the SQL statement')}
-|===
-[%autowidth.stretch, options=\"header\"]
-|===
-| Option | Description
-#{param_column_divider}
-#{param_filter_columns} #{exec_order}
-#{param_format} #{exec_order}
-#{param_from}
-#{param_instance}
-#{param_replace_values} #{exec_order}
-#{param_row_divider}
-#{param_timeout}
-#{param_to}
-#{param_transpose} #{exec_order}
-|===
-
-=== `grafana_sql_value`
-[cols=\"~,80\"]
-|===
-| Call | `+grafana_sql_value:<datasource_id>[sql=\"<sql_query>\",options]+`
-| Description | Returns a table with all results of the given query. #{replaces_variables('in the SQL statement')}
-|===
-[%autowidth.stretch, options=\"header\"]
-|===
-| Option | Description
-#{param_filter_columns} #{exec_order}
-#{param_format} #{exec_order}
-#{param_from}
-#{param_instance}
-#{param_replace_values} #{exec_order}
-#{param_timeout}
-#{param_to}
-|==="
-
-          reader.unshift_lines help.split("\n")
-        end
-      end
-    end
-  end
-end
+module GrafanaReporter
+  module Asciidoctor
+    module Extensions
+      # Implements the hook
+      #   include::grafana_help[]
+      #
+      # Shows all available options for the asciidoctor grafana reporter in a asciidoctor readable form.
+      #
+      # == Used document parameters
+      # None
+      class ShowHelpIncludeProcessor < ::Asciidoctor::Extensions::IncludeProcessor
+        include ProcessorMixin
+
+        # :nodoc:
+        def handles?(target)
+          target.start_with? 'grafana_help'
+        end
+
+        # :nodoc:
+        def process(_doc, reader, _target, _attrs)
+          # return if @report.cancel
+          @report.next_step
+          @report.logger.debug('Processing ShowHelpIncludeProcessor')
+
+          reader.unshift_lines Asciidoctor::Help.new.asciidoctor.split("\n")
+        end
+      end
+    end
+  end
+end

data/lib/grafana_reporter/asciidoctor/help.rb

@@ -0,0 +1,435 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module GrafanaReporter
+  module Asciidoctor
+    class Help
+      def asciidoctor(headline_level = 2)
+        help_text(asciidoctor_options.merge(level: headline_level))
+      end
+
+      def github(headline_level = 2)
+        "#{toc}\n\n#{help_text(github_options.merge(level: headline_level))}"
+      end
+
+      private
+
+      def github_options
+        { headline_separator: '#', code_begin: '`', code_end: '`', table_begin: "\n", head_postfix_col: '| -- ' }
+      end
+
+      def asciidoctor_options
+        { headline_separator: '=', code_begin: '`+', code_end: '+`', table_begin: "\n[%autowidth.stretch, options=\"header\"]\n|===\n", table_end: "\n|===" }
+      end
+
+      def help_text(opts)
+        %(#{opts[:headline_separator] * opts[:level]} Global options
+#{global_options_as_text(opts.merge(level: opts[:level] + 1))}
+#{opts[:headline_separator] * opts[:level]} Functions
+#{functions_as_text(opts.merge(level: opts[:level] + 1))})
+      end
+
+      def toc(opts = {})
+        result = []
+
+        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)"
+        prepared_help[:functions].sort.map do |k, v|
+          result << "  * [#{k}](##{k.downcase})"
+        end
+
+        result.join("\n")
+      end
+
+      def global_options_as_text(opts = {})
+        opts = { level: 3 }.merge(opts)
+        result = []
+
+        prepared_help[:global_options].sort.map do |k, v|
+          result << %(
+#{opts[:headline_separator] * opts[:level]} #{opts[:code_begin]}#{k}#{opts[:code_end]}
+Usage: #{opts[:code_begin]}#{v['call']}#{opts[:code_end]}
+
+#{v['description']}
+)
+        end
+
+        result.join
+      end
+
+      def functions_as_text(opts = {})
+        opts = { level: 3, headline_separator: '=' }.merge(opts)
+        result = []
+
+        prepared_help[:functions].sort.map do |k, v|
+          result << %(
+#{opts[:headline_separator] * opts[:level]} #{opts[:code_begin]}#{k}#{opts[:code_end]}
+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]})
+end}
+)
+        end
+
+        result.join
+      end
+
+      def prepared_help
+        yaml = YAML.safe_load(raw_help_yaml)
+
+        result = {}
+        result[:functions] = {}
+        result[:global_options] = yaml['global_options']
+
+        functions = result[:functions]
+        std_opts = yaml['standard_options']
+        yaml.reject { |k, _v| k =~ /.*_options$/ }.each_key do |key|
+          functions[key] = {}
+          res_item = functions[key]
+          res_item[:options] = {}
+
+          item = yaml[key]
+          res_item[:call] = item['call']
+          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.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][:see] = std_opts[opt_key]['see'] if std_opts[opt_key]['see']
+            else
+              res_item[:options][opt_key][:call] = item['options'][opt_key]['call']
+              res_item[:options][opt_key][:description] = item['options'][opt_key]['description']
+              res_item[:options][opt_key][:see] = item['options'][opt_key]['see'] if item['options'][opt_key]['see']
+            end
+          end
+        end
+
+        result
+      end
+
+      def raw_help_yaml
+        return <<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
+      end
+    end
+  end
+end

data/lib/grafana_reporter/asciidoctor/panel_first_value_query.rb

@@ -26,8 +26,8 @@ module GrafanaReporter
         @datasource = @panel.field('datasource')
         @datasource_id = grafana.datasource_id(@datasource)
         super(grafana)
-        @from = translate_date(@from, @variables['grafana-report-timestamp'], false)
-        @to = translate_date(@to, @variables['grafana-report-timestamp'], true)
+        @from = translate_date(@from, @variables['grafana-report-timestamp'], false, @variables['from_timezone'] || @variables['grafana_default_from_timezone'])
+        @to = translate_date(@to, @variables['grafana-report-timestamp'], true, @variables['to_timezone'] || @variables['grafana_default_to_timezone'])
       end
     end
   end

data/lib/grafana_reporter/asciidoctor/panel_image_query.rb

@@ -9,8 +9,9 @@ module GrafanaReporter
       # Sets the proper render variables.
       def pre_process(grafana)
         super
-        @from = translate_date(@from, @variables['grafana-report-timestamp'], false)
-        @to = translate_date(@to, @variables['grafana-report-timestamp'], true)
+        @from = translate_date(@from, @variables['grafana-report-timestamp'], false, @variables['from_timezone'] || @variables['grafana_default_from_timezone'])
+        @to = translate_date(@to, @variables['grafana-report-timestamp'], true, @variables['to_timezone'] || @variables['grafana_default_to_timezone'])
+# TODO: ensure that in case of timezones are specified, that they are also forwarded to the image renderer as URL parameter
         # rename "render-" variables
         @variables = @variables.each_with_object({}) { |(k,v), h| h[k.gsub(/^render-/, '')] = v }
       end

data/lib/grafana_reporter/asciidoctor/panel_table_query.rb

@@ -30,8 +30,8 @@ module GrafanaReporter
         @datasource = @panel.field('datasource')
         @datasource_id = grafana.datasource_id(@datasource)
         super(grafana)
-        @from = translate_date(@from, @variables['grafana-report-timestamp'], false)
-        @to = translate_date(@to, @variables['grafana-report-timestamp'], true)
+        @from = translate_date(@from, @variables['grafana-report-timestamp'], false, @variables['from_timezone'] || @variables['grafana_default_from_timezone'])
+        @to = translate_date(@to, @variables['grafana-report-timestamp'], true, @variables['to_timezone'] || @variables['grafana_default_to_timezone'])
       end
     end
   end

data/lib/grafana_reporter/asciidoctor/query_mixin.rb

@@ -8,8 +8,8 @@ module GrafanaReporter
       # @param item_hash [Hash] variables from item configuration level, i.e. specific call, which may override document
       # @return [void]
       def merge_hash_variables(document_hash, item_hash)
-        merge_variables(document_hash.select { |k, _v| k =~ /^var-/ || k == 'grafana-report-timestamp' }.each_with_object({}) { |(k,v), h| h[k] = ::Grafana::Variable.new(v) })
-        merge_variables(item_hash.select { |k, _v| k =~ /^var-/ || k =~ /^render-/ || k =~ /filter_columns|format|replace_values_.*|transpose|column_divider|row_divider/ }.each_with_object({}) { |(k,v), h| h[k] = ::Grafana::Variable.new(v) })
+        merge_variables(document_hash.select { |k, _v| k =~ /^var-/ || k == 'grafana-report-timestamp' || k =~ /grafana_default_(?:from|to)_timezone/ }.each_with_object({}) { |(k,v), h| h[k] = ::Grafana::Variable.new(v) })
+        merge_variables(item_hash.select { |k, _v| k =~ /^var-/ || k =~ /^render-/ || k =~ /filter_columns|format|replace_values_.*|transpose|column_divider|row_divider|from_timezone|to_timezone/ }.each_with_object({}) { |(k,v), h| h[k] = ::Grafana::Variable.new(v) })
         self.timeout = item_hash['timeout'] || document_hash['grafana-default-timeout'] || timeout
         self.from = item_hash['from'] || document_hash['from'] || from
         self.to = item_hash['to'] || document_hash['to'] || to
@@ -225,8 +225,9 @@ module GrafanaReporter
       # @param report_time [Grafana::Variable] report start time
       # @param is_to_time [Boolean] true, if the time should be calculated for +to+, false if it shall be
       #   calculated for +from+
+      # @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)
+      def translate_date(orig_date, report_time, is_to_time, timezone=nil)
         report_time ||= Variable.new(Time.now.to_s)
         return (DateTime.parse(report_time.raw_value).to_time.to_i * 1000).to_s unless orig_date
         return orig_date if orig_date =~ /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/
@@ -237,6 +238,9 @@ module GrafanaReporter
         raise TimeRangeUnknownError, orig_date unless date_splitted
 
         date = DateTime.parse(report_time.raw_value)
+# TODO: allow from_translated or similar in ADOC template
+        date = date.new_offset(timezone.raw_value) if timezone
+
         # substract specified time
         count = 1
         count = date_splitted[:sub_count].to_i if date_splitted[:sub_count]
@@ -287,7 +291,10 @@ module GrafanaReporter
           date = date.next_year if is_to_time
         end
 
-        (date.to_time.to_i * 1000).to_s
+        # step back one second, if this is the 'to' time
+        date = (date.to_time - 1).to_datetime if is_to_time
+
+        (Time.at(date.to_time.to_i).to_i * 1000).to_s
       end
     end
   end

data/lib/grafana_reporter/asciidoctor/report.rb

@@ -63,17 +63,20 @@ module GrafanaReporter
 
           # build zip file
           zip_file = Tempfile.new('gf_zip')
-          Zip::File.open(zip_file.path, Zip::File::CREATE) do |zipfile|
+          buffer = Zip::OutputStream.write_buffer do |zipfile|
             # add report file
-            zipfile.get_output_stream("#{dest_path.gsub(@config.reports_folder, '')}.#{attrs['convert-backend']}") do |f|
-              f.puts File.read(dest_path)
-            end
+            zipfile.put_next_entry("#{dest_path.gsub(@config.reports_folder, '')}.#{attrs['convert-backend']}")
+            zipfile.write File.read(dest_path)
 
             # add image files
             @image_files.each do |file|
-              zipfile.get_output_stream(file.path.gsub(@config.images_folder, '')) { |f| f.puts File.read(file.path) }
+              zipfile.put_next_entry(file.path.gsub(@config.images_folder, ''))
+              zipfile.write File.read(file.path)
             end
           end
+          File.open(zip_file, 'wb') do |f|
+            f.write buffer.string
+          end
 
           # replace original file with zip file
           zip_file.rewind

data/lib/grafana_reporter/asciidoctor/sql_first_value_query.rb

@@ -27,6 +27,16 @@ module GrafanaReporter
         end
         @result = ''
       end
+
+      # Translates the from and to times.
+      # @see Grafana::AbstractSqlQuery#pre_process
+      # @param grafana [Grafana::Grafana] grafana instance against which the query shall be executed
+      # @return [void]
+      def pre_process(grafana)
+        super(grafana)
+        @from = translate_date(@from, @variables['grafana-report-timestamp'], false, @variables['from_timezone'] || @variables['grafana_default_from_timezone'])
+        @to = translate_date(@to, @variables['grafana-report-timestamp'], true, @variables['to_timezone'] || @variables['grafana_default_to_timezone'])
+      end
     end
   end
 end

data/lib/grafana_reporter/asciidoctor/sql_table_query.rb

@@ -29,6 +29,16 @@ module GrafanaReporter
           end.join(column_divider)
         end
       end
+
+      # Translates the from and to times.
+      # @see Grafana::AbstractSqlQuery#pre_process
+      # @param grafana [Grafana::Grafana] grafana instance against which the query shall be executed
+      # @return [void]
+      def pre_process(grafana)
+        super(grafana)
+        @from = translate_date(@from, @variables['grafana-report-timestamp'], false, @variables['from_timezone'] || @variables['grafana_default_from_timezone'])
+        @to = translate_date(@to, @variables['grafana-report-timestamp'], true, @variables['to_timezone'] || @variables['grafana_default_to_timezone'])
+      end
     end
   end
 end

data/lib/ruby-grafana-reporter.rb

@@ -27,5 +27,3 @@ folders = [
   %w[grafana_reporter application]
 ]
 folders.each { |folder| Dir[File.join(__dir__, *folder, '*.rb')].sort.each { |file| require_relative file } }
-
-# TODO check if panel with ID exists before trying to render image

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-grafana-reporter
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Christian Kohlmeyer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-12-20 00:00:00.000000000 Z
+date: 2021-01-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor
@@ -100,10 +100,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.9'
-description: Provides a standalone and a webservice frontend for creating reportsbased
-  on asciidoctor, including interfaces to integrate dynamic contentcaptured from grafana.By
-  default the reports will be converted to PDF documents, whereas othertarget formats
-  can be used as well.
+description: Provides a standalone and a webservice frontend for creating reports
+  based on asciidoctor, including interfaces to integrate dynamic content captured
+  from grafana.By default the reports will be converted to PDF documents, whereas
+  other target formats can be used as well.
 email: kohly@gmx.de
 executables:
 - ruby-grafana-reporter
@@ -142,6 +142,7 @@ files:
 - "./lib/grafana_reporter/asciidoctor/extensions/sql_table_include_processor.rb"
 - "./lib/grafana_reporter/asciidoctor/extensions/sql_value_inline_macro.rb"
 - "./lib/grafana_reporter/asciidoctor/extensions/value_as_variable_include_processor.rb"
+- "./lib/grafana_reporter/asciidoctor/help.rb"
 - "./lib/grafana_reporter/asciidoctor/panel_first_value_query.rb"
 - "./lib/grafana_reporter/asciidoctor/panel_image_query.rb"
 - "./lib/grafana_reporter/asciidoctor/panel_property_query.rb"