mimi-logger 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d79dac353758f9f0364896918dfb9929f3ba972a727eb93830b32ae209eaa4e
-  data.tar.gz: 4e0400b25ce0af579740fa2fd567ea2ba60e1d36fb5b5189a301049db3e3d8e0
+  metadata.gz: '08802d5b0a249e93a152ad6e55b97dac5f90235815621cf4e184f98f4579f8b0'
+  data.tar.gz: 0ed0db974edfae6ac95a1cbd4d3ad44328c1e2c77013598dc41811b5c83d0dba
 SHA512:
-  metadata.gz: 5c7d372b6eb408b2fbf5cde056708e4195de48a251e540ae5fd31edb6e525afacbda22b9ec9003d89ed9f6f699c092ae2af4a7e5397fae237e0e13d3081232ce
-  data.tar.gz: 9c4db7213fb0f11925bb6a8430e8dcc12c15fbe17c888717ec385be70a60b0a808c48372684463eaa1241908c930ca591e9cb349aadf1c903cb168b95c11f523
+  metadata.gz: fd0d2e2ff59c4389a4cc0bbde0e594d1bb73a7931df7137b9e31126b42f884ed473747473fe18540721dd93fd670ffed38c6cfe299a97052081eec5a68fe0322
+  data.tar.gz: a6ba83b28d31f0586dd1c151fb944315d0d192abf44799c50206544e0ae869897baa5c4f9d392ee6861b57fb22668af4745bbfd9a5d2bc505308f743898ddf92

data/README.md

@@ -118,7 +118,7 @@ web requests will be interleaved and understanding the flow, the cause and effec
 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!`:
+A new context may be initiated by `.new_context!`:
 
 ```ruby
 require 'mimi/logger'
@@ -126,7 +126,7 @@ require 'mimi/logger'
 logger = Mimi::Logger.new
 
 logger.info 'I am a banana!'
-logger.new_context_id!
+logger.new_context!
 logger.info 'I am a banana!' # this is not the same banana, it's from a different context
 ```
 
@@ -156,6 +156,40 @@ new context ID in the beginning of your processing and pass it along with all th
 other components of the system. Upon receiving such a request, another application sets its local context ID
 to the received value and continues.
 
+#### Preserving context
+
+If necessary, it is possible to run a block of code in another logging context and restore
+the original context after completion:
+
+```ruby
+require 'mimi/logger'
+
+logger = Mimi::Logger.new
+
+logger.context_id = 'original-context'
+logger.with_preserved_context do
+  logger.context_id = 'another-context'
+  ...
+end
+logger.context_id # => "original-context"
+```
+
+Or run a block of code with a new temporary context and restore the original one after completion:
+
+```ruby
+require 'mimi/logger'
+
+logger = Mimi::Logger.new
+
+logger.context_id = 'original-context'
+logger.with_new_context do
+  logger.context_id # => "5d11f7c483dcfb2a"
+  ...
+end
+logger.context_id # => "original-context"
+```
+
+
 ## 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.2.2'.freeze
+    VERSION = '0.2.3'.freeze
   end
 end

data/lib/mimi/logger.rb

@@ -1,3 +1,4 @@
+
 # frozen_string_literal: true
 
 require 'forwardable'
@@ -17,10 +18,9 @@ module Mimi
     include Mimi::Core::Module
 
     attr_reader :logger_instance, :options
-    delegate [
-      :debug?, :info?, :warn?, :error?, :fatal?,
-      :<<, :add, :log
-    ] => :logger_instance
+
+    delegate %i[debug? info? warn? error? fatal? << add log] => :logger_instance
+    delegate %i[context_id context_id= new_context! with_new_context with_preserved_context] => self
 
     default_options(
       format: 'json',   # 'string' or 'json'
@@ -75,23 +75,36 @@ module Mimi
 
     # Logs a new message at the corresponding logging level
     #
-    #
-    #
     def debug(*args, &block)
       logger_instance.debug(args, &block)
     end
+
+    # Logs a new message at the corresponding logging level
+    #
     def info(*args, &block)
       logger_instance.info(args, &block)
     end
+
+    # Logs a new message at the corresponding logging level
+    #
     def warn(*args, &block)
       logger_instance.warn(args, &block)
     end
+
+    # Logs a new message at the corresponding logging level
+    #
     def error(*args, &block)
       logger_instance.error(args, &block)
     end
+
+    # Logs a new message at the corresponding logging level
+    #
     def fatal(*args, &block)
       logger_instance.fatal(args, &block)
     end
+
+    # Logs a new message at the corresponding logging level
+    #
     def unknown(*args, &block)
       logger_instance.unknown(args, &block)
     end
@@ -123,6 +136,7 @@ module Mimi
     # Returns formatter Proc object depending on configured format
     #
     # @return [Proc]
+    # @private
     #
     def self.formatter(options)
       case options[:format].to_s
@@ -138,8 +152,8 @@ module Mimi
     # Returns formatter for 'json' format
     #
     # @param options [Hash] logger options
-    #
     # @return [Proc]
+    # @private
     #
     def self.formatter_json(options)
       proc do |severity, _datetime, _progname, message|
@@ -153,8 +167,8 @@ module Mimi
     # Returns formatter for 'string' format
     #
     # @param options [Hash] logger options
-    #
     # @return [Proc]
+    # @private
     #
     def self.formatter_string(options)
       proc do |severity, _datetime, _progname, message|
@@ -183,6 +197,7 @@ module Mimi
     # message and the rest are optional parameters passed in a Hash argument.
     #
     # @return [Hash]
+    # @private
     #
     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
@@ -218,44 +233,65 @@ module Mimi
     # 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
+    # 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
+      Thread.current[CONTEXT_ID_THREAD_VARIABLE] || new_context!
     end
 
     # Sets the new context ID to the given value
     #
-    # @param id [String]
+    # @param id [String] a new context ID
+    # @return [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
+    # Starts a new logging context, generates a new random context ID and sets it as current
     #
     # @return [String] a new context ID
     #
-    def self.new_context_id!
+    def self.new_context!
       self.context_id = SecureRandom.hex(CONTEXT_ID_SIZE)
     end
 
-    def new_context_id!
-      self.class.new_context_id!
+    # Executes a given block and ensures the context is restored afterwards
+    #
+    # @example
+    #   logger.context_id # => "5d11f7c483dcfb2a"
+    #   logger.with_preserved_context do
+    #     logger.context_id = "temporary-context"
+    #     logger.context_id # => "temporary-context"
+    #   end
+    #   logger.context_id # => "5d11f7c483dcfb2a"
+    #
+    def self.with_preserved_context(&_block)
+      preserved_context_id = context_id
+      yield
+    ensure
+      self.context_id = preserved_context_id
     end
 
-    # private-ish
+    # Executes a given block in a new context and restores the context afterwards
+    #
+    # @example
+    #   logger.context_id # => "5d11f7c483dcfb2a"
+    #   logger.with_new_context do
+    #     logger.context_id # => "e211ef95633a04b5"
+    #   end
+    #   logger.context_id # => "5d11f7c483dcfb2a"
+    #
+    def self.with_new_context(&_block)
+      with_preserved_context do
+        new_context!
+        yield
+      end
+    end
 
+    # @private
     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.2.2
+  version: 0.2.3
 platform: ruby
 authors:
 - Alex Kukushkin
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-04-19 00:00:00.000000000 Z
+date: 2018-04-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mimi-core