User Guide
To have the datasource running, you need Grafana installed and operational. If you have no prior experience with grafana, please refer to the grafana getting started guide.
As the datasource's purpose is to visualize Cassandra's data using Grafana, some basic understanding of Grafana and Cassandra is recommended but not required.
Keep your data safe! We strongly recommend creating a dedicated user in Cassandra when working with Grafana. This user should have read-only permissions, and should only be applied to the tables you explicitly want Grafana to access. If you need some help with that, check this documentation for RBAC (role-based access control).
Use the grafana-cli tool to install Apache Cassandra from the command line. The plugin will be installed into your grafana plugins directory; the default is /var/lib/grafana/plugins.
grafana-cli plugins install hadesarchitect-cassandra-datasource
Alternatively, you can manually download the .zip file and unpack it into your grafana plugins directory.
Download the plugin using latest release, please download and uncompress a zip file into the Grafana plugins directory (grafana/plugins).
- Add the Cassandra DataSource as a datasource at the datasource configuration page.
- Configure the datasource specifying contact point and port like "10.11.12.13:9042", username and password, skip the keyspace. It's recommended to use a dedicated user with read-only permissions only to the table you have to access.
- Push the "Save and Test" button, if there is an error message, check the credentials and connection.
First, to visualize the data, you have to create a panel. Choose or create a dashboard and create a panel. In the panel setup, choose the correct datasource from the previous steps.
There are two ways to query data from Cassandra: Query Configurator and Query Editor. Configurator is easier to use but has limited capabilities, Editor is more powerful but requires an understanding of CQL.
Query Configurator is the easiest way to query data. At first, enter the keyspace and table name, then pick proper columns. If keyspace and table names are given correctly, the datasource will suggest the column names automatically.
- Time Column - the column storing the timestamp value, it's used to answer "when" question.
-
Value Column - the column storing the value you'd like to show. It can be the
value,temperatureor whatever property you need. -
ID Column - the column to uniquely identify the source of the data, e.g.
sensor_id,shop_id, or whatever allows you to identify the origin of data.
After that, you have to specify the ID Value, the particular ID of the data origin you want to show. You may need to enable "ALLOW FILTERING" although we recommend avoiding it.
Example Imagine you want to visualise reports of a temperature sensor installed in your smart home. Given the sensor reports its ID, time, location and temperature every minute, we create a table to store the data and put some values there:
CREATE TABLE IF NOT EXISTS temperature (
sensor_id uuid,
registered_at timestamp,
temperature int,
location text,
PRIMARY KEY ((sensor_id), registered_at)
);
insert into temperature (sensor_id, registered_at, temperature, location) values (99051fe9-6a9c-46c2-b949-38ef78858dd0, '2020-04-01T11:21:59.001+0000', 18, 'kitchen');
insert into temperature (sensor_id, registered_at, temperature, location) values (99051fe9-6a9c-46c2-b949-38ef78858dd0, '2020-04-01T11:22:59.001+0000', 19, 'kitchen');
insert into temperature (sensor_id, registered_at, temperature, location) values (99051fe9-6a9c-46c2-b949-38ef78858dd0, '2020-04-01T11:23:59.001+0000', 20, 'kitchen');
In this case, we have to fill the configurator fields the following way to get the results:
- Keyspace - smarthome (keyspace name)
- Table - temperature (table name)
- Time Column - registered_at (occurence)
- Value Column - temperature (value to show)
- ID Column - sensor_id (ID of the data origin)
- ID Value - 99051fe9-6a9c-46c2-b949-38ef78858dd0 ID of the sensor
- ALLOW FILTERING - FALSE (not required, so we are happy to avoid)
In the case of a few origins (multiple sensors), you will need to add more rows. If your case is as simple as that, a query configurator will be a good choice, otherwise please proceed to the query editor.
Query Editor is a more powerful way to query data. To enable query editor, press the "toggle text edit mode" button.
Query Editor unlocks all possibilities of CQL including Used-Defined Functions, aggregations, etc.
SELECT sensor_id, CAST(temperature as double), registered_at FROM test.test WHERE sensor_id IN (99051fe9-6a9c-46c2-b949-38ef78858dd1, 99051fe9-6a9c-46c2-b949-38ef78858dd0) AND registered_at > $__timeFrom and registered_at < $__timeTo
- Follow the order of the SELECT expressions, it's important!
-
Identifier - the first property in the SELECT expression must be the ID, something that uniquely identifies the data (e.g.
sensor_id) - Value - The second property must be the value that you are going to show
- Timestamp - The third value must be a timestamp of the value. All other properties will be ignored
- To filter data by time, use
$__timeFromand$__timeToplaceholders as in the example. The datasource will replace them with time values from the panel. Notice It's important to add the placeholders otherwise query will try to fetch data for the whole period of time. Don't try to specify the timeframe on your own, just put the placeholders. It's grafana's job to specify time limits.
