ruby-grafana-reporter 0.4.0 → 0.4.1

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 (40) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +185 -180
  3. data/lib/VERSION.rb +2 -2
  4. data/lib/grafana/abstract_datasource.rb +32 -12
  5. data/lib/grafana/errors.rb +1 -9
  6. data/lib/grafana/grafana.rb +3 -7
  7. data/lib/grafana/graphite_datasource.rb +6 -0
  8. data/lib/grafana/prometheus_datasource.rb +6 -0
  9. data/lib/grafana/sql_datasource.rb +6 -0
  10. data/lib/grafana/unsupported_datasource.rb +7 -0
  11. data/lib/grafana/webrequest.rb +1 -1
  12. data/lib/grafana_reporter/abstract_query.rb +20 -62
  13. data/lib/grafana_reporter/abstract_report.rb +66 -15
  14. data/lib/grafana_reporter/alerts_table_query.rb +5 -5
  15. data/lib/grafana_reporter/annotations_table_query.rb +4 -4
  16. data/lib/grafana_reporter/application/application.rb +10 -16
  17. data/lib/grafana_reporter/application/webservice.rb +34 -10
  18. data/lib/grafana_reporter/asciidoctor/alerts_table_include_processor.rb +5 -5
  19. data/lib/grafana_reporter/asciidoctor/annotations_table_include_processor.rb +5 -5
  20. data/lib/grafana_reporter/asciidoctor/panel_image_block_macro.rb +2 -1
  21. data/lib/grafana_reporter/asciidoctor/panel_image_inline_macro.rb +7 -5
  22. data/lib/grafana_reporter/asciidoctor/panel_property_inline_macro.rb +2 -1
  23. data/lib/grafana_reporter/asciidoctor/panel_query_table_include_processor.rb +6 -5
  24. data/lib/grafana_reporter/asciidoctor/panel_query_value_inline_macro.rb +5 -5
  25. data/lib/grafana_reporter/asciidoctor/processor_mixin.rb +43 -2
  26. data/lib/grafana_reporter/asciidoctor/report.rb +17 -41
  27. data/lib/grafana_reporter/asciidoctor/sql_table_include_processor.rb +4 -4
  28. data/lib/grafana_reporter/asciidoctor/sql_value_inline_macro.rb +4 -4
  29. data/lib/grafana_reporter/configuration.rb +14 -2
  30. data/lib/grafana_reporter/console_configuration_wizard.rb +2 -10
  31. data/lib/grafana_reporter/demo_report_wizard.rb +16 -2
  32. data/lib/grafana_reporter/erb/report.rb +43 -0
  33. data/lib/grafana_reporter/errors.rb +9 -1
  34. data/lib/grafana_reporter/help.rb +1 -5
  35. data/lib/grafana_reporter/logger/{two_way_logger.rb → two_way_delegate_logger.rb} +0 -0
  36. data/lib/grafana_reporter/panel_image_query.rb +2 -2
  37. data/lib/grafana_reporter/query_value_query.rb +4 -4
  38. data/lib/ruby_grafana_extension.rb +8 -0
  39. data/lib/ruby_grafana_reporter.rb +13 -0
  40. metadata +9 -6
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: db7e3fbf0f8c1a3d7d9ce8d3e3e215b6f6bb5ec3c170252d575e0516b3312b20
4
- data.tar.gz: b05cfa64a8d5bef650917df47ad9b84a140f302e87d2c6664c1fab3272e7212e
3
+ metadata.gz: 799071f1a4ed0795aeb9dbdc7fe175d3e023f4d0de3844f0ae57e85343ab47b4
4
+ data.tar.gz: 6524d4a07cd49c6622d69507e0ee6c3a37c18c358f8a3dc63b56848255c38e4c
5
5
  SHA512:
6
- metadata.gz: 3925cc108c3cedc51d6a37926b4ba937296cfd55137d8af40b9254bb92383cf253713321e95e6cfcfeb50de9adf7acd11777cf108227527d2c87658d74173a51
7
- data.tar.gz: 79c345933fd16d7c2acfa24715ef09119c1973c605bb5a7b2caa959fcf08ae748e087338717d6e4343281e68a9a3ed9440d5c74e57846691f7033ef2f41e4079
6
+ metadata.gz: f52466eb19bc813271c4f67818414f578750f2a7d9254244cb5213be47ffa50e8a1849788935211391b606cc944a84b9bef6b46aec583185bbe94958d2e080a5
7
+ data.tar.gz: 4eae953b1ad50b9d188d66f3f7bf0c9c6184ff3009da077f2ed07c0d082d7b3d7be75c362143033b27b8256482886e797c78ab750bdde5a85cf198ea8b4fe540
data/README.md CHANGED
@@ -1,180 +1,185 @@
1
- [![MIT License](https://img.shields.io/github/license/divinity666/ruby-grafana-reporter.svg?style=flat-square)](https://github.com/divinity666/ruby-grafana-reporter/blob/master/LICENSE)
2
- [![Build Status](https://travis-ci.org/divinity666/ruby-grafana-reporter.svg?branch=master)](https://travis-ci.org/github/divinity666/ruby-grafana-reporter?branch=master)
3
- [![Coverage Status](https://coveralls.io/repos/github/divinity666/ruby-grafana-reporter/badge.svg?branch=master)](https://coveralls.io/github/divinity666/ruby-grafana-reporter?branch=master)
4
- [![Gem Version](https://badge.fury.io/rb/ruby-grafana-reporter.svg)](https://badge.fury.io/rb/ruby-grafana-reporter)
5
-
6
- # Ruby Grafana Reporter
7
- Reporting Service for Grafana
8
-
9
- ## Table of Contents
10
-
11
- * [About the project](#about-the-project)
12
- * [Features](#features)
13
- * [Quick Start](#quick-start)
14
- * [Grafana integration](#grafana-integration)
15
- * [Webservice overview](#webservice-overview)
16
- * [Roadmap](#roadmap)
17
- * [Donations](#donations)
18
-
19
- ## About the project
20
-
21
- Did you ever want to create (professional) reports based on Grafana dashboards?
22
- I did so in order to being able to automatically get monthly reports of my
23
- home's energy usage. That's how it started.
24
-
25
- ## Features
26
-
27
- * Build PDF reports based on [grafana](https://github.com/grafana/grafana) dashboards
28
- (other formats supported)
29
- * Include dynamic content from grafana (see [function documentation](FUNCTION_CALLS.md)
30
- as a detailed reference):
31
- * panels as images
32
- * tables based on grafana panel queries or custom database queries (no images!)
33
- * single values to be integrated in text, based on grafana panel queries or custom
34
- database queries
35
- * Multi purpose use of the reporter
36
- * webservice to be called directly from grafana - it also runs without further
37
- dependencies in the standard asciidoctor docker container!
38
- * standalone command line tool, e.g. to be automated with cron or bash scrips
39
- * Comes with a complete configuration wizard, including functionality to build a
40
- demo report on top of the configured grafana host
41
- * Supports all SQL based datasources, as well as graphite and prometheus
42
- * Solid as a rock, also in case of template errors and whatever else may happen
43
- * Full [API documentation](https://rubydoc.info/gems/ruby-grafana-reporter) available
44
-
45
- ## Quick Start
46
-
47
- You don't have a grafana setup runnning already? No worries, just configure
48
- `https://play.grafana.org` in the configuration wizard and see the magic
49
- happen for that!
50
-
51
- If your grafana setup requires a login, you'll have to setup an api key for
52
- the reporter. Please follow the steps
53
- [described here](https://github.com/divinity666/ruby-grafana-reporter/issues/2#issuecomment-811836757)
54
- first.
55
-
56
- **Windows:**
57
-
58
- * [Download latest Windows executable](https://github.com/divinity666/ruby-grafana-reporter/releases/latest)
59
- * `ruby-grafana-reporter -w`
60
-
61
- Known issues:
62
- * images are currently not included in PDF conversions due to missing support in Prawn gem for windows;
63
- other target formats do work properly with images
64
-
65
- **Raspberry Pi:**
66
-
67
- * `sudo apt-get install ruby`
68
- * `gem install ruby-grafana-reporter`
69
- * `ruby-grafana-reporter -w`
70
-
71
- **Ruby environment:**
72
-
73
- * `gem install ruby-grafana-reporter`
74
- * `ruby-grafana-reporter -w`
75
-
76
- **Docker environment** (advanced users):
77
-
78
- * [Download latest single-rb file](https://github.com/divinity666/ruby-grafana-reporter/releases/latest)
79
- to an empty folder
80
- * create a configuration file by calling `ruby ruby-grafana-reporter -w` (if in doubt,
81
- run the command within your docker container)
82
- * create file `/<<path-to-single-rb-file-folder>>/startup.sh` with the following
83
- content:
84
-
85
- ```
86
- cd /documents
87
- ruby bin/ruby-grafana-reporter
88
- ```
89
- * add asciidoctor your compose yaml:
90
-
91
- ```
92
- asciidoctor:
93
- image: asciidoctor/docker-asciidoctor
94
- container_name: asciidoctor
95
- hostname: asciidoctor
96
- volumes:
97
- - /<<path-to-single-rb-file-folder>>:/documents
98
- command:
99
- sh /documents/startup.sh
100
- restart: unless-stopped
101
- ```
102
- * start/restart the asciidoctor docker container
103
-
104
- ## Grafana integration
105
-
106
- The key feature of the report is, that it can easily be integrated with grafana.
107
-
108
- For accessing the reporter from grafana, you need to simply add a link to your
109
- grafana dashboard:
110
-
111
- * Open the dashboard configuration
112
- * Select `Links`
113
- * Select `Add`
114
- * Fill out as following:
115
- * Type: `link`
116
- * Url: `http://<<your-server-url>>:<<your-webservice-port>>/render?var-template=demo_report`
117
- * Title: `Demo Report`
118
- * Select `Time range`
119
- * Select `Variable values`
120
- * Select `Add`
121
-
122
- Now go back to your dashboard and click the newly generated `Demo Report`
123
- link on it. Now the renderer should start it's task and show you the expected
124
- results.
125
-
126
- Please note, that the reporter won't automatically refresh your screen to update
127
- the progress. Simply hit `F5` to refresh your browser. After the report has been
128
- successfully built, it will show the PDF after the next refresh automatically.
129
-
130
- You want to select a template in grafana, which shall then be rendered?
131
- Piece of cake: Just add a dashboard variable to your grafana dashboard named
132
- `template` and let the user select or enter a template name. To make use of it,
133
- you should change the link of the `Demo Report` link to
134
- `http://<<your-server-url>>:<<your-webservice-port>>/render?`. On
135
- hitting the new link in the dashboard, grafana will add the selected template as
136
- a variable and forward it to the reporter.
137
-
138
- ## Webservice overview
139
-
140
- Running the reporter as a webservice provides the following URLs
141
-
142
- /overview - for all running or retained renderings
143
- /render - for rendering a template, 'var-template' is the only mandatory GET parameter
144
- /view_report - for viewing the status or receving the result of a specific rendering, is automatically called after a successfull /render call
145
- /cancel_report - for cancelling the rendering of a specific report, normally not called manually, but on user interaction in the /view_report or /overview URL
146
-
147
- The main endpoint to call for report generation is configured in the previous chapter [Grafana integration](#grafana-integration).
148
-
149
- However, if you would like to see, currently running report generations and previously generated reports, you may want to call the endpoint `/overview`.
150
-
151
- ## Roadmap
152
-
153
- This is just a collection of things, I am heading for in future, without a schedule.
154
-
155
- * Support all grafana datasources
156
- * Solve code TODOs
157
- * Become [rubocop](https://rubocop.org/) ready
158
-
159
- ## Contributing
160
-
161
- If you'd like to contribute, please fork the repository and use a feature
162
- branch. Pull requests are warmly welcome.
163
-
164
- ## Licensing
165
-
166
- The code in this project is licensed under MIT license.
167
-
168
- ## Acknowledgements
169
- * [asciidoctor](https://github.com/asciidoctor/asciidoctor)
170
- * [asciidoctor-pdf](https://github.com/asciidoctor/asciidoctor-pdf)
171
- * [grafana](https://github.com/grafana/grafana)
172
-
173
- Inspired by [Izak Marai's grafana reporter](https://github.com/IzakMarais/reporter)
174
-
175
- ## Donations
176
-
177
- If this project saves you as much time as I hope it does, and if you'd like to
178
- support my work, feel free donate, even a cup of coffee is appreciated :)
179
-
180
- [![paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif)](https://www.paypal.com/donate?hosted_button_id=35LH6JNLPHPHQ)
1
+ [![MIT License](https://img.shields.io/github/license/divinity666/ruby-grafana-reporter.svg?style=flat-square)](https://github.com/divinity666/ruby-grafana-reporter/blob/master/LICENSE)
2
+ [![Build Status](https://travis-ci.org/divinity666/ruby-grafana-reporter.svg?branch=master)](https://travis-ci.org/github/divinity666/ruby-grafana-reporter?branch=master)
3
+ [![Coverage Status](https://coveralls.io/repos/github/divinity666/ruby-grafana-reporter/badge.svg?branch=master)](https://coveralls.io/github/divinity666/ruby-grafana-reporter?branch=master)
4
+ [![Gem Version](https://badge.fury.io/rb/ruby-grafana-reporter.svg)](https://badge.fury.io/rb/ruby-grafana-reporter)
5
+
6
+ # Ruby Grafana Reporter
7
+ Reporting Service for Grafana
8
+
9
+ ## Table of Contents
10
+
11
+ * [About the project](#about-the-project)
12
+ * [Features](#features)
13
+ * [Quick Start](#quick-start)
14
+ * [Grafana integration](#grafana-integration)
15
+ * [Webservice overview](#webservice-overview)
16
+ * [Roadmap](#roadmap)
17
+ * [Donations](#donations)
18
+
19
+ ## About the project
20
+
21
+ Did you ever want to create (professional) reports based on Grafana dashboards?
22
+ I did so in order to being able to automatically get monthly reports of my
23
+ home's energy usage. That's how it started.
24
+
25
+ ## Features
26
+
27
+ * Build reports based on [grafana](https://github.com/grafana/grafana) dashboards, PDF
28
+ (default) and many other formats supported
29
+ * Easy-to-use configuration wizard, including fully automated functionality to create a
30
+ demo report
31
+ * Include dynamic content from grafana (find here a reference for all
32
+ [asciidcotor reporter calls](FUNCTION_CALLS.md)):
33
+ * panels as images
34
+ * tables based on grafana panel queries or custom database queries (no images!)
35
+ * single values to be integrated in text, based on grafana panel queries or custom
36
+ database queries
37
+ * Multi purpose use of the reporter
38
+ * webservice to be called directly from grafana
39
+ * standalone command line tool, e.g. to be automated with `cron` or `bash` scrips
40
+ * seemlessly runs from asciidocotor docker container without further dependencies
41
+ * Webhook callbacks before, on cancel and on finishing callbacks (see configuration file)
42
+ * Solid as a rock, also in case of template errors and whatever else may happen
43
+ * Full [API documentation](https://rubydoc.info/gems/ruby-grafana-reporter) available
44
+
45
+ Functionalities are provided as shown here:
46
+
47
+ Database | Image rendering | Panel-based rendering | Query-based rendering
48
+ ------------------------- | :-------: | :-----------: | :------------:
49
+ all SQL based datasources | supported | supported | supported
50
+ Graphite | supported | supported | supported
51
+ Prometheus | supported | supported | supported
52
+ other datasources | supported | not-supported | not-supported
53
+
54
+ ## Quick Start
55
+
56
+ You don't have a grafana setup runnning already? No worries, just configure
57
+ `https://play.grafana.org` in the configuration wizard and see the magic
58
+ happen!
59
+
60
+ If your grafana setup requires a login, you'll have to setup an api key for
61
+ the reporter. Please follow the steps
62
+ [described here](https://github.com/divinity666/ruby-grafana-reporter/issues/2#issuecomment-811836757)
63
+ first.
64
+
65
+ **Windows:**
66
+
67
+ * [Download latest Windows executable](https://github.com/divinity666/ruby-grafana-reporter/releases/latest)
68
+ * `ruby-grafana-reporter -w`
69
+
70
+ **Raspberry Pi:**
71
+
72
+ * `sudo apt-get install ruby`
73
+ * `gem install ruby-grafana-reporter`
74
+ * `ruby-grafana-reporter -w`
75
+
76
+ **Ruby environment:**
77
+
78
+ * `gem install ruby-grafana-reporter`
79
+ * `ruby-grafana-reporter -w`
80
+
81
+ **Docker environment** (advanced users):
82
+
83
+ * [Download latest single-rb file](https://github.com/divinity666/ruby-grafana-reporter/releases/latest)
84
+ to an empty folder
85
+ * create a configuration file by calling `ruby ruby-grafana-reporter -w` (if in doubt,
86
+ run the command within your docker container)
87
+ * create file `/<<path-to-single-rb-file-folder>>/startup.sh` with the following
88
+ content:
89
+
90
+ ```
91
+ cd /documents
92
+ ruby bin/ruby-grafana-reporter
93
+ ```
94
+ * add asciidoctor your compose yaml:
95
+
96
+ ```
97
+ asciidoctor:
98
+ image: asciidoctor/docker-asciidoctor
99
+ container_name: asciidoctor
100
+ hostname: asciidoctor
101
+ volumes:
102
+ - /<<path-to-single-rb-file-folder>>:/documents
103
+ command:
104
+ sh /documents/startup.sh
105
+ restart: unless-stopped
106
+ ```
107
+ * start/restart the asciidoctor docker container
108
+
109
+ ## Grafana integration
110
+
111
+ The key feature of the report is, that it can easily be integrated with grafana.
112
+
113
+ For accessing the reporter from grafana, you need to simply add a link to your
114
+ grafana dashboard:
115
+
116
+ * Open the dashboard configuration
117
+ * Select `Links`
118
+ * Select `Add`
119
+ * Fill out as following:
120
+ * Type: `link`
121
+ * Url: `http://<<your-server-url>>:<<your-webservice-port>>/render?var-template=demo_report`
122
+ * Title: `Demo Report`
123
+ * Select `Time range`
124
+ * Select `Variable values`
125
+ * Select `Add`
126
+
127
+ Now go back to your dashboard and click the newly generated `Demo Report`
128
+ link on it. Now the renderer should start it's task and show you the expected
129
+ results.
130
+
131
+ Please note, that the reporter won't automatically refresh your screen to update
132
+ the progress. Simply hit `F5` to refresh your browser. After the report has been
133
+ successfully built, it will show the PDF after the next refresh automatically.
134
+
135
+ You want to select a template in grafana, which shall then be rendered?
136
+ Piece of cake: Just add a dashboard variable to your grafana dashboard named
137
+ `template` and let the user select or enter a template name. To make use of it,
138
+ you should change the link of the `Demo Report` link to
139
+ `http://<<your-server-url>>:<<your-webservice-port>>/render?`. On
140
+ hitting the new link in the dashboard, grafana will add the selected template as
141
+ a variable and forward it to the reporter.
142
+
143
+ ## Webservice overview
144
+
145
+ Running the reporter as a webservice provides the following URLs
146
+
147
+ /overview - for all running or retained renderings
148
+ /render - for rendering a template, 'var-template' is the only mandatory GET parameter
149
+ /view_report - for viewing the status or receving the result of a specific rendering, is automatically called after a successfull /render call
150
+ /cancel_report - for cancelling the rendering of a specific report, normally not called manually, but on user interaction in the /view_report or /overview URL
151
+
152
+ The main endpoint to call for report generation is configured in the previous chapter [Grafana integration](#grafana-integration).
153
+
154
+ However, if you would like to see, currently running report generations and previously generated reports, you may want to call the endpoint `/overview`.
155
+
156
+ ## Roadmap
157
+
158
+ This is just a collection of things, I am heading for in future, without a schedule.
159
+
160
+ * Support all grafana datasources
161
+ * Solve code TODOs
162
+ * Become [rubocop](https://rubocop.org/) ready
163
+
164
+ ## Contributing
165
+
166
+ If you'd like to contribute, please fork the repository and use a feature
167
+ branch. Pull requests are warmly welcome.
168
+
169
+ ## Licensing
170
+
171
+ The code in this project is licensed under MIT license.
172
+
173
+ ## Acknowledgements
174
+ * [asciidoctor](https://github.com/asciidoctor/asciidoctor)
175
+ * [asciidoctor-pdf](https://github.com/asciidoctor/asciidoctor-pdf)
176
+ * [grafana](https://github.com/grafana/grafana)
177
+
178
+ Inspired by [Izak Marai's grafana reporter](https://github.com/IzakMarais/reporter)
179
+
180
+ ## Donations
181
+
182
+ If this project saves you as much time as I hope it does, and if you'd like to
183
+ support my work, feel free donate. :)
184
+
185
+ [![paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif)](https://www.paypal.com/donate?hosted_button_id=35LH6JNLPHPHQ)
data/lib/VERSION.rb CHANGED
@@ -1,6 +1,6 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  # Version information
4
- GRAFANA_REPORTER_VERSION = [0, 4, 0].freeze
4
+ GRAFANA_REPORTER_VERSION = [0, 4, 1].freeze
5
5
  # Release date
6
- GRAFANA_REPORTER_RELEASE_DATE = '2021-04-14'
6
+ GRAFANA_REPORTER_RELEASE_DATE = '2021-05-17'
@@ -6,33 +6,53 @@ module Grafana
6
6
  class AbstractDatasource
7
7
  attr_reader :model
8
8
 
9
+ @@subclasses = []
10
+
11
+ # Registers the subclass as datasource, which is asked by {#accepts?}, if it can handle a datasource
12
+ # model.
13
+ # @param subclass [Class] class inheriting from this abstract class
14
+ def self.inherited(subclass)
15
+ @@subclasses << subclass
16
+ end
17
+
18
+ # Overwrite this method, to specify if the current datasource implementation handles the given model.
19
+ # This method is called by {#build_instance} to determine, if the current datasource implementation
20
+ # can handle the given grafana model. By default this method returns false.
21
+ # @param model [Hash] grafana specification of the datasource to check
22
+ # @return [Boolean] True if fits, false otherwise
23
+ def self.handles?(_model)
24
+ false
25
+ end
26
+
9
27
  # Factory method to build a datasource from a given datasource Hash description.
10
28
  # @param ds_model [Hash] grafana specification of a single datasource
11
29
  # @return [AbstractDatasource] instance of a fitting datasource implementation
12
30
  def self.build_instance(ds_model)
13
31
  raise InvalidDatasourceQueryProvidedError, ds_model unless ds_model.is_a?(Hash)
14
- raise InvalidDatasourceQueryProvidedError, ds_model unless ds_model['meta']
15
- raise InvalidDatasourceQueryProvidedError, ds_model unless ds_model['meta']['id']
16
- raise InvalidDatasourceQueryProvidedError, ds_model unless ds_model['meta']['category']
17
-
18
- return SqlDatasource.new(ds_model) if ds_model['meta']['category'] == 'sql'
19
32
 
20
- case ds_model['meta']['id']
21
- when 'graphite'
22
- return GraphiteDatasource.new(ds_model)
23
-
24
- when 'prometheus'
25
- return PrometheusDatasource.new(ds_model)
33
+ raise InvalidDatasourceQueryProvidedError, ds_model unless ds_model['meta'].is_a?(Hash)
26
34
 
35
+ @@subclasses.each do |datasource_class|
36
+ return datasource_class.new(ds_model) if datasource_class.handles?(ds_model)
27
37
  end
28
38
 
29
- raise DatasourceTypeNotSupportedError.new(ds_model['name'], ds_model['meta']['id'])
39
+ UnsupportedDatasource.new(ds_model)
30
40
  end
31
41
 
32
42
  def initialize(model)
33
43
  @model = model
34
44
  end
35
45
 
46
+ # @return [String] category of the datasource, e.g. `tsdb` or `sql`
47
+ def category
48
+ @model['meta']['category']
49
+ end
50
+
51
+ # @return [String] type of the datasource, e.g. `mysql`
52
+ def type
53
+ @model['type'] || @model['meta']['id']
54
+ end
55
+
36
56
  # @return [String] name of the datasource
37
57
  def name
38
58
  @model['name']