Grafana is a popular visualization tool commonly used to analyze time series, logs, and other data.
This tutorial will show how to create a connection between existing Grafana and Couchbase installations using the Grafana Couchbase data source plugin.
The pre-built releases as well as the source code of the plugin can be found at https://github.com/couchbaselabs/grafana-plugin.
Go to release page and download the
couchbase-datasource.zip for the latest release.
On your Grafana server, find the
plugins property in the Grafana configuration file. This property configures the location of the Grafana plugins directory. Refer to the Grafana configuration documentation for more information.
Extract the downloaded
couchbase-datasource directory into the configured Grafana plugins directory.
Make sure that
dist directory from the archive is located at
By default, Grafana does not load unsigned plugins so, we need to set
allow_loading_unsigned_plugins setting in grafana configuration.
To do so, locate Grafana's
custom.ini configuration file, which usually can be found in the
conf sub-directory of grafana working directory, an add
allow_loading_usigned_plugins=couchbase-datasource under the
[plugins] section to "couchbase-datasource":
Alternatively, you can set
GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINSGrafana environment variable to
Restart the Grafana server. To verify that the new instance of Grafana has successfully loaded the plugin, search for a line in the server startup log that looks similar to this one:
grafana | logger=plugin.manager t=2022-05-13T15:54:22.47+0000 lvl=info msg="Plugin registered" pluginId=couchbase-datasource
To configure the plugin, open Grafana in your web browser and go to the "Configuration -> Data sources" section. Click on the "Add data source" button and click on the "Couchbase" data source connector in the plugin list.
Provide the cluster URL, username, and password to connect to a Couchbase server and click the "Save & test" button. The plugin will connect to the cluster during the test and ping its query service. Provided configuration will be stored automatically if the test passes.
Please note that the plugin does not handle security and user privileges. Use Couchbase RBAC to limit which data users can access through the plugin.
The Couchbase data source plugin supports querying the data using the SQL++ query language. Go to the "Explore" section and select "Couchbase" as your data source:
The plugin provides
time_range pseudo-functions that allow applying Grafana time range filters to the resulting query.
These functions take the name of a field with time data as their only argument.
str_time_range is used in the following Grafana query to apply the time range by filtering on an ISO-8601 date field:
SELECT * from `logs` WHERE str_time_range(registration_date)
will be transformed by the plugin to a SQL++ query that looks like this:
SELECT * FROM (
SELECT * FROM `logs` WHERE
STR_TO_MILLIS(registration_time) > STR_TO_MILLIS("2022-10-20 00:00:00") AND STR_TO_MILLIS(registration_time) < STR_TO_MILLIS("2022-10-21 00:00:00")
) AS data ORDER BY str_to_millis(data.registration_time) ASC
For fields that contain dates expressed as Unix timestamps, the
time_range function should be used:
SELECT time, content from `logs` where time_range(registration_timestamp)
Fields that contain dates in other formats need to be transformed into either ISO-8601 or a Unix timestamp before using them in a query:
SELECT STR_TO_MILLIS(date, "RFC850") as time, content FROM `logs` WHERE time_range(time)
Grafana automatically detects what kind of data a query selects and shows it as a value graph or log messages.
The Couchbase data source plugin also supports querying data from the cluster using the analytics service. To do so, activate the "Run using analytics service" toggle on the right side of the screen immediately below the query text field.
As user queries are handled directly on the cluster, all embedded and user defined SQL++ functions can be used as usual, for example:
SELECT SUM(count), date_trunc_str(time, "minute") FROM test WHERE str_time_range(time) GROUP BY date_trunc_str(time, "minute)
Couchbase data source plugin supports all standard Grafana widgets and most of the widgets available in the plugin store.
To create a new dashboard, navigate to "Dashboards -> Browse" and click the "New Dashboard" button, which should open the dashboard editing interface. Select "Add a new panel" to add a panel.
Under the panel preview, select the Couchbase data source and enter your data query. Then, select the desired time interval in the top right corner above the preview. The preview should update automatically.
You can change the type of visualization used to render your data using the drop-down at the top of the right section of the screen:
Grafana Couchbase data source plugin allows users to analyze time series, logging, and other data stored in a Couchbase cluster. Integration with analytics service allows exploring the data without downgrading the cluster's performance. Rich visualization tools that come with Grafana will allow users to extract more insights from their data quickly.