README.md in rails_semantic_logger-1.2.1 vs README.md in rails_semantic_logger-1.3.0

- old
+ new

@@ -1,17 +1,17 @@ rails_semantic_logger ===================== Improved logging for Ruby on Rails -* http://github.com/ClarityServices/rails_semantic_logger +* http://github.com/reidmorrison/rails_semantic_logger -### Overview +## Overview -Rails Semantic Logger replaces the Rails default logger with [Semantic Logger](http://github.com/ClarityServices/semantic_logger) +Rails Semantic Logger replaces the Rails default logger with [Semantic Logger](http://github.com/reidmorrison/semantic_logger) -[Semantic Logger](http://github.com/ClarityServices/semantic_logger) takes +[Semantic Logger](http://github.com/reidmorrison/semantic_logger) takes logging in Ruby to a new level by adding several new capabilities to the commonly used Logging API: Dynamic @@ -135,11 +135,11 @@ * Semantic Logger is completely thread safe and all methods can be called concurrently from any thread * Tagged logging keeps any tagging data on a per-thread basis to ensure that tags from different threads are not inter-mingled -### Introduction +## Introduction Just by including the rails_semantic_logger gem, Rails Semantic Logger will replace the default Rails logger with Semantic Logger. Without further configuration it will log to the existing Rails log file in a more efficient multi-threaded way. @@ -162,13 +162,13 @@ 2012-10-19 12:05:51.109 I [35940:JRubyWorker-10] ActionController -- Rendered layouts/_footer.html.erb (16.0ms) 2012-10-19 12:05:51.109 I [35940:JRubyWorker-10] ActionController -- Rendered admin/index.html.erb within layouts/base (1329.0ms) 2012-10-19 12:05:51.113 I [35940:JRubyWorker-10] ActionController -- Completed 200 OK in 3795ms (Views: 1349.0ms | ActiveRecord: 88.0ms | Mongo: 0.0ms) ``` -### Logging API +## Logging API -#### Standard Logging methods +### Standard Logging methods The Semantic Logger logging API supports the existing logging interface for the Rails and Ruby Loggers. For example: ```ruby @@ -210,11 +210,11 @@ logger.debug("Calling Supplier", :request => 'update', :user => 'Jack') logger.debug { "A total of #{result.inject(0) {|sum, i| i+sum }} were processed" } ``` -### Exceptions +## Exceptions The Semantic Logger adds an optional parameter to the existing log methods so that a corresponding Exception can be logged in a standard way ```ruby @@ -225,11 +225,11 @@ # Re-raise or handle the exception raise exception end ``` -#### Payload +### Payload The Semantic Logger adds an extra parameter to the existing log methods so that additional payload can be logged, such as a Hash or a Ruby Exception object. ```ruby @@ -239,11 +239,11 @@ The additional payload is machine readable so that we don't have to write complex regular expressions so that a program can analyze log output. With the MongoDB appender the payload is written directly to MongoDB as part of the document and is therefore fully searchable -#### Benchmarking +### Benchmarking Another common logging requirement is to measure the time it takes to execute a block of code based on the log level. For example: ```ruby @@ -296,11 +296,11 @@ :exception Optional, Ruby Exception object to log along with the duration of the supplied block ``` -#### Logging levels +### Logging levels The following logging levels are available through Semantic Logger :trace, :debug, :info, :warn, :error, :fatal @@ -315,11 +315,11 @@ in the development environment for low level trace logging of methods calls etc. If only the rails logger is being used, then :trace level calls will be logged as debug calls only if the log level is set to trace -#### Changing the Class name for Log Entries +### Changing the Class name for Log Entries When Semantic Logger is included in a Rails project it automatically replaces the loggers for Rails, ActiveRecord::Base, ActionController::Base, and ActiveResource::Base with wrappers that set their Class name. For example: @@ -354,11 +354,11 @@ This will result in the log output identifying the log entry as from the ExternalSupplier class 2012-08-30 15:37:29.474 I [48308:ScriptThreadProcess: script/rails] (5.2ms) ExternalSupplier -- Calling external interface -#### Tagged Logging +### Tagged Logging Semantic Logger allows any Ruby or Rails program to also include tagged logging. This means that any logging performed within a block, including any called libraries or gems to include the specified tag with every log entry. @@ -372,11 +372,11 @@ logger.debug("Hello World") # ... end ``` -#### Beyond Tagged Logging +### Beyond Tagged Logging Blocks of code can be tagged with not only values, but can be tagged with entire hashes of data. The additional hash of data will be merged into the payload of every log entry @@ -388,11 +388,11 @@ logger.debug("Hello World") # ... end ``` -#### Installation +### Installation Add the following line to Gemfile ```ruby gem 'rails_semantic_logger' @@ -403,20 +403,22 @@ bundle install This will automatically replace the standard Rails logger with Semantic Logger which will write all log data to the configured Rails logger. -#### Configuration +### Configuration By default Semantic Logger will detect the log level from Rails. To set the log level explicitly, add the following line to config/environments/production.rb inside the Application.configure block ```ruby config.log_level = :trace ``` +#### MongoDB logging + To log to both the Rails log file and MongoDB add the following lines to config/environments/production.rb inside the Application.configure block ```ruby config.after_initialize do @@ -430,49 +432,125 @@ :collection_size => 25.gigabytes ) end ``` +#### Logging to Syslog + +Configuring rails to also log to a local Syslog: +```ruby +config.after_initialize do + config.semantic_logger.add_appender(SemanticLogger::Appender::Syslog.new) +end +``` + +Configuring rails to also log to a remote Syslog server such as syslog-ng over TCP: +```ruby +config.after_initialize do + config.semantic_logger.add_appender(SemanticLogger::Appender::Syslog.new(:server => 'tcp://myloghost:514')) +end +``` + +#### Colorized Logging + If the Rails colorized logging is enabled, then the colorized formatter will be used by default. To disable colorized logging in both Rails and SemanticLogger: ```ruby config.colorize_logging = false ``` -### Custom Appenders and Formatters +## Custom Appenders and Formatters -To write your own appenders or formatting, see [SemanticLogger](http://github.com/ClarityServices/semantic_logger) +The format of data logged by Semantic Logger is specific to each appender. -### Log Rotation +To change the text file log format in Rails SemanticLogger, create a rails initializer with the following code and customize as needed. +For example: 'config/initializers/semantic_logger_formatter.rb' +```ruby +# Replace the format of the existing log file appender +SemanticLogger.appenders.first.formatter = Proc.new do |log| + tags = log.tags.collect { |tag| "[#{tag}]" }.join(" ") + " " if log.tags && (log.tags.size > 0) + + message = log.message.to_s + message << " -- " << log.payload.inspect if log.payload + message << " -- " << "#{log.exception.class}: #{log.exception.message}\n#{(log.exception.backtrace || []).join("\n")}" if log.exception + + duration_str = log.duration ? "(#{'%.1f' % log.duration}ms) " : '' + + "#{SemanticLogger::Appender::Base.formatted_time(log.time)} #{log.level.to_s[0..0].upcase} [#{$$}:#{log.thread_name}] #{tags}#{duration_str}#{log.name} : #{message}" +end +``` + +To write your own appenders or formatting, see [SemanticLogger](http://github.com/reidmorrison/semantic_logger) + +## Log Rotation + Since the log file is not re-opened with every call, when the log file needs to be rotated, use a copy-truncate operation rather than deleting the file. -### Dependencies +## Process Forking -- Ruby MRI 1.8.7, 1.9.3 (or above) Or, JRuby 1.6.3 (or above) +The following frameworks are automatically detected when rails is configured +so that the necessary callbacks are registered to re-open appenders after a process fork: + +- Phusion Passenger +- Resque + +### Unicorn + +With Unicorn, add the following code to you Unicorn configuration: + +```ruby +# config/unicorn.conf.rb +after_fork do |server, worker| + # Re-open appenders after forking the process + SemanticLogger.reopen +end +``` + +### Puma + +If running Puma 2 in Clustered mode and you're preloading your application, +add the following to your worker boot code: + +```ruby +# config/puma.rb +on_worker_boot do + # Re-open appenders after forking the process + SemanticLogger.reopen +end +``` + +## Dependencies + +- Ruby MRI 1.8.7, 1.9.3, 2.0 (or above) Or, JRuby 1.6.3 (or above) - Rails 2, 3, 4 or above Meta ---- -* Code: `git clone git://github.com/ClarityServices/rails_semantic_logger.git` -* Home: <https://github.com/ClarityServices/rails_semantic_logger> -* Bugs: <http://github.com/ClarityServices/rails_semantic_logger/issues> +* Code: `git clone git://github.com/reidmorrison/rails_semantic_logger.git` +* Home: <https://github.com/reidmorrison/rails_semantic_logger> +* Bugs: <http://github.com/reidmorrison/rails_semantic_logger/issues> * Gems: <http://rubygems.org/gems/rails_semantic_logger> This project uses [Semantic Versioning](http://semver.org/). -Authors -------- +Author +------ Reid Morrison :: reidmo@gmail.com :: @reidmorrison +Contributors +------------ + +Marc Bellingrath :: marrrc.b@gmail.com + License ------- -Copyright 2012 Clarity Services, Inc. +Copyright 2012, 2013, 2014 Reid Morrison Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at