ruby-grafana-reporter 0.2.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3ffea90aebd213a65781274b5825d3f47d2a68e804821dd4a887ebdaebd67ae
-  data.tar.gz: 931c47a54cebe300a6f0b3e3dffb470ac6ce6f4faddc8558e90bd18d4273b1d5
+  metadata.gz: 799071f1a4ed0795aeb9dbdc7fe175d3e023f4d0de3844f0ae57e85343ab47b4
+  data.tar.gz: 6524d4a07cd49c6622d69507e0ee6c3a37c18c358f8a3dc63b56848255c38e4c
 SHA512:
-  metadata.gz: d0c187b97ec27c6ac374069d9253215d78c2b04d6e8ff10cc1bd660486d0f998c742cfd65a4d415cdb2b8045fed1c6800ccf2c64cbe21fc530b82527b4183f69
-  data.tar.gz: b7b22e087b05c9c1bb6c0c92526755c1883ac9a57ca53c64e809de18e213421a2c65329618a42a75aa80b2ebdc0a38f48b28ac15eb2b9dd02c7c2250c838953c
+  metadata.gz: f52466eb19bc813271c4f67818414f578750f2a7d9254244cb5213be47ffa50e8a1849788935211391b606cc944a84b9bef6b46aec583185bbe94958d2e080a5
+  data.tar.gz: 4eae953b1ad50b9d188d66f3f7bf0c9c6184ff3009da077f2ed07c0d082d7b3d7be75c362143033b27b8256482886e797c78ab750bdde5a85cf198ea8b4fe540

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,14 +9,11 @@ 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)
+* [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
@@ -24,55 +22,93 @@ 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
+## Features
 
-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).
+* Build reports based on [grafana](https://github.com/grafana/grafana) dashboards, PDF
+(default) and many other formats supported
+* Easy-to-use configuration wizard, including fully automated functionality to create a
+demo report
+* 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
+* Multi purpose use of the reporter
+  * webservice to be called directly from grafana
+  * standalone command line tool, e.g. to be automated with `cron` or `bash` scrips
+  * seemlessly runs from asciidocotor docker container without further dependencies
+* Webhook callbacks before, on cancel and on finishing callbacks (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
+
+Functionalities are provided as shown here:
+
+Database | Image rendering | Panel-based rendering | Query-based rendering
+------------------------- | :-------: | :-----------: | :------------:
+all SQL based datasources | supported | supported     | supported
+Graphite                  | supported | supported     | supported
+Prometheus                | supported | supported     | supported
+other datasources         | supported | not-supported | not-supported
+
+## Quick Start
+
+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 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:
@@ -82,27 +118,27 @@ grafana dashboard:
 * Select `Add`
 * Fill out as following:
   * Type: `link`
-  * Url: `http://<<your-server-url>>:<<your-webservice-port>>/render?var-template=myfirsttemplate`
-  * 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>>:<<your-webservice-port>>/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
 
@@ -113,23 +149,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 a simple plugin system to support specific asciidoctor modifications
+* Support all grafana datasources
 * Solve code TODOs
 * Become [rubocop](https://rubocop.org/) ready
 
@@ -138,14 +166,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
-
 ## Licensing
 
 The code in this project is licensed under MIT license.
@@ -160,7 +180,6 @@ Inspired by [Izak Marai's grafana reporter](https://github.com/IzakMarais/report
 ## 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 :)
+support my work, feel free 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)
+#!/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,5 +1,6 @@
 # frozen_string_literal: true
 
 # Version information
-GRAFANA_REPORTER_VERSION = [0, 2, 0].freeze
-GRAFANA_REPORTER_RELEASE_DATE = '2020-11-30'
+GRAFANA_REPORTER_VERSION = [0, 4, 1].freeze
+# Release date
+GRAFANA_REPORTER_RELEASE_DATE = '2021-05-17'

data/lib/grafana/abstract_datasource.rb

@@ -0,0 +1,136 @@
+# 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
+
+    @@subclasses = []
+
+    # Registers the subclass as datasource, which is asked by {#accepts?}, if it can handle a datasource
+    # model.
+    # @param subclass [Class] class inheriting from this abstract class
+    def self.inherited(subclass)
+      @@subclasses << subclass
+    end
+
+    # Overwrite this method, to specify if the current datasource implementation handles the given model.
+    # This method is called by {#build_instance} to determine, if the current datasource implementation
+    # can handle the given grafana model. By default this method returns false.
+    # @param model [Hash] grafana specification of the datasource to check
+    # @return [Boolean] True if fits, false otherwise
+    def self.handles?(_model)
+      false
+    end
+
+    # 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'].is_a?(Hash)
+
+      @@subclasses.each do |datasource_class|
+        return datasource_class.new(ds_model) if datasource_class.handles?(ds_model)
+      end
+
+      UnsupportedDatasource.new(ds_model)
+    end
+
+    def initialize(model)
+      @model = model
+    end
+
+    # @return [String] category of the datasource, e.g. `tsdb` or `sql`
+    def category
+      @model['meta']['category']
+    end
+
+    # @return [String] type of the datasource, e.g. `mysql`
+    def type
+      @model['type'] || @model['meta']['id']
+    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

data/lib/grafana/dashboard.rb

@@ -13,8 +13,8 @@ module Grafana
       @grafana = grafana
       @model = model
 
-      initialize_panels
-      initialize_variables
+      init_panels
+      init_variables
     end
 
     # @return [String] +from+ time configured in the dashboard.
@@ -42,35 +42,33 @@ module Grafana
 
       panels.first
     end
-  end
 
-  private
+    private
 
-  # store variables in array as objects of type Variable
-  def initialize_variables
-    @variables = []
-    return unless @model.key?('templating')
+    # store variables in array as objects of type Variable
+    def init_variables
+      @variables = []
+      return unless @model.key?('templating')
 
-    list = @model['templating']['list']
-    return unless list.is_a? Array
+      list = @model['templating']['list']
+      return unless list.is_a? Array
 
-    list.each do |item|
-      @variables << Variable.new(item)
+      list.each { |item| @variables << Variable.new(item) }
     end
-  end
 
-  # read panels
-  def initialize_panels
-    @panels = []
-    return unless @model.key?('panels')
+    # read panels
+    def init_panels
+      @panels = []
+      return unless @model.key?('panels')
 
-    @model['panels'].each do |panel|
-      if panel.key?('panels')
-        panel['panels'].each do |subpanel|
-          @panels << Panel.new(subpanel, self)
+      @model['panels'].each do |panel|
+        if panel.key?('panels')
+          panel['panels'].each do |subpanel|
+            @panels << Panel.new(subpanel, self)
+          end
+        else
+          @panels << Panel.new(panel, self)
         end
-      else
-        @panels << Panel.new(panel, self)
       end
     end
   end