lumberjack 1.2.8 → 1.2.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7912cf1bfe32dcaa911a6a65a0b755fb3051eebc2a7e4a65ff5d422f2f61ad7
-  data.tar.gz: b4077d2ef97be7169ed0e7bca7d107ec3f42372dde45cae1e7cdcedae1fb4e61
+  metadata.gz: 9d05405664f1f85b1a68eb24c21a89d3b57ea8caf09513a348a138d53f1870b0
+  data.tar.gz: 1ccc42fdd657ab4acf89bab8bfd7fb5e7d69d3825367483c49ee10c5c6e037d1
 SHA512:
-  metadata.gz: a092775aec0c7670eda8ff4959a7cc928a57b0934ecc8a1190efe395b437bc0a681bdbd2f3455b98f3cf757904f5f39b31c96e24e9c8bcd7a481b806027e92c8
-  data.tar.gz: 885f76da2738f3f6236a363d9a7dea68f83a80a03e123a3c52c578984f963e959de6fd60d0fd222d9a9933c22ed959181538abb4118163c8fd6528292e88673c
+  metadata.gz: b48a0035d1adf22768071e6025692f001a8d13b931314ab0b6ea9131696bcb38d321db5fc1246bf2c49623cad26770bfdb32fe0e8e169ae455322e2693dad8e8
+  data.tar.gz: f80ae18348c1a3e5261aa27051d4cf3e087550e0d57d3a13459da6f7641e0ea270382478108127f03f6b7596faab27d8d3f92488fbbb2cb0c50c4d247ac61910

data/CHANGELOG.md

@@ -1,129 +1,182 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 1.2.9
+
+### Added
+- Allow passing in formatters as class names when adding them.
+- Allow passing in formatters initialization arguments when adding them.
+- Add truncate formatter for capping the length of log messages.
+
 ## 1.2.8
 
-* Add `Logger#untagged` to remove previously set logging tags from a block.
-* Return result of the block when a block is passed to `Logger#tag`.
+### Added
+- Add `Logger#untagged` to remove previously set logging tags from a block.
+- Return result of the block when a block is passed to `Logger#tag`.
 
 ## 1.2.7
 
-* Allow passing frozen hashes to `Logger#tag`. Tags passed to this method are now duplicated so the logger maintains it's own copy of the hash.
+### Fixed
+- Allow passing frozen hashes to `Logger#tag`. Tags passed to this method are now duplicated so the logger maintains it's own copy of the hash.
 
 ## 1.2.6
 
-* Fix `Logger#tag` so it only ads to the current block's logger tags instead of the global tags if called inside a `Logger#tag` block.
-* Add Logger#remove_tag
+### Added
+- Add Logger#remove_tag
+
+### Fixed
+- Fix `Logger#tag` so it only ads to the current block's logger tags instead of the global tags if called inside a `Logger#tag` block.
+
 
 ## 1.2.5
 
-* Fix logic with recursive reference guard in StructuredFormatter so it only suppresses Enumerable references.
-* Add support for bang methods (error!) for setting the log level.
+### Added
+- Add support for bang methods (error!) for setting the log level.
+
+### Fixed
+- Fixed logic with recursive reference guard in StructuredFormatter so it only suppresses Enumerable references.
 
 ## 1.2.4
 
-* Enhance `ActiveSupport::TaggedLogging` support so code that Lumberjack loggers can be wrapped with a tagged logger.
+### Added
+- Enhance `ActiveSupport::TaggedLogging` support so code that Lumberjack loggers can be wrapped with a tagged logger.
 
 ## 1.2.3
 
-* Fix structured formatter so no-recursive, duplicate references are allowed.
+### Fixed
+- Fix structured formatter so no-recursive, duplicate references are allowed.
 
 ## 1.2.2
 
-* Prevent infinite loops in the structured formatter where objects have backreferences to each other.
+### Fixed
+- Prevent infinite loops in the structured formatter where objects have backreferences to each other.
 
 ## 1.2.1
 
-* Prevent infinite loops where logging a statement triggers the logger.
+### Fixed
+- Prevent infinite loops where logging a statement triggers the logger.
 
 ## 1.2.0
 
-* Enable compatibility with `ActiveSupport::TaggedLogger` by calling `tagged_logger!` on a logger.
-* Add `tag_formatter` to logger to specify formatting of tags for output.
-* Allow adding and removing classes by name to formatters.
-* Allow adding and removing multiple classes in a single call to a formatter.
-* Allow using symbols and strings as log level for silencing a logger.
-* Ensure flusher thread gets stopped when logger is closed.
-* Add writer for logger device attribute.
-* Handle passing an array of devices to a multi device.
-* Helper method to get a tag with a specified name.
-* Add strip formatter to strip whitespace from strings.
-* Support non-alpha numeric characters in template variables.
-* Add backtrace cleaner to ExceptionFormatter.
+### Added
+- Enable compatibility with `ActiveSupport::TaggedLogger` by calling `tagged_logger!` on a logger.
+- Add `tag_formatter` to logger to specify formatting of tags for output.
+- Allow adding and removing classes by name to formatters.
+- Allow adding and removing multiple classes in a single call to a formatter.
+- Allow using symbols and strings as log level for silencing a logger.
+- Ensure flusher thread gets stopped when logger is closed.
+- Add writer for logger device attribute.
+- Handle passing an array of devices to a multi device.
+- Helper method to get a tag with a specified name.
+- Add strip formatter to strip whitespace from strings.
+- Support non-alpha numeric characters in template variables.
+- Add backtrace cleaner to ExceptionFormatter.
 
 ## 1.1.1
 
-* Replace Procs in tag values with the value of calling the Proc in log entries.
+### Added
+- Replace Procs in tag values with the value of calling the Proc in log entries.
 
 ## 1.1.0
 
-* Change `Lumberjack::Logger` to inherit from ::Logger
-* Add support for tags on log messages
-* Add global tag context for all loggers
-* Add per logger tags and tag contexts
-* Reimplement unit of work id as a tag on log entries
-* Add support for setting datetime format on log devices
-* Performance optimizations
-* Add Multi device to output to multiple devices
-* Add `DateTimeFormatter`, `IdFormatter`, `ObjectFormatter`, and `StructuredFormatter`
-* Add rack `Context` middleware for setting thread global context
-* End support for ruby versions < 2.3
-* Add support for modules in formatters
+### Added
+- Change `Lumberjack::Logger` to inherit from ::Logger
+- Add support for tags on log messages
+- Add global tag context for all loggers
+- Add per logger tags and tag contexts
+- Reimplement unit of work id as a tag on log entries
+- Add support for setting datetime format on log devices
+- Performance optimizations
+- Add Multi device to output to multiple devices
+- Add `DateTimeFormatter`, `IdFormatter`, `ObjectFormatter`, and `StructuredFormatter`
+- Add rack `Context` middleware for setting thread global context
+- Add support for modules in formatters
+
+### Removed
+- End support for ruby versions < 2.3
 
 ## 1.0.13
 
-* Reduce amount of code executed inside a mutex lock when writing to the logger stream.
-* Added `:min_roll_check` option to `Lumberjack::Device::RollingLogFile` to reduce file system checks. Default is now to only check if a file needs to be rolled at most once per second.
-* Force immutable strings for Ruby versions that support them.
+### Added
+- Added `:min_roll_check` option to `Lumberjack::Device::RollingLogFile` to reduce file system checks. Default is now to only check if a file needs to be rolled at most once per second.
+- Force immutable strings for Ruby versions that support them.
+
+### Changed
+- Reduce amount of code executed inside a mutex lock when writing to the logger stream.
 
 ## 1.0.12
 
-* Add support for `ActionDispatch` request id for better Rails compatibility.
+### Added
+- Add support for `ActionDispatch` request id for better Rails compatibility.
 
 ## 1.0.11
 
-* Fix Ruby 2.4 deprecation warning on Fixnum (thanks koic).
-* Fix gemspec files to be flat array (thanks e2).
+### Fixed
+- Fix Ruby 2.4 deprecation warning on Fixnum (thanks koic).
+- Fix gemspec files to be flat array (thanks e2).
 
 ## 1.0.10
 
-* Expose option to manually roll log files.
-* Minor code cleanup.
+### Added
+- Expose option to manually roll log files.
+
+### Changed
+- Minor code cleanup.
 
 ## 1.0.9
 
-* Add method so Formatter is compatible with `ActiveSupport` logging extensions.
+### Added
+- Add method so Formatter is compatible with `ActiveSupport` logging extensions.
 
 ## 1.0.8
 
-* Fix another internal variable name conflict with `ActiveSupport` logging extensions.
+### Fixed
+- Fix another internal variable name conflict with `ActiveSupport` logging extensions.
 
 ## 1.0.7
 
-* Fix broken formatter attribute method.
+### Fixed
+- Fix broken formatter attribute method.
 
 ## 1.0.6
 
-* Fix internal variable name conflict with `ActiveSupport` logging extensions.
+### Fixed
+- Fix internal variable name conflict with `ActiveSupport` logging extensions.
 
 ## 1.0.5
 
-* Update docs.
-* Remove autoload calls to make thread safe.
-* Make compatible with Ruby 2.1.1 Pathname.
-* Make compatible with standard library Logger's use of progname as default message.
+### Changed
+- Update docs.
+- Remove autoload calls to make thread safe.
+- Make compatible with Ruby 2.1.1 Pathname.
+- Make compatible with standard library Logger's use of progname as default message.
 
 ## 1.0.4
 
-* Add ability to supply a unit of work id for a block instead of having one generated every time.
+### Added
+- Add ability to supply a unit of work id for a block instead of having one generated every time.
 
 ## 1.0.3
 
-* Change log file output format to binary to avoid encoding warnings.
-* Fixed bug in log file rolling that left the file locked.
+### Fixed
+- Change log file output format to binary to avoid encoding warnings.
+- Fixed bug in log file rolling that left the file locked.
 
 ## 1.0.2
 
-* Remove deprecation warnings under ruby 1.9.3.
-* Add more error checking around file rolling.
+### Fixed
+- Remove deprecation warnings under ruby 1.9.3.
+- Add more error checking around file rolling.
 
 ## 1.0.1
 
-* Writes are no longer buffered by default.
+### Fixed
+- Writes are no longer buffered by default.
+
+## 1.0.0
+
+### Added
+- Initial release

data/README.md

@@ -8,7 +8,7 @@ Lumberjack is a simple, powerful, and fast logging implementation in Ruby. It us
 
 ## Usage
 
-This code aims to be extremely simple to use. The core interface it the Lumberjack::Logger which is used to log messages (which can be any object) with a specified Severity. Each logger has a level associated with it and messages are only written if their severity is greater than or equal to the level.
+This code aims to be extremely simple to use. The core interface is the Lumberjack::Logger which is used to log messages (which can be any object) with a specified Severity. Each logger has a level associated with it and messages are only written if their severity is greater than or equal to the level.
 
 ```ruby
   logger = Lumberjack::Logger.new("logs/application.log")  # Open a new log file with INFO level
@@ -41,7 +41,7 @@ The following information is recorded for each message:
 
 ### Tags
 
-You can use tags to provide additional meta data about a log message or the context that the log message is being made in. Using tags can keep you log messages clean. You can avoid string interoplation to add additional meta data.
+You can use tags to provide additional meta data about a log message or the context that the log message is being made in. Using tags can keep your log messages clean. You can avoid string interpolation to add additional meta data.
 
 Each of the logger methods includes an additional argument that can be used to specify tags on a messsage:
 

data/VERSION

@@ -1 +1 @@
-1.2.8
+1.2.9

data/lib/lumberjack/context.rb

@@ -5,12 +5,16 @@ module Lumberjack
   class Context
     attr_reader :tags
 
+    # @param [Context] parent_context A parent context to inherit tags from.
     def initialize(parent_context = nil)
       @tags = {}
       @tags.merge!(parent_context.tags) if parent_context
     end
 
     # Set tags on the context.
+    #
+    # @param [Hash] tags The tags to set.
+    # @return [void]
     def tag(tags)
       tags.each do |key, value|
         @tags[key.to_s] = value
@@ -18,16 +22,25 @@ module Lumberjack
     end
 
     # Get a context tag.
+    #
+    # @param [String, Symbol] key The tag key.
+    # @return [Object] The tag value.
     def [](key)
       @tags[key.to_s]
     end
 
     # Set a context tag.
+    #
+    # @param [String, Symbol] key The tag key.
+    # @param [Object] value The tag value.
+    # @return [void]
     def []=(key, value)
       @tags[key.to_s] = value
     end
 
     # Clear all the context data.
+    #
+    # @return [void]
     def reset
       @tags.clear
     end

data/lib/lumberjack/device/date_rolling_log_file.rb

@@ -13,6 +13,9 @@ module Lumberjack
       # Create a new logging device to the specified file. The period to roll the file is specified
       # with the :roll option which may contain a value of :daily, :weekly,
       # or :monthly.
+      #
+      # @param [String, Pathname] path The path to the log file.
+      # @param [Hash] options The options for the device.
       def initialize(path, options = {})
         @manual = options[:manual]
         @file_date = Date.today
@@ -25,6 +28,9 @@ module Lumberjack
         super
       end
 
+      # The date based suffix for file.
+      #
+      # @return [String]
       def archive_file_suffix
         case @roll_period
         when :weekly
@@ -36,6 +42,9 @@ module Lumberjack
         end
       end
 
+      # Check if the file should be rolled.
+      #
+      # @return [Boolean]
       def roll_file?
         if @manual
           true

data/lib/lumberjack/device/log_file.rb

@@ -12,12 +12,19 @@ module Lumberjack
       attr_reader :path
 
       # Create a logger to the file at +path+. Options are passed through to the Writer constructor.
+      #
+      # @param [String, Pathname] path The path to the log file.
+      # @param [Hash] options The options for the device.
       def initialize(path, options = {})
         @path = File.expand_path(path)
         FileUtils.mkdir_p(File.dirname(@path))
         super(file_stream, options)
       end
 
+      # Reopen the log file.
+      #
+      # @param [Object] logdev not used
+      # @return [void]
       def reopen(logdev = nil)
         close
         @stream = file_stream

data/lib/lumberjack/device/multi.rb

@@ -4,6 +4,7 @@ module Lumberjack
   class Device
     # This is a logging device that forward log entries to multiple other devices.
     class Multi < Device
+      # @param [Array<Lumberjack::Device>] devices The devices to write to.
       def initialize(*devices)
         @devices = devices.flatten
       end

data/lib/lumberjack/device/rolling_log_file.rb

@@ -20,10 +20,10 @@ module Lumberjack
         @keep = options[:keep]
         super(path, options)
         @file_inode = begin
-                        stream.lstat.ino
-                      rescue
-                        nil
-                      end
+          stream.lstat.ino
+        rescue
+          nil
+        end
         @@rolls = []
         @next_stat_check = Time.now.to_f
         @min_roll_check = (options[:min_roll_check] || 1.0).to_f
@@ -42,15 +42,15 @@ module Lumberjack
 
       # Roll the log file by renaming it to the archive file name and then re-opening a stream to the log
       # file path. Rolling a file is safe in multi-threaded or multi-process environments.
-      def roll_file! #:nodoc:
+      def roll_file! # :nodoc:
         do_once(stream) do
           archive_file = "#{path}.#{archive_file_suffix}"
           stream.flush
           current_inode = begin
-                            File.stat(path).ino
-                          rescue
-                            nil
-                          end
+            File.stat(path).ino
+          rescue
+            nil
+          end
           if @file_inode && current_inode == @file_inode && !File.exist?(archive_file) && File.exist?(path)
             begin
               File.rename(path, archive_file)
@@ -78,10 +78,10 @@ module Lumberjack
         if @min_roll_check <= 0.0 || Time.now.to_f >= @next_stat_check
           @next_stat_check += @min_roll_check
           path_inode = begin
-                         File.lstat(path).ino
-                       rescue
-                         nil
-                       end
+            File.lstat(path).ino
+          rescue
+            nil
+          end
           if path_inode != @file_inode
             @file_inode = path_inode
             reopen_file
@@ -98,10 +98,10 @@ module Lumberjack
         new_stream = File.open(path, "a", encoding: EXTERNAL_ENCODING)
         new_stream.sync = true if buffer_size > 0
         @file_inode = begin
-                        new_stream.lstat.ino
-                      rescue
-                        nil
-                      end
+          new_stream.lstat.ino
+        rescue
+          nil
+        end
         self.stream = new_stream
         old_stream.close
       end
@@ -127,10 +127,10 @@ module Lumberjack
       end
       begin
         verify = begin
-                   file.lstat
-                 rescue
-                   nil
-                 end
+          file.lstat
+        rescue
+          nil
+        end
         # Execute only if the file we locked is still the same one that needed to be rolled
         yield if verify && verify.ino == @file_inode && verify.size > 0
       ensure

data/lib/lumberjack/device/writer.rb

@@ -60,6 +60,9 @@ module Lumberjack
       # work id will only appear if it is present.
       #
       # The size of the internal buffer in bytes can be set by providing :buffer_size (defaults to 32K).
+      #
+      # @param [IO] stream The stream to write log entries to.
+      # @param [Hash] options The options for the device.
       def initialize(stream, options = {})
         @lock = Mutex.new
         @stream = stream
@@ -77,12 +80,18 @@ module Lumberjack
 
       # Set the buffer size in bytes. The device will only be physically written to when the buffer size
       # is exceeded.
+      #
+      # @param [Integer] value The size of the buffer in bytes.
+      # @return [void]
       def buffer_size=(value)
         @buffer_size = value
         flush
       end
 
       # Write an entry to the stream. The entry will be converted into a string using the defined template.
+      #
+      # @param [LogEntry, String] entry The entry to write to the stream.
+      # @return [void]
       def write(entry)
         string = (entry.is_a?(LogEntry) ? @template.call(entry) : entry)
         return if string.nil?
@@ -105,12 +114,16 @@ module Lumberjack
       end
 
       # Close the underlying stream.
+      #
+      # @return [void]
       def close
         flush
         stream.close
       end
 
       # Flush the underlying stream.
+      #
+      # @return [void]
       def flush
         lines = nil
         @lock.synchronize do
@@ -120,10 +133,17 @@ module Lumberjack
         write_to_stream(lines) if lines
       end
 
+      # Get the datetime format.
+      #
+      # @return [String] The datetime format.
       def datetime_format
         @template.datetime_format if @template.respond_to?(:datetime_format)
       end
 
+      # Set the datetime format.
+      #
+      # @param [String] format The datetime format.
+      # @return [void]
       def datetime_format=(format)
         if @template.respond_to?(:datetime_format=)
           @template.datetime_format = format

data/lib/lumberjack/device.rb

@@ -13,29 +13,44 @@ module Lumberjack
     require_relative "device/null"
 
     # Subclasses must implement this method to write a LogEntry.
+    #
+    # @param [Lumberjack::LogEntry] entry The entry to write.
+    # @return [void]
     def write(entry)
       raise NotImplementedError
     end
 
     # Subclasses may implement this method to close the device.
+    #
+    # @return [void]
     def close
       flush
     end
 
     # Subclasses may implement this method to reopen the device.
+    #
+    # @param [Object] logdev The log device to use.
+    # @return [void]
     def reopen(logdev = nil)
       flush
     end
 
     # Subclasses may implement this method to flush any buffers used by the device.
+    #
+    # @return [void]
     def flush
     end
 
     # Subclasses may implement this method to get the format for log timestamps.
+    #
+    # @return [String] The format for log timestamps.
     def datetime_format
     end
 
     # Subclasses may implement this method to set a format for log timestamps.
+    #
+    # @param [String] format The format for log timestamps.
+    # @return [void]
     def datetime_format=(format)
     end
   end

data/lib/lumberjack/formatter/date_time_formatter.rb

@@ -7,6 +7,7 @@ module Lumberjack
     class DateTimeFormatter
       attr_reader :format
 
+      # @param [String] format The format to use when formatting the date/time object.
       def initialize(format = nil)
         @format = format.dup.to_s.freeze unless format.nil?
       end

data/lib/lumberjack/formatter/exception_formatter.rb

@@ -9,6 +9,8 @@ module Lumberjack
     class ExceptionFormatter
       attr_accessor :backtrace_cleaner
 
+      # @param [#call] backtrace_cleaner An object that responds to `call` and takes
+      #   an array of strings (the backtrace) and returns an array of strings (the
       def initialize(backtrace_cleaner = nil)
         self.backtrace_cleaner = backtrace_cleaner
       end

data/lib/lumberjack/formatter/id_formatter.rb

@@ -6,6 +6,7 @@ module Lumberjack
     # as a default formatter for objects pulled from a data store. By default it will use :id as the
     # id attribute.
     class IdFormatter
+      # @param [Symbol, String] id_attribute The attribute to use as the id.
       def initialize(id_attribute = :id)
         @id_attribute = id_attribute
       end

data/lib/lumberjack/formatter/pretty_print_formatter.rb

@@ -11,6 +11,8 @@ module Lumberjack
 
       # Create a new formatter. The maximum width of the message can be specified with the width
       # parameter (defaults to 79 characters).
+      #
+      # @param [Integer] width The maximum width of the message.
       def initialize(width = 79)
         @width = width
       end

data/lib/lumberjack/formatter/structured_formatter.rb

@@ -9,6 +9,8 @@ module Lumberjack
       class RecusiveReferenceError < StandardError
       end
 
+      # @param [Formatter] formatter The formatter to call on each element
+      #   in the structure.
       def initialize(formatter = nil)
         @formatter = formatter
       end

data/lib/lumberjack/formatter/truncate_formatter.rb

@@ -0,0 +1,27 @@
+# frozen_string_literals: true
+
+module Lumberjack
+  class Formatter
+    # Truncate a string object to a specific length. This is useful
+    # for formatting messages when there is a limit on the number of
+    # characters that can be logged per message. This formatter should
+    # only be used when necessary since it is a lossy formatter.
+    #
+    # When a string is truncated, it will have a unicode ellipsis
+    # character (U+2026) appended to the end of the string.
+    class TruncateFormatter
+      # @param [Integer] length The maximum length of the string (defaults to 32K)
+      def initialize(length = 32768)
+        @length = length
+      end
+
+      def call(obj)
+        if obj.is_a?(String) && obj.length > @length
+          "#{obj[0, @length - 1]}…"
+        else
+          obj
+        end
+      end
+    end
+  end
+end