ruby-grafana-reporter 0.1.6 → 0.3.0

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

@@ -1,70 +1,73 @@
-require_relative 'processor_mixin'
-
-module GrafanaReporter
-  module Asciidoctor
-    module Extensions
-      # Implements the hook
-      #   grafana_panel_query_value:<panel_id>[<options>]
-      #
-      # Returns the first value of the resulting SQL query.
-      #
-      # == 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
-      #
-      # All other variables starting with +var-+ will be used to replace grafana templating strings
-      # in the given SQL query.
-      #
-      # == Supported options
-      # +query+ - query letter, which shall be used, e.g. +C+ (*mandatory*)
-      #
-      # +instance+ - name of grafana instance, 'default' if not specified
-      #
-      # +dashboard+ - uid of grafana dashboard to use
-      #
-      # +from+ - 'from' time for the sql query
-      #
-      # +to+ - 'to' time for the sql query
-      #
-      # +format+ - see {QueryMixin#format_columns}
-      #
-      # +replace_values+ - see {QueryMixin#replace_values}
-      #
-      # +filter_columns+ - see {QueryMixin#filter_columns}
-      class PanelQueryValueInlineMacro < ::Asciidoctor::Extensions::InlineMacroProcessor
-        include ProcessorMixin
-        use_dsl
-
-        named :grafana_panel_query_value
-
-        # :nodoc:
-        def process(parent, target, attrs)
-          return if @report.cancel
-
-          @report.next_step
-          instance = attrs['instance'] || parent.document.attr('grafana_default_instance') || 'default'
-          dashboard = attrs['dashboard'] || parent.document.attr('grafana_default_dashboard')
-          @report.logger.debug("Processing PanelQueryValueInlineMacro (instance: #{instance}, dashboard: #{dashboard}, panel: #{target}, query: #{attrs['query']})")
-          query = PanelFirstValueQuery.new(@report.grafana(instance).dashboard(dashboard).panel(target), attrs['query'])
-          query.merge_hash_variables(parent.document.attributes, attrs)
-          @report.logger.debug("from: #{query.from}, to: #{query.to}")
-
-          begin
-            create_inline(parent, :quoted, query.execute(@report.grafana(instance)))
-          rescue GrafanaReporterError => e
-            @report.logger.error(e.message)
-            create_inline(parent, :quoted, e.message)
-          rescue StandardError => e
-            @report.logger.fatal(e.message)
-            create_inline(parent, :quoted, e.message)
-          end
-        end
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+
+require_relative 'processor_mixin'
+
+module GrafanaReporter
+  module Asciidoctor
+    module Extensions
+      # Implements the hook
+      #   grafana_panel_query_value:<panel_id>[<options>]
+      #
+      # Returns the first value of the resulting SQL query.
+      #
+      # == 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
+      #
+      # All other variables starting with +var-+ will be used to replace grafana templating strings
+      # in the given SQL query.
+      #
+      # == Supported options
+      # +query+ - query letter, which shall be used, e.g. +C+ (*mandatory*)
+      #
+      # +instance+ - name of grafana instance, 'default' if not specified
+      #
+      # +dashboard+ - uid of grafana dashboard to use
+      #
+      # +from+ - 'from' time for the sql query
+      #
+      # +to+ - 'to' time for the sql query
+      #
+      # +format+ - see {QueryMixin#format_columns}
+      #
+      # +replace_values+ - see {QueryMixin#replace_values}
+      #
+      # +filter_columns+ - see {QueryMixin#filter_columns}
+      class PanelQueryValueInlineMacro < ::Asciidoctor::Extensions::InlineMacroProcessor
+        include ProcessorMixin
+        use_dsl
+
+        named :grafana_panel_query_value
+
+        # :nodoc:
+        def process(parent, target, attrs)
+          return if @report.cancel
+
+          @report.next_step
+          instance = attrs['instance'] || parent.document.attr('grafana_default_instance') || 'default'
+          dashboard = attrs['dashboard'] || parent.document.attr('grafana_default_dashboard')
+          @report.logger.debug("Processing PanelQueryValueInlineMacro (instance: #{instance}, dashboard: #{dashboard},"\
+                               " panel: #{target}, query: #{attrs['query']})")
+          query = PanelFirstValueQuery.new(@report.grafana(instance).dashboard(dashboard).panel(target), attrs['query'])
+          query.merge_hash_variables(parent.document.attributes, attrs)
+          @report.logger.debug("from: #{query.from}, to: #{query.to}")
+
+          begin
+            create_inline(parent, :quoted, query.execute(@report.grafana(instance)))
+          rescue GrafanaReporterError => e
+            @report.logger.error(e.message)
+            create_inline(parent, :quoted, e.message)
+          rescue StandardError => e
+            @report.logger.fatal(e.message)
+            create_inline(parent, :quoted, e.message)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,18 +1,20 @@
-module GrafanaReporter
-  module Asciidoctor
-    # The classes within this module implement the interface to asciidoctor. Each class implements a specific extension to
-    # asciidoctor.
-    module Extensions
-      # This module contains common methods for all asciidoctor extensions.
-      module ProcessorMixin
-        # Used when initializing a object instance, to set the report object, which is currently in progress.
-        # @param report [GrafanaReporter::Asciidoctor::Report] current report
-        # @return [::Asciidoctor::Extensions::Processor] self
-        def current_report(report)
-          @report = report
-          self
-        end
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+
+module GrafanaReporter
+  module Asciidoctor
+    # The classes within this module implement the interface to asciidoctor. Each class implements a specific extension
+    # to asciidoctor.
+    module Extensions
+      # This module contains common methods for all asciidoctor extensions.
+      module ProcessorMixin
+        # Used when initializing a object instance, to set the report object, which is currently in progress.
+        # @param report [GrafanaReporter::Asciidoctor::Report] current report
+        # @return [::Asciidoctor::Extensions::Processor] self
+        def current_report(report)
+          @report = report
+          self
+        end
+      end
+    end
+  end
+end

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

@@ -1,41 +1,43 @@
-module GrafanaReporter
-  module Asciidoctor
-    module Extensions
-      # Implements the hook
-      #   include::grafana_environment[]
-      #
-      # Shows all available variables, which are accessible during this run of the asciidoctor
-      # grafana reporter in a asciidoctor readable form.
-      #
-      # This processor is very helpful during report template design, to find out the available
-      # variables, that can be accessed.
-      #
-      # == Used document parameters
-      # All, to be listed as the available environment.
-      class ShowEnvironmentIncludeProcessor < ::Asciidoctor::Extensions::IncludeProcessor
-        include ProcessorMixin
-
-        # :nodoc:
-        def handles?(target)
-          target.start_with? 'grafana_environment'
-        end
-
-        # :nodoc:
-        def process(doc, reader, _target, _attrs)
-          # return if @report.cancel
-          @report.next_step
-          @report.logger.debug('Processing ShowEnvironmentIncludeProcessor')
-
-          vars = ['== Accessible Variables',
-                  '|===']
-          doc.attributes.sort.each do |k, v|
-            vars << '| `+{' + k.to_s + '}+`' + ' | ' + v.to_s
-          end
-          vars << '|==='
-
-          reader.unshift_lines vars
-        end
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+
+module GrafanaReporter
+  module Asciidoctor
+    module Extensions
+      # Implements the hook
+      #   include::grafana_environment[]
+      #
+      # Shows all available variables, which are accessible during this run of the asciidoctor
+      # grafana reporter in a asciidoctor readable form.
+      #
+      # This processor is very helpful during report template design, to find out the available
+      # variables, that can be accessed.
+      #
+      # == Used document parameters
+      # All, to be listed as the available environment.
+      class ShowEnvironmentIncludeProcessor < ::Asciidoctor::Extensions::IncludeProcessor
+        include ProcessorMixin
+
+        # :nodoc:
+        def handles?(target)
+          target.start_with? 'grafana_environment'
+        end
+
+        # :nodoc:
+        def process(doc, reader, _target, _attrs)
+          # return if @report.cancel
+          @report.next_step
+          @report.logger.debug('Processing ShowEnvironmentIncludeProcessor')
+
+          vars = ['== Accessible Variables',
+                  '|===']
+          doc.attributes.sort.each do |k, v|
+            vars << "| `+{#{k}}+` | #{v}"
+          end
+          vars << '|==='
+
+          reader.unshift_lines vars
+        end
+      end
+    end
+  end
+end

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

@@ -1,202 +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')
-
-          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]. This action is always performed *before* `replace_values`and `filter_columns`.'
-          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`. This action if always performed *after* `format`and *before* `filter_columns`.'
-          param_filter_columns = '| `filter_columns="<column_name_1>,<column_name_2>,..."` | Removes specified columns from result. This action is always performed *after* `format` and `replace_values`.'
-
-          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_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}
-#{param_format}
-#{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}
-#{param_to}
-|===
-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_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}
-#{param_format}
-#{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}
-#{param_to}
-|===
-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_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_dashboard}
-#{param_filter_columns}
-#{param_format}
-#{param_from}
-#{param_instance}
-#{param_replace_values}
-#{param_to}
-|===
-
-=== `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}
-#{param_format}
-#{param_from}
-#{param_instance}
-#{param_replace_values}
-#{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_filter_columns}
-#{param_format}
-#{param_from}
-#{param_instance}
-#{param_replace_values}
-#{param_to}
-|===
-
-=== `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}
-#{param_format}
-#{param_from}
-#{param_instance}
-#{param_replace_values}
-#{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