HTML Ruby Shell Puppet
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
conf Update mongo connection string in example config Sep 29, 2016
debian Fix Ubuntu 12 regression in debian packaging scripts Mar 9, 2017
examples fix bug in iss example script that failed to convert strings to float… May 8, 2017
lib remove a no-longer-used intermediate config file Apr 4, 2018
puppet Version 1.1.0 Aug 1, 2017
rpm merge no autostart change into beta branch Oct 4, 2016
systemd Install systemd script with deb and fix related issues May 17, 2017
test/integration/default/serverspec Merge branch 'plugins-without-extensions' of… Aug 1, 2017
.ruby-version add .ruby-version to ensure local ruby can be used w/ travelling ruby Jul 15, 2015 Update build instructions Sep 28, 2016 Version 1.1.0 Aug 1, 2017 Add more content about developing for instrumentald Sep 28, 2016
Gemfile HOTFIX packagecloud link Oct 3, 2016
LICENSE add MIT license, maintain parity w/ instrumental_agent Apr 15, 2015 Update Jun 29, 2017 Add a release note about running tests before commit a version change May 8, 2017
Rakefile Install systemd script with deb and fix related issues May 17, 2017 Smooth out test running, particularly puppet Apr 12, 2017


Instrumental is an application monitoring platform built for developers who want a better understanding of their production software. Powerful tools, like the Instrumental Query Language, combined with an exploration-focused interface allow you to get real answers to complex questions, in real-time.

InstrumentalD is a server agent that provides system monitoring and service monitoring. It's fast, reliable, runs on anything *nix, is simple to configure and deploy, and has a small memory footprint.


instrumentald is supported on 32-bit and 64-bit Linux, as well as OSX/macOS. There are prebuilt packages available for Debian, Ubuntu, and RHEL systems.

Detailed installation instructions for supported platforms are available in For linux servers, the recommended installation method is to use a prebuilt package, which will automatically install the application as a service in your operating system's startup list.

Once you've installed the package, you will want to edit the /etc/instrumentald.toml file with your Instrumental project token. Example /etc/instrumentald.toml:

project_token = "YOUR_PROJECT_TOKEN"
system = ["cpu", "disk", "load", "memory", "network", "swap"]
docker = ["unix:///var/run/docker.sock"]
memcached = ["localhost:11211"]
mongodb = ["localhost:27017"]
mysql = ["root@tcp("]
nginx = ["http://localhost:80/status"]
postgresql = ["postgres://postgres@localhost?sslmode=disable"]
redis = ["tcp://localhost:6379"]

System Metrics

Unless configured otherwise, InstrumentalD will collect system metrics from every server on which it's installed, including:

  • CPU Stats
  • Disk Stats
  • Load Stats
  • Memory Stats
  • Network Stats
  • Swap Stats

A detailed list of system metrics collected by InstrumentalD can be found in the Instrumental documentation.

Service Metrics

InstrumentalD is built to make it easy to collect the most important metrics from your critical services. It's currently capable of capturing metrics from the following services:

Custom Plugin Scripts

InstrumentalD can monitor arbitrary processes and system events through a plugin scripting system. Writing plugins is easier than you'd think! Plugin script installation and development instructions are listed in, and we've got several examples to get you started.

Command Line Usage

Basic usage:

instrumentald -k <PROJECT_TOKEN>

To start instrumentald as a daemon:

instrumentald -k <PROJECT_TOKEN> start

The project token can also be provided by setting the INSTRUMENTAL_TOKEN environment variable, which eliminates the need to supply the key via command line option.

By default, instrumentald will use the hostname of the current host when reporting metrics, e.g. 'hostname.cpu.in_use'. To specify a different hostname:

instrumentald -k <PROJECT_TOKEN> -H <HOSTNAME>

The start command will start and detach the process. You may issue additional commands to the process like:

  • stop - stop the currently running instrumentald process
  • restart - restart the currently running instrumentald process
  • foreground - run the process in the foreground instead of detaching
  • status - display daemon status (running, stopped)
  • clean - remove any files created by the daemon
  • kill - forcibly halt the daemon and remove its pid file

By default, instrumentald will look for a configuration file at /etc/instrumentald.toml. You can pass an alternative instead:

instrumentald -k <PROJECT_TOKEN> -H <HOSTNAME> -c <PATH_TO_CONF>

Troubleshooting & Help

We are here to help! Email us at