ruby-grafana-reporter 0.2.2 → 0.4.3

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

@@ -1,70 +0,0 @@
-# frozen_string_literal: true
-
-module GrafanaReporter
-  module Asciidoctor
-    module Extensions
-      # Implements the hook
-      #   include::grafana_sql_table:<datasource_id>[<options>]
-      #
-      # Returns the results of the SQL query as a asciidoctor table.
-      #
-      # == Used document parameters
-      # +grafana_default_instance+ - name of grafana instance, 'default' if not specified
-      #
-      # +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
-      # +sql+ - sql statement (*mandatory*)
-      #
-      # +instance+ - name of grafana instance, 'default' if not specified
-      #
-      # +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 SqlTableIncludeProcessor < ::Asciidoctor::Extensions::IncludeProcessor
-        include ProcessorMixin
-
-        # :nodoc:
-        def handles?(target)
-          target.start_with? 'grafana_sql_table:'
-        end
-
-        # :nodoc:
-        def process(doc, reader, target, attrs)
-          return if @report.cancel
-
-          @report.next_step
-          instance = attrs['instance'] || doc.attr('grafana_default_instance') || 'default'
-          @report.logger.debug("Processing SqlTableIncludeProcessor (instance: #{instance},"\
-                               " datasource: #{target.split(':')[1]}, sql: #{attrs['sql']})")
-          query = SqlTableQuery.new(attrs['sql'], target.split(':')[1])
-          query.merge_hash_variables(doc.attributes, attrs)
-          @report.logger.debug("from: #{query.from}, to: #{query.to}")
-
-          begin
-            reader.unshift_lines query.execute(@report.grafana(instance))
-          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
-      end
-    end
-  end
-end

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

@@ -1,66 +0,0 @@
-# frozen_string_literal: true
-
-module GrafanaReporter
-  module Asciidoctor
-    module Extensions
-      # Implements the hook
-      #   grafana_sql_value:<datasource_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
-      #
-      # +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
-      # +sql+ - sql statement (*mandatory*)
-      #
-      # +instance+ - name of grafana instance, 'default' if not specified
-      #
-      # +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 SqlValueInlineMacro < ::Asciidoctor::Extensions::InlineMacroProcessor
-        include ProcessorMixin
-        use_dsl
-
-        named :grafana_sql_value
-
-        # @see GrafanaReporter::Asciidoctor::SqlFirstValueQuery
-        def process(parent, target, attrs)
-          return if @report.cancel
-
-          @report.next_step
-          instance = attrs['instance'] || parent.document.attr('grafana_default_instance') || 'default'
-          @report.logger.debug("Processing SqlValueInlineMacro (instance: #{instance}, datasource: #{target},"\
-                               " sql: #{attrs['sql']})")
-          query = SqlFirstValueQuery.new(attrs['sql'], target)
-          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/value_as_variable_include_processor.rb

@@ -1,86 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'processor_mixin'
-
-module GrafanaReporter
-  module Asciidoctor
-    module Extensions
-      # Implements the hook
-      #   include::grafana_value_as_variable[<options>]
-      #
-      # Returns an attribute definition in asciidoctor format. This is needed if you want to refer to values of
-      # a grafana query within a variable in asciidoctor. As this works without this function for the
-      # `IncludeProcessor`s values, it will not work for all the other processors.
-      #
-      # This method is just a proxy for all other hooks and will forward parameters accordingly.
-      #
-      # Example:
-      #
-      #   include:grafana_value_as_variable[call="grafana_sql_value:1",variable_name="my_variable",sql="SELECT 'looks good'",<any_other_option>]
-      #
-      # This will call the {SqlValueInlineMacro} with `datasource_id` set to `1` and store the result in the
-      # variable. The resulting asciidoctor variable definition will be created as:
-      #
-      #   :my_variable: looks good
-      #
-      # and can be refered to in your document easily as
-      #
-      #   {my_variable}
-      #
-      # == Supported options
-      # +call+ - regular call to the reporter hook (*mandatory*)
-      #
-      # +variable_name+ - name of the variable, to which the result shall be assigned (*mandatory*)
-     class ValueAsVariableIncludeProcessor < ::Asciidoctor::Extensions::IncludeProcessor
-        include ProcessorMixin
-
-        # :nodoc:
-        def handles?(target)
-          target.start_with? 'grafana_value_as_variable'
-        end
-
-        # :nodoc:
-        def process(doc, reader, target, attrs)
-          return if @report.cancel
-
-          # do NOT increase step, as this is done by sub processor
-          # @report.next_step
-
-          call_attr = attrs.delete('call')
-          call, target = call_attr.split(':') if call_attr
-          attribute = attrs.delete('variable_name')
-          @report.logger.debug("Processing ValueAsVariableIncludeProcessor (call: #{call}, target: #{target},"\
-                               " variable_name: #{attribute}, attrs: #{attrs})")
-          if !call || !attribute
-            @report.logger.error("Missing mandatory attribute 'call' or 'variable_name'.")
-            return reader
-          end
-
-          # TODO: remove dirty hack to allow the document as parameter for other processors
-          def doc.document
-            self
-          end
-
-          # TODO: properly show error messages also in document
-          ext = doc.extensions.find_inline_macro_extension(call) if doc.extensions.inline_macros?
-          if !ext
-            @report.logger.error("Could not find inline macro extension for '#{call}'.")
-          else
-            @report.logger.debug('ValueAsVariableIncludeProcessor: Calling sub-method.')
-            item = ext.process_method.call(doc, target, attrs)
-            if !item.text.to_s.empty?
-              result = ":#{attribute}: #{item.text}"
-              @report.logger.debug("ValueAsVariableIncludeProcessor: Adding '#{result}' to document.")
-              reader.unshift_line(result)
-            else
-              @report.logger.debug("ValueAsVariableIncludeProcessor: Not adding variable '#{attribute}',"\
-                                   ' as query result was empty.')
-            end
-          end
-
-          reader
-        end
-      end
-    end
-  end
-end

data/lib/grafana_reporter/asciidoctor/help.rb

@@ -1,435 +0,0 @@
-# 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