RubyGems - ruby-grafana-reporter - Versions diffs - 0.1.7 → 0.2.0 - Mend

ruby-grafana-reporter 0.1.7 → 0.2.0

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 (45) hide show

checksums.yaml +4 -4
data/README.md +166 -339
data/bin/ruby-grafana-reporter +5 -4
data/lib/VERSION.rb +5 -3
data/lib/grafana/abstract_panel_query.rb +22 -20
data/lib/grafana/abstract_query.rb +132 -127
data/lib/grafana/abstract_sql_query.rb +51 -42
data/lib/grafana/dashboard.rb +77 -66
data/lib/grafana/errors.rb +66 -61
data/lib/grafana/grafana.rb +130 -131
data/lib/grafana/panel.rb +41 -39
data/lib/grafana/panel_image_query.rb +52 -49
data/lib/grafana/variable.rb +217 -259
data/lib/grafana_reporter/abstract_report.rb +112 -109
data/lib/grafana_reporter/application/application.rb +404 -229
data/lib/grafana_reporter/application/errors.rb +33 -30
data/lib/grafana_reporter/application/webservice.rb +231 -0
data/lib/grafana_reporter/asciidoctor/alerts_table_query.rb +104 -99
data/lib/grafana_reporter/asciidoctor/annotations_table_query.rb +99 -96
data/lib/grafana_reporter/asciidoctor/errors.rb +40 -37
data/lib/grafana_reporter/asciidoctor/extensions/alerts_table_include_processor.rb +92 -86
data/lib/grafana_reporter/asciidoctor/extensions/annotations_table_include_processor.rb +91 -86
data/lib/grafana_reporter/asciidoctor/extensions/panel_image_block_macro.rb +69 -67
data/lib/grafana_reporter/asciidoctor/extensions/panel_image_inline_macro.rb +68 -65
data/lib/grafana_reporter/asciidoctor/extensions/panel_property_inline_macro.rb +61 -58
data/lib/grafana_reporter/asciidoctor/extensions/panel_query_table_include_processor.rb +78 -75
data/lib/grafana_reporter/asciidoctor/extensions/panel_query_value_inline_macro.rb +73 -70
data/lib/grafana_reporter/asciidoctor/extensions/processor_mixin.rb +20 -18
data/lib/grafana_reporter/asciidoctor/extensions/show_environment_include_processor.rb +43 -41
data/lib/grafana_reporter/asciidoctor/extensions/sql_table_include_processor.rb +70 -67
data/lib/grafana_reporter/asciidoctor/extensions/sql_value_inline_macro.rb +66 -65
data/lib/grafana_reporter/asciidoctor/extensions/value_as_variable_include_processor.rb +61 -57
data/lib/grafana_reporter/asciidoctor/panel_first_value_query.rb +34 -32
data/lib/grafana_reporter/asciidoctor/panel_image_query.rb +25 -23
data/lib/grafana_reporter/asciidoctor/panel_property_query.rb +44 -43
data/lib/grafana_reporter/asciidoctor/panel_table_query.rb +38 -36
data/lib/grafana_reporter/asciidoctor/query_mixin.rb +310 -309
data/lib/grafana_reporter/asciidoctor/report.rb +177 -159
data/lib/grafana_reporter/asciidoctor/sql_first_value_query.rb +37 -34
data/lib/grafana_reporter/asciidoctor/sql_table_query.rb +39 -32
data/lib/grafana_reporter/configuration.rb +257 -326
data/lib/grafana_reporter/errors.rb +48 -38
data/lib/grafana_reporter/logger/two_way_logger.rb +58 -52
data/lib/ruby-grafana-reporter.rb +29 -27
metadata +10 -23

checksums.yaml CHANGED

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aaffc7971d9bbdc7b7333d0e9e2bb11bb9c0f4a0a2a564718739793e76ad2f81
-  data.tar.gz: d14e3ef3e7892a15c960ba30e9f6a8c803668a071fe4d221d30d23c20ebbd6e0
+  metadata.gz: c3ffea90aebd213a65781274b5825d3f47d2a68e804821dd4a887ebdaebd67ae
+  data.tar.gz: 931c47a54cebe300a6f0b3e3dffb470ac6ce6f4faddc8558e90bd18d4273b1d5
 SHA512:
-  metadata.gz: 2585ee385b52e447922274769637ec0465bf3a24daceb88afcdaae2fc64d29bcad3d6790bdc7a24d38b881afa6ceeaf9715aa183eaa12084b91c284c46b3b64f
-  data.tar.gz: f608747c46af7c40f9eeb8a8a986a73d81bf85f35e68657046caf53182c8289c62e524eb49b4886117b9db5427de103e30f468403a52ae209a6c59fc9cc62489
+  metadata.gz: d0c187b97ec27c6ac374069d9253215d78c2b04d6e8ff10cc1bd660486d0f998c742cfd65a4d415cdb2b8045fed1c6800ccf2c64cbe21fc530b82527b4183f69
+  data.tar.gz: b7b22e087b05c9c1bb6c0c92526755c1883ac9a57ca53c64e809de18e213421a2c65329618a42a75aa80b2ebdc0a38f48b28ac15eb2b9dd02c7c2250c838953c

data/README.md CHANGED

@@ -1,339 +1,166 @@
-[![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.org/divinity666/ruby-grafana-reporter.svg?branch=master)](https://travis-ci.org/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)
-# Ruby Grafana Reporter
-Reporting Service for Grafana
-## Table of Contents
-* [About the project](#about-the-project)
-* [Getting started](#getting-started)
-  * [Initial Configuration](#initial-configuration)
-  * [Option 1) "Baremetal" Ruby](#baremetal-ruby)
-  * [Option 2) As a GEM](#as-a-gem)
-  * [Option 3) Docker](#docker)
-  * [Grafana integration](#grafana-integration)
-* [Webservice overview](#webservice-overview)
-* [Features](#features)
-* [Roadmap](#roadmap)
-* [Contributing](#contributing)
-* [Licensing](#licensing)
-* [Acknowledgements](#acknowledgements)
-* [Donations](#donations)
-## About the project
-Did you ever want to create (professional) reports based on Grafana dashboards?
-I did so in order to being able to automatically get monthly reports of my
-home's energy usage. That's how it started.
-The reporter provides reporting capabilities for Grafana. It is based on
-(but not limited to) [asciidoctor](https://github.com/asciidoctor/asciidoctor)
-report templates, which can dynamically integrate Grafana panels, queries,
-images etc. to create dynamic PDF reports on the fly.
-The report may also be returned in any other format that asciidoctor supports.
-The reporter can run standalone or as a webservice. It is built to
-integrate without further dependencies with the asciidoctor docker image.
-The complete
-[API documentation](https://rubydoc.info/gems/ruby-grafana-reporter) can be
-found here.
-## Getting started
-There exist several ways of installing the reporter. All of them have in
-common, that they require a working ruby environment. Check with the following
-commands, that the tools are setup and run properly:
-    ruby -v
-    gem -v
-### Initial Configuration
-#### Configuration file
-Create a first configuration file, named e.g. `myconfig` with the following
-content:
-    grafana-reporter:
-      templates-folder: templates
-      reports-folder: reports
-    grafana:
-      default:
-        host: <<url to your grafana host, e.g. https://localhost:3000>>
-        api_key: <<api key to be used by the reporter>>
-        datasources: # mandatory, if the api_key has only viewer rights, optional otherwise
-          "<<data source name in grafana>>": <<data source id in grafana>>
-    default-document-attributes:
-      imagesdir: .
-#### "Hello World" asciidoctor template
-Create a first asciidoctor template file in your `templates-folder`, e.g.
-`myfirsttemplate.adoc` with the following content:
-    = First Ruby Grafana Reporter Example
-    include::grafana_help[]
-    include::grafana_environment[]
-Now you're ready to go! Let's check it out!
-### "Baremetal" Ruby
-To install on a plain ruby installation, make sure that the `ruby` command is
-accessible from your command line and then follow these steps:
-Download the ruby grafana reporter to a folder of your choice.
-Install asciidoctor
-    gem install asciidoctor asciidoctor-pdf zip
-or simply use
-    bundle install
-To check if all dependencies are setup properly, run the following command
-in that folder:
-    ruby bin/ruby-grafana-reporter -h
-Check that your configured grafana instance can be accessed properly:
-    ruby bin/ruby-grafana-reporter myconfig --test default
-Now you may want to check the conversion of your Hello World example:
-    ruby bin/ruby-grafana-reporter myconfig --template myfirsttemplate.adoc --output myfirstrender.pdf
-You should now find a PDF document named `myfirstrender.pdf` which includes a detailed
-help page on how to use the ruby grafana reporter functions in asciidoctor, as well
-as a list of all environment variables that can be accessed.
-If this has been working properly as well, you might want to run the reporter
-as a webservice. Nothing easier than that. Just call:
-    ruby bin/ruby-grafana-reporter myconfig
-Test your configuration by requesting the following URL in a browser of your
-choice:
-    http://<<your-server-url>>:8815/render?var-template=myfirsttemplate.adoc
-If this now also serves you the PDF document after a few seconds (remember to
-reload the page), you are done with the reporter service and might want to go
-to step into the integration with grafana.
-### As a GEM
-Installation as a gem is a simple way, if you don't want to mess with the
-efforts of a barebone installation.
-To install as a gem, simply run:
-    gem install ruby-grafana-reporter
-To see if it works properly, you may run the application:
-    ruby-grafana-reporter
-To check if your configured grafana instance can be accessed properly:
-    ruby-grafana-reporter myconfig --test default
-Now you may want to check the conversion of your Hello World example:
-    ruby-grafana-reporter myconfig --template myfirsttemplate.adoc --output myfirstrender.pdf
-You should now find a PDF document named `myfirstrender.pdf` which includes a detailed
-help page on how to use the ruby grafana reporter functions in asciidoctor, as well
-as a list of all environment variables that can be accessed.
-If this has been working properly as well, you might want to run the reporter
-as a webservice. Nothing easier than that. Just call:
-    ruby-grafana-reporter myconfig
-Test your configuration by requesting the following URL in a browser of your
-choice:
-    http://<<your-server-url>>:8815/render?var-template=myfirsttemplate.adoc
-If this now also serves you the PDF document after a few seconds (remember to
-reload the page), you are done with the reporter service and might want to go
-to step into the integration with grafana.
-### Docker
-One of the key features of the reporter is, that it can work seemlessly with
-the official `asciidoctor` docker container without further dependencies.
-Assuming you have a `docker-compose` setup running, you may want to add the
-following to your services secion in your `docker-compose.yml`:
-    asciidoctor:
-      image: asciidoctor/docker-asciidoctor
-      container_name: asciidoctor
-      hostname: asciidoctor
-      volumes:
-        - /<<an-empty-local-path>>:/documents
-      restart: unless-stopped
-After running this container, you have to copy the reporter files. Download the
-ruby grafana reporter to the folder `<<an-empty-local-path>>`. I tend to use
-the single file application there.
-To test the setup, you'll have to first step inside the container, e.g. by
-calling `docker exec` with the appropriate parameters. Then you can simply
-run
-    ruby bin/ruby-grafana-reporter -h
-Check that your configured grafana instance can be accessed properly:
-    ruby bin/ruby-grafana-reporter myconfig --test default
-Now you may want to check the conversion of your Hello World example:
-    ruby bin/ruby-grafana-reporter myconfig --template myfirsttemplate.adoc --output myfirstrender.pdf
-You should now find a PDF document named `myfirstrender.pdf` which includes a detailed
-help page on how to use the ruby grafana reporter functions in asciidoctor, as well
-as a list of all environment variables that can be accessed.
-If this has been working properly as well, you might want to run the reporter
-as a webservice always when starting the container. To do so, use the following
-`docker-compose` configuration. Watch out for the added lines!
-    asciidoctor:
-      image: asciidoctor/docker-asciidoctor
-      container_name: asciidoctor
-      hostname: asciidoctor
-      volumes:
-        - /<<an-empty-local-path>>:/documents
-      command:
-        sh /documents/startup.sh
-      restart: unless-stopped
-Additionally you need to create a `startup.sh` file in the folder
-`<<an-empty-local-path>>` with the following content:
-    cd /documents
-    ruby bin/ruby-grafana-reporter myconfig
-After restarting the container, the service should be running.
-Test your configuration by requesting the following URL in a browser of your
-choice:
-    http://<<your-server-url>>:8815/render?var-template=myfirsttemplate.adoc
-If this now also serves you the PDF document after a few seconds (remember to
-reload the page), you are done with the reporter service and might want to go
-to step into the integration with grafana.
-### Grafana integration
-The key feature of the report is, that it can easily be integrated with grafana
-(I've not even been talking about the features it is providing for that, but
-you'll find them having a look in the example results above).
-For accessing the reporter 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>>:8815/render?var-template=myfirsttemplate.adoc`
-  * Title: `MyFirstReport`
-  * Select `Time range`
-  * Select `Variable values`
-* Select `Add`
-Now go back to your dashboard and click the newly generated 'MyFirstReport'
-link on it. Now the renderer should start it's task and show you the expected
-results.
-But now the fun just starts! Try out the functions stated in the
-'MyFirstReport' PDF file, to include the dynamic content in your asciidoctor
-template.
-Additionally you might want to make the selection of the template variable.
-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 'MyFirstReport' link to
-`http://<<your-server-url>>:8815/render?`
-That's it. Let me know your feedback!
-## Webservice overview
-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
-    /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
-## Features
-* Build report template including all imaginable grafana content:
-  * panels as images
-  * panel table query or custom query results as real document tables (not images!)
-  * single panel value or custom query single value result integrated in texts
-* Solid as a rock, also in case of template errors (at least it aims to be)
-* Runs standalone or as a webservice
-* Seamlessly integrates with asciidoctor docker container
-* Developed for being able to support other tools than asciidoctor as well
-## Roadmap
-This is just a collection of things, I am heading for in future, without a schedule.
-* Add documentation of possible asciidoctor calls to grafana
-* Add documentation for configuration file
-* Add a simple plugin system to support specific asciidoctor modifications
-* 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.
-Though not yet valid for my code, I'd like to see the project become
-[rubocop](https://rubocop.org/) ready :-)
-Definitely open spots from my side are:
-* This README
-* Clean and properly setup test cases
-* An own webpage for this project
-## 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 this project saves you as much time as I hope it does, and if you'd like to
-support my work, feel free donate, even a cup of coffee is appreciated :)
-[![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.org/divinity666/ruby-grafana-reporter.svg?branch=master)](https://travis-ci.org/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)
+# Ruby Grafana Reporter
+Reporting Service for Grafana
+## Table of Contents
+* [About the project](#about-the-project)
+* [Getting started](#getting-started)
+  * [Grafana integration](#grafana-integration)
+  * [Webservice overview](#webservice-overview)
+* [Features](#features)
+* [Roadmap](#roadmap)
+* [Contributing](#contributing)
+* [Licensing](#licensing)
+* [Acknowledgements](#acknowledgements)
+* [Donations](#donations)
+## About the project
+Did you ever want to create (professional) reports based on Grafana dashboards?
+I did so in order to being able to automatically get monthly reports of my
+home's energy usage. That's how it started.
+The reporter provides reporting capabilities for Grafana. It is based on
+(but not limited to) [asciidoctor](https://github.com/asciidoctor/asciidoctor)
+report templates, which can dynamically integrate Grafana panels, queries,
+images etc. to create dynamic PDF reports on the fly.
+The report may also be returned in any other format that asciidoctor supports.
+The reporter can run standalone or as a webservice. It is built to
+integrate without further dependencies with the asciidoctor docker image.
+The complete
+[API documentation](https://rubydoc.info/gems/ruby-grafana-reporter) can be
+found here.
+## Getting started
+There exist several ways of installing the reporter. Here I cover the easiest
+setup by using ruby gems. If you need further installation help, or want to use
+a "baremetal" ruby setup or a docker integration, please have a look at the more
+extended [installation documentation](INSTALL.md).
+To install the reporter as a gem, simply run:
+    gem install ruby-grafana-reporter
+If no configuration file is in place, you might want to use the configuration
+wizard, which leads you through all necessary steps:
+    ruby-grafana-reporter -w
+Now you're ready to go! Let's check it out!
+    ruby-grafana-reporter -t demo_report -o my_first_render.pdf
+If everything works as expected, you should find a file named `my_first_render.pdf`
+in the current folder, which contains a detailed explanation of all available
+commands as well as your available configuration options.
+To run the reporter as a service, you only need to call it like this:
+    ruby-grafana-reporter
+Neat, isn't it?
+### Grafana integration
+The key feature of the report is, that it can easily be integrated with grafana
+(I've not even been talking about the features it is providing for that, but
+you'll find them having a look in the example results above).
+For accessing the reporter 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=myfirsttemplate`
+  * Title: `MyFirstReport`
+  * Select `Time range`
+  * Select `Variable values`
+* Select `Add`
+Now go back to your dashboard and click the newly generated 'MyFirstReport'
+link on it. Now the renderer should start it's task and show you the expected
+results.
+But now the fun just starts! Try out the functions stated in the
+'MyFirstReport' PDF file, to include the dynamic content in your asciidoctor
+template.
+Additionally you might want to make the selection of the template variable.
+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 'MyFirstReport' link to
+`http://<<your-server-url>>:<<your-webservice-port>>/render?`
+That's it. Let me know your feedback!
+## Webservice overview
+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
+    /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
+## Features
+* Build report template including all imaginable grafana content:
+  * panels as images
+  * panel table query or custom query results as real document tables (not images!)
+  * single panel value or custom query single value result integrated in texts
+* Solid as a rock, also in case of template errors (at least it aims to be)
+* Runs standalone or as a webservice
+* Seamlessly integrates with asciidoctor docker container
+* Developed for being able to support other tools than asciidoctor as well
+## Roadmap
+This is just a collection of things, I am heading for in future, without a schedule.
+* Add documentation of possible asciidoctor calls to grafana
+* Add a simple plugin system to support specific asciidoctor modifications
+* 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.
+Though not yet valid for my code, I'd like to see the project become
+[rubocop](https://rubocop.org/) ready :-)
+Definitely open spots from my side are:
+* This README
+* Clean and properly setup test cases
+## 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 this project saves you as much time as I hope it does, and if you'd like to
+support my work, feel free donate, even a cup of coffee is appreciated :)
+[![paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif)](https://www.paypal.com/donate?hosted_button_id=35LH6JNLPHPHQ)