README.md in semantic_logger-2.3.1 vs README.md in semantic_logger-2.4.0

- old
+ new

@@ -3,17 +3,17 @@ Improved logging for Ruby * http://github.com/ClarityServices/semantic_logger -### Note: +## Note: As of SemanticLogger V2.0 the Rails logging is no longer automatically replaced when including SemanticLogger. Include the [rails_semantic_logger](http://github.com/ClarityServices/rails_semantic_logger) gem to replace the Rails default logger with SemanticLogger -### Overview +## Overview Semantic Logger takes logging in Ruby to a new level by adding several new capabilities to the commonly used Logging API: Dynamic @@ -130,11 +130,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 Semantic Logger is a Logger that supports logging of meta-data, along with text messages to multiple appenders An appender is a Logging destination such as a File, MongoDB collection, etc.. @@ -181,13 +181,13 @@ Since Semantic Logger can call existing Loggers, it does not force end-users to have to adopt a Semantic aware adapter. Although, such adapters create tremendous value in the problem monitoring and determination processes. -### 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 @@ -229,11 +229,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 @@ -244,11 +244,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 @@ -258,11 +258,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 @@ -315,11 +315,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 @@ -334,11 +334,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 in semantic_logger/railtie.rb: @@ -373,11 +373,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. @@ -391,11 +391,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 @@ -407,11 +407,11 @@ logger.debug("Hello World") # ... end ``` -### Using SemanticLogger +## Standalone SemanticLogger When using SemanticLogger inside of Rails all we need to do is include the rails_semantic_logger gem and the default Rails logger will be replaced with Semantic Logger. @@ -531,21 +531,38 @@ end end end ``` -### Configuration +### Logging to Syslog +Log to a local Syslog: +```ruby +require 'semantic_logger' +SemanticLogger.default_level = :trace +SemanticLogger.add_appender(SemanticLogger::Appender::Syslog.new) +``` + +Log to a local file and to a remote Syslog server such as syslog-ng over TCP: +```ruby +require 'semantic_logger' +SemanticLogger.default_level = :trace +SemanticLogger.add_appender('development.log') +SemanticLogger.add_appender(SemanticLogger::Appender::Syslog.new(:server => 'tcp://myloghost:514')) +``` + +## Configuration + The Semantic Logger follows the principle where multiple appenders can be active at the same time. For example, this allows one to log to MongoDB and the Rails log file at the same time. -#### Rails Configuration +### Rails Configuration To automatically replace the Rails logger with Semantic Logger use the gem [rails_semantic_logger](http://github.com/ClarityServices/rails_semantic_logger) -### Log Struct +## Log Struct Internally all log messages are passed around in a Log Struct. In order to write your own custom formatter or log appender it is necessary to understand the fields: @@ -587,11 +604,11 @@ level_index [Integer] * Internal use only. Index of the log level -#### Mixing Logging Levels +### Mixing Logging Levels It is sometimes useful to log a subset of the log messages to a separate file or appender. For example, log :error and :fatal level messages to a special error file. @@ -625,11 +642,11 @@ ==> warnings.log <== 2013-08-02 14:15:56.735273 W [35669:70176909690580] MyClass -- This is a warning message ``` -#### Custom Formatters +### Custom Formatters The formatting for each appender can be replaced with custom code. To replace the existing formatter supply a block of code when creating the appender. Example: Formatter that just returns the Log Struct @@ -702,26 +719,12 @@ document end SemanticLogger.add_appender(mongodb_appender) ``` -### SysLog and other standard loggers +## Performance -To write log entries to a Syslog logger or any other logger of your choice, -that conforms the standard Ruby Logger API, Semantic Logger has an Appender to -use that logger. - -For example to configure rails to also log to the Syslogger gem: -```ruby -config.after_initialize do - # Besides logging to the local file also log to Syslogger - config.semantic_logger.appenders << SemanticLogger::Appender::Wrapper.new(Syslogger.new("yourappname")) -end -``` - -### Performance - The traditional logging implementations write their log information to file in the same thread of execution as the program itself. This means that for every log entry the program has to wait for the data to be written. With Semantic Logger it uses a dedicated thread for logging so that writing to @@ -729,16 +732,16 @@ Also, since the logging is in this separate thread there is no impact to program execution if we decided to add another appender. For example, log to both a file and a MongoDB collection. -### Log Rotation +## 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 over deleting the file. -### Why Semantic logging? +## Why Semantic logging? Just as there is the initiative to add Semantic information to data on the web so that computers can directly understand the content without having to resort to complex regular expressions or machine learning techniques, it is important to be able to do the same with log files or data. @@ -748,11 +751,11 @@ Once the logging data is in the NOSQL data store it can be queried quickly and efficiently. Some SQL data stores also allow complex data types that could be used for storing and querying the logging data -### Architecture & Performance +## Architecture & Performance In order to ensure that logging does not hinder the performance of the application all log entries are written to thread-safe Queue. A separate thread is responsible for writing the log entries to each of the appenders. @@ -764,11 +767,11 @@ terminates it will call flush on each of the appenders. Calling SemanticLogger::Logger#flush will wait until all outstanding log messages have been written and flushed to their respective appenders before returning. -### Write your own Appender +## Write your own Appender To write your own appender it should meet the following requirements: * Inherit from SemanticLogger::Base * In the initializer connect to the resource being logged to @@ -819,24 +822,24 @@ To have your appender included in the standard list of appenders follow the fork instructions below. Very Important: New appenders will not be accepted without complete working tests. See the [MongoDB Appender Test](https://github.com/ClarityServices/semantic_logger/blob/master/test/appender_mongodb_test.rb) for an example. -### Dependencies +## Dependencies - Ruby MRI 1.8.7, 1.9.3 (or above) Or, JRuby 1.6.3 (or above) - Optional: To log to MongoDB, Mongo Ruby Driver 1.5.2 or above -### Install +## Install gem install semantic_logger To log to MongoDB, it also needs the Ruby Mongo Driver gem install mongo -### Future +## Future - Add support for a configuration file that can set log level by class name - Configuration file to support adding appenders - Based on end-user demand add appenders for: Syslog, hadoop, redis, etc.. @@ -848,18 +851,23 @@ * Bugs: <http://github.com/ClarityServices/semantic_logger/issues> * Gems: <http://rubygems.org/gems/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,2013 Clarity Services, Inc. +Copyright 2012,2013 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