ruby-grafana-reporter 0.4.1 → 0.4.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +336 -185
  3. data/lib/VERSION.rb +2 -2
  4. data/lib/grafana/abstract_datasource.rb +30 -17
  5. data/lib/grafana/errors.rb +4 -4
  6. data/lib/grafana/grafana.rb +2 -0
  7. data/lib/grafana/grafana_property_datasource.rb +12 -0
  8. data/lib/grafana/graphite_datasource.rb +27 -5
  9. data/lib/grafana/influxdb_datasource.rb +156 -0
  10. data/lib/grafana/panel.rb +1 -1
  11. data/lib/grafana/prometheus_datasource.rb +37 -6
  12. data/lib/grafana/sql_datasource.rb +10 -11
  13. data/lib/grafana/variable.rb +29 -22
  14. data/lib/grafana_reporter/abstract_query.rb +150 -31
  15. data/lib/grafana_reporter/abstract_report.rb +37 -5
  16. data/lib/grafana_reporter/abstract_table_format_strategy.rb +34 -0
  17. data/lib/grafana_reporter/alerts_table_query.rb +5 -6
  18. data/lib/grafana_reporter/annotations_table_query.rb +5 -6
  19. data/lib/grafana_reporter/application/application.rb +7 -2
  20. data/lib/grafana_reporter/application/webservice.rb +35 -30
  21. data/lib/grafana_reporter/asciidoctor/adoc_plain_table_format_strategy.rb +25 -0
  22. data/lib/grafana_reporter/asciidoctor/alerts_table_include_processor.rb +7 -5
  23. data/lib/grafana_reporter/asciidoctor/annotations_table_include_processor.rb +7 -5
  24. data/lib/grafana_reporter/asciidoctor/help.rb +458 -0
  25. data/lib/grafana_reporter/asciidoctor/panel_image_block_macro.rb +5 -4
  26. data/lib/grafana_reporter/asciidoctor/panel_image_inline_macro.rb +5 -4
  27. data/lib/grafana_reporter/asciidoctor/panel_property_inline_macro.rb +5 -4
  28. data/lib/grafana_reporter/asciidoctor/panel_query_table_include_processor.rb +6 -6
  29. data/lib/grafana_reporter/asciidoctor/panel_query_value_inline_macro.rb +4 -4
  30. data/lib/grafana_reporter/asciidoctor/processor_mixin.rb +21 -35
  31. data/lib/grafana_reporter/asciidoctor/report.rb +16 -26
  32. data/lib/grafana_reporter/asciidoctor/show_help_include_processor.rb +1 -1
  33. data/lib/grafana_reporter/asciidoctor/sql_table_include_processor.rb +6 -4
  34. data/lib/grafana_reporter/asciidoctor/sql_value_inline_macro.rb +5 -3
  35. data/lib/grafana_reporter/console_configuration_wizard.rb +2 -2
  36. data/lib/grafana_reporter/csv_table_format_strategy.rb +23 -0
  37. data/lib/grafana_reporter/demo_report_wizard.rb +5 -2
  38. data/lib/grafana_reporter/erb/demo_report_builder.rb +46 -0
  39. data/lib/grafana_reporter/erb/report.rb +14 -21
  40. data/lib/grafana_reporter/erb/report_jail.rb +21 -0
  41. data/lib/grafana_reporter/errors.rb +19 -3
  42. data/lib/grafana_reporter/panel_image_query.rb +2 -5
  43. data/lib/grafana_reporter/query_value_query.rb +1 -19
  44. data/lib/grafana_reporter/report_webhook.rb +12 -8
  45. data/lib/ruby_grafana_reporter.rb +10 -11
  46. metadata +9 -3
  47. data/lib/grafana_reporter/help.rb +0 -443
@@ -0,0 +1,21 @@
1
+ # frozen_string_literal: true
2
+
3
+ module GrafanaReporter
4
+ module ERB
5
+ # An instance of this class is used as binding for the ERB execution, i.e.
6
+ # this class contains everything known within the ERB template
7
+ class ReportJail
8
+ attr_reader :report, :attributes
9
+
10
+ def initialize(report, attributes)
11
+ @report = report
12
+ @attributes = attributes
13
+ end
14
+
15
+ # @return binding to this object
16
+ def bind
17
+ binding
18
+ end
19
+ end
20
+ end
21
+ end
@@ -10,9 +10,25 @@ module GrafanaReporter
10
10
 
11
11
  # Raised if a datasource shall be queried, which is not (yet) supported by the reporter
12
12
  class DatasourceNotSupportedError < GrafanaReporterError
13
- def initialize(ds, query)
14
- super("The datasource '#{ds.name}' is of type '#{ds.type}' which is currently not supported for "\
15
- "the query type '#{query}'.")
13
+ def initialize(datasource, query)
14
+ super("The datasource '#{datasource.name}' is of type '#{datasource.type}' which is currently "\
15
+ "not supported for the query type '#{query}'.")
16
+ end
17
+ end
18
+
19
+ # Raised if some unhandled exception is raised during a datasource request execution.
20
+ class DatasourceRequestInternalError < GrafanaReporterError
21
+ def initialize(datasource, message)
22
+ super("The datasource request to '#{datasource.name}' (#{datasource.class}) failed with "\
23
+ "an internal error: #{message}")
24
+ end
25
+ end
26
+
27
+ # Raised if the return value of a datasource request does not match the expected return hash.
28
+ class DatasourceRequestInvalidReturnValueError < GrafanaReporterError
29
+ def initialize(datasource, message)
30
+ super("The datasource request to '#{datasource.name}' (#{datasource.class})"\
31
+ "returned an invalid value: '#{message}'")
16
32
  end
17
33
  end
18
34
 
@@ -5,10 +5,7 @@ module GrafanaReporter
5
5
  class PanelImageQuery < AbstractQuery
6
6
  # Sets the proper render variables.
7
7
  def pre_process
8
- @from = translate_date(@from, @variables['grafana_report_timestamp'], false, @variables['from_timezone'] ||
9
- @variables['grafana_default_from_timezone'])
10
- @to = translate_date(@to, @variables['grafana_report_timestamp'], true, @variables['to_timezone'] ||
11
- @variables['grafana_default_to_timezone'])
8
+ # TODO: properly show error, if a (maybe a repeated template) panel can not be rendered
12
9
  # TODO: ensure that in case of timezones are specified, that they are also forwarded to the image renderer
13
10
  # rename "render-" variables
14
11
  @variables = @variables.each_with_object({}) { |(k, v), h| h[k.gsub(/^render-/, '')] = v }
@@ -18,7 +15,7 @@ module GrafanaReporter
18
15
  # Returns the body of the http query, which contains the raw image.
19
16
  def post_process
20
17
  @result = @result[:content].first
21
- raise ImageCouldNotBeRenderedError, @panel if @result.include?('<html')
18
+ raise ::Grafana::ImageCouldNotBeRenderedError, @panel if @result.include?('<html')
22
19
  end
23
20
 
24
21
  # @see AbstractQuery#raw_query
@@ -3,15 +3,10 @@
3
3
  module GrafanaReporter
4
4
  # This class provides a general query implementation for any kind of single value and table queries.
5
5
  class QueryValueQuery < AbstractQuery
6
- # Translates the from and to times.
7
6
  # @see Grafana::AbstractQuery#pre_process
8
7
  def pre_process
9
8
  @datasource = @panel.datasource if @panel
10
9
 
11
- @from = translate_date(@from, @variables['grafana_report_timestamp'], false, @variables['from_timezone'] ||
12
- @variables['grafana_default_from_timezone'])
13
- @to = translate_date(@to, @variables['grafana_report_timestamp'], true, @variables['to_timezone'] ||
14
- @variables['grafana_default_to_timezone'])
15
10
  @variables['result_type'] ||= Variable.new('')
16
11
  end
17
12
 
@@ -25,7 +20,7 @@ module GrafanaReporter
25
20
 
26
21
  case @variables['result_type'].raw_value
27
22
  when /(?:panel_table|sql_table)/
28
- result_to_table
23
+ @result = format_table_output(@result, row_divider: @variables['row_divider'], column_divider: @variables['column_divider'], table_formatter: @variables['table_formatter'], include_headline: @variables['include_headline'])
29
24
 
30
25
  when /(?:panel_value|sql_value)/
31
26
  tmp = @result[:content] || []
@@ -56,19 +51,6 @@ module GrafanaReporter
56
51
 
57
52
  private
58
53
 
59
- def result_to_table
60
- row_div = '| '
61
- row_div = @variables['row_divider'].raw_value if @variables['row_divider'].is_a?(Grafana::Variable)
62
- col_div = ' | '
63
- col_div = @variables['column_divider'].raw_value if @variables['column_divider'].is_a?(Grafana::Variable)
64
-
65
- @result = @result[:content].map do |row|
66
- row_div + row.map do |item|
67
- col_div == ' | ' ? item.to_s.gsub('|', '\\|') : item.to_s
68
- end.join(col_div)
69
- end
70
- end
71
-
72
54
  def modify_results
73
55
  @result = format_columns(@result, @variables['format'])
74
56
  @result = replace_values(@result, @variables.select { |k, _v| k =~ /^replace_values_\d+/ })
@@ -12,14 +12,18 @@ module GrafanaReporter
12
12
  # Implements the call of the configured webhook.
13
13
  # Provides the following report information in JSON format:
14
14
  #
15
- # +object_id+ - id of the current report
16
- # +path+ - file path to the report
17
- # +status+ - report status as string, e.g. +cancelled+, +finished+ or +in progress+
18
- # +execution_time+ - execution time of the report
19
- # +template+ - name of the used template
20
- # +start_time+ - time when the report creation started
21
- # +end_time+ - time when the report creation ended
22
- # +event+ - event, which has happened
15
+ # :object_id - id of the current report
16
+ # :path - file path to the report
17
+ # :status - report status as string, e.g. `cancelled`, `finished` or `in progress`
18
+ # :execution_time - execution time in seconds of the report
19
+ # :template - name of the used template
20
+ # :start_time - time when the report creation started
21
+ # :end_time - time when the report creation ended
22
+ # :event - event, which has happened, e.g. `on-before-create`
23
+ #
24
+ # Please note that this callback is a non-blocking event, i.e. the report
25
+ # generation is proceeding, no matter if the callback is successfull and
26
+ # no matter how long the execution of the callback does take.
23
27
  def callback(event, report)
24
28
  # build report information as JSON
25
29
  data = { object_id: report.object_id, path: report.path, status: report.status,
@@ -18,17 +18,16 @@ require 'asciidoctor-pdf'
18
18
  require 'zip'
19
19
  require_relative 'VERSION'
20
20
 
21
- # TODO: show error in document, if grafana could not be accessed
22
- # TODO: show backtrace in extension error rescues
23
- # TODO: improve ERB calls
24
- # TODO: add test case for proper image generation
25
- # TODO: allow to choose report-class during execution, not mandatory by config file
26
- # TODO: add docu for ERB reports
27
- # TODO: add docu for custom plugins
28
- # TODO: add docu for webhook
29
-
30
- # TODO: enable as asciidoctor extension
31
- # TODO: build ADOC template as a result with resolved grafana content for further editing
21
+ # TODO: add test to see if datasource default formats are applied
22
+ # TODO: add test for render-height and render-width, as they are not forwarded
23
+ # TODO: show convert-backend, template language and all variables in webservice overview
24
+ # TODO: add automated test against grafana playground before building a new release
25
+ # TODO: allow registration of files to be defined in config file
26
+ # TODO: PRIO: check in cloud - variables fetched from queries are replaced with SQL query instead of the resolved values, which can lead to issues, e.g. when using that in a function as SUBSTRING
27
+ # TODO: PRIO: allow multiple report classes in configuration file including possibility to decide for the individual class for each rendering call
28
+ # TODO: add configuration example to README
29
+ # TODO: find a way, how to automatically update test grafana responses with _real_ grafana responses
30
+ # TODO: append necessary variables on demo report creation for plain SQL queries, as they are lacking the grafana reference
32
31
 
33
32
  folders = [
34
33
  %w[grafana],
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: ruby-grafana-reporter
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.4.1
4
+ version: 0.4.5
5
5
  platform: ruby
6
6
  authors:
7
7
  - Christian Kohlmeyer
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2021-05-17 00:00:00.000000000 Z
11
+ date: 2021-08-26 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: asciidoctor
@@ -121,6 +121,7 @@ files:
121
121
  - "./lib/grafana/grafana_property_datasource.rb"
122
122
  - "./lib/grafana/graphite_datasource.rb"
123
123
  - "./lib/grafana/image_rendering_datasource.rb"
124
+ - "./lib/grafana/influxdb_datasource.rb"
124
125
  - "./lib/grafana/panel.rb"
125
126
  - "./lib/grafana/prometheus_datasource.rb"
126
127
  - "./lib/grafana/sql_datasource.rb"
@@ -129,13 +130,16 @@ files:
129
130
  - "./lib/grafana/webrequest.rb"
130
131
  - "./lib/grafana_reporter/abstract_query.rb"
131
132
  - "./lib/grafana_reporter/abstract_report.rb"
133
+ - "./lib/grafana_reporter/abstract_table_format_strategy.rb"
132
134
  - "./lib/grafana_reporter/alerts_table_query.rb"
133
135
  - "./lib/grafana_reporter/annotations_table_query.rb"
134
136
  - "./lib/grafana_reporter/application/application.rb"
135
137
  - "./lib/grafana_reporter/application/errors.rb"
136
138
  - "./lib/grafana_reporter/application/webservice.rb"
139
+ - "./lib/grafana_reporter/asciidoctor/adoc_plain_table_format_strategy.rb"
137
140
  - "./lib/grafana_reporter/asciidoctor/alerts_table_include_processor.rb"
138
141
  - "./lib/grafana_reporter/asciidoctor/annotations_table_include_processor.rb"
142
+ - "./lib/grafana_reporter/asciidoctor/help.rb"
139
143
  - "./lib/grafana_reporter/asciidoctor/panel_image_block_macro.rb"
140
144
  - "./lib/grafana_reporter/asciidoctor/panel_image_inline_macro.rb"
141
145
  - "./lib/grafana_reporter/asciidoctor/panel_property_inline_macro.rb"
@@ -150,10 +154,12 @@ files:
150
154
  - "./lib/grafana_reporter/asciidoctor/value_as_variable_include_processor.rb"
151
155
  - "./lib/grafana_reporter/configuration.rb"
152
156
  - "./lib/grafana_reporter/console_configuration_wizard.rb"
157
+ - "./lib/grafana_reporter/csv_table_format_strategy.rb"
153
158
  - "./lib/grafana_reporter/demo_report_wizard.rb"
159
+ - "./lib/grafana_reporter/erb/demo_report_builder.rb"
154
160
  - "./lib/grafana_reporter/erb/report.rb"
161
+ - "./lib/grafana_reporter/erb/report_jail.rb"
155
162
  - "./lib/grafana_reporter/errors.rb"
156
- - "./lib/grafana_reporter/help.rb"
157
163
  - "./lib/grafana_reporter/logger/two_way_delegate_logger.rb"
158
164
  - "./lib/grafana_reporter/panel_image_query.rb"
159
165
  - "./lib/grafana_reporter/panel_property_query.rb"
@@ -1,443 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- require 'yaml'
4
-
5
- module GrafanaReporter
6
- # This class generates the functional help documentation for the reporter.
7
- # It can create the documentation for github markdown, as well as in asciidoctor.
8
- class Help
9
- # @param headline_level [Integer] top level of headline
10
- # @return [String] asciidoctor compatible documentation
11
- def asciidoctor(headline_level = 2)
12
- help_text(asciidoctor_options.merge(level: headline_level))
13
- end
14
-
15
- # @param headline_level [Integer] top level of headline
16
- # @return [String] github markdown compatible documentation
17
- def github(headline_level = 2)
18
- "#{toc}\n\n#{help_text(github_options.merge(level: headline_level))}"
19
- end
20
-
21
- private
22
-
23
- def github_options
24
- { headline_separator: '#', code_begin: '`', code_end: '`', table_begin: "\n", head_postfix_col: '| -- ' }
25
- end
26
-
27
- def asciidoctor_options
28
- { headline_separator: '=', code_begin: '`+', code_end: '+`', table_begin: "\n[%autowidth.stretch, "\
29
- "options=\"header\"]\n|===\n", table_end: "\n|===" }
30
- end
31
-
32
- def help_text(opts)
33
- %(#{opts[:headline_separator] * opts[:level]} Global options
34
- #{global_options_as_text(opts.merge(level: opts[:level] + 1))}
35
- #{opts[:headline_separator] * opts[:level]} Functions
36
- #{functions_as_text(opts.merge(level: opts[:level] + 1))})
37
- end
38
-
39
- def toc
40
- result = []
41
-
42
- result << 'Table of contents'
43
- result << '* [Global options](#global-options)'
44
- prepared_help[:global_options].sort.map do |k, _v|
45
- result << " * [#{k}](##{k.downcase})"
46
- end
47
-
48
- result << '* [Functions](#functions)'
49
- prepared_help[:functions].sort.map do |k, _v|
50
- result << " * [#{k}](##{k.downcase})"
51
- end
52
-
53
- result.join("\n")
54
- end
55
-
56
- def global_options_as_text(opts = {})
57
- opts = { level: 3 }.merge(opts)
58
- result = []
59
-
60
- prepared_help[:global_options].sort.map do |k, v|
61
- result << %(
62
- #{opts[:headline_separator] * opts[:level]} #{opts[:code_begin]}#{k}#{opts[:code_end]}
63
- Usage: #{opts[:code_begin]}#{v['call']}#{opts[:code_end]}
64
-
65
- #{v['description']}
66
- )
67
- end
68
-
69
- result.join
70
- end
71
-
72
- def functions_as_text(opts = {})
73
- opts = { level: 3, headline_separator: '=' }.merge(opts)
74
- result = []
75
-
76
- prepared_help[:functions].sort.map do |k, v|
77
- result << %(
78
- #{opts[:headline_separator] * opts[:level]} #{opts[:code_begin]}#{k}#{opts[:code_end]}
79
- Usage: #{opts[:code_begin]}#{v[:call]}#{opts[:code_end]}
80
-
81
- #{v[:description]}#{"\n\nSee also: #{v[:see]}" if v[:see]}#{unless v[:options].empty?
82
- %(
83
- #{opts[:table_begin]}| Option | Description#{"\n#{opts[:head_postfix_col] * 2}" if opts[:head_postfix_col]}
84
- #{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]})
85
- end}
86
- )
87
- end
88
-
89
- result.join
90
- end
91
-
92
- def prepared_help
93
- yaml = YAML.safe_load(raw_help_yaml)
94
-
95
- result = {}
96
- result[:functions] = {}
97
- result[:global_options] = yaml['global_options']
98
-
99
- functions = result[:functions]
100
- std_opts = yaml['standard_options']
101
- yaml.reject { |k, _v| k =~ /.*_options$/ }.each_key do |key|
102
- functions[key] = {}
103
- res_item = functions[key]
104
- res_item[:options] = {}
105
-
106
- item = yaml[key]
107
- res_item[:call] = item['call']
108
- res_item[:description] = item['description']
109
- res_item[:see] = item['see']
110
-
111
- opts = ((item['options'] ? item['options'].keys : [])
112
- (item['standard_options'] ? item['standard_options'].keys : [])).sort
113
- opts.each do |opt_key|
114
- res_item[:options][opt_key] = {}
115
-
116
- if item['standard_options'].key?(opt_key)
117
- res_item[:options][opt_key][:call] = std_opts[opt_key]['call']
118
- res_item[:options][opt_key][:description] = "#{std_opts[opt_key]['description']} "\
119
- "#{item['standard_options'][opt_key]}".chop
120
- res_item[:options][opt_key][:see] = std_opts[opt_key]['see'] if std_opts[opt_key]['see']
121
- else
122
- res_item[:options][opt_key][:call] = item['options'][opt_key]['call']
123
- res_item[:options][opt_key][:description] = item['options'][opt_key]['description']
124
- res_item[:options][opt_key][:see] = item['options'][opt_key]['see'] if item['options'][opt_key]['see']
125
- end
126
- end
127
- end
128
-
129
- result
130
- end
131
-
132
- # TODO: use same wording/grouping as in README file
133
- def raw_help_yaml
134
- <<~YAML_HELP
135
- global_options:
136
- grafana_default_instance:
137
- call: ":grafana_default_instance: <instance_name>"
138
- description: >-
139
- Specifies which grafana instance shall be used. If not set, the grafana instance names `default`
140
- will be used.
141
-
142
- grafana_default_dashboard:
143
- call: ":grafana_default_dashboard: <dashboard_uid>"
144
- description: >-
145
- Specifies to which dashboard the queries shall be targeted by default.
146
-
147
- grafana_default_from_timezone:
148
- call: ":grafana_default_from_timezone: <timezone>"
149
- description: Specifies which timezone shall be used for the `from` time, e.g. `CET` or `CEST`.
150
-
151
- grafana_default_to_timezone:
152
- call: ":grafana_default_to_timezone: <timezone>"
153
- description: Specifies which timezone shall be used for the `to` time, e.g. `CET` or `CEST`.
154
-
155
- from:
156
- call: ":from: <from_timestamp>"
157
- description: >-
158
- Overrides the time setting from grafana. It may contain dates as `now-1M/M`, which will be translated
159
- properly to timestamps relative to the called time.
160
-
161
- to:
162
- call: ":to: <to_timestamp>"
163
- description: >-
164
- Overrides the time setting from grafana. It may contain dates as `now-1M/M`, which will be translated
165
- properly to timestamps relative to the called time.
166
-
167
- standard_options:
168
- instance:
169
- call: instance="<instance_name>"
170
- description: >-
171
- can be used to override global grafana instance, set in the report with `grafana_default_instance`.
172
- If nothing is set, the configured grafana instance with name `default` will be used.
173
-
174
- dashboard:
175
- call: dashboard="<dashboard_uid>"
176
- description: >-
177
- Specifies the dashboard to be used. If `grafana_default_dashboard` is specified in the report template,
178
- this value can be overridden with this option.
179
-
180
- from:
181
- call: from="<timestamp>"
182
- description: can be used to override default `from` time
183
-
184
- from_timezone:
185
- call: from_timezone="<timezone>"
186
- description: can be used to override system timezone for `from` time and will also override `grafana_default_from_timezone` option
187
-
188
- to_timezone:
189
- call: to_timezone="<timezone>"
190
- description: can be used to override system timezone for `to` time and will also override `grafana_default_to_timezone` option
191
-
192
- to:
193
- call: to="<timestamp>"
194
- description: can be used to override default `to` time
195
-
196
- format:
197
- call: format="<format_col1>,<format_col2>,..."
198
- description: >-
199
- Specify format in which the results shall be returned, e.g. `%.2f` for only two digit decimals of a
200
- float. Several columns are separated by `,`. Execution is applied in the following order `format`,
201
- `replace_values`, `filter_columns`, `transpose`.
202
- see: 'https://ruby-doc.org/core-2.4.0/Kernel.html#method-i-sprintf'
203
-
204
- replace_values:
205
- call: replace_values="<replace_1>:<with_1>,<replace_2>:<with_2>,..."
206
- description: >-
207
- Specify result values which shall be replaced, e.g. `2:OK` will replace query values `2` with value `OK`.
208
- Replacing several values is possible by separating by `,`. Matches with regular expressions are also
209
- supported, but must be full matches, i.e. have to start with `^` and end with `$`, e.g. `^[012]$:OK`.
210
- Number replacements can also be performed, e.g. `<8.2` or `<>3`. Execution is applied in the following order `format`,
211
- `replace_values`, `filter_columns`, `transpose`.
212
- see: https://ruby-doc.org/core-2.7.1/Regexp.html#class-Regexp-label-Character+Classes
213
-
214
- filter_columns:
215
- call: filter_columns="<column_name_1>,<column_name_2>,..."
216
- description: >-
217
- Removes specified columns from result. Execution is applied in the following order `format`, `replace_values`,
218
- `filter_columns`, `transpose`.
219
-
220
- transpose:
221
- call: transpose="true"
222
- description: >-
223
- Transposes the query result, i.e. columns become rows and rows become columnns. Execution is applied in the
224
- following order `format`, `replace_values`, `filter_columns`, `transpose`.
225
-
226
- column_divider:
227
- call: column_divider="<divider>"
228
- description: >-
229
- Replace the default column divider with another one. Defaults to ` | ` for being interpreted as a asciidoctor column.
230
-
231
- row_divider:
232
- call: row_divider="<divider>"
233
- description: >-
234
- Replace the default row divider with another one. Defaults to `| ` for being interpreted as a asciidoctor row.
235
-
236
- timeout:
237
- call: timeout="<timeout_in_seconds>"
238
- description: >-
239
- Set a timeout for the current query. If not overridden with `grafana-default-timeout` in the report template,
240
- this defaults to 60 seconds.
241
-
242
- # ----------------------------------
243
- # FUNCTION DOCUMENTATION STARTS HERE
244
- # ----------------------------------
245
-
246
- grafana_help:
247
- description: Show all available grafana calls within the asciidoctor templates, including available options.
248
- call: 'include::grafana_help[]'
249
-
250
- grafana_environment:
251
- description: Shows all available variables in the rendering context which can be used in the asciidoctor template.
252
- call: 'include::grafana_environment[]'
253
-
254
- grafana_alerts:
255
- description: >-
256
- Returns a table of active alert states including the specified columns and the connected information. Supports
257
- all query parameters from the Grafana Alerting API, such as `query`, `state`, `limit`, `folderId` and others.
258
- call: 'include::grafana_alerts[columns="<column_name_1>,<column_name_2>,...",options]'
259
- see: https://grafana.com/docs/grafana/latest/http_api/alerting/#get-alerts
260
- options:
261
- columns:
262
- description: >-
263
- Specifies columns that shall be returned. Valid columns are `id`, `dashboardId`, `dashboardUId`, `dashboardSlug`,
264
- `panelId`, `name`, `state`, `newStateDate`, `evalDate`, `evalData` and `executionError`.
265
- call: columns="<column_name_1>,<columns_name_2>,..."
266
- panel:
267
- description: >-
268
- If specified, the resulting alerts are filtered for this panel. This option will only work, if a `dashboard`
269
- or `grafana_default_dashboard` is set.
270
- call: panel="<panel_id>"
271
- standard_options:
272
- column_divider:
273
- dashboard: >-
274
- If this option, or the global option `grafana_default_dashboard` is set, the resulting alerts will be limited to
275
- this dashboard. To show all alerts in this case, specify `dashboard=""` as option.
276
- filter_columns:
277
- format:
278
- from:
279
- instance:
280
- replace_values:
281
- row_divider:
282
- timeout:
283
- to:
284
- transpose:
285
- from_timezone:
286
- to_timezone:
287
-
288
- grafana_annotations:
289
- description: >-
290
- Returns a table of all annotations, matching the specified filter criteria and the specified columns. Supports all
291
- query parameters from the Grafana Alerting API, such as `limit`, `alertId`, `panelId` and others.
292
- call: 'include::grafana_annotations[columns="<column_name_1>,<column_name_2>,...",options]'
293
- see: https://grafana.com/docs/grafana/latest/http_api/annotations/#find_annotations
294
- options:
295
- columns:
296
- description: >-
297
- Specified the columns that shall be returned. Valid columns are `id`, `alertId`, `dashboardId`, `panelId`, `userId`,
298
- `userName`, `newState`, `prevState`, `time`, `timeEnd`, `text`, `metric` and `type`.
299
- call: columns="<column_name_1>,<columns_name_2>,..."
300
- panel:
301
- description: >-
302
- If specified, the resulting alerts are filtered for this panel. This option will only work, if a `dashboard` or
303
- `grafana_default_dashboard` is set.
304
- call: panel="<panel_id>"
305
- standard_options:
306
- column_divider:
307
- dashboard: >-
308
- If this option, or the global option `grafana_default_dashboard` is set, the resulting alerts will be limited to this
309
- dashboard. To show all alerts in this case, specify `dashboard=""` as option.
310
- filter_columns:
311
- format:
312
- from:
313
- instance:
314
- replace_values:
315
- row_divider:
316
- timeout:
317
- to:
318
- transpose:
319
- from_timezone:
320
- to_timezone:
321
-
322
- grafana_panel_property:
323
- description: >-
324
- Returns a property field for the specified panel. `<type>` can either be `title` or `description`.
325
- Grafana variables will be replaced in the returned value.
326
- call: 'grafana_panel_property:<panel_id>["<type>",options]'
327
- see: https://grafana.com/docs/grafana/latest/variables/templates-and-variables/#variable-syntax
328
- standard_options:
329
- dashboard:
330
- instance:
331
-
332
- grafana_panel_image:
333
- description: Includes a panel image as an image in the document. Can be called for inline-images as well as for blocks.
334
- call: 'grafana_panel_image:<panel_id>[options] or grafana_panel_image::<panel_id>[options]'
335
- options:
336
- render-height:
337
- description: can be used to override default `height` in which the panel shall be rendered
338
- call: render-height="<height>"
339
- render-width:
340
- description: can be used to override default `width` in which the panel shall be rendered
341
- call: render-width="<width>"
342
- render-theme:
343
- description: can be used to override default `theme` in which the panel shall be rendered (light by default)
344
- call: render-theme="<theme>"
345
- render-timeout:
346
- description: can be used to override default `timeout` in which the panel shall be rendered (60 seconds by default)
347
- call: render-timeout="<timeout>"
348
- standard_options:
349
- dashboard:
350
- from:
351
- instance:
352
- timeout:
353
- to:
354
- from_timezone:
355
- to_timezone:
356
-
357
- grafana_panel_query_table:
358
- description: >-
359
- Returns the results of a query, which is configured in a grafana panel, as a table in asciidoctor.
360
- Grafana variables will be replaced in the panel's SQL statement.
361
- call: 'include::grafana_panel_query_table:<panel_id>[query="<query_letter>",options]'
362
- see: https://grafana.com/docs/grafana/latest/variables/templates-and-variables/#variable-syntax
363
- options:
364
- query:
365
- call: query="<query_letter>"
366
- description: +<query_letter>+ needs to point to the grafana query which shall be evaluated, e.g. +A+ or +B+.
367
- standard_options:
368
- column_divider:
369
- dashboard:
370
- filter_columns:
371
- format:
372
- from:
373
- instance:
374
- replace_values:
375
- row_divider:
376
- timeout:
377
- to:
378
- transpose:
379
- from_timezone:
380
- to_timezone:
381
-
382
- grafana_panel_query_value:
383
- call: 'grafana_panel_query_value:<panel_id>[query="<query_letter>",options]'
384
- description: >-
385
- Returns the value in the first column and the first row of a query, which is configured in a grafana panel.
386
- Grafana variables will be replaced in the panel's SQL statement.
387
- see: https://grafana.com/docs/grafana/latest/variables/templates-and-variables/#variable-syntax
388
- options:
389
- query:
390
- call: query="<query_letter>"
391
- description: +<query_letter>+ needs to point to the grafana query which shall be evaluated, e.g. +A+ or +B+.
392
- standard_options:
393
- dashboard:
394
- filter_columns:
395
- format:
396
- from:
397
- instance:
398
- replace_values:
399
- timeout:
400
- to:
401
- from_timezone:
402
- to_timezone:
403
-
404
- grafana_sql_table:
405
- call: 'include::grafana_sql_table:<datasource_id>[sql="<sql_query>",options]'
406
- description: >-
407
- Returns a table with all results of the given query.
408
- Grafana variables will be replaced in the SQL statement.
409
- see: https://grafana.com/docs/grafana/latest/variables/templates-and-variables/#variable-syntax
410
- standard_options:
411
- column_divider:
412
- filter_columns:
413
- format:
414
- from:
415
- instance:
416
- replace_values:
417
- row_divider:
418
- timeout:
419
- to:
420
- transpose:
421
- from_timezone:
422
- to_timezone:
423
-
424
- grafana_sql_value:
425
- call: 'grafana_sql_value:<datasource_id>[sql="<sql_query>",options]'
426
- description: >-
427
- Returns the value in the first column and the first row of the given query.
428
- Grafana variables will be replaced in the SQL statement.
429
- see: https://grafana.com/docs/grafana/latest/variables/templates-and-variables/#variable-syntax
430
- standard_options:
431
- filter_columns:
432
- format:
433
- from:
434
- instance:
435
- replace_values:
436
- timeout:
437
- to:
438
- from_timezone:
439
- to_timezone:
440
- YAML_HELP
441
- end
442
- end
443
- end