TimeBase plugin for Grafana overview, installation and operation guide
Click Tag to Display Pages: integrations development

Time-series data stored in TimeBase streams can be visualized in in Grafana charting and monitoring tool with TimeBase Grafana Plugin. Plugin offers a wide range of instruments to process and analyze time-series data.

Prerequisites

The following components are required to run and use TimeBase Grafana Plugin:

  1. Grafana Server - data visualization and processing server.
  2. TimeBase Web Admin - plugin uses TimeBase Web Admin API to communicate with TimeBase Server.
  3. TimeBase Server - where all time-series data is stored.

Deployment

Grafana plugin is distributed in ZIP archive. All you need to do to install, is to unpack ZIP to a folder of your choice.

Manual Installation

  1. Download a ZIP archive with plugin from nexus repository
  2. Unpack archive to Grafana Server plug-ins directory. In case you use bare-metal installation of Grafana it is {GRAFANA_HOME}/data/plugins. In case you use Grafana Docker image, mount directory to /var/lib/grafana/plugins.
  3. Restart Grafana Server

Installation Via Grafana-CLI

  1. Run command grafana-cli --pluginUrl {plugin-zip-url} plugins install deltix-timebase-datasource-plugin
  2. Restart Grafana Server

Docker Compose

Unpacked plugin should be located in ./grafana-plugins directory.

# docker-compose example

version: '2'
services:
  grafana:
    image: grafana/grafana:7.1.3
    ports:
      - "3000:3000"
    volumes:
      - grafana-volume:/var/lib/grafana
      - ./grafana-plugins:/var/lib/grafana/plugins           # plugins directory
      - ./datasources:/etc/grafana/provisioning/datasources  # provisioning datasources directory
  web-admin:
    image: registry.deltixhub.com/quantserver.docker/timebase/ws-server:0.3.66
    ports: 
      - "8099:8099"
    environment: 
      JAVA_OPTS: '-Dtimebase.url=dxtick://host.docker.internal:8011'

volumes:
  grafana-volume:

Datasource provisioning configuration (should be located in ./datasources directory):

# timebase.yaml

apiVersion: 1

# list of datasources to insert/update depending
# what's available in the database
datasources:
  # <string, required> name of the datasource. Required
  - name: TimeBase
    # <string, required> datasource type. Required
    type: deltix-timebase-datasource-plugin
    # <string, required> access mode. proxy or direct (Server or Browser in the UI). Required
    access: proxy
    # <int> org id. will default to orgId 1 if not specified
    orgId: 1
    # <string> custom UID which can be used to reference this datasource in other parts of the configuration, if not specified will be generated automatically
    uid: my_unique_uid
    # <string> url
    url: http://web-admin:8099
    # <bool> mark as default datasource. Max one per org
    isDefault:
    jsonData:
      timebaseUrl: http://web-admin:8099 # web admin url
      timebaseUser: 'admin' # web admin user
    secureJsonData:
      timebasePassword: 'admin'
    version: 1
    # <bool> allow users to edit datasources from the UI.
    editable: false

Authentication with Auth0

Configure Auth0

  1. In Applications create a Regular Web Application
  2. In application Settings set Allowed Callback URLs: /login/generic_oauth
  3. In User Management create a new user. Username and password will be subsequently used by Grafana plugin corresponding users.

Configure TimeBase

Add the following environmental variables to the TimeBase Web Admin chart:

GF_SERVER_ROOT_URL: <grafana_base_url>
GF_AUTH_GENERIC_OAUTH_ALLOW_SIGN_UP: true
GF_AUTH_GENERIC_OAUTH_ENABLED: true
GF_AUTH_GENERIC_OAUTH_NAME: Auth0
GF_AUTH_GENERIC_OAUTH_SCOPES: openid profile email
GF_AUTH_GENERIC_OAUTH_TOKEN_URL: https://<your_domain>.auth0.com/oauth/token
GF_AUTH_GENERIC_OAUTH_AUTH_URL: https://<your_domain>.us.auth0.com/authorize
GF_AUTH_GENERIC_OAUTH_API_URL: https://<your_domain>.us.auth0.com/userinfo
GF_AUTH_GENERIC_OAUTH_CLIENT_ID: <client_id>
GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET: <secret>

Configure Grafana Plugin

  • Click Server Admin icon, navigate to Users and create a New User
  • Make sure that user’s username matches the corresponding username in Auth0
  • Please note, that even though it is required to set the password for a new user, password from Auth0 will override the password you provide for the Grafana user.

How To Use Plugin

Following sections describe TimeBase plugin functionality. See Grafana Docs for more in depth information about all the features and tools offered by Grafana.

Adding Data Source

Grafana plugin uses TimeBase as a data source. You can use more than one TimeBase instance as Grafana plugin data source.

  1. In the Configuration menu select Data Source
  2. Click Add Data Source and find your TimeBase Plugin
  3. Configure plugin settings
    • Name - Plugin name
    • URL - TimeBase Web Admin URL
    • User - TimeBase Web Admin user Username
    • Password - TimeBase Web Admin user Password
  4. Click Test to check the connection with TimeBase. You will see a confirmation message in case the connection is successful.

  5. Set toggle to Default to make the current selection a default data source

Creating New Dashboard

  1. Go to Create menu and click Dashboard
  2. Click Add new panel to create a dashboard

Queries

On a new panel you can make queries to the selected data source and visualize them on the dashboard.

  1. In Queries tab select TimeBase plugin in the drop down list. Each custom plugin has own set of parameters.
  2. You may create just one or a combination of several queries. Click + Query to add another query.

Query Parameters

TimeBase plugin offers the following categories of parameters you can use to make data queries:

Stream

Time-series data is stored in streams. Each TimeBase instance can be seen as a collection of streams. Here you can select a specific stream to visualize data that it stores.

  • Select a stream you wish to place a query to.
  • Use WHERE/AND clauses to extract data that meets specific conditions.

Symbol

Time-series data is recorded in streams in a form of Messages. Each message has a timestamp (time and date of a message) and symbol (specific identifier of a data source like sensor id, trading instrument name etc) that serve for data indexing. You can select a specific symbol to sort stream data by, for example display all readings for a specific IoT sensor (sensor id is a symbol value in this case).

  • Use drop down list of symbols to select a specific symbol for your query or select All() to display data for all the available symbols.

Select

In this section you can select specific message fields to filter your query, perform different data aggregations and computations using available fields and functions.

Field

TimeBase messages may be of different types (classes). Each message class has a specific set of attributes (fields). In Grafana UI it is visualized as class:field in the Fields section. Imagine a water meter, meter id is a symbol, meter reading is a field. Another example of a field may be a trading instrument price and quantity (trading instrument name is a symbol, price and quantity are fields).

  • Select at least one Field from the drop down list of available fields. Available fields are determined by message types (classes) in your stream. The selected data is displayed on the dashboard and is changed as you add more fields and perform any additional manipulations with data.
  • On the dashboard, you can select between fields you wish to display

Functions

You can perform various manipulations with your data set using mathematical, financial and/or statistical functions. Hover over each function to see details. You can use combinations of functions.

Aggregations

Use a set of available aggregations and aliases to manipulate with the selected data. You can use a combination of aggregations.

Group By

Use this section to set time intervals and to make additional groupings of the selected data. For example, in case you have selected All() symbols from your stream, you can use group by symbol to view data for each symbol in the stream. Use a predefined time range options or manually input time range (e.g. 45s) to sort data in time.

Option

This option is enabled in case you select at least one specific field to Group By your data set. In this case, the selected field(s) serves as a key. You can arrange data with this key either placed in table column or row.

View

Grafana supports DATAFRAME and TIMESERIES visualization formats. Select the format that your plugin supports.