ruby-grafana-reporter 0.5.3 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b50055253026b61f26a424e6016118db18c4b1998e1a26f8fa6f4c8c37f9d6d
-  data.tar.gz: 9ce58b615705b752f13260b4497b297aa1ad193f018a5699e0d4dca53fb1a743
+  metadata.gz: '00837acead340b75df1bc4dcdf93c05c8014c1317aae288191b592b77a660a7a'
+  data.tar.gz: 2e072de19e45e7fe5f167f37ec4a88be2a482bf7843df96f059a9489e48760b6
 SHA512:
-  metadata.gz: 3d96e06e01a4f5d861603528f64f57cfdbca4fe32a9790f8bc82982ea8581d6d07243aa5bfccd1fac018f1da1f1ad7a514fc31a9ff1f660aa2abf99ebfd5a2ab
-  data.tar.gz: 17b0f9e00461cea9c9fab69572d16b12a69494b06e52500c4f0ba01ced604116c57419726982a87cdd08f462465c4e4e9fe4a891211ff185be2ca52c67c5841d
+  metadata.gz: eec08117ef1a83e7c0a016e80cce31c67fcf552253b63141a440951fa94f1168531b31131ae5cc79e50ac14bf4161a867b717f1c2bfb77ed6d0edac985b7cc38
+  data.tar.gz: fe05d5a7baeb91411fb5942602cd66a66ae8dfcc65eedb7cf421617ffa6c827f5d2a11306dc33ffae9370033a35c10883c17c11f25d8a431bebaf7ae476af4ef

data/LICENSE

@@ -1,20 +1,20 @@
-MIT License
-
-Copyright (c) 2020 Christian Kohlmeyer
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of
-this software and associated documentation files (the "Software"), to deal in
-the Software without restriction, including without limitation the rights to
-use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
-of the Software, and to permit persons to whom the Software is furnished to do
-so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESs
-FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
-COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
-IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+MIT License
+
+Copyright (c) 2020 Christian Kohlmeyer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESs
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,336 +1,337 @@
-[![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)
-[![Build Status](https://travis-ci.com/divinity666/ruby-grafana-reporter.svg?branch=master)](https://travis-ci.com/github/divinity666/ruby-grafana-reporter?branch=master)
-[![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)
-[![Gem Version](https://badge.fury.io/rb/ruby-grafana-reporter.svg)](https://badge.fury.io/rb/ruby-grafana-reporter)
-
-# Ruby Grafana Reporter
-Reporting Service for Grafana
-
-## Table of Contents
-
-* [About the project](#about-the-project)
-* [Features](#features)
-* [Supported datasources](#supported-datasources)
-* [Quick Start](#quick-start)
-  * [Setup](#setup)
-  * [Grafana integration](#grafana-integration)
-* [Advanced information](#advanced-information)
-  * [Webservice](#webservice)
-  * [Using ERB templates](#using-erb-templates)
-  * [Using webhooks](#using-webhooks)
-  * [Developing your own plugin](#developing-your-own-plugin)
-* [Roadmap](#roadmap)
-* [Donations](#donations)
-
-## About the project
-
-[Grafana](https://github.com/grafana/grafana) is a great tool for monitoring and
-visualizing data from different sources. Anyway the free version is lacking a
-professional reporting functionality. And this is, where the ruby grafana reporter
-steps in.
-
-The key functionality of the reporter is to capture data and images from grafana
-dashboards and to use it in your custom templates to finally create reports in PDF
-(default), HTML, or any other format.
-
-By default (an extended version of) Asciidoctor is enabled as template language.
-
-## Features
-
-* Supports creation of reports for multiple [grafana](https://github.com/grafana/grafana)
-dashboards (and also multiple grafana installations!) in one resulting report
-* PDF (default), HTML and many other report formats are supported
-* Easy-to-use configuration wizard, including fully automated functionality to create a
-demo report for your dashboard
-* Include dynamic content from grafana (find here a reference for all
-[asciidcotor reporter calls](FUNCTION_CALLS.md)):
-  * panels as images
-  * tables based on grafana panel queries or custom database queries (no images!)
-  * single values to be integrated in text, based on grafana panel queries or custom
-database queries
-* Runs as
-  * webservice to be called directly from grafana
-  * standalone command line tool, e.g. to be automated with `cron` or `bash` scrips
-  * microservice from standard asciidoctor docker container without any dependencies
-* Supports webhook callbacks on before, on cancel and on finishing a report (see
-configuration file)
-* Solid as a rock, also in case of template errors and whatever else may happen
-* Full [API documentation](https://rubydoc.info/gems/ruby-grafana-reporter) available
-
-## Supported datasources
-
-Functionalities are provided as shown here:
-
-Database                  | Image rendering | Raw queries   | Composed queries
-------------------------- | :-------------: | :-----------: | :------------:
-all SQL based datasources | supported       | supported     | supported
-Graphite                  | supported       | supported     | supported
-InfluxDB                  | supported       | supported     | supported
-Prometheus                | supported       | supported     | n/a in grafana
-other datasources         | supported       | not supported | not supported
-
-The characteristics of a raw query are, that the query is either specified manually in
-the panel specification or in the calling template.
-
-Composed queries are all kinds of query, where the grafana UI feature (aka visual editor
-mode) for query specifications are used. In this case grafana is translating the UI query
-specification to a raw query, which then in fact is sent to the database.
-
-## Quick Start
-
-
-### Setup
-
-You don't have a grafana setup runnning already? No worries, just configure
-`https://play.grafana.org` in the configuration wizard and see the magic
-happen!
-
-If your grafana setup requires a login, you'll have to setup an api key for
-the reporter. Please follow the steps
-[described here](https://github.com/divinity666/ruby-grafana-reporter/issues/2#issuecomment-811836757)
-first.
-
-**Windows:**
-
-* [Download latest Windows executable](https://github.com/divinity666/ruby-grafana-reporter/releases/latest)
-* `ruby-grafana-reporter -w`
-
-**Raspberry Pi:**
-
-* `sudo apt-get install ruby`
-* `gem install ruby-grafana-reporter`
-* `ruby-grafana-reporter -w`
-
-**Ruby environment:**
-
-* `gem install ruby-grafana-reporter`
-* `ruby-grafana-reporter -w`
-
-**Docker environment** (advanced users):
-
-* [Download latest single-rb file](https://github.com/divinity666/ruby-grafana-reporter/releases/latest)
-to an empty folder
-* create a configuration file by calling `ruby ruby-grafana-reporter -w` (if in doubt,
-run the command within your docker container)
-* create file `/<<path-to-single-rb-file-folder>>/startup.sh` with the following
-content:
-
-```
-cd /documents
-ruby bin/ruby-grafana-reporter
-```
-* add the startup script to your asciidoctor section in your docker-compose.yaml:
-
-```
-asciidoctor:
-  image: asciidoctor/docker-asciidoctor
-  container_name: asciidoctor
-  hostname: asciidoctor
-  volumes:
-    - /<<path-to-single-rb-file-folder>>:/documents
-  command:
-    sh /documents/startup.sh
-  restart: unless-stopped
-```
-* start/restart the asciidoctor docker container
-
-### Grafana integration
-
-For using the reporter directly from grafana, you need to simply add a link to your
-grafana dashboard:
-
-* Open the dashboard configuration
-* Select `Links`
-* Select `Add`
-* Fill out as following:
-  * Type: `link`
-  * Url: `http://<<your-server-url>>:<<your-webservice-port>>/render?var-template=demo_report`
-  * Title: `Demo Report`
-  * Select `Time range`
-  * Select `Variable values`
-* Select `Add`
-
-Now go back to your dashboard and click the newly generated `Demo Report`
-link on it. Now the renderer should start it's task and show you the expected
-results.
-
-Please note, that the reporter won't automatically refresh your screen to update
-the progress. Simply hit `F5` to refresh your browser. After the report has been
-successfully built, it will show the PDF after the next refresh automatically.
-
-You want to select a template in grafana, which shall then be rendered?
-Piece of cake: Just add a dashboard variable to your grafana dashboard named
-`template` and let the user select or enter a template name. To make use of it,
-you should change the link of the `Demo Report` link to
-`http://<<your-server-url>>:<<your-webservice-port>>/render?`. On
-hitting the new link in the dashboard, grafana will add the selected template as
-a variable and forward it to the reporter.
-
-## Advanced information
-
-### Webservice
-
-Running the reporter as a webservice provides the following URLs
-
-    /overview - for all running or retained renderings
-    /render - for rendering a template, 'var-template' is the only mandatory GET parameter, all parameters will be passed to the report templates as attributes
-    /view_report - for viewing the status or receving the result of a specific rendering, is automatically called after a successfull /render call
-    /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
-
-The main endpoint to call for report generation is configured in the previous chapter [Grafana integration](#grafana-integration).
-
-However, if you would like to see, currently running report generations and previously generated reports, you may want to call the endpoint `/overview`.
-
-### Using ERB templates
-
-By default the configuration wizard will setup the reporter with the asciidoctor
-template language enabled. For several reasons, you may want to take advantage of
-the ruby included
-[ERB template language](https://docs.ruby-lang.org/en/master/ERB.html).
-
-Anyway you should consider, that ERB templates can include harmful code. So make
-sure, that you will only use ERB templates in a safe environment.
-
-To enable the ERB template language, you need to modify your configuration file
-in the section `grafana-reporter`:
-
-````
-grafana-reporter:
-  report-class: GrafanaReporter::ERB::Report
-````
-
-Restart the grafana reporter instance, if running as webservice. That's all.
-
-In ERB templates, you have access to the variables `report`, which is a reference
-to the currently executed
-[ERB Report object](https://rubydoc.info/gems/ruby-grafana-reporter/GrafanaReporter/ERB/Report)
-and `attributes`, which contains a hash
-of variables, which have been handed over to the report generations, e.g. from
-a webservice call.
-
-To test the configuration, you may want to run the configuration wizard again,
-which will create an ERB template for you.
-
-### Using webhooks
-
-Webhooks provide an easy way to get automatically informed about the progress
-of a report. The nice thing is, that this is completely independent from
-running the reporter as webservice, i.e. these callbacks are also called if you
-run the reporter standalone.
-
-To use webhooks, you have to specify, in which progress states of a report you
-are interested. Therefore you have to configure it in the `grafana-reporter`
-section of your configuration file, e.g.
-
-````
-grafana-reporter:
-  callbacks:
-    all:
-      - http://<<your_callback_url>>
-````
-
-Remember to restart the reporter, if it is running as a webservice.
-
-After having done so, your callback url will be called for each event with
-a JSON body including all necessary information of the report. For details see
-[callback](https://rubydoc.info/gems/ruby-grafana-reporter/GrafanaReporter/ReportWebhook#callback-instance_method).
-
-### Developing your own plugin
-
-The reporter is designed to allow easy integration of your own plugins,
-without having to modify the reporter base source on github (or anywhere
-else). This section shows how to implement and load a custom datasource.
-
-Implementing a custom datasource is needed, if you use a custom datasource
-grafana plugin, which is not yet supported by the reporter. In that case you
-can build your own custom datasource for the reporter and load it on demand
-with a command line parameter, without having to build your own fork of this
-project.
-
-This documentation will provide a simple, but mocked implementation of an
-imagined grafana datasource.
-
-First of all, let's create a new text file, e.g. `my_datasource.rb` with the
-following content:
-
-````
-class MyDatasource < ::Grafana::AbstractDatasource
-  def self.handles?(model)
-    tmp = new(model)
-    tmp.type == 'my_datasource'
-  end
-
-  def request(query_description)
-    # see https://rubydoc.info/gems/ruby-grafana-reporter/Grafana/AbstractDatasource#request-instance_method
-    # for detailed information of given parameters and expected return format
-
-    # TODO: call your datasource, e.g. via REST call
-    # TODO: return the value in the needed format
-  end
-
-  def raw_query_from_panel_model(panel_query_target)
-    # TODO: extract or build the query from the given grafana panel query target hash
-  end
-
-  def default_variable_format
-    # TODO, specify the default variable format
-    # see https://rubydoc.info/gems/ruby-grafana-reporter/Grafana/Variable#value_formatted-instance_method
-    # for detailed information.
-  end
-end
-````
-
-The only thing left to do now, is to make this datasource known to the
-reporter. This can be done with the `-r` command line flag, e.g.
-
-````
-ruby-grafana-reporter -r my_datasource.rb
-````
-
-The reporter implemented some magic, to automatically register datasource
-implementations on load, if they inherit from `::Grafana::AbstractDatasource`.
-This means, that you don't have to do anything else here.
-
-Now the reporter knows about your datasource implementation and will use it,
-if you request information from a panel, which is linked to the type
-`my_datasource` as specified in the `handles?` method above. If any errors
-occur during execution, the reporter will catch them and show them in the error
-log.
-
-Registering a custom ruby file is independent from running the reporter as a
-webservice or as a standalone executable. In any case the reporter will apply
-the file.
-
-Technically, loading your own plugin will call require for your ruby file,
-_after_ all reporter files have been loaded and _before_ the execution of the
-webservice or a rendering process starts.
-
-## Roadmap
-
-This is just a collection of things, I am heading for in future, without a schedule.
-
-* Support grafana internal datasources
-* Solve code TODOs
-* Become [rubocop](https://rubocop.org/) ready
-
-## Contributing
-
-If you'd like to contribute, please fork the repository and use a feature
-branch. Pull requests are warmly welcome.
-
-## Licensing
-
-The code in this project is licensed under MIT license.
-
-## Acknowledgements
-* [asciidoctor](https://github.com/asciidoctor/asciidoctor)
-* [asciidoctor-pdf](https://github.com/asciidoctor/asciidoctor-pdf)
-* [grafana](https://github.com/grafana/grafana)
-
-Inspired by [Izak Marai's grafana reporter](https://github.com/IzakMarais/reporter)
-
-## Donations
-
-If you like this project and you would like to support my work, feel free to donate. :)
-
-[![paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif)](https://www.paypal.com/donate?hosted_button_id=35LH6JNLPHPHQ)
+[![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)
+[![Build Status](https://travis-ci.com/divinity666/ruby-grafana-reporter.svg?branch=master)](https://travis-ci.com/github/divinity666/ruby-grafana-reporter?branch=master)
+[![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)
+[![Gem Version](https://badge.fury.io/rb/ruby-grafana-reporter.svg)](https://badge.fury.io/rb/ruby-grafana-reporter)
+
+# Ruby Grafana Reporter
+Reporting Service for Grafana
+
+## Table of Contents
+
+* [About the project](#about-the-project)
+* [Features](#features)
+* [Supported datasources](#supported-datasources)
+* [Quick Start](#quick-start)
+  * [Setup](#setup)
+  * [Grafana integration](#grafana-integration)
+* [Advanced information](#advanced-information)
+  * [Webservice](#webservice)
+  * [Using ERB templates](#using-erb-templates)
+  * [Using webhooks](#using-webhooks)
+  * [Developing your own plugin](#developing-your-own-plugin)
+* [Roadmap](#roadmap)
+* [Donations](#donations)
+
+## About the project
+
+[Grafana](https://github.com/grafana/grafana) is a great tool for monitoring and
+visualizing data from different sources. Anyway the free version is lacking a
+professional reporting functionality. And this is, where the ruby grafana reporter
+steps in.
+
+The key functionality of the reporter is to capture data and images from grafana
+dashboards and to use it in your custom templates to finally create reports in PDF
+(default), HTML, or any other format.
+
+By default (an extended version of) Asciidoctor is enabled as template language.
+
+## Features
+
+* Supports creation of reports for multiple [grafana](https://github.com/grafana/grafana)
+dashboards (and also multiple grafana installations!) in one resulting report
+* PDF (default), HTML and many other report formats are supported
+* Easy-to-use configuration wizard, including fully automated functionality to create a
+demo report for your dashboard
+* Include dynamic content from grafana (find here a reference for all
+[asciidcotor reporter calls](FUNCTION_CALLS.md)):
+  * panels as images
+  * tables based on grafana panel queries or custom database queries (no images!)
+  * single values to be integrated in text, based on grafana panel queries or custom
+database queries
+* Runs as
+  * webservice to be called directly from grafana
+  * standalone command line tool, e.g. to be automated with `cron` or `bash` scrips
+  * microservice from standard asciidoctor docker container without any dependencies
+* Supports webhook callbacks on before, on cancel and on finishing a report (see
+configuration file)
+* Solid as a rock, also in case of template errors and whatever else may happen
+* Full [API documentation](https://rubydoc.info/gems/ruby-grafana-reporter) available
+
+## Supported datasources
+
+Functionalities are provided as shown here:
+
+Database                  | Image rendering | Raw queries   | Composed queries
+------------------------- | :-------------: | :-----------: | :------------:
+all SQL based datasources | supported       | supported     | supported
+Graphite                  | supported       | supported     | supported
+InfluxDB                  | supported       | supported     | supported
+Prometheus                | supported       | supported     | n/a in grafana
+other datasources         | supported       | not supported | not supported
+
+The characteristics of a raw query are, that the query is either specified manually in
+the panel specification or in the calling template.
+
+Composed queries are all kinds of query, where the grafana UI feature (aka visual editor
+mode) for query specifications are used. In this case grafana is translating the UI query
+specification to a raw query, which then in fact is sent to the database.
+
+## Quick Start
+
+
+### Setup
+
+You don't have a grafana setup runnning already? No worries, just configure
+`https://play.grafana.org` in the configuration wizard and see the magic
+happen!
+
+If your grafana setup requires a login, you'll have to setup an api key for
+the reporter. Please follow the steps
+[described here](https://github.com/divinity666/ruby-grafana-reporter/issues/2#issuecomment-811836757)
+first.
+
+**Windows:**
+
+* [Download latest Windows executable](https://github.com/divinity666/ruby-grafana-reporter/releases/latest)
+* `ruby-grafana-reporter -w`
+
+**Raspberry Pi:**
+
+* `sudo apt-get install ruby`
+* `gem install ruby-grafana-reporter`
+* `ruby-grafana-reporter -w`
+
+**Ruby environment:**
+
+* `gem install ruby-grafana-reporter`
+* `ruby-grafana-reporter -w`
+
+**Docker environment** (advanced users):
+
+* [Download latest single-rb file](https://github.com/divinity666/ruby-grafana-reporter/releases/latest)
+to an empty folder
+* create a configuration file by calling `ruby ruby-grafana-reporter -w` (if in doubt,
+run the command within your docker container)
+* create file `/<<path-to-single-rb-file-folder>>/startup.sh` with the following
+content:
+
+```
+cd /documents
+ruby bin/ruby-grafana-reporter
+```
+* add the startup script to your asciidoctor section in your docker-compose.yaml:
+
+```
+asciidoctor:
+  image: asciidoctor/docker-asciidoctor
+  container_name: asciidoctor
+  hostname: asciidoctor
+  volumes:
+    - /<<path-to-single-rb-file-folder>>:/documents
+  command:
+    sh /documents/startup.sh
+  restart: unless-stopped
+```
+* start/restart the asciidoctor docker container
+
+### Grafana integration
+
+For using the reporter directly from grafana, you need to simply add a link to your
+grafana dashboard:
+
+* Open the dashboard configuration
+* Select `Links`
+* Select `Add`
+* Fill out as following:
+  * Type: `link`
+  * Url: `http://<<your-server-url>>:<<your-webservice-port>>/render?var-template=demo_report`
+  * Title: `Demo Report`
+  * Select `Time range`
+  * Select `Variable values`
+* Select `Add`
+
+Now go back to your dashboard and click the newly generated `Demo Report`
+link on it. Now the renderer should start it's task and show you the expected
+results.
+
+Please note, that the reporter won't automatically refresh your screen to update
+the progress. Simply hit `F5` to refresh your browser. After the report has been
+successfully built, it will show the PDF after the next refresh automatically.
+
+You want to select a template in grafana, which shall then be rendered?
+Piece of cake: Just add a dashboard variable to your grafana dashboard named
+`template` and let the user select or enter a template name. To make use of it,
+you should change the link of the `Demo Report` link to
+`http://<<your-server-url>>:<<your-webservice-port>>/render?`. On
+hitting the new link in the dashboard, grafana will add the selected template as
+a variable and forward it to the reporter.
+
+## Advanced information
+
+### Webservice
+
+Running the reporter as a webservice provides the following URLs
+
+    /overview - for all running or retained renderings
+    /render - for rendering a template, 'var-template' is the only mandatory GET parameter, all parameters will be passed to the report templates as attributes
+    /view_report - for viewing the status or receving the result of a specific rendering, is automatically called after a successfull /render call
+    /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
+
+The main endpoint to call for report generation is configured in the previous chapter [Grafana integration](#grafana-integration).
+
+However, if you would like to see, currently running report generations and previously generated reports, you may want to call the endpoint `/overview`.
+
+### Using ERB templates
+
+By default the configuration wizard will setup the reporter with the asciidoctor
+template language enabled. For several reasons, you may want to take advantage of
+the ruby included
+[ERB template language](https://docs.ruby-lang.org/en/master/ERB.html).
+
+Anyway you should consider, that ERB templates can include harmful code. So make
+sure, that you will only use ERB templates in a safe environment.
+
+To enable the ERB template language, you need to modify your configuration file
+in the section `grafana-reporter`:
+
+````
+grafana-reporter:
+  report-class: GrafanaReporter::ERB::Report
+````
+
+Restart the grafana reporter instance, if running as webservice. That's all.
+
+In ERB templates, you have access to the variables `report`, which is a reference
+to the currently executed
+[ERB Report object](https://rubydoc.info/gems/ruby-grafana-reporter/GrafanaReporter/ERB/Report)
+and `attributes`, which contains a hash
+of variables, which have been handed over to the report generations, e.g. from
+a webservice call.
+
+To test the configuration, you may want to run the configuration wizard again,
+which will create an ERB template for you.
+
+### Using webhooks
+
+Webhooks provide an easy way to get automatically informed about the progress
+of a report. The nice thing is, that this is completely independent from
+running the reporter as webservice, i.e. these callbacks are also called if you
+run the reporter standalone.
+
+To use webhooks, you have to specify, in which progress states of a report you
+are interested. Therefore you have to configure it in the `grafana-reporter`
+section of your configuration file, e.g.
+
+````
+grafana-reporter:
+  callbacks:
+    all:
+      - http://<<your_callback_url>>
+````
+
+Remember to restart the reporter, if it is running as a webservice.
+
+After having done so, your callback url will be called for each event with
+a JSON body including all necessary information of the report. For details see
+[callback](https://rubydoc.info/gems/ruby-grafana-reporter/GrafanaReporter/ReportWebhook#callback-instance_method).
+
+### Developing your own plugin
+
+The reporter is designed to allow easy integration of your own plugins,
+without having to modify the reporter base source on github (or anywhere
+else). This section shows how to implement and load a custom datasource.
+
+Implementing a custom datasource is needed, if you use a custom datasource
+grafana plugin, which is not yet supported by the reporter. In that case you
+can build your own custom datasource for the reporter and load it on demand
+with a command line parameter, without having to build your own fork of this
+project.
+
+This documentation will provide a simple, but mocked implementation of an
+imagined grafana datasource.
+
+First of all, let's create a new text file, e.g. `my_datasource.rb` with the
+following content:
+
+````
+class MyDatasource < ::Grafana::AbstractDatasource
+  def self.handles?(model)
+    tmp = new(model)
+    tmp.type == 'my_datasource'
+  end
+
+  def request(query_description)
+    # see https://rubydoc.info/gems/ruby-grafana-reporter/Grafana/AbstractDatasource#request-instance_method
+    # for detailed information of given parameters and expected return format
+
+    # TODO: call your datasource, e.g. via REST call
+    # TODO: return the value in the needed format
+  end
+
+  def raw_query_from_panel_model(panel_query_target)
+    # TODO: extract or build the query from the given grafana panel query target hash
+  end
+
+  def default_variable_format
+    # TODO, specify the default variable format
+    # see https://rubydoc.info/gems/ruby-grafana-reporter/Grafana/Variable#value_formatted-instance_method
+    # for detailed information.
+  end
+end
+````
+
+The only thing left to do now, is to make this datasource known to the
+reporter. This can be done with the `-r` command line flag, e.g.
+
+````
+ruby-grafana-reporter -r my_datasource.rb
+````
+
+The reporter implemented some magic, to automatically register datasource
+implementations on load, if they inherit from `::Grafana::AbstractDatasource`.
+This means, that you don't have to do anything else here.
+
+Now the reporter knows about your datasource implementation and will use it,
+if you request information from a panel, which is linked to the type
+`my_datasource` as specified in the `handles?` method above. If any errors
+occur during execution, the reporter will catch them and show them in the error
+log.
+
+Registering a custom ruby file is independent from running the reporter as a
+webservice or as a standalone executable. In any case the reporter will apply
+the file.
+
+Technically, loading your own plugin will call require for your ruby file,
+_after_ all reporter files have been loaded and _before_ the execution of the
+webservice or a rendering process starts.
+
+## Roadmap
+
+This is just a collection of things, I am heading for in future, without a schedule.
+
+* Support grafana internal datasources
+* Support additional templating variable types
+* Solve code TODOs
+* Become [rubocop](https://rubocop.org/) ready
+
+## Contributing
+
+If you'd like to contribute, please fork the repository and use a feature
+branch. Pull requests are warmly welcome.
+
+## Licensing
+
+The code in this project is licensed under MIT license.
+
+## Acknowledgements
+* [asciidoctor](https://github.com/asciidoctor/asciidoctor)
+* [asciidoctor-pdf](https://github.com/asciidoctor/asciidoctor-pdf)
+* [grafana](https://github.com/grafana/grafana)
+
+Inspired by [Izak Marai's grafana reporter](https://github.com/IzakMarais/reporter)
+
+## Donations
+
+If you like this project and you would like to support my work, feel free to donate. :)
+
+[![paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif)](https://www.paypal.com/donate?hosted_button_id=35LH6JNLPHPHQ)

data/bin/ruby-grafana-reporter

@@ -1,5 +1,5 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require_relative '../lib/ruby_grafana_reporter'
-GrafanaReporter::Application::Application.new.configure_and_run(ARGV) unless defined?(Ocra)
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/ruby_grafana_reporter'
+GrafanaReporter::Application::Application.new.configure_and_run(ARGV) unless defined?(Ocra)

data/lib/VERSION.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 # Version information
-GRAFANA_REPORTER_VERSION = [0, 5, 3].freeze
+GRAFANA_REPORTER_VERSION = [0, 6, 1].freeze
 # Release date
-GRAFANA_REPORTER_RELEASE_DATE = '2022-03-24'
+GRAFANA_REPORTER_RELEASE_DATE = '2022-08-30'

data/lib/grafana/abstract_datasource.rb

@@ -82,6 +82,7 @@ module Grafana
     #   }
     #
     # @param query_description [Hash] query description, which will requested:
+    # @option query_description [String] :grafana_version grafana version, for which the request is to be prepared
     # @option query_description [String] :from +from+ timestamp
     # @option query_description [String] :to +to+ timestamp
     # @option query_description [Integer] :timeout expected timeout for the request
@@ -170,7 +171,13 @@ module Grafana
       data = data['frames']
       headers = []
       data.first['schema']['fields'].each do |headline|
-        header = headline['config']['displayNameFromDS'].nil? ? headline['name'] : headline['config']['displayNameFromDS']
+        use_name_only = true
+        if not headline['config'].nil?
+          if not headline['config']['displayNameFromDS'].nil?
+            use_name_only = false
+          end
+        end
+        header = use_name_only ? headline['name'] : headline['config']['displayNameFromDS']
         headers << header
       end
       content = data.first['data']['values'][0].zip(data.first['data']['values'][1])

data/lib/grafana/dashboard.rb

@@ -58,7 +58,14 @@ module Grafana
       list = @model['templating']['list']
       return unless list.is_a? Array
 
-      list.each { |item| @variables << Variable.new(item, self) }
+      list.each do |item|
+        begin
+          @variables << Variable.new(item, self)
+        rescue => e
+          # TODO: show this message as a warning - needs test cleanup
+          @grafana.logger.debug(e.message)
+        end
+      end
     end
 
     # read panels

data/lib/grafana/grafana.rb

@@ -86,7 +86,15 @@ module Grafana
     # @param datasource_uid [String] unique id of the searched datasource
     # @return [Datasource] Datasource for the specified datasource unique id
     def datasource_by_uid(datasource_uid)
-      datasource = @datasources.select { |_name, ds| ds.uid == datasource_uid }.values.first
+      datasource = @datasources.select do |ds_name, ds|
+        if (ds.nil?)
+          # print debug info for https://github.com/divinity666/ruby-grafana-reporter/issues/29
+          @logger.warn("Datasource with name #{ds_name} is nil, which should never happen. Check logs for details.")
+          false
+        else
+          ds.uid == datasource_uid
+        end
+      end.values.first
       raise DatasourceDoesNotExistError.new('uid', datasource_uid) unless datasource
 
       datasource
@@ -156,6 +164,12 @@ module Grafana
       json = JSON.parse(settings.body)
       json['datasources'].select { |_k, v| v['id'].to_i.positive? }.each do |ds_name, ds_value|
         @datasources[ds_name] = AbstractDatasource.build_instance(ds_value)
+
+        # print debug info for https://github.com/divinity666/ruby-grafana-reporter/issues/29
+        if @datasources[ds_name].nil?
+          @logger.error("Datasource with name '#{ds_name}' and configuration: '#{ds_value}' could not be initialized.")
+          @datasources.delete(ds_name)
+        end
       end
       @datasources['default'] = @datasources[json['defaultDatasource']]
     end

data/lib/grafana/panel.rb

@@ -37,7 +37,7 @@ module Grafana
     #
     # @param variables [Hash] variables hash, which should be use to resolve variable datasource
     def resolve_variable_datasource(variables)
-      @datasource_uid_or_name = AbstractDatasource.new(nil).replace_variables(@datasource_uid_or_name, variables, 'raw')
+      @datasource_uid_or_name = AbstractDatasource.new(nil).replace_variables(@datasource_uid_or_name, variables, 'raw') if @datasource_uid_or_name.is_a?(String)
     end
 
     # @return [Datasource] datasource object specified for the current panel

data/lib/grafana/prometheus_datasource.rb

@@ -24,21 +24,15 @@ module Grafana
       interval = interval.raw_value if interval.is_a?(Variable)
       query = query_hash[:query] || query_description[:raw_query]
 
-      url = if instant
-        "/api/datasources/proxy/#{id}/api/v1/query?time=#{query_description[:to]}&query="\
-        "#{CGI.escape(replace_variables(query, query_description[:variables]))}"
+      ver = query_description[:grafana_version].split('.').map{|x| x.to_i}
+      request = nil
+      if (ver[0] == 7 and ver[1] < 5) or ver[0] < 7
+        request = prepare_get_request({query_description: query_description, instant: instant, interval: interval, query: query})
       else
-        "/api/datasources/proxy/#{id}/api/v1/query_range?start=#{query_description[:from]}"\
-        "&end=#{query_description[:to]}"\
-        "&query=#{CGI.escape(replace_variables(query, query_description[:variables]))}"\
-        "&step=#{interval}"
+        request = prepare_post_request({query_description: query_description, instant: instant, interval: interval, query: query})
       end
 
-      webrequest = query_description[:prepared_request]
-      webrequest.relative_url = url
-      webrequest.options.merge!({ request: Net::HTTP::Get })
-
-      result = webrequest.execute(query_description[:timeout])
+      result = request.execute(query_description[:timeout])
       preformat_response(result.body)
     end
 
@@ -54,13 +48,67 @@ module Grafana
     end
 
     private
+    def prepare_get_request(hash)
+      url = if hash[:instant]
+        "/api/datasources/proxy/#{id}/api/v1/query?time=#{hash[:query_description][:to]}&query="\
+        "#{CGI.escape(replace_variables(hash[:query], hash[:query_description][:variables]))}"
+      else
+        "/api/datasources/proxy/#{id}/api/v1/query_range?start=#{hash[:query_description][:from]}"\
+        "&end=#{hash[:query_description][:to]}"\
+        "&query=#{CGI.escape(replace_variables(hash[:query], hash[:query_description][:variables]))}"\
+        "&step=#{hash[:interval]}"
+      end
+
+      webrequest = hash[:query_description][:prepared_request]
+      webrequest.relative_url = url
+      webrequest.options.merge!({ request: Net::HTTP::Get })
+
+      webrequest
+    end
+
+    def prepare_post_request(hash)
+      webrequest = hash[:query_description][:prepared_request]
+      webrequest.relative_url = '/api/ds/query'
+
+      params = {
+        from: hash[:query_description][:from],
+        to: hash[:query_description][:to],
+        queries: [{
+          datasource: { type: type, uid: uid },
+          datasourceId: id,
+          exemplar: false,
+          expr: hash[:query],
+          format: 'time_series',
+          interval: '',
+          # intervalFactor: ### 2,
+          # intervalMs: ### 15000,
+          # legendFormat: '', ### {{job}}
+          # maxDataPoints: 999,
+          metric: '',
+          queryType: 'timeSeriesQuery',
+          refId: 'A',
+          # requestId: '14A',
+          # utcOffsetSec: 7200,
+          step: hash[:interval]
+        }],
+        range: {
+          #from: ### "2022-07-31T16:19:26.198Z",
+          #to: ### "2022-07-31T16:19:26.198Z",
+          raw: { from: hash[:query_description][:variables]['from'].raw_value, to: hash[:query_description][:variables]['to'].raw_value }
+        }
+      }
+
+      webrequest.options.merge!({ request: Net::HTTP::Post, body: params.to_json })
+
+      webrequest
+    end
 
     def preformat_response(response_body)
       # TODO: show raw response body to debug case https://github.com/divinity666/ruby-grafana-reporter/issues/24
       begin
         return preformat_dataframe_response(response_body)
       rescue
-        # TODO: show an info, that the response if not a dataframe
+        # TODO: show an info, that the response is not a dataframe
       end
 
       json = JSON.parse(response_body)

data/lib/grafana/variable.rb

@@ -240,7 +240,7 @@ module Grafana
         if !@config['current'].nil?
           self.raw_value = @config['current']['value']
         else
-          raise GrafanaError.new("Grafana variable with type '#{@config['type']}' and name '#{@config['name']}' could not be handled properly. Please raise a ticket.")
+          raise GrafanaError.new("Grafana variable with type '#{@config['type']}' and name '#{@config['name']}' cannot be handled properly by the reporter. Check your results and raise a ticket on github.")
         end
       end
     end

data/lib/grafana_reporter/abstract_query.rb

@@ -13,7 +13,6 @@ module GrafanaReporter
     attr_reader :variables, :result, :panel, :dashboard
 
     def timeout
-      # TODO: PRIO check where value priorities should be evaluated
       return @variables['timeout'].raw_value if @variables['timeout']
       return @variables['grafana_default_timeout'].raw_value if @variables['grafana_default_timeout']
 
@@ -81,7 +80,11 @@ module GrafanaReporter
 
       begin
         @result = @datasource.request(from: from, to: to, raw_query: raw_query, variables: @variables,
-                                      prepared_request: @grafana.prepare_request, timeout: timeout)
+                                      prepared_request: @grafana.prepare_request, timeout: timeout,
+                                      grafana_version: @grafana.version)
+        if @variables['verbose_log']
+          @logger.debug("Raw result: #{@result}") if @variables['verbose_log'].raw_value.downcase == "true"
+        end
       rescue ::Grafana::GrafanaError
         # grafana errors will be directly passed through
         raise
@@ -95,6 +98,9 @@ module GrafanaReporter
       raise DatasourceRequestInvalidReturnValueError.new(@datasource, @result) unless datasource_response_valid?
 
       post_process
+      if @variables['verbose_log']
+        @logger.debug("Formatted result: #{@result}") if @variables['verbose_log'].raw_value.downcase == "true"
+      end
       @result
     end
 

data/lib/grafana_reporter/asciidoctor/help.rb

@@ -201,7 +201,7 @@ end}
                 two digit decimals of a float. Several column formats are separated by `,`, i.e. `%.2f,%.3f` would
                 apply `%.2f` to the first column and `%.3f` to the second column. All other columns would not be
                 formatted. You may also format time in milliseconds to a time format by specifying e.g. `date:iso`.
-                Commas in format strings are supported, but have to be escaped by useing `_,`.
+                Commas in format strings are supported, but have to be escaped by using `_,`.
                 Execution of related functions is applied in the following order `format`,
                 `replace_values`, `filter_columns`, `transpose`.
               see: 'https://ruby-doc.org/core/Kernel.html#method-i-sprintf'
@@ -217,11 +217,16 @@ end}
                 `replace_values`, `filter_columns`, `transpose`.
               see: https://ruby-doc.org/core/Regexp.html#class-Regexp-label-Character+Classes
 
+            include_headline:
+              call: include_headline="true"
+              description: >-
+                Adds the headline of the columns as first row of the resulting table.
+
             filter_columns:
               call: filter_columns="<column_name_1>,<column_name_2>,..."
               description: >-
                 Removes specified columns from result.  Commas in format strings are supported, but have to be
-                escaped by useing `_,`. Execution of related functions is applied in the following order
+                escaped by using `_,`. Execution of related functions is applied in the following order
                 `format`, `replace_values`, `filter_columns`, `transpose`.
 
             transpose:
@@ -271,6 +276,12 @@ end}
               description: >-
                 Optional parameter for Prometheus `instant` queries. Ignored for other datasources than Prometheus.
 
+            verbose_log:
+              call: verbose_log="true"
+              description: >-
+                Setting this option will show additional information about the returned query results in the log as
+                DEBUG messages.
+
           # ----------------------------------
           # FUNCTION DOCUMENTATION STARTS HERE
           # ----------------------------------
@@ -313,6 +324,7 @@ end}
               filter_columns:
               format:
               from:
+              include_headline:
               instance:
               replace_values:
               row_divider:
@@ -348,6 +360,7 @@ end}
               filter_columns:
               format:
               from:
+              include_headline:
               instance:
               replace_values:
               row_divider:
@@ -409,6 +422,7 @@ end}
               filter_columns:
               format:
               from:
+              include_headline:
               instance:
               replace_values:
               row_divider:
@@ -420,6 +434,7 @@ end}
               to_timezone:
               instant:
               interval:
+              verbose_log:
 
           grafana_panel_query_value:
             call: 'grafana_panel_query_value:<panel_id>[query="<query_letter>",options]'
@@ -444,6 +459,7 @@ end}
               to_timezone:
               instant:
               interval:
+              verbose_log:
 
           grafana_sql_table:
             call: 'include::grafana_sql_table:<datasource_id>[sql="<sql_query>",options]'
@@ -456,6 +472,7 @@ end}
               filter_columns:
               format:
               from:
+              include_headline:
               instance:
               replace_values:
               row_divider:
@@ -467,6 +484,7 @@ end}
               to_timezone:
               instant:
               interval:
+              verbose_log:
 
           grafana_sql_value:
             call: 'grafana_sql_value:<datasource_id>[sql="<sql_query>",options]'
@@ -490,6 +508,30 @@ end}
               to_timezone:
               instant:
               interval:
+              verbose_log:
+
+          grafana_value_as_variable:
+            call: 'include::grafana_value_as_variable[call="<grafana_reporter_call>",variable_name="<your_variable_name>",options]'
+            description: >-
+              Executes the given +<grafana_reporter_call>+ and stored the resulting value
+              in the given +<your_variable_name>+, so that it can be used in asciidoctor
+              at any position with +{<your_variable_name>}+.
+
+              A sample call could look like this: +include:grafana_value_as_variable[call="grafana_sql_value:1",variable_name="my_variable",sql="SELECT 'looks good'",<any_other_option>]+
+
+              If the function succeeds, it will add this to the asciidoctor file:
+
+              +:my_variable: looks good+
+
+              Please note, that you may add any other option to the call. These will
+              simply be passed 1:1 to the +<grafana_reporter_call>+.
+            options:
+              call:
+                call: call="<grafana_reporter_call>"
+                description: Call to grafana reporter function, for which the result shall be stored as variable. Please note that only functions without +include::+ are supported here.
+              variable_name:
+                call: variable_name="<your_variable_name>"
+                description: Name of the variable, which will get the value assigned.
         YAML_HELP
       end
     end

data/lib/grafana_reporter/asciidoctor/processor_mixin.rb

@@ -40,7 +40,7 @@ module GrafanaReporter
           k =~ /^(?:timeout|from|to)$/ ||
           k =~ /filter_columns|format|replace_values_.*|transpose|from_timezone|
                to_timezone|result_type|query|table_formatter|include_headline|
-               column_divider|row_divider|instant|interval/x
+               column_divider|row_divider|instant|interval|verbose_log/x
         end)
 
         result

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-grafana-reporter
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.6.1
 platform: ruby
 authors:
 - Christian Kohlmeyer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-03-24 00:00:00.000000000 Z
+date: 2022-08-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asciidoctor
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.6'
+        version: '2.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.6'
+        version: '2.3'
 - !ruby/object:Gem::Dependency
   name: rubyzip
   requirement: !ruby/object:Gem::Requirement
@@ -86,6 +86,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.16'
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
@@ -167,7 +181,6 @@ files:
 - "./lib/grafana_reporter/query_value_query.rb"
 - "./lib/grafana_reporter/report_webhook.rb"
 - "./lib/grafana_reporter/reporter_environment_datasource.rb"
-- "./lib/ruby_grafana_extension.rb"
 - "./lib/ruby_grafana_reporter.rb"
 - LICENSE
 - README.md
@@ -186,14 +199,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.5
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: Reporter Service for Grafana

data/lib/ruby_grafana_extension.rb

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'ruby_grafana_reporter'
-
-config = GrafanaReporter::Configuration.new
-config.config = GrafanaReporter::Application::Application.load_config
-
-GrafanaReporter::Asciidoctor::Report.new(config).register