ruby-grafana-reporter 0.1.6

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1ed0c1b79ce0e155cc974eaa86c09221e106376660515903765cb9e78e9c00f1
+  data.tar.gz: 5e6fb779aa14cfbcc75f4f6916b24013fdcb036bf1a9fb46f844bbf0eaa99771
+SHA512:
+  metadata.gz: caac9139284da4855b6ca4686b4283129ca455ad0ad3b68b0e06c0232e48facacd4e813efe0960cb277f1d8d8ce64e30209af04fd6ab7eadac778a973c0192a3
+  data.tar.gz: b738db7b1bc73c95369682c977e7db4757920539ec07ba386f7b91af7ea3321403f759a75ad4041c3bd94756eea2c1e70bc24759e9a9ee72fcec871958c3d85f

data/LICENSE

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

data/README.md

@@ -0,0 +1,248 @@
+[![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)
+
+# Ruby Grafana Reporter
+(Asciidoctor) Reporter 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
+
+Download the ruby grafana reporter to a folder of your choice.
+
+You may want to use the single file application as well. BTW, you may build
+your own single file application by calling
+
+    ruby bin/get_single_file_application.rb
+
+### Barebone ruby installation
+
+To install on a plain ruby installation, follow these steps:
+
+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.rb -h
+
+### GEM installation
+
+To install as a gem, simply run:
+
+    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.
+
+## Initial Configuration
+
+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: .
+
+Check out if the configuration is valid and your grafana instance can be accessed
+properly.
+
+### Barebone ruby installation
+
+    ruby bin/ruby-grafana-reporter.rb myconfig --test default
+
+### GEM installation
+
+    require 'ruby-grafana-reporter'
+    GrafanaReporter::Application::Application.new.configure_and_run(["myconfig", "--test", "default"])
+
+### 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`.
+
+## Hello World example
+
+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!
+
+### 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
+
+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
+
+Test your configuration by requesting the following URL in a browser of your
+choice:
+
+    http://<<your-server-url>>:8815/render?var-template=myfirsttemplate.adoc
+
+### 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.
+
+Test your configuration by requesting the following URL in a browser of your
+choice:
+
+    http://<<your-server-url>>:8815/render?var-template=myfirsttemplate.adoc
+
+## 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
+* 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 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
+
+## 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.
+
+## Acknowledgements
+* [asciidoctor](https://github.com/asciidoctor/asciidoctor)
+* [asciidoctor-pdf](https://github.com/asciidoctor/asciidoctor-pdf)
+
+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)
+

data/lib/VERSION.rb

@@ -0,0 +1,3 @@
+# Version information
+GRAFANA_REPORTER_VERSION = [0, 1, 6].freeze
+GRAFANA_REPORTER_RELEASE_DATE = '2020-10-19'

data/lib/grafana/abstract_panel_query.rb

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

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

data/lib/grafana/abstract_sql_query.rb

@@ -0,0 +1,42 @@
+module Grafana
+  # @abstract
+  #
+  # Used as a superclass for all queries, which execute SQL queries against {Grafana}.
+  #
+  # @see AbstractQuery
+  class AbstractSqlQuery < AbstractQuery
+    attr_reader :sql, :datasource_id
+
+    # @param raw_sql [String] raw sql statement, as it can be sent to a SQL database
+    # @param datasource_id [Integer] ID of the datasource against which the query is run
+    def initialize(raw_sql, datasource_id)
+      super()
+      @sql = raw_sql
+      @datasource_id = datasource_id
+    end
+
+    # @return [String] relative URL, where the request has to be sent to.
+    def url
+      '/api/tsdb/query'
+    end
+
+    # @return [Hash] request, which executes the SQL statement against the specified datasource
+    def request
+      { body: { from: @from, to: @to, queries: [rawSql: @sql, datasourceId: @datasource_id.to_i, format: 'table'] }.to_json, request: Net::HTTP::Post }
+    end
+
+    # Replaces all variables in the SQL statement.
+    def pre_process(grafana)
+      raise MissingSqlQueryError if @sql.nil?
+      unless grafana.datasource_id_exists?(@datasource_id.to_i)
+        raise DatasourceDoesNotExistError.new('id', @datasource_id)
+      end
+
+      @sql = replace_variables(@sql, grafana_variables)
+      # remove comments in query
+      @sql.gsub!(/--[^\r\n]*(?:[\r\n]+|$)/, ' ')
+      @sql.gsub!(/\r\n/, ' ')
+      @sql.gsub!(/\n/, ' ')
+    end
+  end
+end