intake 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: febaaa600f3b7a5c8ed974a8e059a4d5ea12e61b0e5edf6fb0bf3c707f56027b
-  data.tar.gz: 9bc82ce4ad485486a397e63c84c7a54445df78b2e3f285b1d0ec26d1cfddfdc8
+  metadata.gz: b845805181f81717bfc41734b8f35905d0adff760ba182e95c9ece95285d7a4e
+  data.tar.gz: 19e290811468e20994441c4ea2f2747b81cfbc36d257ae1d9eadd1a18713c705
 SHA512:
-  metadata.gz: bf360302e2ece8d18034a1b34587d3fa6c8a267f8d13ec64535b7de212e7307235b58b76a28c5f429fed832ee1ef4a1aa05c57391ba5cd74f98d207aa2c71033
-  data.tar.gz: d140b351c1171e9a5bce2e5e4d01926900300f60a8e18ce0c0c591cadcf54ac6ced6fa22b584cf3d8ad4dff754dfc31399613ba39a1b2a8a750869026c430ab1
+  metadata.gz: df4713a410191c85e398f66bea3aea0c97bcfaf5274472689c2889cf7a185cd9c36bee2ee6a9196d7fc27e7c2d5efeafb61045972302eaf4f5f199c62878594e
+  data.tar.gz: bc7a9a6e520c8de2d2c043ba999327e1f604bd8310f425ad5ce096c020b9b51d85ca6e8d3f69b4a96bb32002cda26a1cf7f3f2597b5217584ee619ec3c3eb1a8

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/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: intake
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Andrey Maraev
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-10-09 00:00:00.000000000 Z
+date: 2022-10-19 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