Leo is an extension to the NAD (Node Agent Daemon) client which will automatically create a check, a set of graphs, and a worksheet for a particular host. Leo’s goal is to make configuration of a host as simple as possible.

After running a simple command line script, you will be able to log into your Circonus account and view graphs for CPU Usage, Disk, Network, and Memory utilization, as well as a worksheet for your host. Leo will prompt you for information such as IP or hostname, Circonus auth token, Broker id, and the location of a config file. Then, it will take that information  and give it to NAD, which will use it to create the check, graphs, and worksheet.

If you decide try Leo, we would love to hear your feedback. You can send any comments, including what you liked, what you thought could be improved, and any questions, to: [email protected]

To get started with Leo, visit our youtube channel and watch our tutorials for installing and configuring Leo:

Installation Tutorial


  1. This program is installed on an amazon web services ec2 instance running CentOS.
  2. You must have node.js and nad already installed.

More info on NAD is available on github here.

There are two ways to install Leo: wget and git clone.


# wget https://github.com/circonus-labs/leo/archive/master.zip
# unzip master.zip
# cd leo-master
# npm install

git clone

# git clone https://github.com/circonus-labs/leo.git
# cd leo
# npm install

There is a third way to install leo that is not included in the video. This method takes into account that Leo is published as an npm module as circonus-leo. However, this method is not recommended because it will require users to go through the node_modules directory before it can reach Leo, and consequently adds an extra step to the process of running Leo.


# npm install

Configuration Tutorial


The instructions below assume that you installed Leo using git clone. If you used wget or npm, the instructions are the same, but you access Leo through the leo-master directory for wget, and go through node_modules/leo for npm.

To get an auth/API token:

  1. On your Circonus account, go to “API Tokens” under the “User” section of the Main Menu and click “New API Token +”
  2. In your terminal write :
    # leo/bin/circonus-setup -k ["YOUR API TOKEN"] -t ["YOUR IP ADRESS OR HOSTNAME"]
  3. Hit enter. You will receive an error saying “App: nad still pending approval”
  4. Then go back to your Circonus account and refresh your “API Tokens” page. You should now have an option to allow NAD access.
  5. Click the “Allow Access” option.

To find your Broker Id:

  1. Go to your Dashboard and click the “manage brokers” option above the map that displays all of the brokers.
  2. Click the menu symbol (the little hamburger) to the left of the broker you want to use.
  3. Click “view API object”. The number that comes after ‘”_cid”: “/broker/’ is your broker id. For example, if the API object read “_cid”: “/broker/3”, the broker id would be 3.

You can either configure Leo with one command line request that contains all of your information or run Leo and let it prompt you for your info.

Command Line Request

This example is using the default settings, which includes a JSON check, 4 graphs (CPU Usage, Disks, Network, and Memory), and a worksheet containing that check and those 4 graphs:

 # leo/bin/circonus-setup -k ["YOUR API TOKEN"] -t ["YOUR IP ADRESS OR HOSTNAME"] -b ["BROKER ID"] --alldefault 

Once you hit enter, it will prompt you to save your settings to a config file. Either enter in the name of the file to which you want your information to be saved, or just hit enter to skip this step. Then it should tell you that 1 check, 4 graphs, and 1 worksheet have been created.

Letting Leo Prompt You

# leo/bin/circonus-setup 

After running this code, Leo will prompt you for your auth token, target, broker id, whether or not you want to use the defaults settings (if you say no you can use the type of check you want to create and the metrics you want), and for a config file to which it will send your information. It will then create a check, graphs, and a worksheet based on the information you provided.

Let’s look at Leo in action through the creation of a JSON check and its counterparts:

Checks & Metrics

Leo can create either a JSON check or a PostgreSQL check containing up to 155 different metrics.



One worksheet will be created for each configured check.



If you choose to create a JSON check, Leo and NAD will create a graph for CPU, Disk space, Memory, and Network utilization. For a PostgreSQL check, Leo and NAD will create a PostgreSQL Connections graph.


Get blog updates.

Keep up with the latest in telemtry data intelligence and observability.