gregolsky / ravendb-grafana-datasource

RavenDB Data Source Plugin for Grafana

This RavenDB data source plugin allows you to query and visualize your RavenDB data in Grafana.

For monitoring metrics of a RavenDB instance (not its data) use the RavenDB Telegraf plugin.
Please refer to: Monitoring RavenDB Metrics.

In this readme:

• Sample dashboard showing data from RavenDB
• Install the RavenDB data source plugin
• Set RavenDB as your data source - Unsecure server
• Set RavenDB as your data source - Secure server
• Querying Features

Sample dashboard showing data from RavenDB

Install the RavenDB data source plugin

1. Download latest Grafana from here.
2. Download the latest RavenDB data source plugin zip file (ravendb-datasource-1.x.x.zip) from here.
3. Extract the plugin zip file into the following folder in your Grafana working directory:
   $GRAFANA_WORKING_DIR/data/plugins
4. Open your Grafana configuration file, located under the 'conf' folder and apply the following:
   Edit the [Plugins] section - add ravendb-datasource as an unsigned plugin:
   allow_loading_unsigned_plugins = ravendb-datasource
   
5. Run Grafana - the RavenDB plugin will now show in the installed data sources plugins list.
   

Run on Docker now

All you need is docker-compose.yml from this repository. Then inside the directory you downloaded it to run the following command:

$ docker-compose up -d

It is going to start Grafana with RavenDB plugin already installed for you on port 3000 - http://localhost:3000.

Set RavenDB as your data source - Unsecure server

1. Enter a name for this data source settings.
2. Enter the database name from which to retrieve data.
3. Enter your unsecure RavenDB server URL.
4. Click Save & test to test and save this configuration.

Set RavenDB as your data source - Secure server

1. Enter a name for this data source settings.
2. Enter the database name from which to retrieve data.
3. Enter your secure RavenDB server URL.
4. Toggle on TLS Client Auth.
5. Enter the server name.
   The above example refers to a free server instance in RavenDB Cloud.
   Replace it with your own hostname.
6. Enter the certificate Public Key (starts with -----BEGIN CERTIFICATE-----)
   Can be taken from the *.pem file (see below).
7. Enter the certificate Private Key (starts with -----BEGIN RSA PRIVATE KEY-----)
   Can be taken from the *.key file (see below).
8. Click Save & test to test and save this configuration.

How to get the certificate parts

Download the certificate from your product instance on RavenDB Cloud.

Open the downloaded zip file.
The certificate parts needed for the Grafana settings are found under the PEM folder.

• *.client.certificate.crt => the certificate itself
• *.client.certificate.key => contains the private key
• *.client.certificate.pem => contains both private & public key

Querying Features

• RQL
  From Grafana, query your RavenDB collections/indexes with RQL - Raven Query Language

• Visualizations
  The queried data can be presented in any of Grafana's tables & charts visualizations,
  including Table data, Time series data & Spatial data.

• Grafana Variables
  Querying with Grafana variables and templates is supported by the RavenDB plugin.

• Examples
  All query examples bellow are based on RavenDB's sample data.
  A simple collecton query
  Generate values for a Grafana variable
  Reference Grafana variable in a query
  Project query results as Time Series data
  Project query results as Spatial data
  Using Time Macro variables in a time series query
  Querying with Multi-Value variables

A simple collection query

Query for data from the 'Employees' collection:

from 'Employees' select LastName, FirstName, Title, Address

Generate values for a Grafana variable

A RavenDB query can be used to populate a Grafana variable of Type: Query.
Only the first column from the results is used.
Therefore, use a query which returns a single column, e.g. Name here below.
The Name results will populate the Grafana variable values.

from 'Products' select distinct Name 

Reference Grafana variable in a query

Once the Grafana variable is defined, it can be used within the RQL query.
The following RQL queries a RavenDB index, results are filtered using the Product variable.

from index 'Product/Rating'
where Name = "${Product}"
select Rating

Project query results as Time Series data

Alias a Date field (e.g. OrderedAt) with Time.
Grafana will autodetect this as a time column and the results can be viewed in the time series chart.

from 'Orders'
select Freight, OrderedAt as Time

Project query results as Spatial data

Alias a GeoData field (e.g. Address.Location.Latitude) with Latitude/Longitude.
The results can then be viewed in the Geomap Panel.

from 'Suppliers'
where Address.Location != null
select 
   Name,
   Address.Location.Latitude as Latitude,
   Address.Location.Longitude as Longitude

Using Time Macro variables in a time series query

Grafana Variable	Description	Example
$timeFilter	Will be replaced by the date range selected in Grafana's time selector	"2021-11-17T16:56:28.158Z" and "2022-02-17T09:45:12.697Z"
$__interval	Will be replaced by the interval suggested by Grafana (Time range / max data points)	5m, 15s, etc.

from 'Products'
where id() == 'products/77-A'
select timeseries(
   from 'INC:Views'
   between $timeFilter
   group by $__interval
   select sum()
)

Querying with Multi-Value variables

In order to properly use a multi-value variable in your query, format it using doublequote.
The following RQL:

from 'Employees'
where FirstName in (${paramName:doublequote})

Will be translated to:

from 'Employees'
where FirstName in ("Peter", "Anna", "John")

Links

• RavenDB
• RavenDB Demo