Getting Started

So, you're getting a monitoring and alerting environment set up. You've looked around at your options, and you've either decided to graduate from what everyone else is using, or you're starting fresh. In any event: welcome!

Hopefully you'll come to find Arborist a reliable, trustworthy framework for describing and reporting on the state of your environment. We made this system specifically so you can get some sleep. Ultimately, if you never think about monitoring after it is set up -- then it's doing it job. You deserve a raise. Failing that, at least a power nap on the company time. Perhaps you'd prefer a handful of paper clips and white-out from the office cabinet? Who knows what floats your boat.

The point is, you're here, and you're good. Lets talk about Arborist.

First things first, if you're just looking for a general description of what sets Arborist apart, head over to the Overview and skim through that. It's meant to be a bit more high-level manager hand-wavey -- this document is going to get more into the nitty gritty of a setup. Did you read it? No? I'll wait. Take your time.


Hopefully you're back now, and ready to roll up your sleeves.


The Arborist core is written in Ruby. There aren't any external dependencies -- no hall of mirrors, chicken-and-egg setups where your monitoring environment relies on services that it itself should be monitoring.

To install it, simply install ruby, and run:

gem install arborist

It will pull in any required ruby modules. When finished, you'll be armed with a new arborist command at your disposal. Run it!

    arborist - Arborist

    arborist [global options] command [command options] [arguments...]


    -c, --config=CONFIGFILE - Load the specified CONFIGFILE. (default: none)
    -d, --[no-]debug        - Enable debugging output
    --help                  - Show this message
    -l, --loglevel=LEVEL    - Set log level to LEVEL (one of debug, info, warn, error, fatal) (default: none)
    -n, --[no-]dry-run      - Don't actually do anything, just show what would happen.
    -r, --requires=arg      - Additional Ruby libs to require before doing anything. (default: none)
    -v, --[no-]verbose      - Enable verbose output
    --version               - Display the program version

    client - Start an interactive client session
    config - Dump a default Arborist config file
    help   - Shows a list of commands or help for one command
    start  - Start an Arborist daemon
    watch  - Watch events in an Arborist manager

If you see something similar to the above, congratulations, we're ready to start getting things monitored.

The arborist command has a variety of uses:

As we get things initially set up, in the interests of simplicity I'm going to assume you'll be running everything on a single machine. I'll show you how to scale it out later.

Make (and enter) a directory that's going to hold your configurations -- how about /usr/local/arborist?

mkdir /usr/local/arborist
cd /usr/local/arborist

Although Arborist doesn't need a configuration file to run (it has sane defaults for everything), we're going to generate one now anyway, so we don't have to later, when we want to change things.

arborist config > arborist.conf

Arborist uses Configurability to manage settings. Don't worry about what these things do yet, we'll get into them soon. Again, those are all the default values.

Your config file should look something like so...

  __default__: warn STDERR
  tree_api_url: ipc:///tmp/arborist_tree.sock
  event_api_url: ipc:///tmp/arborist_events.sock
    status_history_size: 0
    flap_threshold: 0
    checkpoint_frequency: 30.0
    heartbeat_frequency: 1.0
    linger: 5.0

These are the defaults. Okay. Lets get that Manager Daemon running.