log_sinks 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1c36d2668770385f86b0fe13843d91fae5f9f2164d53d9a42aaca1a6d0859242
+  data.tar.gz: 1b52160fef8827b617b7fb00b728b97b3641c3e5c70ef47b61e8e10b86e154a5
+SHA512:
+  metadata.gz: 3c51e5bb67d705cbd01795883e8e8b3fa3a397e7bd82690c306f70c52fe41eea78c16a0cfc829fcbaf4a3c814716dca9b32c3bd30138f0b2ec9fdc40b25617c9
+  data.tar.gz: e3bbfb26c3100466d1d95232d2512467f319b32371dfe4b07e261a26e90721b1fd29753b88dc6b6dcc0374a4cfae14713e3b6b54e3c9749c03c16c7a604e1fd9

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Andrey Maraev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,20 @@
+# log_sinks
+
+## Description
+
+**log_sinks** is a powerful yet easy to use logging library.
+The library is designed with multiple base principles:
+
+* Be a drop-in replacement for Ruby `Logger`
+* Advanced API to support structured logging
+* Highly efficient non-blocking logger API
+
+## Installation
+
+```shell
+gem install log_sinks
+```
+
+## License
+
+The MIT License. See the [LICENSE](/LICENSE) file for the full text.

data/lib/log_sinks/event_drain.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'singleton'
+
+module LogSinks
+  # EventDrain is a single receiver of messages from loggers. EventDrain forward events to registered sinks
+  class EventDrain
+    include Singleton
+
+    def initialize
+      @sinks = []
+    end
+
+    def add_sink(sink)
+      @sinks << sink
+    end
+
+    def drain(event)
+      @sinks.each { |s| s.receive(event) }
+    end
+
+    def clear_sinks
+      @sinks.clear
+    end
+  end
+end

data/lib/log_sinks/filter.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module LogSinks
+  # Filter is a proc-like object that filters events to be accepted by [LogSinks::Sink]
+  class Filter
+    # Applies filter to the event
+    # @param event [LogSinks::Event] event to filter
+    # @return [Boolean] true if [LogSinks::Sink] should accept the event; false otherwise
+    def call(_event)
+      true
+    end
+  end
+end

data/lib/log_sinks/filters/level_filter.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative '../level'
+require_relative '../filter'
+
+module LogSinks
+  module Filters
+    # Filter by event level. Pass if event level is greater or equal to filter level.
+    class LevelFilter < Filter
+      # Initializes new instance of [LogSinks::Filters::LevelFilter]
+      # @param limit_level [LogSinks::Level|Symbol] filter level
+      def initialize(limit_level)
+        super()
+        @limit_level = LogSinks::Level[limit_level]
+      end
+
+      # Applies filter to the event
+      # @argument event [LogSinks::Event] event to test
+      # @return [Boolean] true if event pass the filter; false otherwise
+      def call(event)
+        event.level >= @limit_level
+      end
+    end
+  end
+end

data/lib/log_sinks/filters/logger_name_prefix_filter.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative '../filter'
+
+module LogSinks
+  module Filters
+    # Filter event by logger name. Pass if logger name starts with logger prefix.
+    class LoggerNamePrefixFilter < LogSinks::Filter
+      def initialize(prefix, include_root: true)
+        super()
+        @prefix = prefix
+        @include_root = include_root
+      end
+
+      def call(event)
+        name = event.logger_name
+        (@include_root && name == :root) || name.start_with?(@prefix)
+      end
+    end
+  end
+end

data/lib/log_sinks/formatter.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module LogSinks
+  # Base class that serializes event to data format acceptable by sink (usually it's [String])
+  class Formatter
+    def initialize
+      @timestamp_format = '%Y-%m-%dT%H:%M:%S.%6N'
+    end
+
+    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"
+      # rubocop:enable Layout/LineLength
+    end
+  end
+end

data/lib/log_sinks/io_sink.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative 'formatter'
+require_relative 'sink'
+
+module LogSinks
+  # Sink that writes log events to IO stream, e.g., STDOUT or file stream
+  class IOSink < Sink
+    def initialize(io, pump_class: LogSinks::Pumps::InThreadPump)
+      super(pump_class: pump_class)
+      @io = io
+      @formatter = ::LogSinks::Formatter.new
+    end
+
+    attr_writer :formatter
+
+    def drain(event)
+      txt = @formatter.call(event)
+      @io.write(txt)
+    end
+  end
+end

data/lib/log_sinks/level.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module LogSinks
+  # Log event level.
+  class Level
+    class << self
+      def []=(name, level)
+        (@s ||= {})[name] = level
+      end
+
+      def [](name)
+        (@s ||= {})[name]
+      end
+    end
+
+    attr_reader :name, :val
+
+    def initialize(name, val)
+      @val = val
+      @name = name
+    end
+
+    def to_s
+      @name.to_s.upcase
+    end
+
+    def <(other)
+      @val < other.val
+    end
+
+    def <=(other)
+      @val <= other.val
+    end
+
+    def >(other)
+      @val > other.val
+    end
+
+    def >=(other)
+      @val >= other.val
+    end
+
+    def ==(other)
+      @val == other.val
+    end
+
+    # Define LogSinks levels
+    [[:debug, 1000], [:info, 2000], [:warn, 3000], [:error, 4000], [:fatal, 5000]].each do |(n, v)|
+      ::LogSinks::Level[n] = ::LogSinks::Level.new(n, v).freeze
+    end
+  end
+end

data/lib/log_sinks/log_event.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module LogSinks
+  # Represents a log event.
+  class LogEvent
+    def initialize(timestamp, level, logger_name, msg, meta: nil)
+      @data = meta || {}
+      @data[:timestamp] = timestamp
+      @data[:level] = level
+      @data[:logger_name] = logger_name
+      @data[:message] = msg
+    end
+
+    def timestamp
+      self[:timestamp]
+    end
+
+    def level
+      self[:level]
+    end
+
+    def logger_name
+      self[:logger_name]
+    end
+
+    def message
+      self[:message]
+    end
+
+    def [](key)
+      @data[key]
+    end
+  end
+end

data/lib/log_sinks/logger.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'time'
+
+require_relative 'event_drain'
+require_relative 'level'
+require_relative 'log_event'
+require_relative 'mdc'
+require_relative 'repository'
+
+module LogSinks
+  # Logger is a object that captures log event and forward that to event sinks.
+  class Logger
+    class << self
+      def [](name)
+        ::LogSinks::Repository.instance.get_or_add(name) do |logger_name|
+          Logger.new(logger_name)
+        end
+      end
+    end
+
+    attr_reader :name
+
+    def initialize(name)
+      validate_name(name)
+
+      @name = name
+      @level = ::LogSinks::Level[:info]
+    end
+
+    def level?(level)
+      @level.val <= level.val
+    end
+
+    def level=(level)
+      @level = case level
+               when String, Symbol then ::LogSinks::Level[level.to_sym]
+               when ::LogSinks::Level then level
+               end
+    end
+
+    %i[debug info warn error fatal].each do |level|
+      code = <<-CODE
+        undef :#{level} if method_defined? :#{level}
+        LEVEL_#{level} = ::LogSinks::Level[:#{level}]
+
+        def #{level}(msg = nil, meta: nil, error: nil, &block)
+          log_event(LEVEL_#{level}, msg, meta: meta, error: error, &block)
+        end
+      CODE
+      class_eval(code)
+    end
+
+    def log_event(level, msg = nil, meta: nil, error: nil)
+      return false unless level?(level)
+
+      msg = yield if msg.nil? && block_given?
+      meta ||= {}
+      meta[:error] = error unless error.nil?
+      meta.merge!(MDC.items)
+      event = ::LogSinks::LogEvent.new(Time.now, level, @name, msg, meta: meta)
+      dispatch_event event
+    end
+
+    private
+
+    def validate_name(name)
+      case name
+      when String
+        raise ArgumentError, 'logger name must not be empty' if name.empty?
+      else
+        raise ArgumentError, 'logger name must be a string'
+      end
+    end
+
+    def dispatch_event(event)
+      EventDrain.instance.drain(event)
+    end
+  end
+end

data/lib/log_sinks/mdc.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module LogSinks
+  # Mapped Diagnostic Context (MDC) is thread-aware Hash-like storage to add extra context details to logged events.
+  module MDC
+    SYNC_MUTEX = Mutex.new
+
+    class << self
+      def []=(key, value)
+        context[key] = value
+      end
+
+      def clear(key)
+        context.delete(key)
+        nil
+      end
+
+      def store(key, value)
+        MDC[key] = value
+      end
+
+      def items
+        context.dup.freeze
+      end
+
+      private
+
+      def context
+        if Thread.current[:log_sinks_mdc].nil?
+          SYNC_MUTEX.synchronize do
+            Thread.current[:log_sinks_mdc] = {} if Thread.current[:log_sinks_mdc].nil?
+          end
+        end
+        Thread.current[:log_sinks_mdc]
+      end
+    end
+  end
+end

data/lib/log_sinks/pumps/dedicated_thread_pump.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'concurrent'
+require 'immutable/deque'
+
+require_relative 'in_thread_pump'
+
+module LogSinks
+  module Pumps
+    # A pump that drains events to the sink in a dedicated thread
+    class DedicatedThreadPump < InThreadPump
+      def initialize(sink)
+        super
+
+        @drain_buffer = Concurrent::AtomicReference.new
+        @drain_buffer.set(Immutable::Deque.empty)
+        @has_events_flag = Concurrent::Event.new
+        @drain_thread = Thread.new { drain_thread_func }
+      end
+
+      def receive(event)
+        @drain_buffer.update { |buffer| buffer.push(event) }
+        @has_events_flag.set
+      end
+
+      protected
+
+      def drain_thread_func
+        @has_events_flag.reset
+
+        loop do
+          @has_events_flag.wait(0.1)
+          @has_events_flag.reset
+
+          drain_backlog(snapshot_backlog)
+        end
+      end
+
+      def snapshot_backlog
+        backlog = nil
+        loop do
+          backlog = @drain_buffer.get
+          break if @drain_buffer.compare_and_set(backlog, Immutable::Deque.empty)
+        end
+        backlog
+      end
+
+      def drain_backlog(backlog)
+        until backlog.empty?
+          e = backlog.first
+          backlog = backlog.shift
+          @sink.drain(e)
+        end
+      end
+    end
+  end
+end

data/lib/log_sinks/pumps/in_thread_pump.rb

@@ -0,0 +1,16 @@
+# frozen_string_litral: true
+
+module LogSinks
+  module Pumps
+    # A pump that drains events to the sink in the current thread
+    class InThreadPump
+      def initialize(sink)
+        @sink = sink
+      end
+
+      def receive(event)
+        @sink.drain event
+      end
+    end
+  end
+end

data/lib/log_sinks/repository.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'singleton'
+
+module LogSinks
+  # Repository stores references to loggers by logger name.
+  class Repository
+    include Singleton
+
+    # Initializes new instance of [LogSinks] class.
+    def initialize
+      @store = {}
+      @mutex = Mutex.new
+    end
+
+    # Tests if logger with given name exists
+    # @return [Boolean] true if logger exists; false otherwise.
+    def key?(name)
+      @store.key? canonize_name(name)
+    end
+
+    def get_or_add(name)
+      name = canonize_name(name)
+      logger = @store[name]
+
+      if logger.nil?
+        logger = @mutex.synchronize do
+          @store[name] = yield(name) unless @store.key?(name)
+          @store[name]
+        end
+      end
+      logger
+    end
+
+    private
+
+    def canonize_name(name)
+      case name
+      when :root, 'root' then 'root'
+      when String then name
+      when Symbol then name.to_s
+      when Module then module_name(name)
+      when Object then module_name(name.class)
+      end
+    end
+
+    def module_name(mod)
+      mod.name
+    end
+  end
+end

data/lib/log_sinks/ruby_logger_adapter.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+require_relative 'level'
+require_relative 'logger'
+
+module LogSinks
+  # Logger is a object that captures log event and forward that to event sinks.
+  class Logger
+    def as_ruby_logger(progname: nil)
+      RubyLoggerAdapter.new(self, progname)
+    end
+  end
+
+  # Adapter for [LogSinks::Logger] to match [::Logger] interface.
+  class RubyLoggerAdapter
+    [
+      [::Logger::DEBUG, ::LogSinks::Level[:debug]],
+      [::Logger::INFO, ::LogSinks::Level[:info]],
+      [::Logger::WARN, ::LogSinks::Level[:warn]],
+      [::Logger::ERROR, ::LogSinks::Level[:error]],
+      [::Logger::FATAL, ::LogSinks::Level[:fatal]],
+      [::Logger::UNKNOWN, ::LogSinks::Level[:fatal]]
+    ].each do |(n, v)|
+      ::LogSinks::Level[n] = v
+    end
+
+    %i[DEBUG INFO WARN ERROR FATAL UNKNOWN].each do |l|
+      code = <<-CODE
+        LEVEL_#{l} = ::LogSinks::Level[::Logger::Severity::#{l}]
+
+        def #{l.downcase}(progname = nil, &block)
+          log_event(LEVEL_#{l}, nil, progname, &block)
+        end
+      CODE
+      class_eval(code)
+    end
+
+    def initialize(logger, progname)
+      @progname = progname
+      @logger = logger
+      @meta = { progname: @progname }
+    end
+
+    def add(severity, message = nil, progname = nil, &block)
+      severity = ::LogSinks::Level[severity] unless severity.is_a? ::LogSinks::Level
+      log_event(severity, message, progname, &block)
+    end
+
+    private
+
+    def log_event(severity, message, progname, &block)
+      return true unless @logger.level?(severity)
+
+      progname = @progname if progname.nil?
+
+      if message.nil? && block.nil?
+        message = progname
+        progname = @progname
+      end
+
+      meta = progname == @progname ? @meta : { progname: progname }
+      @logger.log_event(severity, message, meta: meta, &block)
+      true
+    end
+  end
+end

data/lib/log_sinks/sink.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative 'filter'
+require_relative 'pumps/in_thread_pump'
+
+module LogSinks
+  # Sink receives log event and writes to a permanent storage.
+  class Sink
+    def initialize(pump_class: LogSinks::Pumps::InThreadPump)
+      @filters = []
+      @pump = pump_class.new(self)
+    end
+
+    def flush
+      @has_events_flag.set if @thread_model == :dedicated_thread
+    end
+
+    def receive(event)
+      return unless accept_event?(event)
+
+      @pump.receive event
+    end
+
+    def add_filter(filter)
+      @filters << filter
+    end
+
+    # Receives a message and write to a permanent storage
+    def drain(_event)
+      nil
+    end
+
+    protected
+
+    def accept_event?(event)
+      proceed = true
+      @filters.each do |f|
+        proceed &&= f.call(event)
+        break unless proceed
+      end
+      proceed
+    end
+  end
+end

data/lib/log_sinks/version.rb

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

data/lib/log_sinks.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative 'log_sinks/io_sink'
+require_relative 'log_sinks/logger'
+require_relative 'log_sinks/pumps/in_thread_pump'
+require_relative 'log_sinks/pumps/dedicated_thread_pump'
+require_relative 'log_sinks/version'
+require_relative 'log_sinks/filters/level_filter'
+require_relative 'log_sinks/filters/logger_name_prefix_filter'

metadata

@@ -0,0 +1,189 @@
+--- !ruby/object:Gem::Specification
+name: log_sinks
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andrey Maraev
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-10-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby-ext
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+- !ruby/object:Gem::Dependency
+  name: immutable-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: code-scanning-rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+- !ruby/object:Gem::Dependency
+  name: debug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.6.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.6.0
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 13.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 13.0.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.11.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.11.0
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.36.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.36.0
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.2
+description:
+email:
+- the_vk@thevk.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/log_sinks.rb
+- lib/log_sinks/event_drain.rb
+- lib/log_sinks/filter.rb
+- lib/log_sinks/filters/level_filter.rb
+- lib/log_sinks/filters/logger_name_prefix_filter.rb
+- lib/log_sinks/formatter.rb
+- lib/log_sinks/io_sink.rb
+- lib/log_sinks/level.rb
+- lib/log_sinks/log_event.rb
+- lib/log_sinks/logger.rb
+- lib/log_sinks/mdc.rb
+- lib/log_sinks/pumps/dedicated_thread_pump.rb
+- lib/log_sinks/pumps/in_thread_pump.rb
+- lib/log_sinks/repository.rb
+- lib/log_sinks/ruby_logger_adapter.rb
+- lib/log_sinks/sink.rb
+- lib/log_sinks/version.rb
+homepage: https://github.com/the-vk/log_sinks
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.3
+signing_key:
+specification_version: 4
+summary: Powerful and extensible logging library
+test_files: []