TrueSight API Documentation
OverviewAccountActionsAdministration
Alarms v1Alarms v2BatchingDashboards
DatasetsEventsExtended Metrics
GroupsHostgroupsMetersMetricsProduct
PluginsRelaysSourcesSource-TagsSynchronize Data
Tenants
Terms

Relays

Relay serves as plug-in manager for TrueSight Pulse plugins. TrueSight Pulse Meter already includes built-in Relay service, which is automatically started with the Meter and ready to be used immediately. Relay securely communicates with TrueSight Pulse SaaS to allow you to manage the Relay remotely, either to install / uninstall plugins or set configuration.

Note: Previously TrueSight Pulse Graphdat Relay was a separate app (written in NodeJS), that had to be installed separately. The instructions below are only relevant for deprecated Graphdat Relay used with Graphdat Agent. This is unsupported configuration, all users should uninstall Graphdat Agent and Relay and migrate to TrueSight Pulse Meter, which replaces both Agent and Relay. See more details in this help article.

Installation (no longer relevant if TrueSight Pulse Meter used)

Because graphdat-relay is built with NodeJS you must first insure that NodeJS is installed, and it should is up to date. Run

node -v

to see your version of NodeJS. TrueSight Pulse (and many other modules you will encounter) require at a minimum node v0.8.1. If you are running v0.6.x, you need to jump over to NodeJS and grab a newer version of node. Both v0.8.x (stable) and v0.10.x (latest) will do nicely.

Once NodeJS is installed simply use the Node Package Manager to install graphdat-relay:

[sudo] npm install graphdat-relay -g

Configuration

The only information graphdat-relay requires when launching is the email and API token. These can both be found in the Account tab of your Settings dialog. You should then create a directory where you wish to run the relay and create a configuration file called config.json with this information. The relay should be given permissions to read/write within this directory because the relay will need to download/install plugins as well as configuration files.

For example, assuming we want to use a folder called '.graphdat-relay' we can do:

mkdir ~/.graphdat-relay
cd ~/.graphdat-relay
graphdat-relay -e "your email address" -t "your api token"

Once you created the config.json try launching:

sudo graphdat-relay

If all is successful you should see the host name appear in the Relays tab of the Settings dialog.

Running as a daemon/service

Because you will most likely want to run the relay in the background and have it launch on system startup it is recommended that you launch it as a daemon on Linux, or service on Windows.

There are many common ways of setting up a daemon/service depending on your OS.

To daemonize the process on linux, follows these steps.

# create the relay configuration directory
sudo mkdir -p /etc/graphdat-relay
cd /etc/graphdat-relay

# create the relays configuration file
sudo graphdat-relay -e your-email -t your-token

# if you get a "sudo: graphdat-relay: command not found" error
# the graphdat-relay is not in sudo's path
# run "which graphdat-relay" to get the location of the relay
# and update the command above with that value

# if you get a "/usr/bin/env: node: No such file or directory" error
# node is not in sudo's path.
# run "which node" and add the PATH to the command
# sudo PATH=$PATH:nodepath graphdat-relay -e your-email -t your-token

# download the init.d script for your OS

# * Debian/Ubuntu (https://gist.github.com/codemoran/7441959)
sudo curl --output /etc/init.d/graphdat-relay \
https://gist.github.com/codemoran/7441959/raw/bb3aa37c0052f87736f8b3ba57c3edccca520c07/graphdat-relay-debian-init

# * Redhat/CentOS (https://gist.github.com/codemoran/7442551)
sudo curl --output /etc/init.d/graphdat-relay \
https://gist.githubusercontent.com/codemoran/7442551/raw/067109faff11c0d70ced13fd99b75cc175feae58/graphdat-relay-redhat-init

# make the init script executable
sudo chmod +x /etc/init.d/graphdat-relay

# The init file has the following configuration options
# * CONFIG=/etc/graphdat-relay
# * DAEMON=$(which graphdat-relay-daemon)
# * NODEBIN=$(which node)
# If these values are not correct,
# edit the /etc/init.d/graphdat-relay and update

# add the relay to auto start up
sudo update-rc.d graphdat-relay defaults

# start the relay
sudo /etc/init.d/graphdat-relay start

# check the status of the relay
sudo /etc/init.d/graphdat-relay status

# stop the relay
sudo /etc/init.d/graphdat-relay stop

And for Windows there are tools such as svrstart and FireDaemon to create a Windows service.