Adding a Custom Grafana Dashboard

On This Page

Overview

The platform includes a pre-deployed version of the open-source Grafana analytics and monitoring platform. For detailed information about working with Grafana, see the Grafana documentation. Grafana allows the creation of custom web dashboards that visualize real-time data queries. This tutorial outlines the steps for creating your own Grafana dashboard for querying data in the your cluster’s data containers by using the custom iguazio Grafana data source, or by using a Prometheus data source for running Prometheus queries on platform TSDB tables. You can repeat this procedure to create as many dashboards as you wish.

Prerequisites

  1. To use Grafana to visualize data in the platform, you first need to create a new Grafana service from the dashboard Services page. For general information about creating new services, see creating a new service.

    Note
    • In cloud platform environments, Grafana is currently available as a shared single-instance tenant-wide service.

    • To add the iguazio data source to your Grafana service, you must set the service’s Platform data-access user parameter to a platform user whose credentials will be used for accessing the data in the platform.

  2. To use a Prometheus data source, you first need to create a TSDB table and a Prometheus service that’s configured to query this table.

    When you create a new Grafana service, it automatically includes data sources for all existing platform Prometheus services that are accessible to the running user of the Grafana service. However, to add a Grafana data source for a new Prometheus service that’s create after the creation of the Grafana service, you need to do one of the following:

    • Restart the Grafana service. This will update the service’s data sources to include all relevant existing Prometheus services. However, note that any Grafana UI changes that were previously made for this service might be lost.

    • Manually add the data source for the Prometheus service:

      1. Open the dashboard Services page and copy the HTTPS URL of the target Prometheus service (the service-name link target in the Name column).
      2. Select the service-name link of your Grafana service to open the Grafana UI.
      3. From the Grafana side navigation menu, select the configuration gear-wheel icon (Settings icon) to display the Configuration | Data Source tab.
      4. Select Add Data Source, and then select Prometheus from the data-sources list.
      5. Optionally edit the default data-source name in the Name field (for example, to use the name of the selected Prometheus service).
      6. In the URL field, paste the Prometheus service URL that you copied in the first step.
      7. Optionally set additional configuration parameters, and then select Save & Test.
  3. To successfully submit queries and visualize data with Grafana, you need to have data in you cluster’s data containers that matches your queries. The instructions in this tutorial demonstrate how to create a dashboard that queries the following tables; to query other tables, you’ll need to adjust your dashboard configuration, and especially the query parameters, to match the path and attributes of an existing table in your cluster.

    • A bank_nosql NoSQL table in the “bigdata” container. You can create a compatible table by following the instructions in the Converting a CSV File to a NoSQL Table tutorial.
    • A sample-tsdb TSDB table in the “bigdata” container. You can create such a table by using the TSDB CLI (tsdbctl). For example, you can run the following command from a web-based shell or a Jupyter terminal to create the table used in the tutorial examples:

      tsdbctl create -c bigdata -t sample-tsdb -r 1/s
              

      After creating the TSDB table, ingest some sample metrics into the table so that you have data to visualize with Grafana. You can do this by running the V3IO TSDB CLI or by using a Nuclio TSDB ingestion function. For detailed TSDB CLI usage instructions, see the Working with the TSDB CLI tutorial.

Using the iguazio Data Source

  1. Select your Grafana service from the platform dashboard’s Services page, and log into the service with your platform credentials.

  2. From the side navigation menu, select the plus-sign icon (Side-menu plus icon) to display the Create menu, and select Dashboard from the menu.

    Create-dashboard menu selection
  3. In the new-panel Add tab, select the desired visualization type. In this step, select Table. (A graph example is provided in Step 11.)

    Table visualization-type selection
  4. Select Panel Title, and select Edit from the menu.

    Panel-title edit selection
  5. In the Metrics tab, select the Data Source drop-down arrow, and select iguazio from the list of data sources.

    Data-source selection
  6. In the first metrics-query row (A), select the query-type drop-down arrow and select the query type. You can select between timeseries for querying a time-series database (TSDB), and table for querying a standard NoSQL table. In this step, select table. (A timeseries example is provided in Step 12.)

    Table query-type selection
  7. Select the drop-down arrow for the query-parameters box (next to the query type) and enter your query parameters. The parameters are entered using the syntax <parameter name>=<parameter value>; [<parameter name>=<parameter value>; ...].

    Table query parameters example
    Note
    To see the query parameters in the UI, select the query fly-out menu icon (Query menu icon) and then select the Toggle Edit Mode option from the menu. To run the defined queries, select the refresh button (Refresh icon) from the top menu toolbar.

    The iguazio data source supports the following query parameters:

    • backend [Required] — the backend type.

      • For table queries, you must set this parameter to “kv”.
      • For timeseries queries, you must set this parameter to “tsdb”.
    • container [Required] — the name of the data container that contains the queried table. For example, “bigdata” or “users”.

    • table [Required] — a Unix file-system path to a table within the configured container. For example, “mytable” (for a table in the container’s root directory) or “examples/” for a nested table.

    • fields — a comma-separated list of one or more query fields to include in the query.

      • For table queries, this parameter should be set to a comma-separated list of item-attribute names — for example, “id,first_name,last_name”.
      • For timeseries queries, this parameter should be set to a comma-separated list of sample metric names — for example, “temperature” or “cpu0,cpu1,cpu2”.
      Note

      You must set either the fields or filter parameter; you can also select to set both parameters.

    • filter — a filter expression that restricts the query to specific items.

      • For table queries, the filter is applied to the names of item attributes (table columns). For example, filter=ID>10.
      • For timeseries queries, the filter is applied to the names of labels and/or metrics. To reference a metric name in the filter, use the __name__ attribute. For example, “starts(__name__,'metric') AND device==1”.

      As indicated, you must set the filter and/or fields parameter.

    Enter the following query parameters to query selected attributes in the “bank_nosql” table in the root directory of the “bigdata” container, or edit the parameters to match the data in another NoSQL table in your cluster:

    backend=kv; container=bigdata; table=zeppelin_getting_started_example/bank_nosql; fields=age,job,marital,education,balance,housing,loan,contact,day,month,duration;
        

    You can also add additional queries, if you wish.

  8. Select the General tab and edit the panel title. For example, set the title to “Bank”.

    Edit bank-table panel title
  9. You can optionally make additional configurations for your dashboard panel from the Options, Column Styles, and Time range tabs.

  10. From the top-menu toolbar, select the save icon (Save icon). Enter a new name for your dashboard, optionally change the dashboard folder, and select Save. For example, set the name to “Iguazio Dashboard” and save the dashboard in the default “General” folder.

    Save dashboard
    Tip
    Instead of selecting the save icon from the toolbar, you can select the settings icon (Settings icon) to display the Settings page. In addition to setting the dashboard name and folder, this page lets you make other configurations; for example, you can define variables to use in your query parameters.

    You now have a “Bank” dashboard panel with a table that provides real-time visualization of the data in the “bank_nosql” table in the “bigdata” container.

    Grafana dashboard NoSQL table example

    In the following steps, you’ll add a TSDB graph to your dashboard.

  11. From the top-menu toolbar, select the add-panel icon (Add-panel icon) to display the new-panel Add tab that you saw in Step 3. This time, select the Graph visualization type.

    Graph visualization-type selection
  12. Select the Panel Title | Edit menu option (as you did in Step 4). In the Metrics tab, select iguazio as the data source (as you did in Step 5), but this time select the timeseries query type (unlike the table selection in Step 6).

    Time-series query-type selection
  13. Select the drop-down arrow for the query-parameters box (next to the query type) and enter your query parameters using the syntax <parameter name>=<parameter value>; [<parameter name>=<parameter value>; ...] — similar to what you did in Step 7, except that you need to enter time-series query parameters for a TSDB table; see the supported query parameters in Step 7.

    Time-series query parameters example
    Note
    As explained for the table query, you can toggle the query edit mode from the query menu (Query menu icon) to see the parameters in the UI, and use the refresh button (Refresh icon) in the top menu toolbar to run the query.

    Enter the following query parameters to query “metric0” samples in the “sample-tsdb” table in the root directory of the “bigdata” container, or edit the parameters to match the data in another TSDB table in your cluster:

    backend=tsdb; container=bigdata; table=sample-tsdb; fields=metric0;
        

    You can also add additional queries, if you wish.

  14. Select the General tab and edit the panel title, as you did in Step 8, but this time enter another title — for example, “Sample TSDB”.

    Edit TSDB panel title
  15. You can optionally make additional configurations for your dashboard panel from the Axes, Legend Styles, Display, Alert, and Time range tabs.

  16. From the top-menu toolbar, select the save icon (Save icon) to save your changes.

    You now have a “Sample TSDB” dashboard panel with a graph that provides real-time visualization of the data in the sample-tsdb TSDB table in the “bigdata” container.

    Grafana dashboard TSDB graph table

Outcome

Go to the Grafana home page and select your “Iguazio Dashboard” dashboard from the list. You’ll see your two panels on the dashboard. Note that you can change the time range for the visualization from the top-menu toolbar. You can also customize the dashboard by resizing panels and dragging them to change their arrangement. The following image demonstrates a dashboard that displays the panels that you defined in this tutorial:

Custom Grafana dashboard example

Using a Prometheus Data Source

  1. Log into your Grafana service and select your Grafana dashboard. To edit an existing dashboard, open the dashboard and then, from the top-menu toolbar, select the add-panel icon (Add-panel icon) to display the new-panel Add tab. To create a new dashboard, follow Steps 24 of the iguazio data-source instructions; select the visualization type that suites your need (such as table or graph).

  2. In the Metrics tab, select the Data Source drop-down arrow, and select your desired Prometheus data source.

  3. From the Metrics tab, add Prometheus TSDB queries.

  4. Select the General tab and edit the panel title, as you did in Step 8, but use another title — for example, the name of your Prometheus data source.

  5. From the top-menu toolbar, select the save icon (Save icon) to save your changes.

Outcome

Go to the Grafana home page and select your dashboard from the list. You should be able to see your new Prometheus panel on the dashboard.

See Also