Ready? Let's go!

For this tutorial, you'll need a *nix system, Java, and Ruby.

Installing Riemann

Riemann's components are all configured to work out-of-the-box on localhost, and this quickstart assumes you'll be running everything locally. If you're jumping right into running Riemann on multiple nodes, check out Putting Riemann into production for tips.

$ wget https://github.com/riemann/riemann/releases/download/0.3.11/riemann-.tar.bz2
$ tar xvfj riemann-.tar.bz2
$ cd riemann-

Check the md5sum to verify the tarball:

$ wget https://github.com/riemann/riemann/releases/download/0.3.11/riemann-.tar.bz2.md5
$ md5sum -c riemann-.tar.bz2.md5

You can also install Riemann via the Debian or RPM packages, through Puppet, Vagrant, or Chef.

Start the server

bin/riemann etc/riemann.config

Riemann is now listening for events. Install the Ruby client, utility package, and dashboard. You may need to install ruby-dev for some dependencies; your OS package manager should have a version available for your Ruby install.

gem install riemann-client riemann-tools riemann-dash

Start the dashboard. If riemann-dash isn't in your path, check your rubygems bin directory.

riemann-dash

Point your web browser to http://localhost:4567/. You'll see a big title in the top pane and a quick overview of the control scheme in the bottom pane. At the top right is the current host your browser is connected to. At the top left is the pager, which shows your workspaces--like tabs, in a browser.

Let's change the title into a Grid view. Hold CTRL (or OPTION/META depending on your OS) and click the big title "Riemann" in the top pane. The title will be shaded grey to indicate that view is selected.

Then, press "e" to edit, and change "Title" to "Grid". We need to choose a query to select specific states from the index. For starters, let's select everything by typing true in the query field. Hit "Apply" when you're ready.

This new view is likely a little small, so hit "+" a few times to make it bigger. Views are rescaled relative to their neighbors in a container.

Right now the index is empty, so you won't see any events. Let's send some:

riemann-health

The riemann-health daemon is a little Ruby program that submits events about the state of your CPU, memory, load, and disks to a Riemann server. If you switch back to the dashboard, you'll see your local host's state appear. The Grid view organizes events according to their host and service. Color indicates state, and the shaded bars show metrics. You can hover over an event, like CPU, to see its description.

Working with Clients

Now that Riemann is installed, let's try sending some of our own states through the Ruby client.

$ irb -r riemann/client
ruby-1.9.3 :001 > r = Riemann::Client.new
 => #<Riemann::Client ... >

We can send events with <<. For example, let's log an HTTP request.

ruby-1.9.3 :002 > r << {
host: "www1",
service: "http req",
metric: 2.53,
state: "critical",
description: "Request took 2.53 seconds.",
tags: ["http"]
}

On the dashboard, critical events (like the one we just submitted) show up in red. All of these fields are optional, by the way. The ruby client will assume your events come from the local host name unless you pass host: nil.

Now let's ask for all events that have a service beginning with "http".

ruby-1.9.3 :003 > r['service =~ "http%"']
[<Riemann::Event time: 1330041937,
state: "critical",
service: "http req",
host: "www1",
description: "Request took 2.53 seconds.",
tags: ["http"],
ttl: 300.0,
metric_f: 2.5299999713897705>]

There's the event we submitted. You could send these events from Rack middleware to log every request to your app, or track exceptions. Riemann can be configured to calculate rates, averages, min/max, distributions, and more.

Get started with your own streams

A stream is just a function that takes a variable number of child streams and returns a function that takes an event and responds to the event it is passed when it is invoked.

Streams can modify an event and pass the modified event on to their child streams. Alternatively they can look at the event and choose which of the child streams to pass the event onto, filtering or partitioning the event stream.

The Riemann/streams namespace provides a number of functions that handle common stream processing tasks.

By default the Riemann config file contains a stream definition that writes each incoming event into the index. We can create more streams by using the streams function.

Add the following to the bottom of the riemann.config file:

      (streams
        prn)

To test this configuration, reload it and then send an event via the irb shell. The content of the event should be printed in the Riemann log.

When Riemann receives an event it passes it on to all the streams that are registered. When a stream processes an event it can pass the event, or a modified version of it onto its child streams. Let's modify our code to demonstrate this.

      (streams
        prn
        (with {:state "normal"} prn)
        prn)

Now when you submit an event it should get printed three times and you should see that one event has a state of "normal" (the one resulting from the middle stream) and the other two have a state of nil.

The streams statement adds each stream function to the current core. This means the following two statements are equivalent.

      (streams
        prn
        (with {:state "normal"} prn)
        prn)
      
      (streams prn)
      (streams (with {:state "normal"} prn))
      (streams prn)

You can now starting adding stream statements to the configuration file to start processing your own events. For specific examples of common event processing tasks see the howto guide.

What next?

James Turnbull has written a beautiful introduction to Riemann which takes you through the whole setup process and monitoring some basic services.

Riemann comes with a standard config that listens on the local ipv4 interface and indexes all events, but that's just the the start. You can learn a little more about Riemann core concepts, and use etc/riemann.config as a guide for your own configuration. When you're ready to run Riemann in production, check out Changing the config and Putting Riemann into production.

Riemann's config is a Clojure program. A little bit of Clojure knowledge will help clear up where to use parentheses, how functions work, and how to write more advanced streams. I've written a concise guide for Clojure's structure, basic types, and functions, which should equip you with all the fundamentals.