mimi-logger 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: fbe29541826be5c0039eaa0e048fb358b16fbdce
-  data.tar.gz: 3df2c56beae9eebb87a7651f4a38d14e871d6395
+SHA256:
+  metadata.gz: 1dac6f3cbaeef0582579cb7f695e92896676d9267c286e7d82d95d7d72312219
+  data.tar.gz: 3e9866931dff24f400dca04da3e1e41d59139f33860c621d2e7136656f80f87d
 SHA512:
-  metadata.gz: 18b631e1f90f9406c9556710b721e3761a01e9fff760881330f9b996f758ef2aa41e8eb9ead36432f7b06ab15d02b6f2753c83d9780a9050ec9dc4ae6b1e0432
-  data.tar.gz: 644d8221e16b761a5a7fcb63484566e88659421e71677eb728b3684f1938cec4453ff1fd50e3ee6a4a59804f3c57c999479654a15081567cb093a537ae744034
+  metadata.gz: 0c02fa6f4e89c807b5b6284aec1e304939cf3aec08820c73db08380b81a0b0f071e85e99c55810bf8e0b584a5497f227748311dd44b7d4e9b087b649970a2b2a
+  data.tar.gz: 62cdc14d5fcbfe555e2fe45af17db5c004d051767445802dbb35fa3525825f4de514afad51da9fd700f110ae4c1ad70680344da47641b3bba50250a7c2dfdf9e

data/README.md

@@ -25,11 +25,93 @@ Or install it yourself as:
 ```ruby
 require 'mimi/logger'
 
-logger = Mimi::Logger.new
+logger = Mimi::Logger.new format: :string
 
 logger.info 'I am a banana!' # outputs "I, I am a banana!" to STDOUT
 ```
 
+### Logging format
+
+Since v0.2.0 the default format for logging is JSON:
+
+```ruby
+require 'mimi/logger'
+
+logger = Mimi::Logger.new
+
+logger.info 'I am a banana' # => '{"s":"I","m":"I am a banana","c":"60eecc2e764fe2f6"}'
+```
+
+The following properties of a serialized JSON object are reserved:
+
+name | description
+-----|------------
+  s  | severity, one of D,I,W,E,F
+  m  | message
+  c  | context ID, 8 bytes hex encoded
+
+Additional properties may be provided by the caller and they will be included in the logged JSON:
+
+```ruby
+require 'mimi/logger'
+
+logger = Mimi::Logger.new
+
+t_start = Time.now
+... # work, work
+logger.info 'Jobs done', t: Time.now - t_start
+# => '{"s":"I","m":"Jobs done","c":"60eecc2e764fe2f6", "t": 13.794034499}'
+```
+
+### Logging context
+
+Logging context refers to a set of instructions that are somehow logically grouped. For example,
+the whole logic processing an incoming web request can be seen as operating within a single context
+of this particular web request. In a distributed or a multithreaded application it would be beneficial
+to identify logged messages produced within same context, otherwise the messages related to different
+web requests will be interleaved and understanding the flow, the cause and effect would be very difficult.
+
+To solve this problem, Mimi::Logger allows for setting an arbitrary (or random) context ID, which is local
+to the current thread, and which is included in every logged message.
+
+A new context may be initiated by `.new_context_id!`:
+
+```ruby
+require 'mimi/logger'
+
+logger = Mimi::Logger.new
+
+logger.info 'I am a banana!'
+logger.new_context_id!
+logger.info 'I am a banana!' # this is not the same banana, it's from a different context
+```
+
+Or it can be set to an explicit value:
+
+```ruby
+require 'mimi/logger'
+
+logger = Mimi::Logger.new
+
+logger.info 'I am a banana!'
+logger.context_id = 'different-context!'
+logger.info 'I am a banana!' # this is not the same banana, it's from a 'different-context!'
+
+```
+
+#### Context ID in a multithreaded application
+
+The context ID is local to a current thread, so it's safe to start or assign a different context ID
+in other threads of the application.
+
+#### Context ID in a distributed application
+
+If you have a distributed multicomponent application (e.g. microservice architecture), context ID
+may help to track requests between multiple parties. In order to achieve it, you need to generate a
+new context ID in the beginning of your processing and pass it along with all the requests/messages to
+other components of the system. Upon receiving such a request, another application sets its local context ID
+to the received value and continues.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/kukushkin/mimi-logger. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.

data/lib/mimi/logger/version.rb

@@ -1,5 +1,5 @@
 module Mimi
   class Logger
-    VERSION = '0.1.2'.freeze
+    VERSION = '0.2.0'.freeze
   end
 end

data/lib/mimi/logger.rb

@@ -1,5 +1,8 @@
+# frozen_string_literal: true
+
 require 'forwardable'
 require 'logger'
+require 'json'
 require 'mimi/core'
 
 module Mimi
@@ -7,17 +10,21 @@ module Mimi
   # Mimi::Logger is a preconfigured logger which outputs log messages to STDOUT.
   #
   class Logger
+    CONTEXT_ID_SIZE = 8 # bytes
+    CONTEXT_ID_THREAD_VARIABLE = 'mimi_logger_context_id'
+
     extend Forwardable
     include Mimi::Core::Module
 
     attr_reader :logger_instance
     delegate [
-      :debug, :info, :warn, :error, :fatal, :unknown,
       :debug?, :info?, :warn?, :error?, :fatal?,
       :<<, :add, :log
     ] => :logger_instance
 
     default_options(
+      format: 'json',   # 'string' or 'json'
+      log_context: true,
       level: 'info',
       cr_character: '↲' # alternative CR: ↵ ↲ ⏎
     )
@@ -36,7 +43,7 @@ module Mimi
     #   logger.debug 'blabla' # => "D, blabla"
     #
     def initialize(*args)
-      io = args.shift if args.first.is_a?(IO)
+      io = args.shift if args.first.is_a?(IO) || args.first.is_a?(StringIO)
       io ||= STDOUT
       opts = args.shift if args.first.is_a?(Hash)
       opts ||= {}
@@ -51,7 +58,7 @@ module Mimi
 
     # Returns the current log level
     #
-    # @return [Fixnum]
+    # @return [Integer]
     #
     def level
       logger_instance.level
@@ -60,18 +67,41 @@ module Mimi
     # Sets the log level.
     # Allows setting the log level from a String or a Symbol, in addition to the standard ::Logger::INFO etc.
     #
-    # @param [String,Symbol,Fixnum] value
+    # @param [String,Symbol,Integer] value
     #
     def level=(value)
       logger_instance.level = self.class.level_from_any(value)
     end
 
+    # Logs a new message at the corresponding logging level
+    #
+    #
+    #
+    def debug(*args, &block)
+      logger_instance.debug(args, &block)
+    end
+    def info(*args, &block)
+      logger_instance.info(args, &block)
+    end
+    def warn(*args, &block)
+      logger_instance.warn(args, &block)
+    end
+    def error(*args, &block)
+      logger_instance.error(args, &block)
+    end
+    def fatal(*args, &block)
+      logger_instance.fatal(args, &block)
+    end
+    def unknown(*args, &block)
+      logger_instance.unknown(args, &block)
+    end
+
     # Returns the log level inferred from value
     #
-    # @param value [String,Symbol,Fixnum]
+    # @param value [String,Symbol,Integer]
     #
     def self.level_from_any(value)
-      return value if value.is_a?(Fixnum)
+      return value if value.is_a?(Integer)
       case value.to_s.downcase.to_sym
       when :debug
         ::Logger::DEBUG
@@ -90,12 +120,138 @@ module Mimi
       end
     end
 
+    # Returns formatter Proc object depending on configured format
+    #
+    # @return [Proc]
+    #
     def self.formatter
+      case module_options[:format].to_s
+      when 'json'
+        formatter_json
+      when 'string'
+        formatter_string
+      else
+        raise "Invalid format specified for Mimi::Logger: '#{module_options[:format]}'"
+      end
+    end
+
+    # Returns formatter for 'json' format
+    #
+    # @return [Proc]
+    #
+    def self.formatter_json
       proc do |severity, _datetime, _progname, message|
-        "#{severity.to_s[0]}, #{message.to_s.tr("\n", module_options[:cr_character])}\n"
+        h = formatter_message_args_to_hash(message)
+        h[:c] = context_id if module_options[:log_context]
+        h[:s] = severity.to_s[0]
+        h.to_json
+      end
+    end
+
+    # Returns formatter for 'string' format
+    #
+    # @return [Proc]
+    #
+    def self.formatter_string
+      proc do |severity, _datetime, _progname, message|
+        h = formatter_message_args_to_hash(message)
+        parts = []
+        parts << severity.to_s[0]
+        parts << context_id if module_options[:log_context]
+        parts << h[:m].to_s.tr("\n", module_options[:cr_character])
+        parts << '...' unless h.except(:m).empty?
+        parts.join(', ')
+      end
+    end
+
+    # Converts logger methods arguments passed in various forms to a message hash.
+    #
+    # Arguments to a logger may be passed in 6 different ways:
+    # @example
+    #   logger.info('String')
+    #   logger.info('String', param1: '..and a Hash')
+    #   logger.info(m: 'Just a Hash', param1: 'with optional data')
+    #
+    #   # and the same 3 ways in a block form
+    #   logger.info { ... }
+    #
+    # This helper method converts all possible variations into one Hash, where key m: refers to the
+    # message and the rest are optional parameters passed in a Hash argument.
+    #
+    # @return [Hash]
+    #
+    def self.formatter_message_args_to_hash(message_args)
+      message_args = message_args.is_a?(String) || message_args.is_a?(Hash) ? [message_args] : message_args
+      if !message_args.is_a?(Array) || message_args.size > 2
+        raise ArgumentError, "Mimi::Logger arguments expected to be Array of up to 2 elements: #{message_args.inspect}"
       end
+
+      h = {}
+      arg1 = message_args.shift
+      arg2 = message_args.shift
+
+      if arg1.is_a?(String)
+        if arg2 && !arg2.is_a?(Hash)
+          raise ArgumentError, 'Mimi::Logger arguments are expected to be one of (<String>, <Hash>, [<String>, <Hash>])'
+        end
+        h = arg2.dup || {}
+        h[:m] = arg1
+      elsif arg1.is_a?(Hash)
+        if arg2
+          raise ArgumentError, 'Mimi::Logger arguments are expected to be one of (<String>, <Hash>, [<String>, <Hash>])'
+        end
+        h = arg1.dup
+      else
+        raise ArgumentError, 'Mimi::Logger arguments are expected to be one of (<String>, <Hash>, [<String>, <Hash>])'
+      end
+      h
+    end
+
+    # Returns current context ID if set, otherwise generates and sets a new context ID
+    # and returns it.
+    #
+    # Context ID is local to the current thread. It identifies a group of instructions
+    # happening within same logical context, as a single operation. For example, processing
+    # an incoming request may be seen as a single context.
+    #
+    # Context ID is logged with every message
+    #
+    # @return [String] a hex encoded context ID
+    #
+    def self.context_id
+      Thread.current[CONTEXT_ID_THREAD_VARIABLE] || new_context_id!
     end
 
+    def context_id
+      self.class.context_id
+    end
+
+    # Sets the new context ID to the given value
+    #
+    # @param id [String]
+    #
+    def self.context_id=(id)
+      Thread.current[CONTEXT_ID_THREAD_VARIABLE] = id
+    end
+
+    def context_id=(id)
+      self.class.context_id = id
+    end
+
+    # Generates a new random context ID and sets it as current
+    #
+    # @return [String] a new context ID
+    #
+    def self.new_context_id!
+      self.context_id = SecureRandom.hex(CONTEXT_ID_SIZE)
+    end
+
+    def new_context_id!
+      self.class.new_context_id!
+    end
+
+    # private-ish
+
     def self.module_manifest
       {
         log_level: {

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mimi-logger
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Alex Kukushkin
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-05-17 00:00:00.000000000 Z
+date: 2018-04-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mimi-core
@@ -123,7 +123,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5.1
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: A pre-configured logger for microservice applications