ruby-grafana-reporter 0.1.7 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aaffc7971d9bbdc7b7333d0e9e2bb11bb9c0f4a0a2a564718739793e76ad2f81
-  data.tar.gz: d14e3ef3e7892a15c960ba30e9f6a8c803668a071fe4d221d30d23c20ebbd6e0
+  metadata.gz: db7e3fbf0f8c1a3d7d9ce8d3e3e215b6f6bb5ec3c170252d575e0516b3312b20
+  data.tar.gz: b05cfa64a8d5bef650917df47ad9b84a140f302e87d2c6664c1fab3272e7212e
 SHA512:
-  metadata.gz: 2585ee385b52e447922274769637ec0465bf3a24daceb88afcdaae2fc64d29bcad3d6790bdc7a24d38b881afa6ceeaf9715aa183eaa12084b91c284c46b3b64f
-  data.tar.gz: f608747c46af7c40f9eeb8a8a986a73d81bf85f35e68657046caf53182c8289c62e524eb49b4886117b9db5427de103e30f468403a52ae209a6c59fc9cc62489
+  metadata.gz: 3925cc108c3cedc51d6a37926b4ba937296cfd55137d8af40b9254bb92383cf253713321e95e6cfcfeb50de9adf7acd11777cf108227527d2c87658d74173a51
+  data.tar.gz: 79c345933fd16d7c2acfa24715ef09119c1973c605bb5a7b2caa959fcf08ae748e087338717d6e4343281e68a9a3ed9440d5c74e57846691f7033ef2f41e4079

data/README.md

@@ -1,6 +1,7 @@
 [![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)
+[![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
@@ -8,18 +9,11 @@ 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)
+* [Quick Start](#quick-start)
+* [Grafana integration](#grafana-integration)
+* [Webservice overview](#webservice-overview)
 * [Roadmap](#roadmap)
-* [Contributing](#contributing)
-* [Licensing](#licensing)
-* [Acknowledgements](#acknowledgements)
 * [Donations](#donations)
 
 ## About the project
@@ -28,222 +22,88 @@ 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:
+## Features
 
-    ruby bin/ruby-grafana-reporter myconfig --test default
+* Build PDF reports based on [grafana](https://github.com/grafana/grafana) dashboards
+(other formats supported)
+* Include dynamic content from grafana (see [function documentation](FUNCTION_CALLS.md)
+as a detailed reference):
+  * 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
+* Multi purpose use of the reporter
+  * webservice to be called directly from grafana - it also runs without further
+dependencies in the standard asciidoctor docker container!
+  * standalone command line tool, e.g. to be automated with cron or bash scrips
+* Comes with a complete configuration wizard, including functionality to build a
+demo report on top of the configured grafana host
+* Supports all SQL based datasources, as well as graphite and prometheus
+* 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
 
-Now you may want to check the conversion of your Hello World example:
+## Quick Start
 
-    ruby bin/ruby-grafana-reporter myconfig --template myfirsttemplate.adoc --output myfirstrender.pdf
+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 for that!
 
-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 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.
 
-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!
+**Windows:**
 
-    asciidoctor:
-      image: asciidoctor/docker-asciidoctor
-      container_name: asciidoctor
-      hostname: asciidoctor
-      volumes:
-        - /<<an-empty-local-path>>:/documents
-      command:
-        sh /documents/startup.sh
-      restart: unless-stopped
+* [Download latest Windows executable](https://github.com/divinity666/ruby-grafana-reporter/releases/latest)
+* `ruby-grafana-reporter -w`
 
-Additionally you need to create a `startup.sh` file in the folder
-`<<an-empty-local-path>>` with the following content:
+Known issues:
+* images are currently not included in PDF conversions due to missing support in Prawn gem for windows;
+other target formats do work properly with images
 
-    cd /documents
-    ruby bin/ruby-grafana-reporter myconfig
+**Raspberry Pi:**
 
-After restarting the container, the service should be running.
+* `sudo apt-get install ruby`
+* `gem install ruby-grafana-reporter`
+* `ruby-grafana-reporter -w`
 
-Test your configuration by requesting the following URL in a browser of your
-choice:
+**Ruby environment:**
 
-    http://<<your-server-url>>:8815/render?var-template=myfirsttemplate.adoc
+* `gem install ruby-grafana-reporter`
+* `ruby-grafana-reporter -w`
 
-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 environment** (advanced users):
 
-### Grafana integration
+* [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:
 
-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).
+```
+cd /documents
+ruby bin/ruby-grafana-reporter
+```
+* add asciidoctor your 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
+
+The key feature of the report is, that it can easily be integrated with grafana.
 
 For accessing the reporter from grafana, you need to simply add a link to your
 grafana dashboard:
@@ -253,27 +113,27 @@ grafana dashboard:
 * Select `Add`
 * Fill out as following:
   * Type: `link`
-  * Url: `http://<<your-server-url>>:8815/render?var-template=myfirsttemplate.adoc`
-  * Title: `MyFirstReport`
+  * 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 'MyFirstReport'
+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.
 
-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.
+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.
 
-Additionally you might want to make the selection of the template variable.
+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 'MyFirstReport' link to
-`http://<<your-server-url>>:8815/render?`
-
-That's it. Let me know your feedback!
+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.
 
 ## Webservice overview
 
@@ -284,24 +144,15 @@ Running the reporter as a webservice provides the following URLs
     /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
+The main endpoint to call for report generation is configured in the previous chapter [Grafana integration](#grafana-integration).
 
-* 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
+However, if you would like to see, currently running report generations and previously generated reports, you may want to call the endpoint `/overview`.
 
 ## 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
+* Support all grafana datasources
 * Solve code TODOs
 * Become [rubocop](https://rubocop.org/) ready
 
@@ -310,15 +161,6 @@ This is just a collection of things, I am heading for in future, without a sched
 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.
@@ -336,4 +178,3 @@ 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)
-

data/bin/ruby-grafana-reporter

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

data/lib/VERSION.rb

@@ -1,3 +1,6 @@
-# Version information
-GRAFANA_REPORTER_VERSION = [0, 1, 7].freeze
-GRAFANA_REPORTER_RELEASE_DATE = '2020-10-24'
+# frozen_string_literal: true
+
+# Version information
+GRAFANA_REPORTER_VERSION = [0, 4, 0].freeze
+# Release date
+GRAFANA_REPORTER_RELEASE_DATE = '2021-04-14'

data/lib/grafana/abstract_datasource.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Grafana
+  # This abstract class defines the base functionalities for the common datasource implementations.
+  # Additionally it provides a factory method to build a real datasource from a given specification.
+  class AbstractDatasource
+    attr_reader :model
+
+    # Factory method to build a datasource from a given datasource Hash description.
+    # @param ds_model [Hash] grafana specification of a single datasource
+    # @return [AbstractDatasource] instance of a fitting datasource implementation
+    def self.build_instance(ds_model)
+      raise InvalidDatasourceQueryProvidedError, ds_model unless ds_model.is_a?(Hash)
+      raise InvalidDatasourceQueryProvidedError, ds_model unless ds_model['meta']
+      raise InvalidDatasourceQueryProvidedError, ds_model unless ds_model['meta']['id']
+      raise InvalidDatasourceQueryProvidedError, ds_model unless ds_model['meta']['category']
+
+      return SqlDatasource.new(ds_model) if ds_model['meta']['category'] == 'sql'
+
+      case ds_model['meta']['id']
+      when 'graphite'
+        return GraphiteDatasource.new(ds_model)
+
+      when 'prometheus'
+        return PrometheusDatasource.new(ds_model)
+
+      end
+
+      raise DatasourceTypeNotSupportedError.new(ds_model['name'], ds_model['meta']['id'])
+    end
+
+    def initialize(model)
+      @model = model
+    end
+
+    # @return [String] name of the datasource
+    def name
+      @model['name']
+    end
+
+    # @return [Integer] ID of the datasource
+    def id
+      @model['id'].to_i
+    end
+
+    # @abstract
+    #
+    # Executes a request for the current database with the given options.
+    #
+    # Used format of the response will always be the following:
+    #
+    #   {
+    #     :header => [column_title_1, column_title_2],
+    #     :content => [
+    #                   [row_1_column_1, row_1_column_2],
+    #                   [row_2_column_1, row_2_column_2]
+    #                 ]
+    #   }
+    #
+    # @param query_description [Hash] query description, which will requested:
+    # @option [String] :from +from+ timestamp
+    # @option [String] :to +to+ timestamp
+    # @option [Integer] :timeout expected timeout for the request
+    # @option [WebRequest] :prepared_request prepared web request for relevant {Grafana} instance, if this is needed by datasource
+    # @option [String] :raw_query raw query, which shall be executed. May include variables, which will be replaced before execution
+    # @option [Hash<Variable>] :variables hash of variables, which can potentially be replaced in the given +:raw_query+
+    # @return [Hash] sql result formatted as stated above
+    def request(query_description)
+      raise NotImplementedError
+    end
+
+    # @abstract
+    #
+    # The different datasources supported by grafana use different ways to store the query in the
+    # panel's JSON model. This method extracts a query from that description, that can be used
+    # by the {AbstractDatasource} implementation of the datasource.
+    #
+    # @param panel_query_target [Hash] grafana panel target, which contains the query description
+    # @return [String] query string, which can be used as +raw_query+ in a {#request}
+    def raw_query_from_panel_model(panel_query_target)
+      raise NotImplementedError
+    end
+
+    private
+
+    # Replaces the grafana variables in the given string with their replacement value.
+    #
+    # @param string [String] string in which the variables shall be replaced
+    # @param variables [Hash<String,Variable>] Hash containing the variables, which shall be replaced in the
+    #  given string
+    # @return [String] string in which all variables are properly replaced
+    def replace_variables(string, variables = {})
+      res = string
+      repeat = true
+      repeat_count = 0
+
+      # TODO: find a proper way to replace variables recursively instead of over and over again
+      # TODO: add tests for recursive replacement of variable
+      while repeat && (repeat_count < 3)
+        repeat = false
+        repeat_count += 1
+        variables.each do |var_name, obj|
+          # only set ticks if value is string
+          variable = var_name.gsub(/^var-/, '')
+          res = res.gsub(/(?:\$\{#{variable}(?::(?<format>\w+))?\}|\$#{variable})/) do
+            # TODO: respect datasource requirements for formatting here
+            obj.value_formatted($LAST_MATCH_INFO ? $LAST_MATCH_INFO[:format] : nil)
+          end
+        end
+        repeat = true if res.include?('$')
+      end
+
+      res
+    end
+  end
+end