Riemann is an event stream processor.

Events

Events are just structs. They're sent over Protocol Buffers, and in Riemann are treated as immutable maps. Each event has these (optional) fields:

In addition to these standard fields, events can contain any number of *custom* fields with string values. See Howto: Custom event attributes for more details.

Streams live in the (streams ...) section of your config file. You can think of (streams) as the top level stream, the source from which all events flow. In this documentation, we'll often leave it implied.

Here's a simple stream which sends critical events from any service beginning with "riak" to delacroix@vonbraun.com.

(streams
  (where (and (service #"^riak")
              (state "critical"))
         (email "delacroix@vonbraun.com")))

The first argument to where is the predicate expression, which where uses to test each event. Events which match the predicate are passed to each of where's children, and if they don't match, nothing happens. In this case, there's one child the email stream.

You can think of streams like rivers in the real world. Events flow through tributaries and streams, pool in lakes and dams, and are filtered by grates and boulders. Riemann streams aren't really queries; they're more like pipelines which events flow through.

We need to detect state transitions for each service independently, so we'll start by splitting the event stream with (by).

(by [:host :service])

The (by) stream is like a river delta, or a fuel manifold. It splits the event stream into n distinct streams, each one independent. We get one fork for each unique host and service, so all the events from host 1 and service 1 flow together.

Since we haven't given (by) any child streams yet, it'll just drop every event on the floor. Most streams can take any number of children, so it's common to see something like (by [:host :service] (some-stream ...) (some-other-stream ...) ...).

For each one of those independent streams, we'll detect state transitions with (changed).

(by [:host :service]
    (changed :state))

Whenever an event arrives with a different state than the previous event, (changed :state) passes on the new event to its children. Otherwise, nothing happens.

With those state transitions, we'll roll up more than 5 events per 3600 seconds. In a given hour, rollup will allow four events to pass through immediately. Then it aggregates all successive events in a buffer, which is passed on at the end of the hour.

(by [:host :service]
    (changed :state
             (rollup 5 3600
                     (email "delacroix@vonbraun.com"))))

Rollup's child is an (email) stream, which emails events it receives to Delacroix. I think there's a problem in the sim units today!

Queries

Clients can query the index for particular events using a simple query language. Dashboard views are each powered by a single query. Queries can be applied on the index of past events, but can also tap into the stream of events going to the index in real-time.

# Simple equality
state = "ok"

# Wildcards
(service =~ "disk%") or
(state != "critical" and host =~ "%.trioptimum.com")

# Standard operator precedence applies
metric_f > 2.0 and not host = nil

# Anything with a tag "product"
tagged "product"

# All states
true

Query messages return a list of matching events. See the query tests for tons of examples, or read the full grammar.