intake 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: febaaa600f3b7a5c8ed974a8e059a4d5ea12e61b0e5edf6fb0bf3c707f56027b
-  data.tar.gz: 9bc82ce4ad485486a397e63c84c7a54445df78b2e3f285b1d0ec26d1cfddfdc8
+  metadata.gz: 0da496aeddc3a2af915242e66b0dde99077f9db6fad39b1aa608db88c4b3c7d7
+  data.tar.gz: 3e6f74f74938ca1ac38c4c6ffef7f6518a159ce208b26cd6fc442e1063e7d2b6
 SHA512:
-  metadata.gz: bf360302e2ece8d18034a1b34587d3fa6c8a267f8d13ec64535b7de212e7307235b58b76a28c5f429fed832ee1ef4a1aa05c57391ba5cd74f98d207aa2c71033
-  data.tar.gz: d140b351c1171e9a5bce2e5e4d01926900300f60a8e18ce0c0c591cadcf54ac6ced6fa22b584cf3d8ad4dff754dfc31399613ba39a1b2a8a750869026c430ab1
+  metadata.gz: 7b79c556355cd93395449943a59e1fda06af7081357fd94581a5ae8e192b10b3e5e113e8848b66c56cc9ab1b7e0242bbdbc1217c65c845dedf2e88f931e252c0
+  data.tar.gz: ed1959f3d7d111bd7acfb62412eec03c76767ef2cdf57ceab35ac5c0640dbc516cf5cf5e0f15c69367dab5a6f1ff7781264bcdd0f43f86c9a4aec95ba1f62929

data/README.md

@@ -1,3 +1,5 @@
+[![.github/workflows/rsspec.yml](https://github.com/the-vk/intake/actions/workflows/rspec.yml/badge.svg)](https://github.com/the-vk/intake/actions/workflows/rspec.yml)
+
 # intake
 
 ## Description
@@ -15,6 +17,198 @@ The library is designed with multiple base principles:
 gem install intake
 ```
 
+## Design
+
+**intake** has two primary components:
+
+* Logger
+* Sink
+
+**Intake::Logger** is a component that captures a logging event and forwards that to **Intake::EventDrain** which is a single point to collect log events.
+
+A logger may optionally filter events by filter to quickly discard events with level below threshold.
+
+**Intake::Sink** is a component that receives event logs and writes to a permanent storage.
+
+A sink may filter events by level, logger name, or any other event attributes.
+
+## Examples
+
+This example sets up logging to write messages to STDOUT.
+**intake** writes messages in Ruby Logger format.
+```ruby
+require 'intake`
+
+log = Intake[:root]
+log.level = :info
+Intake.add_sink Intake::IOSink.new($stdout)
+
+log.debug 'debug message'
+log.debug { 'proc debug message' }
+# Logger methods can take a block to generate log message
+# Blocks allow to delay expensive message evaluation until and unless event is logged
+log.debug do
+  print("you don't see me!")
+  'expensive proc debug message'
+end
+log.info 'info message'
+log.info { 'proc info message' }
+log.warn 'warn message'
+log.warn { 'proc warn message' }
+log.error 'error message'
+log.error { 'proc error message' }
+log.fatal 'fatal message'
+log.fatal { 'proc fatal message' }
+```
+
+Output:
+
+```
+I, [2022-10-09T15:57:58.377963 #12484] INFO -- : info message
+I, [2022-10-09T15:57:58.378097 #12484] INFO -- : proc info message
+W, [2022-10-09T15:57:58.378121 #12484] WARN -- : warn message
+W, [2022-10-09T15:57:58.378133 #12484] WARN -- : proc warn message
+E, [2022-10-09T15:57:58.378169 #12484] ERROR -- : error message
+E, [2022-10-09T15:57:58.378212 #12484] ERROR -- : proc error message
+F, [2022-10-09T15:57:58.378255 #12484] FATAL -- : fatal message
+F, [2022-10-09T15:57:58.378297 #12484] FATAL -- : proc fatal message
+```
+
+### Sinks and filters
+
+**intake** supports multuple target sinks with various filters.
+
+```ruby
+log = Intake[:root]
+log.level = :debug
+io_sink = Intake::IOSink.new($stdout)
+# filter is a proc-like object to make a decision on events
+# event is accepted by sink if #call(event) returns true
+io_sink.add_filter Intake::Filters::LevelFilter.new(:warn)
+Intake.add_sink io_sink
+file_sink = Intake::IOSink.new(File.new('/dev/null', 'a'))
+file_sink.add_filter Intake::Filters::LevelFilter.new(:info)
+
+log.debug 'debug message'     # not logged
+log.info 'info message'       # logged to file
+log.warn 'warn message'       # logged to both stdout and file
+log.error 'error message'     # logged to both stdout and file
+log.fatal 'fatal message'     # logged to both stdout and file
+```
+
+Output:
+
+```
+W, [2022-10-09T16:08:48.752905 #14476] WARN -- : warn message
+E, [2022-10-09T16:08:48.752983 #14476] ERROR -- : error message
+F, [2022-10-09T16:08:48.753031 #14476] FATAL -- : fatal message
+```
+
+### MDC
+
+Mapped diagnostic context (MDC) is a thread-local storage to attach extra information to log events, e.g. operation id or correlation id.
+
+```ruby
+log = Intake[:root]
+log.level = :info
+sink = Intake::IOSink.new($stdout)
+sink.formatter = ->(e) { "#{e.timestamp} [#{e[:correlation_id]}] - #{e.logger_name}: - #{e.message}\n" }
+Intake.add_sink sink
+
+log.info 'a message'
+
+Intake::MDC[:correlation_id] = :abc
+
+log.info 'message with MDC'
+
+Intake::MDC.clear(:correlation_id)
+
+log.info 'a message with no MDC'
+```
+
+Output:
+
+```
+2022-10-09 16:13:23 -0700 [] - root: - a message
+2022-10-09 16:13:23 -0700 [abc] - root: - message with MDC
+2022-10-09 16:13:23 -0700 [] - root: - a message with no MDC
+```
+
+### Structured logging
+
+**Intake::Logger** methods takes optional keyword argument **meta** with a Hash with extra details about log event.
+Sink may write meta to output in structured format that allows to query logs.
+
+```ruby
+log = Intake[:root]
+log.level = :info
+sink = Intake::IOSink.new($stdout)
+sink.formatter = ->(e) { "#{e.timestamp} [#{e[:user_id]}] - #{e.logger_name}: - #{e.message}\n" }
+Intake.add_sink sink
+
+log.info 'a message', meta: { user_id: 'username' }
+```
+
+Output:
+
+```
+2022-10-09 16:18:21 -0700 [username] - root: - a message
+```
+### Ruby Logger adapter
+
+**intake** provides an adapter to Ruby Logger API. Adapter can be used as drop-in replacement of regular Ruby Logger.
+
+```ruby
+require 'intake'
+
+log = Intake[:root]
+Intake.add_sink Intake::IOSink.new($stdout)
+log.level = :debug
+log = log.as_ruby_logger
+
+log.add(Logger::Severity::FATAL, 'msg', 'sample')
+
+log.debug 'debug'
+log.info 'info'
+log.warn 'warn'
+log.error 'error'
+log.fatal 'fatal'
+log.unknown 'unknown'
+
+log.warn { 'warn proc message' }
+
+log = Intake[:root].as_ruby_logger(progname: 'sample')
+
+log.debug 'debug'
+log.info 'info'
+log.warn 'warn'
+log.error 'error'
+log.fatal 'fatal'
+log.unknown 'unknown'
+
+log.warn { 'warn proc message' }
+```
+
+Output:
+
+```
+F, [2022-10-09T16:16:13.918872 #14918] FATAL -- sample: msg
+D, [2022-10-09T16:16:13.918992 #14918] DEBUG -- : debug
+I, [2022-10-09T16:16:13.919053 #14918] INFO -- : info
+W, [2022-10-09T16:16:13.919114 #14918] WARN -- : warn
+E, [2022-10-09T16:16:13.919143 #14918] ERROR -- : error
+F, [2022-10-09T16:16:13.919191 #14918] FATAL -- : fatal
+F, [2022-10-09T16:16:13.919219 #14918] FATAL -- : unknown
+W, [2022-10-09T16:16:13.919267 #14918] WARN -- : warn proc message
+D, [2022-10-09T16:16:13.919319 #14918] DEBUG -- sample: debug
+I, [2022-10-09T16:16:13.919363 #14918] INFO -- sample: info
+W, [2022-10-09T16:16:13.919417 #14918] WARN -- sample: warn
+E, [2022-10-09T16:16:13.919442 #14918] ERROR -- sample: error
+F, [2022-10-09T16:16:13.919491 #14918] FATAL -- sample: fatal
+F, [2022-10-09T16:16:13.919542 #14918] FATAL -- sample: unknown
+W, [2022-10-09T16:16:13.919594 #14918] WARN -- sample: warn proc message
+```
+
 ## License
 
 The MIT License. See the [LICENSE](/LICENSE) file for the full text.

data/lib/intake/exception_formatter.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Intake
+  # Base class that formats exception object to string
+  class ExceptionFormatter
+    attr_accessor :backtrace, :cause
+
+    def initialize
+      @backtrace = true
+      @cause = true
+    end
+
+    # Formats error to string
+    def call(err)
+      format(err, []).join("\n")
+    end
+
+    protected
+
+    def format(err, lines)
+      lines << format_title(err)
+      lines.concat(err.backtrace) if backtrace
+      format(err.cause, lines) if cause && !err.cause.nil?
+      lines
+    end
+
+    def format_title(err)
+      "Caused by: <#{err.class.name}> #{err.message}"
+    end
+
+    def format_backtrace(err, lines)
+      lines + err.backtrace
+    end
+  end
+end

data/lib/intake/formatter.rb

@@ -9,7 +9,7 @@ module Intake
 
     def call(event)
       # rubocop:disable Layout/LineLength
-      "#{event.level.to_s[0]}, [#{event.timestamp.strftime(@timestamp_format)} ##{Process.pid}] #{event.level} -- #{event[:progname]}: #{event.message}\n"
+      "#{event.level.to_s[0]}, [#{event.timestamp.strftime(@timestamp_format)} ##{Process.pid}] #{event.level} -- #{event[:progname]}: #{event.message}"
       # rubocop:enable Layout/LineLength
     end
   end

data/lib/intake/io_sink.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'exception_formatter'
 require_relative 'formatter'
 require_relative 'sink'
 
@@ -10,12 +11,14 @@ module Intake
       super()
       @io = io
       @formatter = ::Intake::Formatter.new
+      @exception_formatter = ::Intake::ExceptionFormatter.new
     end
 
-    attr_writer :formatter
+    attr_accessor :formatter, :exception_formatter
 
     def drain(event)
-      txt = @formatter.call(event)
+      error_message = "\n#{@exception_formatter.call(event[:error])}" unless event[:error].nil?
+      txt = "#{@formatter.call(event)}#{error_message}\n"
       @io.write(txt)
     end
   end

data/lib/intake/logger.rb

@@ -11,31 +11,38 @@ require_relative 'repository'
 module Intake
   # Logger is a object that captures log event and forward that to event sinks.
   class Logger
+    DEFAULT_LEVEL = ::Intake::Level[:info]
     class << self
       def [](name)
-        ::Intake::Repository.instance.get_or_add(name) do |logger_name|
-          Logger.new(logger_name)
+        ::Intake::Repository.instance.get_or_add(name) do |logger_name, parent|
+          Logger.new(logger_name, parent: parent)
         end
       end
     end
 
     attr_reader :name
 
-    def initialize(name)
+    def initialize(name, parent: nil)
       validate_name(name)
 
       @name = name
-      @level = ::Intake::Level[:info]
+      @level = nil
+      @parent = parent
     end
 
     def level?(level)
-      @level.val <= level.val
+      self.level.val <= level.val
+    end
+
+    def level
+      @level || @parent&.level || DEFAULT_LEVEL
     end
 
     def level=(level)
       @level = case level
                when String, Symbol then ::Intake::Level[level.to_sym]
                when ::Intake::Level then level
+               when nil then nil
                end
     end
 

data/lib/intake/repository.rb

@@ -19,17 +19,16 @@ module Intake
       @store.key? canonize_name(name)
     end
 
-    def get_or_add(name)
-      name = canonize_name(name)
-      logger = @store[name]
+    def get_or_add(name, &block)
+      return nil if name.nil?
 
-      if logger.nil?
-        logger = @mutex.synchronize do
-          @store[name] = yield(name) unless @store.key?(name)
-          @store[name]
+      name = canonize_name(name)
+      unless @store.key? name
+        @mutex.synchronize do
+          create_logger_unsafe(name, &block) unless @store.key? name
         end
       end
-      logger
+      @store[name]
     end
 
     private
@@ -44,8 +43,22 @@ module Intake
       end
     end
 
+    def parent_name(name)
+      separator_rindex = name.rindex('::')
+      separator_rindex.nil? ? 'root' : name[0, separator_rindex]
+    end
+
     def module_name(mod)
       mod.name
     end
+
+    def create_logger_unsafe(name, &block)
+      unless name == 'root'
+        parent_logger_name = parent_name(name)
+        parent_logger = @store[parent_logger_name] || create_logger_unsafe(parent_logger_name, &block)
+      end
+      @store[name] = block.call(name, parent_logger) unless @store.key?(name)
+      @store[name]
+    end
   end
 end

data/lib/intake/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Intake
-  VERSION = '0.1.0'
+  VERSION = '0.3.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: intake
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Andrey Maraev
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-10-09 00:00:00.000000000 Z
+date: 2022-10-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -148,6 +148,7 @@ files:
 - lib/intake.rb
 - lib/intake/async_sink.rb
 - lib/intake/event_drain.rb
+- lib/intake/exception_formatter.rb
 - lib/intake/filter.rb
 - lib/intake/filters/level_filter.rb
 - lib/intake/filters/logger_name_prefix_filter.rb