Skip to content

Latest commit

 

History

History
229 lines (167 loc) · 8.46 KB

INSTALLATION.md

File metadata and controls

229 lines (167 loc) · 8.46 KB
Raw

Install the Grafana Plugin for TDengine

[TDengine] is open-sourced big data platform under GNU AGPL v3.0, designed and optimized for the Internet of Things ( IoT), Connected Cars, Industrial IoT, and IT Infrastructure and Application Monitoring, developed by TDengine.

[TDengine] data source plugin is developed for [Grafana]. This document explains how to install and configure the data source plugin, and use it as a time-series database. We'll take a look at the data source options, variables, querying, and other options specific to this data source.

At first, please refer to Add a data source for instructions on how to add a data source to Grafana. Note that, only users with the organization admin role can add data sources.

Compatiable with TDengine version

TDengine grafana plugin version major changes TDengine version
3.5.1 update taosd and taosX dashboard 3.3.0.0 or later
3.5.0 new taosd and taosX dashboard 3.2.3.0 or later
3.4.0 new adapter dashboard 3.2.0.1 or later
3.2.7 support TDengine 3.0 3.0.0.0 or later

One-line installer

TDENGINE_DS_NAME=TDengine
TDENGINE_CLOUD_URL=
TDENGINE_CLOUD_TOKEN=
bash -c "$(curl -fsSL https://raw.githubusercontent.com/taosdata/grafanaplugin/master/install.sh)"
  • TDengine_DS_NAME: The data source name to create
  • TDENGINE_CLOUD_URL: The TDengine url, eg. http://localhost:6041
  • TDENGINE_CLOUD_TOKEN: The TDengine cloud service token, optional.
  • TDENGINE_USER/TDENGINE_PASSWORD: The TDengine username/password, optional.

Type install.sh --help for the full usage of the script.

Install with GUI

The TDengine data source plugin is already published as a signed Grafana plugin. You can easily install it from Grafana Configuration GUI. In any platform you already installed Grafana, you can open the URL http://localhost:3000 then click plugin menu from left panel.

click plugin menu

Then key in TDengine to search.

search TDengine

Install Manually

We recommend you use the prebuilt package of the plugin in the latest release download page.

Option 1, you can install the TDengine data source plugin with grafana-cli.

sudo -u grafana grafana-cli \
  --pluginUrl https://github.com/taosdata/grafanaplugin/releases/download/v3.1.3/tdengine-datasource-3.1.3.zip \
  plugins install tdengine-datasource

Option 2, you can install the plugin manually.

# make sure to use the right plugins directory
GF_PLUGINS_DIR=/var/lib/grafana/plugins
# install plugin
V=3.1.7
wget -c https://github.com/taosdata/grafanaplugin/releases/download/v$V/tdengine-datasource-$V.zip
sudo -u grafana unzip -oq tdengine-datasource-$V.zip -d $GF_PLUGINS_DIR
sudo -u grafana sh -c "chmod +x $GF_PLUGINS_DIR/tdengine-datasource/tdengine-datasource*"

Here is a unified shell script to automatically download and install the latest plugin in a Grafana server.

# make sure to use the right plugins directory
GF_PLUGINS_DIR=/var/lib/grafana/plugins

get_latest_release() {
  curl --silent "https://api.github.com/repos/taosdata/grafanaplugin/releases/latest" |
    grep '"tag_name":' |
    sed -E 's/.*"v([^"]+)".*/\1/'
}
install_plugin() {
  V=$1
  [ -f tdengine-datasource-$V.zip ] ||
    wget -c https://github.com/taosdata/grafanaplugin/releases/download/v$V/tdengine-datasource-$V.zip
  sudo -u grafana unzip -oq tdengine-datasource-$V.zip -d $GF_PLUGINS_DIR
  sudo -u grafana sh -c "chmod +x $GF_PLUGINS_DIR/tdengine-datasource/tdengine-datasource*"
}

install_plugin $(get_latest_release)

Option 3, if you use the plugin in docker, just set the environment GF_INSTALL_PLUGINS like GF_INSTALL_PLUGINS=https://github.com/taosdata/grafanaplugin/releases/download/v3.1.3/tdengine-datasource-3.1.3.zip;tdengine-datasource, or refer to Build and run a Docker image with pre-installed plugins to pre-build a custom Grafana image with the TDengine data source plugin.

Option 4, build and install this plugin by yourself. You should follow the CONTRIBUTING steps to set up develop environment and build the plugin.

yarn build:all

Then copy the dist/ directory to Grafana plugin directory.

sudo -u grafana rsync -rlzP dist/ /var/lib/grafana/plugins/tdengine-datasource

It will also generate a zipped package named tdengine-datasource-<version>.zip for distribution.

Note that the plugin has not been published to https://grafana.com officially (the plugin is under review, as if you want to know) - that means the plugin is unsigned for public use. So if you use it in 7.x and 8.x of grafana, you should configure in /etc/grafana/grafana.ini by add these lines to allow unsigned plugin before start the Grafana server.

[plugins]
allow_loading_unsigned_plugins = tdengine-datasource

Or use environment variable GF_ALLOW_LOADING_UNSIGNED_PLUGINS=tdengine-datasource in docker and other container-based environments.

In any particular scenario, if you need a signed plugin, please follow the Sign a plugin instructions to sign a private plugin. Commands may be like this:

export GRAFANA_API_KEY=<YOUR_API_KEY>
yarn run grafana-toolkit plugin:sign \
  --signatureType private \
  --rootUrls 'http://localhost:3000'

rootUrls is your local grafana server url.

The next step is restart the Grafana server. The new data source should now be available in the data source type dropdown in the Add Data Source view. For systemd based system, the restart command is:

sudo systemctl restart grafana-server

For SysVInit based system (CentOS 6 etc.):

sudo service grafana-server restart

Installation on macOS

The best way to install Grafana is to use Homebrew with which to install the most recent released version of Grafana using Homebrew package.

Open a terminal and enter:

brew update
brew install grafana

Next, add TDengine’s plugin with the following command:

sudo grafana-cli --pluginsDir /opt/homebrew/var/lib/grafana/plugins --pluginUrl\
  https://github.com/taosdata/grafanaplugin/releases/download/v3.1.3/tdengine-datasource-3.1.3.zip \
  plugins install tdengine-datasource

The pluginsDir option /opt/homebrew/var/lib/grafana/plugins should be overridden if the directory not exist(that will depend on how you install the Grafana service).

You can check the plugins directory to see if tdengine-datasource plugin installed:

$ ls /opt/homebrew/var/lib/grafana/plugins
tdengine-datasource

TDengine plugin has not been signed, so you should change the grafana configuration to allow unsigned plugin.

Since you are using macOS with Homebrew, Grafana instances installed using Homebrew require you to edit the grafana.ini file directly. The way to change the grafana.ini file is to run the following command:

open -a textedit /opt/homebrew/etc/grafana/grafana.ini

Note that, this plugin is signed since v3.1.7. If you are using an older version, please configure to allow loading unsigned plugins:

First, open the file, search for

;allow_loading_unsigned_plugins

Then, delete the semicolon to uncomment it, and change the line to:

allow_loading_unsigned_plugins = tdengine-datasource

After that, go ahead and save the configuration file.

(Re-)start Grafana service:

# brew services start grafana
brew services restart grafana

Point to plugins pages to search and check TDengine plugin is in the list.