Merge branch 'v0.2.2'

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.

Rakefile

@@ -40,6 +40,9 @@ task :build do
   sh 'bundle exec rspec spec/test_single_file.rb'
   rm "spec/tmp_single_file_lib_ruby-grafana-reporter.rb"
 
+  # update help documentation
+  File.write('FUNCTION_CALLS.md', GrafanaReporter::Asciidoctor::Help.new.github)
+
   # build new versions
   require_relative 'lib/VERSION'
 

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'

lib/grafana/dashboard.rb

@@ -13,8 +13,8 @@ def initialize(model, 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 @@ def panel(id)
 
       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

lib/grafana_reporter/asciidoctor/alerts_table_query.rb

@@ -46,8 +46,8 @@ def request
       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

lib/grafana_reporter/asciidoctor/annotations_table_query.rb

@@ -43,8 +43,8 @@ def request
       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

lib/grafana_reporter/asciidoctor/extensions/show_help_include_processor.rb

@@ -16,211 +16,13 @@ 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")
+          reader.unshift_lines Asciidoctor::Help.new.asciidoctor.split("\n")
         end
       end
     end