README.md in logstasher-0.5.0 vs README.md in logstasher-0.5.2
- old
+ new
@@ -1,20 +1,22 @@
# Logstasher [![Gem Version](https://badge.fury.io/rb/logstasher.png)](http://badge.fury.io/rb/logstasher) [![Build Status](https://secure.travis-ci.org/shadabahmed/logstasher.png)](https://secure.travis-ci.org/shadabahmed/logstasher)
### Awesome Logging for Rails !!
This gem is heavily inspired from [lograge](https://github.com/roidrage/lograge), but it's focused on one thing and one thing only. That's making your logs awesome like this:
-[![Awesome Logs](http://i.imgur.com/zZXWQNp.png)](http://i.imgur.com/zZXWQNp.png)
+[![Awesome Logs](https://f.cloud.github.com/assets/830679/2407078/dcde03e8-aa82-11e3-85ac-8c5b3a86676e.png)](https://f.cloud.github.com/assets/830679/2407078/dcde03e8-aa82-11e3-85ac-8c5b3a86676e.png)
How it's done ?
By, using these awesome tools:
* [Logstash](http://logstash.net) - Store and index your logs
* [Kibana](http://kibana.org/) - for awesome visualization. This is optional though, and you can use any other visualizer
-To know how to setup these tools - visit my [blog](http://shadabahmed.com/blog/2013/04/30/logstasher-for-awesome-rails-logging)
+Update: Logstash now includes Kibana build in, so no need to separately install. Logstasher has been test with **logstash version 1.3.3**
+See [quickstart](#quick-setup-for-logstash) for quickly setting up logstash
+
## About logstasher
This gem purely focuses on how to generate logstash compatible logs i.e. *logstash json event format*, without any overhead. Infact, logstasher logs to a separate log file named `logstash_<environment>.log`.
The reason for this separation:
* To have a pure json log file
@@ -90,15 +92,62 @@
# If you are using custom instrumentation, just add it to logstasher custom fields
LogStasher.custom_fields << :myapi_runtime
end
end
+## Listening to `ActiveSupport::Notifications` events
+
+It is possible to listen to any `ActiveSupport::Notifications` events and store arbitrary data to be included in the final JSON log entry:
+
+ # In config/initializers/logstasher.rb
+
+ # Watch calls the block with the same arguments than any ActiveSupport::Notification, plus a store
+ LogStasher.watch('some.activesupport.notification') do |name, start, finish, id, payload, store|
+ # Do something
+ store[:count] = 42
+ end
+
+Would change the log entry to:
+
+```
+{"@source":"unknown","@tags":["request"],"@fields":{"method":"GET","path":"/","format":"html","controller":"file_servers","action":"index","status":200,"duration":28.34,"view":25.96,"db":0.88,"ip":"127.0.0.1","route":"file_servers#index", "parameters":"","ndapi_time":null,"uuid":"e81ecd178ed3b591099f4d489760dfb6","user":"shadab_ahmed@abc.com", "site":"internal","some.activesupport.notification":{"count":42}},"@timestamp":"2013-04-30T13:00:46.354500+00:00"}
+```
+
+The store exposed to the blocked passed to `watch` is thread-safe, and reset after each request.
+By default, the store is only shared between occurences of the same event.
+You can easily share the same store between different types of notifications, by assigning them to the same event group:
+
+ # In config/initializers/logstasher.rb
+
+ LogStasher.watch('foo.notification', event_group: 'notification') do |*args, store|
+ # Shared store with 'bar.notification'
+ end
+
+ LogStasher.watch('bar.notification', event_group: 'notification') do |*args, store|
+ # Shared store with 'foo.notification'
+ end
+
+## Quick Setup for Logstash
+
+* Download logstash from [logstash.net](http://www.logstash.net/)
+* Use this sample config file: [quickstart.conf](https://github.com/shadabahmed/logstasher/raw/master/sample_logstash_configurations/quickstart.conf)
+* Start logstash with the following command:
+```
+java -jar logstash-1.3.3-flatjar.jar agent -f quickstart.conf -- web
+```
+* Visit http://localhost:9292/ to see the Kibana interface and your parsed logs
+* For advanced options see the latest logstash documentation at [logstash.net](http://www.logstash.net/) or visit my blog at (shadabahmed.com)[http://shadabahmed.com/blog/2013/04/30/logstasher-for-awesome-rails-logging] (slightly outdated but will sure give you ideas for distributed setup etc.)
+
## Versions
All versions require Rails 3.0.x and higher and Ruby 1.9.2+. Tested on Rails 4 and Ruby 2.0
## Development
- Run tests - `rake`
- Generate test coverage report - `rake coverage`. Coverage report path - coverage/index.html
## Copyright
Copyright (c) 2013 Shadab Ahmed, released under the MIT license
+
+
+[![Bitdeli Badge](https://d2weczhvl823v0.cloudfront.net/shadabahmed/logstasher/trend.png)](https://bitdeli.com/free "Bitdeli Badge")
+