MIT 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 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.

Documentation

Find the complete API documentation 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 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 ready :-)

Licensing

The code in this project is licensed under MIT license.

Acknowledgements

Inspired by Izak Marai's grafana 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