ougai 1.4.3 → 1.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 056bac74cd408498f0fb9a5db5f8741094a201ac
-  data.tar.gz: 7aec3907ebf359aa409a528a028605c8d4538281
+  metadata.gz: 07b9c78b3ba77163b4181b653717cde507c558c4
+  data.tar.gz: 24908f54426f4695ec3f3db02869de55bf239618
 SHA512:
-  metadata.gz: d1fa397a69c767a637919f3891fba6c5e4a3edadb150483ffce4df6f5870c6f95bc28d33592438c1eabc71c4a2c7f23739e3ce2be8236ed733c65633561b2264
-  data.tar.gz: d8a3ff21840a2d0fb328d12d2fd4f643b2512d3e2f55691d4fd0fcab7943b4f22c6e6248dd42aa603e5ff2abf7b0990c068d94a12ff9e7b1d8ccda1ce27f5a8c
+  metadata.gz: 123c9b422abdacaff15127779c162b211726e048d8b6f93840b31152a257865b550cfa8025131633553189544d66bf5b1072dbbb8f8fa97594d994cbfc160339
+  data.tar.gz: 57f93dda462f828a0130da70ca20b2f900680c74797e63670f71b294b43a1ae580b31a438b71cd122b02f46155f2ca7319cd8ba0e0b912abbd26d036d0d6371f

data/README.md

@@ -6,9 +6,9 @@ Ougai
 [![Code Climate](https://codeclimate.com/github/tilfin/ougai/badges/gpa.svg)](https://codeclimate.com/github/tilfin/ougai)
 [![Test Coverage](https://codeclimate.com/github/tilfin/ougai/badges/coverage.svg)](https://codeclimate.com/github/tilfin/ougai/coverage)
 
-A structured JSON logging system is capable of handling a message, structured data or an exception easily.
-It is compatible with [Bunyan](https://github.com/trentm/node-bunyan) for Node.js.
-It can also output human readable format for the console.
+A structured logging system is capable of handling a message, structured data or an exception easily.
+It has JSON formatter compatible with [Bunyan](https://github.com/trentm/node-bunyan) for Node.js and
+human readable formatter with [Awesome Print](https://github.com/awesome-print/awesome_print) for console.
 
 ## Installation
 
@@ -32,7 +32,8 @@ $ gem install ougai
 
 ## Usage
 
-**Ougai::Logger** is sub-class of original [Logger](https://docs.ruby-lang.org/ja/latest/class/Logger.html) in Ruby.
+**Ougai::Logger** is sub-class of original [Logger](https://ruby-doc.org/stdlib-2.4.1/libdoc/logger/rdoc/Logger.html) in Ruby.
+All arguments of the `initialize` pass through itself to **::Logger**.
 
 ```ruby
 require 'rubygems'
@@ -51,7 +52,7 @@ logger.info('Information!')
 {"name":"main","hostname":"mint","pid":14607,"level":30,"time":"2016-10-16T22:26:48.835+09:00","v":0,"msg":"Information!"}
 ```
 
-### log only a data
+### log only structured data
 
 ```ruby
 logger.info({
@@ -277,9 +278,9 @@ logger.warn('Ignored something.')
 ```
 
 
-## View log by node-bunyan
+## View logs with node-bunyan
 
-Install [bunyan](https://github.com/trentm/node-bunyan) via NPM
+Install [bunyan](https://github.com/trentm/node-bunyan) via npm
 
 ```
 $ npm install -g bunyan
@@ -327,49 +328,12 @@ logger.formatter = Ougai::Formatters::Readable.new
 ![Screen Shot](https://github.com/tilfin/ougai/blob/images/ougai_readable_format.png?raw=true)
 
 
-### Output example on development
+## How to use with famous products, services and libraries
 
-If you modify `application_controller.rb` as
-
-```ruby
-class ApplicationController < ActionController::Base
-  protect_from_forgery with: :exception
-
-  def hello
-    logger.debug 'Call action', somefield: 'somevalue'
-    render plain: 'Hello!'
-  end
-end
-```
-
-logger outputs
-
-```
-[2016-11-03T15:11:24.847+09:00] DEBUG: Call action
-{
-    :somefield => "somevalue"
-}
-[2016-11-03T15:11:24.872+09:00] INFO: Request
-{
-    :request => {
-            :method => "GET",
-              :path => "/",
-            :format => :html,
-        :controller => "ApplicationController",
-            :action => "hello",
-            :status => 200,
-          :duration => 30.14,
-              :view => 3.35,
-                :db => 0.0
-    }
-}
-```
-
-## How to use with famous products and libraries
-
-- [Use as Rails logger](https://github.com/tilfin/ougai/wiki/Use-as-Rails-logger)
+- [Use as Rails logger](https://github.com/tilfin/ougai/wiki/Use-as-Rails-logger) and apply the request with [Lograge](https://github.com/roidrage/lograge)
 - [Customize Sidekiq logger](https://github.com/tilfin/ougai/wiki/Customize-Sidekiq-logger)
 - [Forward logs to Fluentd](https://github.com/tilfin/ougai/wiki/Forward-logs-to-Fluentd)
+- [Forward logs to Logentries](https://github.com/tilfin/ougai/wiki/Forward-logs-to-Logentries)
 
 ## License
 

data/lib/ougai/child_logger.rb

@@ -1,7 +1,9 @@
 module Ougai
+  # A logger created by the `child` method of parent logger
   class ChildLogger
     include Logging
 
+    # @private
     def initialize(parent, fields)
       @parent = parent
       @with_fields = fields
@@ -11,6 +13,7 @@ module Ougai
       @parent.level
     end
 
+    # @private
     def chain(severity, args, fields, hooks)
       hooks.push(@before_log) if @before_log
       @parent.chain(severity, args, merge_fields(@with_fields, fields), hooks)

data/lib/ougai/formatters/bunyan.rb

@@ -3,6 +3,9 @@ require 'json'
 
 module Ougai
   module Formatters
+    # A JSON formatter compatible with node-bunyan
+    # @attr [Boolean] jsonize Whether log should converts JSON (by default this is on).
+    # @attr [Boolean] with_newline Whether tailing NL should be appended (by default this is on).
     class Bunyan < Base
       attr_accessor :jsonize, :with_newline
 

data/lib/ougai/formatters/readable.rb

@@ -2,6 +2,10 @@ require 'ougai/formatters/base'
 
 module Ougai
   module Formatters
+    # A human readble formatter with awesome_print
+    # @attr [Boolean] plain Whether log should be plain not colorized (by default this is off).
+    # @attr [Fixnum] trace_indent The indent space size (by default this is 4).
+    # @attr [Array<String, Symbol>] excluded_fields The fields excluded from all logs.
     class Readable < Base
       attr_accessor :plain, :trace_indent, :excluded_fields
 

data/lib/ougai/logger.rb

@@ -1,4 +1,9 @@
 module Ougai
+  # Main Logger
+  # @attr [String] default_message Use this if log message is not specified (by default this is 'No message').
+  # @attr [String] exc_key The field name of Exception (by default this is :err).
+  # @attr [Hash] with_fields The fields appending to all logs.
+  # @attr [Proc] before_log Hook before logging.
   class Logger < ::Logger
     include Logging
 
@@ -12,6 +17,8 @@ module Ougai
       @formatter = create_formatter
     end
 
+    # Broadcasts the same logs to the another logger
+    # @param logger [Logger] The logger receiving broadcast logs.
     def self.broadcast(logger)
       Module.new do |mdl|
         ::Logger::Severity.constants.each do |severity|
@@ -35,6 +42,7 @@ module Ougai
       end
     end
 
+    # @private
     def chain(severity, args, fields, hooks)
       hooks.push(@before_log) if @before_log
       write(severity, args, merge_fields(@with_fields, fields), hooks)
@@ -42,6 +50,7 @@ module Ougai
 
     protected
 
+    # @private
     def append(severity, args)
       hooks = @before_log ? [@before_log] : []
       write(severity, args, @with_fields, hooks)
@@ -51,6 +60,8 @@ module Ougai
       Formatters::Bunyan.new
     end
 
+    private
+
     def write(severity, args, fields, hooks)
       data = merge_fields(fields, to_item(args))
       hooks.each do |hook|
@@ -73,8 +84,6 @@ module Ougai
       end
     end
 
-    private
-
     def create_item_with_1arg(msg)
       item = {}
       if msg.is_a?(Exception)

data/lib/ougai/logging.rb

@@ -1,47 +1,76 @@
 module Ougai
+  # Common Logging features
   module Logging
     attr_accessor :with_fields
     attr_writer :before_log
 
+    # Log any one or more of a message, an exception and structured data as DEBUG.
+    # If the block is given for delay evaluation, it returns them as an array or the one of them as a value.
+    # @param message [String] The message to log. Use default_message if not specified.
+    # @param ex [Exception] The exception or the error
+    # @param data [Object] Any structured data
+    # @yieldreturn [String|Exception|Object|Array] Any one or more of former parameters
+    # @return [Boolean] true
     def debug(message = nil, ex = nil, data = nil, &block)
       log(Logger::DEBUG, message, ex, data, block)
     end
 
+    # Log any one or more of a message, an exception and structured data as INFO.
+    # @return [Boolean] true
+    # @see Logging#debug
     def info(message = nil, ex = nil, data = nil, &block)
       log(Logger::INFO, message, ex, data, block)
     end
 
+    # Log any one or more of a message, an exception and structured data as WARN.
+    # @return [Boolean] true
+    # @see Logging#debug
     def warn(message = nil, ex = nil, data = nil, &block)
       log(Logger::WARN, message, ex, data, block)
     end
 
+    # Log any one or more of a message, an exception and structured data as ERROR.
+    # @return [Boolean] true
+    # @see Logging#debug
     def error(message = nil, ex = nil, data = nil, &block)
       log(Logger::ERROR, message, ex, data, block)
     end
 
+    # Log any one or more of a message, an exception and structured data as FATAL.
+    # @return [Boolean] true
+    # @see Logging#debug
     def fatal(message = nil, ex = nil, data = nil, &block)
       log(Logger::FATAL, message, ex, data, block)
     end
 
+    # Log any one or more of a message, an exception and structured data as UNKNOWN.
+    # @return [Boolean] true
+    # @see Logging#debug
     def unknown(message = nil, ex = nil, data = nil, &block)
       args = block ? yield : [message, ex, data]
       append(Logger::UNKNOWN, args)
     end
 
+    # Creates a child logger and returns it.
+    # @param fields [Hash] The fields appending to all logs
+    # @return [ChildLogger] A created child logger
     def child(fields = {})
       ChildLogger.new(self, fields)
     end
 
+    # @private
     def chain(_severity, _args, _fields, _hooks)
       raise NotImplementedError
     end
 
     protected
 
+    # @private
     def append(severity, args)
       raise NotImplementedError
     end
 
+    # @private
     def merge_fields(base_data, new_data)
       base_data.merge(new_data) do |_, base_val, new_val|
         if base_val.is_a?(Array) and new_val.is_a?(Array)

data/lib/ougai/version.rb

@@ -1,3 +1,3 @@
 module Ougai
-  VERSION = "1.4.3"
+  VERSION = "1.4.4"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ougai
 version: !ruby/object:Gem::Version
-  version: 1.4.3
+  version: 1.4.4
 platform: ruby
 authors:
 - Toshimitsu Takahashi
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-08-18 00:00:00.000000000 Z
+date: 2017-08-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -53,8 +53,8 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.0'
 description: |2
-      A JSON logging system is capable of handling a message, data or an exception easily.
-      It is compatible with Bunyan for Node.js and can also output human readable format for console.
+      A structured logging system is capable of handling a message, custom data or an exception easily.
+      It has JSON formatter compatible with Bunyan for Node.js and human readable formatter with Awesome Print for console.
 email:
 - toshi@tilfin.com
 executables: []
@@ -103,16 +103,17 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.6.11
 signing_key: 
 specification_version: 4
-summary: JSON logger compatible with node-bunyan is capable of handling data easily.
+summary: JSON logger compatible with node-bunyan is capable of handling structured
+  data easily.
 test_files:
-- spec/child_logger_spec.rb
 - spec/formatters/base_spec.rb
 - spec/formatters/bunyan_spec.rb
 - spec/formatters/readable_spec.rb
-- spec/logger_spec.rb
+- spec/child_logger_spec.rb
 - spec/logging_spec.rb
+- spec/logger_spec.rb
 - spec/ougai_spec.rb
 - spec/spec_helper.rb