Plugins 〉SurrealDB
SurrealDB
Surrealdb
This Grafana data source plugin provides the ability to connect, query, and visualize SurrealDB stored information.
Requirements
Besides the already installed and setup Grafana service -- for minimal version see plugin dependencies -- the following requirements must be met in order to use this plugin:
a deployed SurrealDB instance which is accessible through the network of your the Grafana service where this plugin will be installed
an existing SurrealDB namespace
an existing SurrealDB database
an optional existing SurrealDB scope
an existing SurrealDB user which has access to the namespace, database, and optionally the scope -- recommendation is to use a SurrealDB user which has the
VIEWER
role in order to perform exclusively read-only operations and do not alter any database state to maintain the data integrity
Since the plugin is used to query the contents of one or multiple SurrealDB tables, the existence of the tables in question is not required per default, because the plugin can be installed without an existing table and e.g. query and visualize database information as well.
Installation
The plugin can be installed through the user interface in the Grafana service itself or by using the command-line utility via:
$ grafana cli plugins install fiskaly-surrealdb-datasource
If the Grafana service was setup in a containerized context via e.g. docker-compose
or started locally on a machine the plugin can be installed automatically for the Grafana instance during start-up by setting the following environment variable:
GF_INSTALL_PLUGINS="fiskaly-surrealdb-datasource"
Configuration
Following the data source management documentation and selecting this plugin in the add new data source connection page, the configuration of this plugin requires the following parameters to be setup:
Location
of the WebSocket connection in form of aaddress:port
schema (required, default value:localhost:8000
)Namespace
to use (required, default value:default
)Database
to use (required, default value:default
)Scope
to use (optional)Username
for the user to interact with the SurrealDB instance (required, default value:root
)Password
of the provided user to perform the authentication (required, default value:root
)
Usage
The plugin defines three query modes: Raw
, Log
, and Metric
For all modes the actual query is written in SurrealQL.
Therefore, the Raw
mode is representing the query results in a table view as preferred visualization type.
The Log
mode changes the preferred visualization type to log-based view and allows to define/set the log Time
and optional log Message
column information.
For time series value-based visualizations, the plugin provides a Metric
mode to represent the query results in a graph view as preferred visualization type.
This mode allows to further configure/set the actual Data
column to visualize the time series.
Furthermore, based on the Data
column there is an option to perform data grouping of a given Field
as well as to perform different Rate
computations in a given Interval
.
Variable Query
This plugin provides raw
query support for dashboard variables.
The values of the first column in the query response are used for the result set of values for the defined variable in the dashboard.
Design
The plugin consists of a frontend and a backend part.
The frontend is written in TypeScript and provides two major components:
(1) a ConfigEditor
to setup and connect to a SurrealDB instance; and
(2) a QueryEditor
to write queries in SurrealDB Query Language (SurrealQL), configure the query mode, and interact with the backend part of the data source plugin.
The backend is written in Golang and provides a low-level connection through the SurrealDB WebSocket interface. After the successful connection and signin operation, all queries sent from the frontend part to the backend part are directly executed through the WebSocket connection using the custom query operation.
Since SurrealDB as well as Grafana support variables the plugin supports and performs the following variable resolving steps: (1) in the frontend part are all Grafana scope provided variables replaced; and (2) in the backend part defines the following plugin specific variables and replaces those before the query is send and executed on the SurrealDB instance:
$interval
defined by the current query editor context$now
current timestamp in UTC taken at the beginning of the query execution$from
starting time as UTC timestamp of the current query editor context$to
ending time as UTC timestamp of the current query editor context
Grafana Cloud Free
- Free tier: Limited to 3 users
- Paid plans: $55 / user / month above included usage
- Access to all Enterprise Plugins
- Fully managed service (not available to self-manage)
Self-hosted Grafana Enterprise
- Access to all Enterprise plugins
- All Grafana Enterprise features
- Self-manage on your own infrastructure
Grafana Cloud Free
- Free tier: Limited to 3 users
- Paid plans: $55 / user / month above included usage
- Access to all Enterprise Plugins
- Fully managed service (not available to self-manage)
Self-hosted Grafana Enterprise
- Access to all Enterprise plugins
- All Grafana Enterprise features
- Self-manage on your own infrastructure
Grafana Cloud Free
- Free tier: Limited to 3 users
- Paid plans: $55 / user / month above included usage
- Access to all Enterprise Plugins
- Fully managed service (not available to self-manage)
Self-hosted Grafana Enterprise
- Access to all Enterprise plugins
- All Grafana Enterprise features
- Self-manage on your own infrastructure
Grafana Cloud Free
- Free tier: Limited to 3 users
- Paid plans: $55 / user / month above included usage
- Access to all Enterprise Plugins
- Fully managed service (not available to self-manage)
Self-hosted Grafana Enterprise
- Access to all Enterprise plugins
- All Grafana Enterprise features
- Self-manage on your own infrastructure
Grafana Cloud Free
- Free tier: Limited to 3 users
- Paid plans: $55 / user / month above included usage
- Access to all Enterprise Plugins
- Fully managed service (not available to self-manage)
Self-hosted Grafana Enterprise
- Access to all Enterprise plugins
- All Grafana Enterprise features
- Self-manage on your own infrastructure
Installing SurrealDB on Grafana Cloud:
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
For more information, visit the docs on plugin installation.
Installing on a local Grafana:
For local instances, plugins are installed and updated via a simple CLI command. Plugins are not updated automatically, however you will be notified when updates are available right within your Grafana.
1. Install the Data Source
Use the grafana-cli tool to install SurrealDB from the commandline:
grafana-cli plugins install
The plugin will be installed into your grafana plugins directory; the default is /var/lib/grafana/plugins. More information on the cli tool.
Alternatively, you can manually download the .zip file for your architecture below and unpack it into your grafana plugins directory.
Alternatively, you can manually download the .zip file and unpack it into your grafana plugins directory.
2. Configure the Data Source
Accessed from the Grafana main menu, newly installed data sources can be added immediately within the Data Sources section.
Next, click the Add data source button in the upper right. The data source will be available for selection in the Type select box.
To see a list of installed data sources, click the Plugins item in the main menu. Both core data sources and installed data sources will appear.
Changelog
0.3.0
Provided dashboard variable-based query support.
0.2.0
Provided new groupBy
functionality in metric
query mode in order to perform data grouping for plain metric
values as well as rate
based functions.
Updated plugin documentation and screenshots.
0.1.2
Enabled Grafana policy token for signing the data source plugin in order to be published in the Grafana plugin catalog.
0.1.1
Added additional optional scope
for data source configuration.
Provided the data source plugin handling to respect the hide
query option.
Improved internal stability of the plugin backend.
0.1.0
Initial release.
Provides basic data source connection to a SurrealDB instance through the configuration of location
, namespace
, database
, username
, and password
.
The query editor provides a raw
, log
, and metric
mode.