ruby-grafana-reporter 0.1.6 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ed0c1b79ce0e155cc974eaa86c09221e106376660515903765cb9e78e9c00f1
-  data.tar.gz: 5e6fb779aa14cfbcc75f4f6916b24013fdcb036bf1a9fb46f844bbf0eaa99771
+  metadata.gz: '00728deba4250ed327170393bbeaac1b1d6d1002463a5a243285ac570f09231f'
+  data.tar.gz: 2985a11f6404e622ff279dbe3e328b38e4202bf665b2fef9e23746bbfd6c3459
 SHA512:
-  metadata.gz: caac9139284da4855b6ca4686b4283129ca455ad0ad3b68b0e06c0232e48facacd4e813efe0960cb277f1d8d8ce64e30209af04fd6ab7eadac778a973c0192a3
-  data.tar.gz: b738db7b1bc73c95369682c977e7db4757920539ec07ba386f7b91af7ea3321403f759a75ad4041c3bd94756eea2c1e70bc24759e9a9ee72fcec871958c3d85f
+  metadata.gz: 92de552918a451f9bac1196dfbb05dc1ad64e0059f4c90fe06c079e5e181fee96a07858ae0c5815e3dbf37358c4aa271fcd8d129bb6721f3c8a53f285325fc25
+  data.tar.gz: aff95df6e4b5a8636905ec498433d1fcdae6d7b9aa2d26640815a68160c2f74c39078adfbe32a67c9115855ddd97683c6844ea0347e18cf010586e2bd036faed

data/README.md

@@ -1,234 +1,155 @@
-[![MIT License](https://img.shields.io/github/license/divinity666/ruby-grafana-reporter.svg?style=flat-square)](https://github.com/divinity666/ruby-grafana-reporter/blob/main/LICENSE)
+[![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
-(Asciidoctor) Reporter Service for Grafana
+Reporting Service for Grafana
 
-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 a full extension setup for the famous
-[Asciidoctor](https://github.com/asciidoctor/asciidoctor) and can perfectly
-integrate in a docker environment.
-
-As a result of the reporter, you receive PDF documents or any other format that
-is supported by [Asciidoctor](https://github.com/asciidoctor/asciidoctor).
-
-## Documentation
-
-Find the complete
-[API documentation](https://rubydoc.info/github/divinity666/ruby-grafana-reporter)
-at this link.
-
-## Installing
-
-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
+## Table of Contents
 
-Download the ruby grafana reporter to a folder of your choice.
+* [About the project](#about-the-project)
+* [Getting started](#getting-started)
+  * [Grafana integration](#grafana-integration)
+  * [Webservice overview](#webservice-overview)
+* [Documentation](#documentation)
+* [Features](#features)
+* [Roadmap](#roadmap)
+* [Contributing](#contributing)
+* [Licensing](#licensing)
+* [Acknowledgements](#acknowledgements)
+* [Donations](#donations)
 
-You may want to use the single file application as well. BTW, you may build
-your own single file application by calling
+## About the project
 
-    ruby bin/get_single_file_application.rb
-
-### Barebone ruby installation
-
-To install on a plain ruby installation, follow these steps:
+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.
 
-Install asciidoctor
+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.
 
-    gem install asciidoctor asciidoctor-pdf zip
+The report may also be returned in any other format that asciidoctor supports.
 
-or simply use
+The reporter can run standalone or as a webservice. It is built to
+integrate without further dependencies with the asciidoctor docker image.
 
-    bundle install
+Can't wait to see, what functions the reporter provides within the asciidoctor
+templates? Have a look at the [function documentation](FUNCTION_CALLS.md).
 
-To check if all dependencies are setup properly, run the following command
-in that folder:
+## Getting started
 
-    ruby bin/ruby-grafana-reporter.rb -h
+There exist several ways of installing the reporter. 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).
 
-### GEM installation
+Windows users may directly use the provided executable.
 
-To install as a gem, simply run:
+Following these steps sets up the reporter on a fresh Raspberry Pi installation:
 
+    sudo apt-get install ruby
     gem install ruby-grafana-reporter
 
-To see if it works properly, you may run:
-
-    irb
-    require 'ruby-grafana-reporter'
-    GrafanaReporter::Application::Application.new.configure_and_run
-
-The gem installation might mainly be interesting, if you would like to use the
-reporter as a library and include it in other application setups.
-
-### Docker integration
-
-Essentially you need to make the application available within your asciidoctor
-docker container and run the following command
-
-    ruby bin/ruby-grafana-reporter.rb -h
-
-If you are unsure, on how to make it available in the container, you may refer
-to the information in chapter 'Run as a service' for the docker integration
-below.
+That's it. Let's now configure a grafana setup with the configuration wizard:
 
-## Initial Configuration
+    ruby-grafana-reporter -w
 
-Create a first configuration file, named e.g. `myconfig` with the following
-content:
+It is strongly recommended, to also create the demo PDF file, as stated at the end
+of the procedure, to get a detailed documentation of all the reporter capabilities.
+The whole [function documentation](FUNCTION_CALLS.md) is also available at the
+previous link.
 
-    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: .
+To run the reporter as a service, you only need to call it like this:
 
-Check out if the configuration is valid and your grafana instance can be accessed
-properly.
+    ruby-grafana-reporter
 
-### Barebone ruby installation
+Neat, isn't it?
 
-    ruby bin/ruby-grafana-reporter.rb myconfig --test default
+### Grafana integration
 
-### GEM installation
+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).
 
-    require 'ruby-grafana-reporter'
-    GrafanaReporter::Application::Application.new.configure_and_run(["myconfig", "--test", "default"])
+For accessing the reporter from grafana, you need to simply add a link to your
+grafana dashboard:
 
-### Docker integration
+* 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`
 
-Same as in barebone ruby installation. Make sure you are running the command
-from inside the container, e.g. by using `docker exec`.
+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.
 
-## Hello World example
+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.
 
-Create a first asciidoctor template file in your `templates-folder`, e.g.
-`myfirsttemplate.adoc` with the following content:
+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?`
 
-    = First Ruby Grafana Reporter Example
-    
-    include::grafana_help[]
+That's it. Let me know your feedback!
 
-    include::grafana_environment[]
-
-Now you're ready to go! Let's check it out!
-
-### Barebone ruby installation
-
-    ruby bin/ruby-grafana-reporter.rb 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.
-
-### GEM installation
-
-    require 'ruby-grafana-reporter'
-    GrafanaReporter::Application::Application.new.configure_and_run(["myconfig", "--template", "myfirsttemplate.adoc", "--output", "myfirstrender.pdf"])
-
-### Docker integration
-
-Same as in barebone ruby installation. Make sure you are running the command
-from inside the container, e.g. by using `docker exec`.
-
-## Run as a service
+## Webservice overview
 
 Running the reporter as a webservice provides the following URLs
 
-    /render - for rendering a template
     /overview - for all running or retained renderings
-    /view_report - for viewing the status or receving the result of a specific rendering
-    /cancel_report - for cancelling the rendering of a specific report
-
-### Barebone ruby installation
-
-    ruby bin/ruby-grafana-reporter.rb myconfig
+    /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
 
-Test your configuration by requesting the following URL in a browser of your
-choice:
+The main endpoint to call for report generation is configured in the previous chapter [Grafana integration](#grafana-integration).
 
-    http://<<your-server-url>>:8815/render?var-template=myfirsttemplate.adoc
+However, if you would like to see, currently running report generations and previously generated reports, you may want to call the endpoint `/overview`.
 
-### GEM installation
-
-    require 'ruby-grafana-reporter'
-    GrafanaReporter::Application::Application.new.configure_and_run(["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
-
-### Docker integration
-
-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
-      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.rb myconfig
-
-After restarting the container, the service should be running.
+## Documentation
 
-Test your configuration by requesting the following URL in a browser of your
-choice:
+The [function documentation](FUNCTION_CALLS.md) contains a complete overview of
+all possible grafana calls, to generate dynamic report templates.
 
-    http://<<your-server-url>>:8815/render?var-template=myfirsttemplate.adoc
+The [API documentation](https://rubydoc.info/gems/ruby-grafana-reporter) can be
+found here.
 
 ## Features
 
-* Integrate grafana panel images, grafana panel query results as table or single values,
-custom SQL query results as tables, alers, annotations and many more
-* Solid as a rock, also in case of template errors (at least it aims to be)
-* Runs standalone or as a webservice
+* 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 and whatever else may happen
+* Fully controllable as command line application or as a webservice
 * Seamlessly integrates with asciidoctor docker container
-* Developed for being able to support other tools than asciidoctor as well
+* Developed 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 for configuration file
-* Share (anonymized) rspec tests in this repo
 * Add a simple plugin system to support specific asciidoctor modifications
 * Solve code TODOs
 * Become [rubocop](https://rubocop.org/) ready
+* Clean and properly setup test cases
 
 ## 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 :-)
-
 ## Licensing
 
 The code in this project is licensed under MIT license.
@@ -236,6 +157,7 @@ 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)
 

data/bin/ruby-grafana-reporter

@@ -0,0 +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)

data/lib/VERSION.rb

@@ -1,3 +1,5 @@
-# Version information
-GRAFANA_REPORTER_VERSION = [0, 1, 6].freeze
-GRAFANA_REPORTER_RELEASE_DATE = '2020-10-19'
+# frozen_string_literal: true
+
+# Version information
+GRAFANA_REPORTER_VERSION = [0, 3, 0].freeze
+GRAFANA_REPORTER_RELEASE_DATE = '2021-03-02'

data/lib/grafana/abstract_panel_query.rb

@@ -1,20 +1,22 @@
-require_relative 'abstract_query'
-
-module Grafana
-  # @abstract
-  #
-  # Used as a superclass for all queries, which rely on a {Panel} object.
-  #
-  # @see AbstractQuery
-  class AbstractPanelQuery < AbstractQuery
-    attr_reader :panel
-
-    # Initializes the variables of the query using {AbstractQuery#extract_dashboard_variables}.
-    # @param panel [Panel] panel for which the query shall be executed
-    def initialize(panel)
-      super()
-      @panel = panel
-      extract_dashboard_variables(@panel.dashboard)
-    end
-  end
-end
+# frozen_string_literal: true
+
+require_relative 'abstract_query'
+
+module Grafana
+  # @abstract
+  #
+  # Used as a superclass for all queries, which rely on a {Panel} object.
+  #
+  # @see AbstractQuery
+  class AbstractPanelQuery < AbstractQuery
+    attr_reader :panel
+
+    # Initializes the variables of the query using {AbstractQuery#extract_dashboard_variables}.
+    # @param panel [Panel] panel for which the query shall be executed
+    def initialize(panel)
+      super()
+      @panel = panel
+      extract_dashboard_variables(@panel.dashboard)
+    end
+  end
+end

data/lib/grafana/abstract_query.rb

@@ -1,127 +1,132 @@
-module Grafana
-  # @abstract Override {#url}, #{#request}, {#pre_process} and {#post_process} in subclass.
-  #
-  # Superclass containing everything for all queries towards grafana.
-  class AbstractQuery
-    attr_accessor :from, :to, :timeout, :result
-    attr_reader :variables
-
-    def initialize
-      @variables = {}
-    end
-
-    # Runs the whole process to receive values properly from this query:
-    # - calls {#pre_process}
-    # - executes this query against the given {Grafana} instance
-    # - calls {#post_process}
-    # - returns the result
-    #
-    # @param grafana [Grafana] {Grafana} object, against which the query is executed
-    # @return [Object] result of the query
-    def execute(grafana)
-      return @result unless @result.nil?
-
-      pre_process(grafana)
-      @result = grafana.execute_http_request(url, request, timeout)
-      post_process
-      @result
-    end
-
-    # Used to retrieve default configurations from the given {Dashboard} and store them as settings in the query.
-    #
-    # Following data is extracted:
-    # - +from+, by {Dashboard#from_time}
-    # - +to+, by {Dashboard#to_time}
-    # - and all variables as {Variable}, prefixed with +var-+, as grafana also does it
-    def extract_dashboard_variables(dashboard)
-      @from = dashboard.from_time
-      @to = dashboard.to_time
-      dashboard.variables.each { |item| merge_variables({ "var-#{item.name}": item }) }
-      self
-    end
-
-    # Merges the given Hash with the stored variables.
-    #
-    # Can be used to easily set many values at once in the local variables hash.
-    #
-    # Please note, that the values of the Hash need to be of type {Variable}.
-    #
-    # @param hash [Hash<String,Variable>] Hash containing variable name as key and {Variable} as value
-    # @return [AbstractQuery] this object
-    def merge_variables(hash)
-      hash.each do |k, v|
-        if @variables[k.to_s].nil?
-          @variables[k.to_s] = v
-        else
-          @variables[k.to_s].raw_value = v.raw_value
-        end
-      end
-      self
-    end
-
-    # @return [Hash<String, Variable>] all grafana variables stored in this query, i.e. the variable name is prefixed with +var-+
-    def grafana_variables
-      @variables.select { |k, _v| k =~ /^var-.+/ }
-    end
-
-    # 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 and 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
-            obj.value_formatted($~[:format])
-          end
-        end
-        repeat = true if res.include?('$')
-      end
-
-      res
-    end
-
-    # @abstract
-    #
-    # @return [String] String containing the relative URL to execute the query
-    def uri
-      raise NotImplementedError
-    end
-
-    # @abstract
-    #
-    # @return [Hash] Hash containing the request parameters, which shall be overwritten or extended in {Grafana#execute_http_request}
-    def request
-      raise NotImplementedError
-    end
-
-    # @abstract
-    #
-    # Use this function to perform all necessary actions, before the query is actually executed.
-    # Here you can e.g. set values of variables or similar.
-    #
-    # @param grafana [Grafana] {Grafana} object, against which the query shall be executed
-    def pre_process(grafana)
-      raise NotImplementedError
-    end
-
-    # @abstract
-    #
-    # Use this function to format the raw result of the @result variable to conform to the expected return value.
-    # You might also want to {#replace_variables} in the @result or similar.
-    def post_process
-      raise NotImplementedError
-    end
-  end
-end
+# frozen_string_literal: true
+
+module Grafana
+  # @abstract Override {#url}, #{#request}, {#pre_process} and {#post_process} in subclass.
+  #
+  # Superclass containing everything for all queries towards grafana.
+  class AbstractQuery
+    attr_accessor :from, :to, :timeout, :result
+    attr_reader :variables
+
+    def initialize
+      @variables = {}
+    end
+
+    # Runs the whole process to receive values properly from this query:
+    # - calls {#pre_process}
+    # - executes this query against the given {Grafana} instance
+    # - calls {#post_process}
+    # - returns the result
+    #
+    # @param grafana [Grafana] {Grafana} object, against which the query is executed
+    # @return [Object] result of the query
+    def execute(grafana)
+      return @result unless @result.nil?
+
+      pre_process(grafana)
+      @result = grafana.execute_http_request(url, request, timeout)
+      post_process
+      @result
+    end
+
+    # Used to retrieve default configurations from the given {Dashboard} and store them as settings in the query.
+    #
+    # Following data is extracted:
+    # - +from+, by {Dashboard#from_time}
+    # - +to+, by {Dashboard#to_time}
+    # - and all variables as {Variable}, prefixed with +var-+, as grafana also does it
+    def extract_dashboard_variables(dashboard)
+      @from = dashboard.from_time
+      @to = dashboard.to_time
+      dashboard.variables.each { |item| merge_variables({ "var-#{item.name}": item }) }
+      self
+    end
+
+    # Merges the given Hash with the stored variables.
+    #
+    # Can be used to easily set many values at once in the local variables hash.
+    #
+    # Please note, that the values of the Hash need to be of type {Variable}.
+    #
+    # @param hash [Hash<String,Variable>] Hash containing variable name as key and {Variable} as value
+    # @return [AbstractQuery] this object
+    def merge_variables(hash)
+      hash.each do |k, v|
+        if @variables[k.to_s].nil?
+          @variables[k.to_s] = v
+        else
+          @variables[k.to_s].raw_value = v.raw_value
+        end
+      end
+      self
+    end
+
+    # @return [Hash<String, Variable>] all grafana variables stored in this query, i.e. the variable name
+    #  is prefixed with +var-+
+    def grafana_variables
+      @variables.select { |k, _v| k =~ /^var-.+/ }
+    end
+
+    # 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
+            obj.value_formatted($LAST_MATCH_INFO ? $LAST_MATCH_INFO[:format] : nil)
+          end
+        end
+        repeat = true if res.include?('$')
+      end
+
+      res
+    end
+
+    # @abstract
+    #
+    # @return [String] String containing the relative URL to execute the query
+    def uri
+      raise NotImplementedError
+    end
+
+    # @abstract
+    #
+    # @return [Hash] Hash containing the request parameters, which shall be overwritten or extended in
+    #  {Grafana#execute_http_request}
+    def request
+      raise NotImplementedError
+    end
+
+    # @abstract
+    #
+    # Use this function to perform all necessary actions, before the query is actually executed.
+    # Here you can e.g. set values of variables or similar.
+    #
+    # @param grafana [Grafana] {Grafana} object, against which the query shall be executed
+    def pre_process(grafana)
+      raise NotImplementedError
+    end
+
+    # @abstract
+    #
+    # Use this function to format the raw result of the @result variable to conform to the expected return value.
+    # You might also want to {#replace_variables} in the @result or similar.
+    def post_process
+      raise NotImplementedError
+    end
+  end
+end