InstrumentalD

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.

Installation

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 INSTALL.md. 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(127.0.0.1:3306)/"]
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:

• Docker
• MySQL
• Memcached
• MongoDB
• Nginx
• PostgreSQL
• Redis

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 PLUGIN_SCRIPTS.md, 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 [email protected].