forked from riemann/riemann
/
concepts.html
125 lines (105 loc) · 4.13 KB
/
concepts.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
---
title: Riemann - Core Concepts
layout: default
---
<h1>Riemann is an <span class="focus">event stream</span> processor.</h1>
<p>Every time something important happens in your system, submit an event
to Riemann. Just handled an HTTP request? Send an event with the time it
took. Caught an exception? Send an event with the stacktrace. Small
daemons can watch your servers and send events about disk capacity, CPU
use, and memory consumption. Every five seconds. It's like top for
hundreds of machines at once.</p>
<p class="callout">Riemann filters, combines, and acts on flows of events to yield useful information.</p>
<div class="cards">
<div class="card">
<h2>Events</h2>
<p>Events are just structs. They're sent over Protocol Buffers, and
in Riemann are treated as immutable maps. Each event has these
(optional) fields:</p>
<table>
<tr>
<th>host</th>
<td>A hostname, e.g. "api1", "foo.com"</td>
</tr>
<tr>
<th>service</th>
<td>e.g. "API port 8000 reqs/sec"</td>
</tr>
<tr>
<th>state</th>
<td>Any string less than 255 bytes, e.g. "ok", "warning", "critical"</td>
</tr>
<tr>
<th>time</th>
<td>The time of the event, in unix epoch seconds</td>
</tr>
<tr>
<th>description</th>
<td>Freeform text</td>
</tr>
<tr>
<th>tags</th>
<td>Freeform list of strings, e.g. ["rate", "fooproduct", "transient"]</td>
</tr>
<tr>
<th>metric</th>
<td>A number associated with this event, e.g. the number of reqs/sec.</td>
</tr>
<tr>
<th>ttl</th>
<td>A floating-point time, in seconds, that this event is considered valid for. Expired states may be removed from the index.</td>
</tr>
</table>
</div>
<div class="card">
<h2>Servers</h2>
<p>The Riemann process listens on port 5555 for TCP connections and
UDP datagrams. It accepts a stream of protocol buffer <i>messages</i>
containing <i>events</i> (or queries, control messages, etc). Those
events are then applied to a tree of <i>streams</i>.</p>
</div>
<div class="card">
<h2>Streams</h2>
<p>A stream is a function that accepts a single event. Many streams
accept children, to which they can forward events. Together, the
streams form a directed graph along which events flow.</p>
<p>A stream can filter the events it receives, passing on those that
match some predicate. They can pass on a changed event to their
children, or fork into several distinct substreams. They can compute
percentiles, rates, or moving averages. Streams can send email about
the events they receive, forward events to other Riemann servers, or
send them to Graphite. Any clojure function accepting an event map
can be a stream.</p>
<p>See the <a href="api/riemann.streams.html">Streams API</a> for details.</p>
</div>
<div class="card">
<h2>The Index</h2>
<p>A special type of stream updates the index: a table of the current
state of all services tracked by Riemann. Indexed states can be queried by a Riemann client to see what the system looks like now. The <a href="dashboard.html">Dashboard</a> is just an HTML view of the index.</p>
<p>Events entered into the index have a :ttl field; states that sit
in the index for too long are removed from the index and reinserted
into the event streams with state "expired". This means that services
which fail to check in regularly enough can trigger alerts.</p>
</div>
<div class="card">
<h2>Queries</h2>
<p>Clients can query the index for particular events.</p>
{% highlight clj %}
# 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
# No states
false
{% endhighlight %}
<p>Query messages return a list of matching events. The full grammar is <a
href="https://github.com/aphyr/riemann/blob/master/src/riemann/Query.g">here</a>.</p>
</div>
</div>