Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 250 lines (197 sloc) 8.502 kB
e95947f @zoka First cut of extraxting fuctionality into ring handler. Not working yet.
authored
1 # ringMon
5904d3a @zoka init
authored
2
610f452 @zoka Added 2-dimensional JSON tables display feature to browser client.
authored
3 A Ring middleware that injects single monitoring page into a Clojure
32898f7 @zoka more README
authored
4 web application based on
5 [Ring]( https://github.com/mmcgrana/ring)
6 library or on higher level web frameworks such as
7 [Noir](https://github.com/ibdknox/noir)
8 or
9 [Compojure](https://github.com/weavejester/compojure).
610f452 @zoka Added 2-dimensional JSON tables display feature to browser client.
authored
10 It is also easily added as a dev dependency to any Clojure applications
32898f7 @zoka more README
authored
11 as well. Actually, it could be incorporated into any JVM (non-Clojure) application
12 with bit more work - planned for later.
13
14 The page displays raw JMX data of interest in tree alike structure.
15 It also shows
16 derived values such as CPU load that is calculated by
17 sampling JMX property OperatingSystem.ProcessCpuTime every
18 2 seconds and statistics for AJAX requests to the middlware itsef.
19 There is also a button to force JVM garbage collection.
9ea2c77 @zoka first cut of the ringMon than can run standalone as a bare Ring app
authored
20
ff31163 @zoka Release 0.1.1
authored
21 Moreover, the page provides full featured
22 [nREPL](https://github.com/clojure/tools.nrepl)
f88ffa0 @zoka readme
authored
23 front end with syntax colored editor, command history and persistent sessions.
cb03775 @zoka Using Noir 1.2.2, README.md addiutions
authored
24
32898f7 @zoka more README
authored
25 Note that for real life application there should be some
bd1e834 @zoka more README
authored
26 mechanism to prevent unathorised access. There is a pluggable authenication
27 function that will be called upon every AJAX command or ringMon page
32898f7 @zoka more README
authored
28 request. The function is passed the pending Ring request map, in order
29 to decide whether to accept it or reject it.
bd1e834 @zoka more README
authored
30 Simple authentication mechanism woukd be to have white list of IP addresses
31 allowed.
32
32898f7 @zoka more README
authored
33 ringMon can be very useful to provide nREPL access
34 to applications deployed to cloud platforms
bd1e834 @zoka more README
authored
35 such as Heroku. Heroku has restriction of one server socket per web app,
36 so the convenient way to share nREPL communication with normal web
784bcdb @zoka more README
authored
37 server traffic was to implement ringMon as a Ring middleware.
bd1e834 @zoka more README
authored
38
39 The communication path for request from browser to nREPL server is:
40
41 ```
32898f7 @zoka more README
authored
42 browser(js)->AJAX->ringMon(clj)->Custom-intra-JVM-trasport(clj)->nREPLserver(clj)
bd1e834 @zoka more README
authored
43 ```
44
32898f7 @zoka more README
authored
45 The reply travels all the way back in reverse order. The nREPL provides
46 pluggable transport architecture. This particular one is based on
47 pair of
162e68c @zoka README
authored
48 [LinkedBlockingQueue](http://docs.oracle.com/javase/6/docs/api/java/util/concurrent/LinkedBlockingQueue.html)s
32898f7 @zoka more README
authored
49 in back to back configuration - very fast and no need for
50 using bencode since the commands and responses are sent as
51 native Clojure data structures.
52
205d2d3 @zoka more README
authored
53 ## Demo
cb03775 @zoka Using Noir 1.2.2, README.md addiutions
authored
54
32898f7 @zoka more README
authored
55 You can see ringMon in action in
56 [this](https://github.com/zoka/noirMon)
57 showcase Noir application deployed
58 at [Heroku](http://noirmon.herokuapp.com/).
1c0c8eb @zoka More readme
authored
59
205d2d3 @zoka more README
authored
60 ## Chat facility
cd2d486 @zoka more README
authored
61
c210754 @zoka README
authored
62 ringMon monitoring page supports a simple chat facility. This may assist
32898f7 @zoka more README
authored
63 remote team members when they work together on the same deployed application
e290325 @zoka more README
authored
64 instance. Or it can be just a fun tool to provide bit of social REPL-ing,
32898f7 @zoka more README
authored
65 such as [noirMon](http://noirmon.herokuapp.com/ringmon/monview.html) does.
cd2d486 @zoka more README
authored
66
e95947f @zoka First cut of extraxting fuctionality into ring handler. Not working yet.
authored
67 ## Usage (for local test)
5904d3a @zoka init
authored
68
69 ```bash
70 lein deps
71 lein run
72 ```
73c7286 @zoka README
authored
73 Point your browser to `localhost:8888`.
32898f7 @zoka more README
authored
74
75 ## Using ringMon in your applications
76
ff31163 @zoka Release 0.1.1
authored
77 If you want to include ringMon in your leiningen project,
78 simply add this to your dependencies:
b82bb29 @zoka Up to date readme
authored
79
80 ```clojure
73c7286 @zoka README
authored
81 [ringmon "0.1.2"]
b82bb29 @zoka Up to date readme
authored
82 ```
a49197e @zoka 0.1.2 Release
authored
83 ringMon `project.clj` is compatible with Leiningen v2.0 as well.
b82bb29 @zoka Up to date readme
authored
84
a17501d @zoka more README
authored
85 To track the latest snapshot (recommended) use:
ff31163 @zoka Release 0.1.1
authored
86
87 ```clojure
73c7286 @zoka README
authored
88 [ringmon "0.1.3-SNAPSHOT"]
ff31163 @zoka Release 0.1.1
authored
89 ```
a17501d @zoka more README
authored
90 ### Bare bones
ff31163 @zoka Release 0.1.1
authored
91
784bcdb @zoka more README
authored
92 In case of bare bones Ring application, the following is needed:
b82bb29 @zoka Up to date readme
authored
93
94 ```clojure
784bcdb @zoka more README
authored
95 (ns my.server
b82bb29 @zoka Up to date readme
authored
96 (:require
97 [ringmon.monitor :as monitor]
98 [ring.adapter.jetty :as jetty]))
99
100 (defn demo [req]
1c0c8eb @zoka More readme
authored
101 (let [headers (:headers req)
102 hostname (get headers "host")
103 uri (:uri req)]
104 (if (or (= uri "/") (= uri "/favicon.ico"))
105 {:status 200
106 :headers {"Content-Type" "text/html"}
107 :body "Hello"})))
b82bb29 @zoka Up to date readme
authored
108
109 (def handler
110 (-> demo
111 ; <-- add your additional middleware here
112 (monitor/wrap-ring-monitor)))
113
784bcdb @zoka more README
authored
114 (defn -main []
115 (let [port (Integer. (get (System/getenv) "PORT" "8080"))]
b82bb29 @zoka Up to date readme
authored
116
784bcdb @zoka more README
authored
117 (println "The ringMon bare bones local demo starting...")
b82bb29 @zoka Up to date readme
authored
118 (jetty/run-jetty handler {:port port})))
119 ```
120
32898f7 @zoka more README
authored
121 Point your browser to `localhost:8080` amd you will see `Hello` response.
122 The monitoring page is at `localhost:8080/ringmon/monview.html`.
123
a17501d @zoka more README
authored
124 ### Noir
125
32898f7 @zoka more README
authored
126 If you are using Noir, then you need to slightly
127 modify startup in your server.clj:
b82bb29 @zoka Up to date readme
authored
128
129 ```clojure
32898f7 @zoka more README
authored
130 (ns myapp.server
b82bb29 @zoka Up to date readme
authored
131 (:require [noir.server :as server]
32898f7 @zoka more README
authored
132 [ringmon.monitor :as monitor])) ; 1. ringmon.monitor is required
b82bb29 @zoka Up to date readme
authored
133
32898f7 @zoka more README
authored
134 (server/load-views "src/myapp/views/")
b82bb29 @zoka Up to date readme
authored
135
136 (defn -main [& m]
137 (let [mode (keyword (or (first m) :dev))
138 port (Integer. (get (System/getenv) "PORT" "8080"))]
139
32898f7 @zoka more README
authored
140 ; 2. add ringmon middlevare _before_ starting the server
b82bb29 @zoka Up to date readme
authored
141 (server/add-middleware monitor/wrap-ring-monitor)
142
143 (server/start port {:mode mode
73c7286 @zoka README
authored
144 :ns 'myapp})))
b82bb29 @zoka Up to date readme
authored
145 ```
32898f7 @zoka more README
authored
146 Again, the monitoring page is at `localhost:8080/ringmon/monview.html`.
147 You might want to add more covenient link to this page in your appllication
148 like it was done in [noirMon](http://noirmon.herokuapp.com/).
cb03775 @zoka Using Noir 1.2.2, README.md addiutions
authored
149
6050c75 @zoka README and comments
authored
150 ### As a replacement for `lein repl`
a17501d @zoka more README
authored
151
df3e46f @zoka Removed depemdency of the Jetty server - it is only used
authored
152 Even if your Clojure application is not web based, you can add
73c7286 @zoka README
authored
153 `[ringmon "0.1.2"]`
154 and
155 `[ring/ring-jetty-adapter "1.0.1"]`
156 to dev dependencies and use it as a replacement for
af57818 @zoka more README
authored
157 built in REPL.
a17501d @zoka more README
authored
158
159 In this case ringMon runs first:
160
161 ```clojure
610f452 @zoka Added 2-dimensional JSON tables display feature to browser client.
authored
162 lein run -m ringmon.server :local-repl true :port 0
a17501d @zoka more README
authored
163 ```
164 This will start a separate Jetty instance on autoselected server
165 port just to serve the nREPL page. Your default browser will automatically
610f452 @zoka Added 2-dimensional JSON tables display feature to browser client.
authored
166 open freh window and load the monitoring page. If `:port` has
a17501d @zoka more README
authored
167 non-zero value then there will be no port autoselection. Default
73c7286 @zoka README
authored
168 value is `8888`.
df3e46f @zoka Removed depemdency of the Jetty server - it is only used
authored
169
73c7286 @zoka README
authored
170 You can run above command on a remote headless server
df3e46f @zoka Removed depemdency of the Jetty server - it is only used
authored
171 as well - the browser start attempt should fail gracefuly. In this case
172 you will want to specify a port that is visible to browser on your desktop.
610f452 @zoka Added 2-dimensional JSON tables display feature to browser client.
authored
173 Automatic browser window activation is disabled by omitting `:local-repl`
174 key or by setting it to false or nil.
a17501d @zoka more README
authored
175
176 At this point your application is not runnning yet.
73c7286 @zoka README
authored
177 You can start it by entering this in nREPL input window:
a17501d @zoka more README
authored
178
179 ```clojure
180 (use 'your.app.main.namespace)
181 (-main)
182 ```
610f452 @zoka Added 2-dimensional JSON tables display feature to browser client.
authored
183 There is an easier way to add web based nREPL capability to your
54857ed @zoka README
authored
184 project if you have Leiningen v 2.0 installed, by
b3c683c @zoka README
authored
185 installing `lein-webrepl` plugin and simply entering:
610f452 @zoka Added 2-dimensional JSON tables display feature to browser client.
authored
186
187 ```bash
188 lein2 webrepl
189 ```
190 in your project folder. No changes are required to
537c123 @zoka README
authored
191 `project.clj`. Note that lein 1.x and 2.0 can be installed side by side.
610f452 @zoka Added 2-dimensional JSON tables display feature to browser client.
authored
192 See
54857ed @zoka README
authored
193 [lein-webrepl GitHub page](https://github.com/zoka/lein-webrepl)
610f452 @zoka Added 2-dimensional JSON tables display feature to browser client.
authored
194 for more info.
195
196 ## Run-time configuration
a17501d @zoka more README
authored
197
4135d68 @zoka more README
authored
198 The map bellow shows the default runtime configuration. It is typically
1e3085f @zoka more README
authored
199 adjusted before web server starts, but it may be changed later as well.
a17501d @zoka more README
authored
200
201 ```clojure
610f452 @zoka Added 2-dimensional JSON tables display feature to browser client.
authored
202
a17501d @zoka more README
authored
203 ; the middleware configuration
204 (def the-cfg (atom
df3e46f @zoka Removed depemdency of the Jetty server - it is only used
authored
205 {
206 :local-repl nil ; set to true if browser is to autostart assuming
207 ; running locally (optional).
208 :http-server nil ; Ring compatible http server start function that
209 ; needs ring-handler and {:port port} as parameters
210 ; If it is not set, the Jetty one will be attempted
211 ; to be resolved dynamically
212 :ring-handler nil ; Ring compatible handler
213 :port nil ; http-server port
610f452 @zoka Added 2-dimensional JSON tables display feature to browser client.
authored
214 ; If ringMon is to use an http server other than Jetty
215 ; then :http-server key value needs to be set prior to calling
216 ; the ringmon.server/start
df3e46f @zoka Removed depemdency of the Jetty server - it is only used
authored
217 ;---------------------------------------------------------------------
218 ; Browser parameters
219 :fast-poll 500 ; browser poll when there is a REPL output activity
a17501d @zoka more README
authored
220 :norm-poll 2000 ; normal browser poll time
df3e46f @zoka Removed depemdency of the Jetty server - it is only used
authored
221 :parent-url "" ; complete url of the parent application main page (optional)
610f452 @zoka Added 2-dimensional JSON tables display feature to browser client.
authored
222 :lein-webrepl nil ; set if runing in standalone mode in context of the
223 ; lein-webrepl plugin. May be used to customize the
224 ; browser behaviour. Also used by nREPL server side
225 ; to merge :main and :repl-init key values from project.clj
df3e46f @zoka Removed depemdency of the Jetty server - it is only used
authored
226 ;-----------------------------------------------------------------------
227 ; access control
a17501d @zoka more README
authored
228 :disabled nil ; general disable, if true then check :the auth-fn
8626377 @zoka more README
authored
229 :auth-fn nil})) ; authorisation callback, checked only if :disabled is true
a17501d @zoka more README
authored
230 ; will be passed a Ring request, return true if Ok
df3e46f @zoka Removed depemdency of the Jetty server - it is only used
authored
231
610f452 @zoka Added 2-dimensional JSON tables display feature to browser client.
authored
232
a17501d @zoka more README
authored
233 ```
df3e46f @zoka Removed depemdency of the Jetty server - it is only used
authored
234 Use `ringmon.monitor/merge-cfg` to change the configuration
a17501d @zoka more README
authored
235 safely.
236
237 ```clojure
238 (defn merge-cfg
239 [cfg]
240 (when (map? cfg)
241 (swap! the-cfg merge cfg)))
242 ```
243
5904d3a @zoka init
authored
244 ## License
245
cb03775 @zoka Using Noir 1.2.2, README.md addiutions
authored
246 Copyright (C) 2012 Zoran Tomicic
5904d3a @zoka init
authored
247
248 Distributed under the Eclipse Public License, the same as Clojure.
249
Something went wrong with that request. Please try again.