Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 218 lines (158 sloc) 7.165 kb
38c6cee @vinibaggio Fixing markdown and adding RMU disclaimer
vinibaggio authored
1 # Outpost
f32779d @vinibaggio Initial commit: README based on RMU's proposal
vinibaggio authored
2
38c6cee @vinibaggio Fixing markdown and adding RMU disclaimer
vinibaggio authored
3 ## Features
f32779d @vinibaggio Initial commit: README based on RMU's proposal
vinibaggio authored
4
d4529a5 @vinibaggio words
vinibaggio authored
5 Outpost is a tool to monitor the state of your service (not server). What does it mean?
f32779d @vinibaggio Initial commit: README based on RMU's proposal
vinibaggio authored
6
7 It means:
8
9 * it can monitor the state of a server, such as MySQL;
10 * it can monitor some business rule to see if everything is running accordingly (such as cron jobs)
11 * it can monitor several servers
12 * it can monitor whatever you can code with Ruby
13
69e6c0e @vinibaggio Better terminology in the README
vinibaggio authored
14 It will connect to the related machines (it won't have any proxies/agents running on the servers to
f32779d @vinibaggio Initial commit: README based on RMU's proposal
vinibaggio authored
15 report data) and collect the data. The idea is to be completely uncoupled with the systems.
16 It should report a status per declared system.
17
18 The idea is to make a reliable framework for the Ruby developer to create his own monitoring rules.
d4529a5 @vinibaggio words
vinibaggio authored
19 So, summing it all up, Nagios in Ruby, much cooler!
f32779d @vinibaggio Initial commit: README based on RMU's proposal
vinibaggio authored
20
b1b4c55 @vinibaggio Added outpost-web as examples
vinibaggio authored
21 ## Information and examples
362bf65 @vinibaggio RDoc link in the README
vinibaggio authored
22
3ca051c @vinibaggio Correcting the README
vinibaggio authored
23 * [Rdoc](http://rdoc.info/github/vinibaggio/outpost/master/frames)
b1b4c55 @vinibaggio Added outpost-web as examples
vinibaggio authored
24 * [outpost-web](http://github.com/vinibaggio/outpost-web)
362bf65 @vinibaggio RDoc link in the README
vinibaggio authored
25
a4a878a @vinibaggio version 0.1.0
vinibaggio authored
26 ## Installing
27
750fc06 @brain-geek Update README with versions of ruby from .travis.yml
brain-geek authored
28 Outpost is tested with Ruby 1.8.7 and Ruby 1.9.3.
cdb306d @vinibaggio words
vinibaggio authored
29
a4a878a @vinibaggio version 0.1.0
vinibaggio authored
30 gem install outpost
31
32 ## Starting
33
34 To create your Outposts, you must require 'outpost'. You also need to include
35 'outpost/scouts' if you want to use the supplied scouts. Example:
36
37 require 'outpost'
38 require 'outpost/scouts'
39
b66a869 @andersonleite Better monitoring name - doc
andersonleite authored
40 class Monitor < Outpost::Application
a4a878a @vinibaggio version 0.1.0
vinibaggio authored
41 using Outpost::Scouts::Http => "web page" do
42 options :host => 'localhost', :port => 3000
43 report :up, :response_code => 200
44 end
45 end
46
b66a869 @andersonleite Better monitoring name - doc
andersonleite authored
47 monitor = Monitor.new
48 monitor.run
49 p monitor.messages # => ["Outpost::Scouts::Http: 'web page' is reporting up."]
a4a878a @vinibaggio version 0.1.0
vinibaggio authored
50
51
d4529a5 @vinibaggio words
vinibaggio authored
52 ## How it works
f32779d @vinibaggio Initial commit: README based on RMU's proposal
vinibaggio authored
53
54 Consider the following example:
55
a4a878a @vinibaggio version 0.1.0
vinibaggio authored
56 require 'outpost'
57 require 'outpost/scouts'
58
3715f86 @vinibaggio Outpost::DSL -> Outpost::Application
vinibaggio authored
59 class HttpOutpostExample < Outpost::Application
a4a878a @vinibaggio version 0.1.0
vinibaggio authored
60 using Outpost::Scouts::Http => "web page" do
a83d5d2 @vinibaggio Ops, fixing words
vinibaggio authored
61 options :host => 'localhost', :port => 3000
62 report :up, :response_code => 200
493e964 @vinibaggio Let's deal with a realistic example
vinibaggio authored
63 report :down, :response_body => {:match => /Ops/}
a83d5d2 @vinibaggio Ops, fixing words
vinibaggio authored
64 end
65 end
f1fafc5 @vinibaggio words
vinibaggio authored
66 outpost = HttpOutpostExample.new
7968ede @vinibaggio Better README
vinibaggio authored
67 outpost.run # => :down
f32779d @vinibaggio Initial commit: README based on RMU's proposal
vinibaggio authored
68
7968ede @vinibaggio Better README
vinibaggio authored
69 In this simple example, an Outpost was created to monitor a web server running
2c96355 @vinibaggio words
vinibaggio authored
70 on localhost at port 3000. Every time #run is called, the outpost will
7968ede @vinibaggio Better README
vinibaggio authored
71 run associated rules (in this example, check if the HTTP response code is 200
72 and report "up" if it does and also check if the response body matches /Ops/,
73 reporting "down" in that case).
f32779d @vinibaggio Initial commit: README based on RMU's proposal
vinibaggio authored
74
d4529a5 @vinibaggio words
vinibaggio authored
75 ## Outpost
76
be29dab @vinibaggio Creating outposts without subclassing
vinibaggio authored
77 Outpost is the description of the system and provides a DSL to do it.
3715f86 @vinibaggio Outpost::DSL -> Outpost::Application
vinibaggio authored
78 Check "How it works" section for an example, or check the [integration tests](https://github.com/vinibaggio/outpost/blob/master/test/integration/basic_application_test.rb)
d4529a5 @vinibaggio words
vinibaggio authored
79 for more.
80
81 ## Scout
82
83 Scout are pure Ruby classes that will test your server. For instance, check the
5c8926e @vinibaggio Updating README to reflect the new changes
vinibaggio authored
84 Outpost::Scouts::Http example below:
d4529a5 @vinibaggio words
vinibaggio authored
85
a83d5d2 @vinibaggio Ops, fixing words
vinibaggio authored
86 module Outpost
5c8926e @vinibaggio Updating README to reflect the new changes
vinibaggio authored
87 module Scouts
88 class Http < Outpost::Scout
89 extend Outpost::Expectations::ResponseCode
90 extend Outpost::Expectations::ResponseBody
91
92 attr_reader :response_code, :response_body
93
94 def setup(options)
95 @host = options[:host]
96 @port = options[:port] || 80
97 @path = options[:path] || '/'
98 end
99
100 def execute
101 response = Net::HTTP.get_response(@host, @path, @port)
102 @response_code = response.code.to_i
103 @response_body = response.body
104 end
a83d5d2 @vinibaggio Ops, fixing words
vinibaggio authored
105 end
106 end
d4529a5 @vinibaggio words
vinibaggio authored
107 end
108
109 It must implement the #setup and #execute methods. The magic lies in the #execute
110 method, where you can implement any kind of logic to test whether your system is up
5c8926e @vinibaggio Updating README to reflect the new changes
vinibaggio authored
111 or not. You may also include expectations in order to process the output of your system.
112 For more information about expectations, check the section below.
d4529a5 @vinibaggio words
vinibaggio authored
113
5c15e09 @vinibaggio Updating Changelog, Readme and TODO about the latest reporting feature
vinibaggio authored
114 If you're interested in the data the Scouts got through a measurement, you can
115 tell Outpost that it must save that data after the measurement is run. That way
116 you can inquiry it for further analysis. This way, you can have Scouts without
117 any expectations/reports, so you can collect data without telling if the system
118 is either up or down. You can check an usage example in the [Reports
119 integration
120 test](https://github.com/vinibaggio/outpost/blob/master/test/integration/reporting_test.rb).
121
5c8926e @vinibaggio Updating README to reflect the new changes
vinibaggio authored
122 ## Expectations
d4529a5 @vinibaggio words
vinibaggio authored
123
8a300e9 @vinibaggio Trying to clarify what are hooks
vinibaggio authored
124 Consider the following code snippet, taken from previous examples:
125
126 report :up, :response_code => 200
127 report :down, :response_body => {:match => /Ops/}
128
5c8926e @vinibaggio Updating README to reflect the new changes
vinibaggio authored
129 In the example above, :response\_code and :response\_body are expectations, responsible
8a300e9 @vinibaggio Trying to clarify what are hooks
vinibaggio authored
130 to get Scout's output and evaluate it, in order to determine a status.
131
132 They must be registered into each Scout that wish to support different types
5c8926e @vinibaggio Updating README to reflect the new changes
vinibaggio authored
133 of expectations. You can supply a block or an object that respond to #call
413371b @vinibaggio more words
vinibaggio authored
134 and return true if any of the rules match. It will receive an instance
be29dab @vinibaggio Creating outposts without subclassing
vinibaggio authored
135 of the scout (so you can query current system state) as the first parameter
413371b @vinibaggio more words
vinibaggio authored
136 and the state defined in the #report method as the second.
d4529a5 @vinibaggio words
vinibaggio authored
137
5c8926e @vinibaggio Updating README to reflect the new changes
vinibaggio authored
138 So you can easily create your own expectation. Let's recreate the :response\_code in
139 Outpost::Scouts::Http:
d4529a5 @vinibaggio words
vinibaggio authored
140
a83d5d2 @vinibaggio Ops, fixing words
vinibaggio authored
141 module Outpost
5c8926e @vinibaggio Updating README to reflect the new changes
vinibaggio authored
142 module Scouts
143 class Http < Outpost::Scout
144 expect(:response_code) { |scout,code| scout.response_code == code }
145
146 attr_reader :response_code
147
148 def setup(options)
149 @host = options[:host]
150 @port = options[:port] || 80
151 @path = options[:path] || '/'
152 end
153
154 def execute
155 response = Net::HTTP.get_response(@host, @path, @port)
156 @response_code = response.code.to_i
157 end
a83d5d2 @vinibaggio Ops, fixing words
vinibaggio authored
158 end
159 end
d4529a5 @vinibaggio words
vinibaggio authored
160 end
161
5c8926e @vinibaggio Updating README to reflect the new changes
vinibaggio authored
162 You can also check the supplied expectations in the source of the project to have
d4529a5 @vinibaggio words
vinibaggio authored
163 an idea on how to implement more complex rules.
164
cadf334 @vinibaggio Notifiers.
vinibaggio authored
165 ## Notifiers
166
167 Notifiers query Outposts and act upon its status and reports. In the example
168 below, an Email notifier is being used to report failures in the system to the
169 system administrator:
170
171 require 'outpost'
172 require 'outpost/scouts'
173 require 'outpost/notifiers'
174
3715f86 @vinibaggio Outpost::DSL -> Outpost::Application
vinibaggio authored
175 class HttpOutpostExample < Outpost::Application
cadf334 @vinibaggio Notifiers.
vinibaggio authored
176 notify Outpost::Notifiers::Email, {
177 :from => 'outpost@example.com',
178 :to => 'sleep_deprived_admin@example.com'
179 }
180
181 using Outpost::Scouts::Http => "web page" do
182 options :host => 'localhost', :port => 3000
183 report :up, :response_code => 200
184 report :down, :response_body => {:match => /Ops/}
185 end
186 end
187 outpost = HttpOutpostExample.new
188 outpost.run # => :down
189
190 # Will send an email to the poor sleep-deprived Sys Admin if the system is
191 # down.
192 outpost.notify if outpost.down?
193
be29dab @vinibaggio Creating outposts without subclassing
vinibaggio authored
194 ## Creating Outpost applications programatically
195
196 It is also possible to create Outposts without having to subclass it. Use the
197 methods #add_scout and #add_notifier and you're set:
198
199 outpost = Outpost::Application.new
5c15e09 @vinibaggio Updating Changelog, Readme and TODO about the latest reporting feature
vinibaggio authored
200
be29dab @vinibaggio Creating outposts without subclassing
vinibaggio authored
201 outpost.add_scout Outpost::Scouts::Http => 'master http server' do
202 options :host => 'localhost', :port => 9595
203 report :up, :response_code => 200
204 end
205
206 outpost.run
207
208 This is good when you want to have some sort of template (by inheriting from
209 Outpost::Application) and then configure things as you go.
210
d4529a5 @vinibaggio words
vinibaggio authored
211 ## TODO
212
0a3ec0d @vinibaggio Mentioning TODO in Readme
vinibaggio authored
213 See [TODO](https://github.com/vinibaggio/outpost/blob/master/TODO.md).
90b0d13 @vinibaggio Adding license
vinibaggio authored
214
215 ## License
216
c5c0832 @vinibaggio Adding MIT license
vinibaggio authored
217 MIT License.
Something went wrong with that request. Please try again.