-
Notifications
You must be signed in to change notification settings - Fork 515
/
quickstart.html
236 lines (184 loc) · 10 KB
/
quickstart.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
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
---
title: Riemann - Quickstart
layout: default
---
<style>
body {
background: #88ff00; /* Old browsers */
background: -moz-radial-gradient(center, ellipse cover, #88ff00 0%, #68ad00 100%); /* FF3.6+ */
background: -webkit-gradient(radial, center center, 0px, center center, 100%, color-stop(0%,#88ff00), color-stop(100%,#68ad00)); /* Chrome,Safari4+ */
background: -webkit-radial-gradient(center, ellipse cover, #88ff00 0%,#68ad00 100%); /* Chrome10+,Safari5.1+ */
background: -o-radial-gradient(center, ellipse cover, #88ff00 0%,#68ad00 100%); /* Opera 12+ */
background: -ms-radial-gradient(center, ellipse cover, #88ff00 0%,#68ad00 100%); /* IE10+ */
background: radial-gradient(ellipse at center, #88ff00 0%,#68ad00 100%); /* W3C */
filter: progid:DXImageTransform.Microsoft.gradient( startColorstr='#88ff00', endColorstr='#68ad00',GradientType=1 ); /* IE6-9 fallback on horizontal gradient */
}
</style>
<div class="row">
<h1>Ready? <span class="focus">Let's go!</span></h1>
</div>
<div class="row">
<div class="twelvecol">
<p class="callout">For this tutorial, you'll need a *nix system, Java,
and Ruby.</p>
</div>
</div>
</div><!-- main -->
<div class="light">
<div class="container">
<div class="row">
<div class="sixcol">
<h2>Installing Riemann</h2>
<p>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 <a
href="/howto.html#putting-riemann-into-production">Putting
Riemann into production</a> for tips.</p>
{% highlight shell_session %}
$ wget https://github.com/riemann/riemann/releases/download/0.3.11/riemann-.tar.bz2
$ tar xvfj riemann-.tar.bz2
$ cd riemann-
{% endhighlight%}
<p>Check the md5sum to verify the tarball:</p>
{% highlight shell_session %}
$ wget https://github.com/riemann/riemann/releases/download/0.3.11/riemann-.tar.bz2.md5
$ md5sum -c riemann-.tar.bz2.md5
{% endhighlight%}
<p>You can also install Riemann via the Debian or RPM packages, through
<a href="https://forge.puppetlabs.com/garethr/riemann">Puppet</a>, <a
href="https://github.com/garethr/riemann-vagrant">Vagrant</a>, or <a
href="https://github.com/hudl/riemann-cookbook">Chef</a>.</p>
<p>Start the server</p>
<code><pre>bin/riemann etc/riemann.config</pre></code>
<p>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.</p>
<code><pre>gem install riemann-client riemann-tools riemann-dash</pre></code>
<p>Start the dashboard. If riemann-dash isn't in your path, check your
rubygems bin directory.</p>
<code><pre>riemann-dash</pre></code>
<p>Point your web browser to <a
href="http://localhost:4567/">http://localhost:4567/</a>. 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.</p>
<p>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.</p>
<p>Then, press "e" to edit, and change "Title" to "Grid". We need to
choose a <i>query</i> to select specific states from the index. For
starters, let's select <i>everything</i> by typing <code>true</code> in
the query field. Hit "Apply" when you're ready.</p>
<p>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.</p>
<p>Right now the index is empty, so you won't see any events. Let's send
some:</p>
<code><pre>riemann-health</pre></code>
<p>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.</p>
<h2>Working with Clients</h2>
<p>Now that Riemann is installed, let's try sending some of our own
states through the Ruby client.</p>
<code><pre><span class="unfocus">$</span> irb -r riemann/client
<span class="unfocus">ruby-1.9.3 :001 ></span> r = Riemann::Client.new
<span class="unfocus"> => #<Riemann::Client ... ></span></pre></code>
<p>We can send events with <code><<</code>. For example, let's log an HTTP request.</p>
<code><pre><span class="unfocus">ruby-1.9.3 :002 ></span> r << {
host: "www1",
service: "http req",
metric: 2.53,
state: "critical",
description: "Request took 2.53 seconds.",
tags: ["http"]
}</pre></code>
<p>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 <code>host: nil</code>.</p>
<p>Now let's ask for all events that have a service beginning with
"http".</p>
<code><pre><span class="unfocus">ruby-1.9.3 :003 ></span> r['service =~ "http%"']
<span class="unfocus">[<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>]</span></pre></code>
<p>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.</p>
</div>
<div class="sixcol last">
<h2>Get started with your own streams</h2>
<p>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.</p>
<p>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.</p>
<p>The <code>Riemann/streams</code> namespace provides a number of functions that handle common stream processing tasks.</p>
<p>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 <code>streams</code> function.<p>
<p>Add the following to the bottom of the <code>riemann.config</code> file:</p>
{% highlight clj %}
(streams
prn)
{% endhighlight %}
<p>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.</p>
<p>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.</p>
{% highlight clj %}
(streams
prn
(with {:state "normal"} prn)
prn)
{% endhighlight %}
<p>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.</p>
<p>The <code>streams</code> statement adds each stream function to the current core. This means the following two statements are equivalent.</p>
{% highlight clj %}
(streams
prn
(with {:state "normal"} prn)
prn)
{% endhighlight %}
{% highlight clj %}
(streams prn)
(streams (with {:state "normal"} prn))
(streams prn)
{% endhighlight %}
<p>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 <a href="howto.html">howto guide</a>.</p>
<h2>What next?</h2>
<p>James Turnbull has written a <a
href="http://kartar.net/2014/12/an-introduction-to-riemann/">beautiful
introduction to Riemann</a> which takes you through the whole setup
process and monitoring some basic services.</p>
<p>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 <a href="/concepts.html">Riemann core
concepts</a>, and use <code>etc/riemann.config</code> as a guide for
your own configuration. When you're ready to run Riemann in production,
check out <a
href="/howto.html#changing-the-config">Changing the
config</a> and <a
href="/howto.html#putting-riemann-into-production">Putting
Riemann into production</a>.</p>
<p>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 <a
href="http://aphyr.com/posts/301-clojure-from-the-ground-up-welcome">structure</a>,
<a
href="http://aphyr.com/posts/302-clojure-from-the-ground-up-basic-types">basic
types</a>, and <a
href="http://aphyr.com/posts/303-clojure-from-the-ground-up-functions">functions</a>,
which should equip you with all the fundamentals.</p>
</div>
</div>
</div>