Install external plugins in Telegraf

Overview

The ctrlX OS Telegraf app provides a huge set of internal plugins, see Telegraf-Plugins. There are also lots of external plugins already available as source code on github, have a look at this list. Furthermore it’s also possible to build a custom Telegraf plugin.

This how to demonstrates how a external Telegraf plugin can be build and installed in ctrlX OS.

Prerequisite

• ctrlX OS - Telegraf App is installed on a ctrlX OS device

• App Build Environment is setup to build the plugin. For the plugin the environment needs to be setup to build go apps (install-go.sh)

Building a external plugin for Telegraf

For implementing a custom external plugin have a look at this guide. It’s to use the Telegraf Execd Go Shim for implementation of external plugins.

In this how to a ready implemented plugin available on GitHub is used as an example. The plugin rand generates random numbers in a configurable range. Follow these steps to clone and build this plugin for the ctrlX OS Telegraf App:

1. Clone the plugin source code from the GitHub to the App-Build-Environment
   git clone https://github.com/ssoroka/rand.git

2. Build the plugin for ctrlX OS
   Build the plugin for the desired architecture. As an example: arm64 for ctrlX CORE X3 or amd64 for ctrlX COREvirtual or X5, X7. This helper script can be used to build and zip the binary:

   Copy

   #!/bin/bash
   ARCH=$1
   if [ -z "$ARCH" ]; then
       ARCH=amd64
   fi
    
   go mod vendor
   go mod tidy
    
   export GOOS=linux
   export GOARCH=$ARCH
    
   if [ "$ARCH" == "arm64" ]; then
       export GOARM=7
       export CGO_ENABLED=1
       export CC=aarch64-linux-gnu-gcc
   fi
    
   TARGET=./bin/${GOARCH}
   mkdir -p "$TARGET"
   go build -o "$TARGET/rand" -v ./cmd/main.go
   cd "$TARGET" || exit
   zip -r "rand_${GOARCH}.zip" rand

   The script is called in the root directory of the repo to generate the zip for arm64 or amd64:
   ./build.sh arm64
./build.sh amd64

3. After the successful builds the artifacts area available in the sub directory:

   Copy

   ./bin
   ├── amd64
   │   ├── rand
   │   └── rand_amd64.zip
   └── arm64
       ├── rand
       └── rand_arm64.zip

   Download these zip artifacts (*.zip) from the app build environment to a local folder of your host-pc so that it can be uploaded via web interface to ctrlX CORE. (Hint: In VS Code the artifact can be downloaded with right click on the zip file in Explorer and click Download.)

Installing the external plugin in ctrlX OS - Telegraf

Creating a Telegraf configuration

Create a new Telegraf configuration before the installation of the plugin. In the ctrlX OS Web-UI click on the “Telegraf” in the sidebar and on “+” to create a new Telegraf configuration. Choose a name of your choice and an empty configuration.

Add the following configuration to your configuration. Be sure to adapt the path to the name of your telegraf-configuration (in this example the configurations name is my-configuration):

[[inputs.execd]]
  command = ["$APP_DATA/my-configuration/rand", "-config", "$APP_DATA/my-configuration/rand.conf"]
  signal = "none"
   
# sample output: write metrics to stdout
[[outputs.file]]
  files = ["stdout"]

Remark: APP_DATA as an alias of the telegraf active configuration directory. APP_DATA=$SNAP_COMMON/solutions/activeConfiguration/telegraf

Upload the external plugin to the ctrlX OS

The Telegraf plugin can now be uploaded via the the app data manager:

1. Click on the icon "Manage app data" in the header bar
   

   

2. Click on the Telegraf folder of the active configuration

3. Navigate into the folder of your configuration (e.g. “my-configration")

4. Click on upload file or file content button
   

   

5. Select the zipped plugin and extract it to the current directory

   

6. Create a new file “rand.conf” (with a click on “+”)

7. Edit the file and add the following configuration
   

   

   Copy

   [[inputs.rand]]
       value_name = "value"
       min = 4
       max = 12

Run the Telegraf configuration and check the logs

The output of this external plugin is written to the console of the the controller. This output can be looked at via the developer view of the diagnostics logbook.

1. Start the Telegraf configuration
   

   

2. Go to "Diagnostics->Logbook" in the sidebar and click on Settings there

3. Enable the Developer view
   

   

4. Have a look at the logger: