{"id":13604473,"url":"https://github.com/ravendb/ravendb-grafana-datasource","last_synced_at":"2025-04-09T16:16:14.291Z","repository":{"id":41562295,"uuid":"445438383","full_name":"ravendb/ravendb-grafana-datasource","owner":"ravendb","description":null,"archived":false,"fork":false,"pushed_at":"2025-02-15T15:51:44.000Z","size":2448,"stargazers_count":7,"open_issues_count":8,"forks_count":5,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-09T16:15:58.513Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ravendb.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-01-07T07:40:51.000Z","updated_at":"2023-01-10T21:04:53.000Z","dependencies_parsed_at":"2024-03-18T15:30:54.643Z","dependency_job_id":null,"html_url":"https://github.com/ravendb/ravendb-grafana-datasource","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ravendb%2Fravendb-grafana-datasource","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ravendb%2Fravendb-grafana-datasource/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ravendb%2Fravendb-grafana-datasource/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ravendb%2Fravendb-grafana-datasource/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ravendb","download_url":"https://codeload.github.com/ravendb/ravendb-grafana-datasource/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248065283,"owners_count":21041872,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T19:00:46.352Z","updated_at":"2025-04-09T16:16:14.249Z","avatar_url":"https://github.com/ravendb.png","language":"TypeScript","funding_links":[],"categories":["Visualization"],"sub_categories":[],"readme":"# RavenDB Data Source Plugin for Grafana\n[![Build](https://github.com/ravendb/ravendb-grafana-datasource/workflows/CI/badge.svg)](https://github.com/ravendb/ravendb-grafana-datasource/actions?query=workflow%3A%22CI%22)\n[![Marketplace](https://img.shields.io/badge/dynamic/json?logo=grafana\u0026color=F47A20\u0026label=marketplace\u0026prefix=v\u0026query=%24.items%5B%3F%28%40.slug%20%3D%3D%20%22ravendb-grafana-datasource%22%29%5D.version\u0026url=https%3A%2F%2Fgrafana.com%2Fapi%2Fplugins)](https://github.com/ravendb/ravendb-grafana-datasource)\n[![Downloads](https://img.shields.io/badge/dynamic/json?logo=grafana\u0026color=F47A20\u0026label=downloads\u0026query=%24.items%5B%3F%28%40.slug%20%3D%3D%20%22ravendb-grafana-datasource%22%29%5D.downloads\u0026url=https%3A%2F%2Fgrafana.com%2Fapi%2Fplugins)](https://github.com/ravendb/ravendb-grafana-datasource)\n[![License](https://img.shields.io/github/license/ravendb/ravendb-grafana-datasource)](LICENSE)\n\n**This RavenDB data source plugin allows you to query and visualize your RavenDB data in Grafana**.\n\nFor monitoring metrics of a RavenDB instance (not its data) use the RavenDB Telegraf plugin.  \nPlease refer to: [Monitoring RavenDB Metrics](https://ravendb.net/docs/article-page/latest/http/server/administration/monitoring).\n\n**In this readme**:\n* [Sample dashboard showing data from RavenDB](#sample-dashboard-showing-data-from-ravendb)\n* [Install the RavenDB data source plugin](#install-the-ravendb-data-source-plugin)\n* [Set RavenDB as your data source - Unsecure server](#set-ravendb-as-your-data-source---unsecure-server)\n* [Set RavenDB as your data source - Secure server](#set-ravendb-as-your-data-source---secure-server)\n* [Querying Features](#querying-features)\n\n# Sample dashboard showing data from RavenDB\n\n![Screen](https://github.com/ravendb/ravendb-grafana-datasource/raw/main/src/img/dashboard_screen.png)\n\n# Install the RavenDB data source plugin\n\n1. Download latest Grafana from [here](https://grafana.com/grafana/download).\n2. Download the latest RavenDB data source plugin zip file (**ravendb-datasource-1.x.x.zip**) from [here](https://github.com/ravendb/ravendb-grafana-datasource/releases).\n3. Extract the plugin zip file into the following folder in your Grafana working directory:  \n   `$GRAFANA_WORKING_DIR/data/plugins`\n4. Open your Grafana configuration file, located under the 'conf' folder and apply the following:  \n   Edit the [Plugins] section - add **ravendb-datasource** as an unsigned plugin:  \n   `allow_loading_unsigned_plugins = ravendb-datasource`  \n   ![addUnsignedPlugin](https://github.com/ravendb/ravendb-grafana-datasource/raw/main/src/img/addUnsignedPlugin.png)\n5. Run Grafana - the RavenDB plugin will now show in the installed data sources plugins list.  \n   ![RavenDBPlugin](https://github.com/ravendb/ravendb-grafana-datasource/raw/main/src/img/RavenDBPlugin.png)\n\n# Run on Docker now\n\nAll you need is [docker-compose.yml](docker-compose.yml) from this repository. Then inside the directory you downloaded it to run the following command:\n\n```\n$ docker-compose up -d\n```\n\nIt is going to start Grafana with RavenDB plugin already installed for you on port `3000` - http://localhost:3000.\n\n# Set RavenDB as your data source - Unsecure server\n\n![unsecure settings](https://github.com/ravendb/ravendb-grafana-datasource/raw/main/src/img/unsecureSettings.png)\n\n1. Enter a name for this data source settings.\n2. Enter the database name from which to retrieve data.\n3. Enter your unsecure RavenDB server URL.\n4. Click Save \u0026 test to test and save this configuration.\n\n# Set RavenDB as your data source - Secure server\n\n![secure settings](https://github.com/ravendb/ravendb-grafana-datasource/raw/main/src/img/secureSettings.png)\n\n1. Enter a name for this data source settings.\n2. Enter the database name from which to retrieve data.\n3. Enter your secure RavenDB server URL.\n4. Toggle on TLS Client Auth.\n5. Enter the server name.  \n   The above example refers to a free server instance in RavenDB Cloud.  \n   Replace it with your own hostname.\n6. Enter the certificate Public Key (starts with _-----BEGIN CERTIFICATE-----_)  \n   Can be taken from the *.pem file (see below).  \n7. Enter the certificate Private Key (starts with _-----BEGIN RSA PRIVATE KEY-----_)  \n   Can be taken from the *.key file (see below).\n8. Click Save \u0026 test to test and save this configuration.\n\n### How to get the certificate parts\n\nDownload the certificate from your product instance on [RavenDB Cloud](https://cloud.ravendb.net).  \n\n![download certificate](https://github.com/ravendb/ravendb-grafana-datasource/raw/main/src/img/downloadCert.png)\n\nOpen the downloaded zip file.  \nThe certificate parts needed for the Grafana settings are found under the _PEM_ folder.\n\n![pem folder](https://github.com/ravendb/ravendb-grafana-datasource/raw/main/src/img/pemFolder.png)\n\n* *.client.certificate.crt =\u003e the certificate itself\n* *.client.certificate.key =\u003e contains the private key\n* *.client.certificate.pem =\u003e contains both private \u0026 public key\n\n# Querying Features\n* **RQL**  \n  From Grafana, query your RavenDB collections/indexes with [RQL - Raven Query Language](https://ravendb.net/docs/article-page/latest/csharp/indexes/querying/what-is-rql)\n\n\n* **Visualizations**  \n  The queried data can be presented in any of Grafana's tables \u0026 charts visualizations,   \n  including Table data, Time series data \u0026 Spatial data.\n\n\n* **Grafana Variables**  \n  Querying with Grafana variables and templates is supported by the RavenDB plugin.\n\n\n* **Examples**  \n  All query examples bellow are based on RavenDB's [sample data](https://ravendb.net/docs/article-page/latest/csharp/studio/database/tasks/create-sample-data).  \n  [A simple collecton query](#a-simple-collection-query)  \n  [Generate values for a Grafana variable](#generate-values-for-a-grafana-variable)  \n  [Reference Grafana variable in a query](#reference-grafana-variable-in-a-query)  \n  [Project query results as Time Series data](#project-query-results-as-time-series-data)  \n  [Project query results as Spatial data](#project-query-results-as-spatial-data)  \n  [Using Time Macro variables in a time series query](#using-time-macro-variables-in-a-time-series-query)  \n  [Querying with Multi-Value variables](#querying-with-multi-value-variables)\n\n### A simple collection query\nQuery for data from the 'Employees' collection:\n```\nfrom 'Employees' select LastName, FirstName, Title, Address\n```\n\n### Generate values for a Grafana variable\nA RavenDB query can be used to populate a Grafana variable of Type: Query.  \nOnly the first column from the results is used.  \nTherefore, use a query which returns a single column, e.g. Name here below.  \nThe Name results will populate the Grafana variable values.\n```\nfrom 'Products' select distinct Name \n```\n\n![DefineQueryVariable](https://github.com/ravendb/ravendb-grafana-datasource/raw/main/src/img/defineQueryVariable.png)\n\n### Reference Grafana variable in a query\nOnce the Grafana variable is defined, it can be used within the RQL query.  \nThe following RQL queries a RavenDB index, results are filtered using the `Product` variable.\n```\nfrom index 'Product/Rating'\nwhere Name = \"${Product}\"\nselect Rating\n```\n\n### Project query results as Time Series data\nAlias a Date field (e.g. OrderedAt) with `Time`.  \nGrafana will autodetect this as a time column and the results can be viewed in the time series chart.\n```\nfrom 'Orders'\nselect Freight, OrderedAt as Time\n```\n\n### Project query results as Spatial data\nAlias a GeoData field (e.g. Address.Location.Latitude) with `Latitude`/`Longitude`.  \nThe results can then be viewed in the Geomap Panel.\n```\nfrom 'Suppliers'\nwhere Address.Location != null\nselect \n   Name,\n   Address.Location.Latitude as Latitude,\n   Address.Location.Longitude as Longitude\n```\n\n![Geospatial query result](https://github.com/ravendb/ravendb-grafana-datasource/raw/main/src/img/geospatial.png)\n\n### Using Time Macro variables in a time series query\n| Grafana Variable | Description                                                                          | Example                                                   |\n|------------------|--------------------------------------------------------------------------------------|-----------------------------------------------------------|\n| `$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\" |\n| `$__interval`    | Will be replaced by the interval suggested by Grafana (Time range / max data points) | 5m, 15s, etc.                                             |\n```\nfrom 'Products'\nwhere id() == 'products/77-A'\nselect timeseries(\n   from 'INC:Views'\n   between $timeFilter\n   group by $__interval\n   select sum()\n)\n```\n\n### Querying with Multi-Value variables\nIn order to properly use a multi-value variable in your query, format it using `doublequote`.  \nThe following RQL:\n```\nfrom 'Employees'\nwhere FirstName in (${paramName:doublequote})\n```\nWill be translated to:\n```\nfrom 'Employees'\nwhere FirstName in (\"Peter\", \"Anna\", \"John\")\n```\n\n# Links\n- [RavenDB](https://ravendb.net)\n- [RavenDB Demo](https://demo.ravendb.net/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fravendb%2Fravendb-grafana-datasource","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fravendb%2Fravendb-grafana-datasource","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fravendb%2Fravendb-grafana-datasource/lists"}