User Guide for GridDB Grafana Input Plugin

Revision: 1.6.0-10082-768e556f

1 Overview

GridDB input plugin for Grafana is used to get data from GridDB and display it as a graph or table on Grafana.

1.1 Requirements

The GridDB input plugin has the following requirements:

1. For a Grafana user with a server or organization administration role, refer to Permissions.

2. A GridDB server must have at least one GridDB user.

1.2 Known limitations

N/A

2 Installation

2.1 Installing Grafana

Refer to Grafana installation.

2.2 Installing the GridDB input plugin

2.2.1 How to build

• Install Node.js and npm by referring to Downloading and installing Node.js and npm.

• Go to $GRAFANA_HOME where the file package.json exists and run the commands below:

1. npm install -g yarn
2. yarn install
3. yarn build

2.2.2 How to install

1. Go to $GRAFANA_HOME/plugins-bundled/internal/input-datasource and create a new folder GridDB-plugin.

2. Copy the folder dist in the GridDB plugin to the folder GridDB-plugin.

3. Restart your Grafana server.

2.3 Adding a GridDB data source

📝 If your Grafana server is behind a proxy server, it is necessary to configure the proxy by setting the environment variables before connecting to GridDB.

1. Set the environment variables for proxy configuration (if needed).
2. Go to $GRAFANA_HOME/bin and run grafana-server.
3. Open a browser and go to the address "localhost:3000."
4. Log in to Grafana with the username and password for Grafana. If it is your first login, the default username/password is admin/admin.
5. Change the password (if it is your first login).
6. Open the side menu by clicking the Grafana icon in the top header.
7. In the side menu under the Configuration link, click the link named Data Sources.
8. Click the + Add data source button in the top header.
9. Enter GridDB in the search field. Ensure GridDB is shown for the data source and click the Select button.
10. Enter any data source name (e.g., GridDB-Cloud) in the Name field.
11. Enter the GridDB Web API URL in the host field in the GridDB Connection section. Do not include the context path such as "/griddb/v2."
12. Enter the cluster name for GridDB.
13. Enter the database name. If nothing is entered, then the default database "public" is used.
14. Enter the username and password of a GridDB user with the READ permission for the database specified in Step 13.
15. Enter a value for the min time interval. The default is 1 second.
16. Click the Save & test button to check a connection to GridDB.

3 Preparing data

Here we create three containers.

1. Create the first container.

• Container name: table30DayTo5years

• Container type: TIMESERIES

• Container schema:

  | Name      | Type           | Constraints    |
  |---------  |-----------     |-------------   |
  | mycolumn1 | TIMESTAMP      | NOT NULL       |
  | col_1     | BYTE           |                |
  | col_2     | SHORT          |                |
  | col_3     | INTEGER        |                |
  | col_4     | LONG           |                |
  | col_5     | FLOAT          |                |
  | col_6     | DOUBLE         |                |
  

2. Create the second container.

• Container name: Multiple_Time_Columns
• Container type: TIMESERIES
• Container schema:

| Name      | Type           | Constraints  |
|---------  |-----------     |------------- |
| col1      | TIMESTAMP      | NOT NULL     |
| col2      | TIMESTAMP      |              |
| col3      | STRING         |              |
| col4      | INTEGER        |              |

• Container name: grafana
• Container type: TIMESERIES
• Container schema:

| Name      | Type           | Constraints  |
|---------  |-----------     |------------- |
| time      | TIMESTAMP      | NOT NULL     |
| col1      | INTEGER        |              |
| col2      | INTEGER        |              |
| col3      | INTEGER        |              |
| col4      | INTEGER        |              |
| col5      | INTEGER        |              |
| col6      | INTEGER        |              |

4 Visualization

4.1 Dashboard

4.1.1 Creating a dashboard for visualization

1. In the side menu, hover the mouse cursor over the icon ''+" and click Dashboard.

   

2. In the New dashboard screen, click the rectangle named Add an empty panel in the Add panel area.

   

3. In the Edit panel screen, select the Query tab on the lower part of the screen and select the data source that you have created in the section Adding a GridDB data source.

4. Select a container from the drop-down list and select the time column in the Query area.

   

   

5. Add a condition for the query.

   

   

   

   📝 You can add more conditions by clicking the "+" button in the condition section.

6. Select the time range for which you want to display data.

   

7. You can choose a graph style as follows:

   

8. When you finish adding queries, the following dashboard will appear.

   

   📝 Each time you add a query, the graph is automatically updated without additional action.

9. You can change the legends displayed by entering a user-defined value in the ALIASED BY text field as shown below:

   

   For more information about special variables you can use, refer to the ALIASED BY field in the Edit Panel screen column of the table in Availability of special query expressions for each data field.

10. Click the Apply button to save the dashboard, and the system will redirect you to the variable screen and display the graph as you have specified.

    

11. Click the Save button to save the dashboard.

4.1.2 Additional settings

In addition to creating a dashboard for visualization as explained in the section Creating a dashboard for visualization, you can add configuration to create a more interactive and dynamic dashboard using variables.

4.1.2.1 Variables

A variable is a placeholder for a value. Variables can be used in metric queries and panel titles.

For more details, refer to Grafana variables.

4.1.2.1.1 Variable settings

1. Open any panel and click the Settings button on the top screen.

2. In the side menu under Settings, click the link named Variables.

3. Click the + Add variable button.

4. Enter a query in the Query field on the Edit screen. You can use the following three predefined parameters:

   1. To get all containers using a parameter, use the format $griddb_container_list.
   2. To get all columns of a specific container using a parameter, use the format$griddb_column_list({container name}).
   3. To get data of a specific container using a parameter, use the format $griddb_query_data({container name}, {columns}, {TQL}).

5. The result of the query is displayed in the Preview of values area.

   • $griddb_container_list

   

   • $griddb_column_list({container name})

   

   • $griddb_query_data({container name}, {columns}, {TQL})

​ 📝 You can configure two options: Multi-value and Include all options. If you enable Multi-value, you can choose multiple values by checking checkboxes. If you enable Include all options, you can select all the checkboxes automatically by checking the checkbox for "All" .

6. Click the Update and Save As buttons to save the variable.

   

7. Enter a dashboard name and select a folder (The default is General) in the Save dashboard as... dialog. To create a folder on the dashboard, refer to How To Create A Folder.

   

8. Click the Save button. A dashboard which has a variable that you have just created is created.

4.1.2.1.2 Visualizing data with variables

1. If a variable has been successfully created in the section Variable settings, the system will redirect you to the screen for the variables you have created.

   

2. Click the Add panel button enclosed in a red rectangle on the top right side of the screen.

   

3. Follow steps 2 and 3 in the section Creating a dashboard for visualization.

4. Select one of the container variables created in the section Variable settings.

   

5. Select time columns as shown below:

   

6. If you want to control data displayed in the graph, add one or more conditions in the CONDITION fields, where you can specify the variable you have created. Note that you need to enter a variable name manually due to a limitation. You cannot choose it from a drop-down list.

   

7. Specify a concrete value in the list above the graph to reflect it to the variable.

   

4.1.2.2 Annotations

In addition to creating a dashboard for visualization as explained in the section Creating a dashboard for visualization and visualizing data with variables, you can set annotations to mark points on the graph with rich events. When you hover the mouse cursor over an annotation you can obtain event description and event tags. The text field can include links to other systems with more detail.

For more details, refer to Grafana annotations.

4.1.2.2.1 Annotation settings

1. Open any panel and click the Settings button on the top screen.

2. In the side menu under Settings, click the link named Annotations.

3. Click the + Add Annotation Query button.

4. Currently, the GridDB input plugin supports two annotation types, i.e., annotation and region annotation. The region annotation is used for a container with multiple time columns (e.g., Multiple_Time_Columns).

   4.1. Enter the following data to create a annotation.

   

​ 4.2. Enter the following data to create a region annotation.

Refer to Appendix to learn about some of the arguments you can add to the query field to create a dynamic query.

5. Click the Save As... button to create an annotation.

6. Add dashboard information in the Save dashboard as... dialog in a similar manner to the way that you have created a variable and click the Save button to save the dashboard.

7. After saving the dashboard, a dashboard will which has the annotation that you have created previously is created.

After completing dashboard settings, in the side menu under the Dashboards link, click the link named Manage. Under the Manage tab, the following screen will appear, displaying a list of the dashboards you have set up.

4.1.2.2.2 Visualizing data with annotations

1. If an annotation has been successfully created in the section Annotation settings, the system will redirect you to the screen for the annotation you have created.

2. Select a container name from the drop-down list and click the Add panel button as shown below.

   

3. An annotation panel will appear. Add a query in a similar manner to the way that you have added a query in the previous section for data visualization.

   

4. The following annotation screen will appear.

4.2 Explore

1. The Explore screen can be accessed in two different ways (1.1. and 1.2.).

   1.1. Click Explore in the side menu.

   

   The system displays the following screen without selecting any data.

   

   1.2. In the variable or annotation screen for visualization, click the option Explore from the Panel Title drop-down list.

   

   The system displays the Explore screen with a time range obtained from the currently selected visualization dashboard.

   

2. Add a query in a similar manner to the way that you have added a query in steps 4, 5, and 7 in the section Creating a dashboard for visualization.

   

3. Click the Run query button to update the data.

4. The following Explore visualization screen is displayed.

5 Related content

N/A

6 Appendix

6.1 Special query expressions

The following expressions can be used in queries to create a dynamic query.

6.1.1 Available special query expressions

6.1.2 Availability of special query expressions for each data field

The following table shows the availability of special query expressions for each data field.

(1): Used for a query with a single annotation. You must always use $__timeFilter to limit data.
(2): Used for a query with a region annotation. You must always use $__rangeFilter to limit data.