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") +