lumberjack 1.2.9 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d05405664f1f85b1a68eb24c21a89d3b57ea8caf09513a348a138d53f1870b0
-  data.tar.gz: 1ccc42fdd657ab4acf89bab8bfd7fb5e7d69d3825367483c49ee10c5c6e037d1
+  metadata.gz: a69bd8640229dc5e150255f601f1280dfe4fb325cee8879aa202114cd335512f
+  data.tar.gz: b2cd71293d94653f03ed04df094d69587d76e2b544d8a46149d139d7e952c0fc
 SHA512:
-  metadata.gz: b48a0035d1adf22768071e6025692f001a8d13b931314ab0b6ea9131696bcb38d321db5fc1246bf2c49623cad26770bfdb32fe0e8e169ae455322e2693dad8e8
-  data.tar.gz: f80ae18348c1a3e5261aa27051d4cf3e087550e0d57d3a13459da6f7641e0ea270382478108127f03f6b7596faab27d8d3f92488fbbb2cb0c50c4d247ac61910
+  metadata.gz: 484530ed54b537da178e956fc654ddcfc81fa74cfed495ba94ca04e1e350d1e29089198da6d77bb700cc227a5ee49949ac8d40c09c152e7e2ffc3ab7a7f6e7a5
+  data.tar.gz: f0025936e20a24d8da09d2dd9cd863aaface259ce2b1b21eff590f7bbb22daa7fcd5a67f192c0abe428131ab145ab0cd271143ab01b7f6b665db69ebcb63becf

data/ARCHITECTURE.md

@@ -0,0 +1,244 @@
+# Lumberjack Gem Architecture
+
+Lumberjack is a simple, powerful, and fast logging implementation in Ruby. It uses nearly the same API as the Logger class in the Ruby standard library and as ActiveSupport::BufferedLogger in Rails. The gem is designed with structured logging in mind, but can be used for simple text logging as well.
+
+## Overview
+
+The Lumberjack architecture follows a clean separation of concerns with the following main components:
+
+- **Logger**: The main interface for creating log entries
+- **LogEntry**: Data structure that captures log messages and metadata
+- **Device**: Abstraction for different output destinations
+- **Formatter**: Handles message formatting and transformation
+- **TagFormatter**: Specialized formatting for tags
+- **Template**: Template engine for customizing log output format
+- **Context**: Thread-local context for managing tags across log entries
+- **Severity**: Log level management and filtering
+
+## Core Architecture
+
+```mermaid
+classDiagram
+    class Logger {
+        +Device device
+        +Formatter formatter
+        +TagFormatter tag_formatter
+        +Integer level
+        +String progname
+        +Hash tags
+        +initialize(device, options)
+        +debug(message, progname, tags)
+        +info(message, progname, tags)
+        +warn(message, progname, tags)
+        +error(message, progname, tags)
+        +fatal(message, progname, tags)
+        +add_entry(severity, message, progname, tags)
+        +tag(tags_hash)
+        +flush()
+        +close()
+    }
+
+    class LogEntry {
+        +Time time
+        +Integer severity
+        +Object message
+        +String progname
+        +Integer pid
+        +Hash tags
+        +initialize(time, severity, message, progname, pid, tags)
+        +severity_label()
+        +tag(name)
+        +to_s()
+    }
+
+    class Device {
+        <<abstract>>
+        +write(entry)*
+        +flush()
+        +close()
+        +reopen()
+        +datetime_format()
+        +datetime_format=(format)
+    }
+
+    class Formatter {
+        +Hash class_formatters
+        +Hash module_formatters
+        +add(classes, formatter)
+        +remove(classes)
+        +format(message)
+        +clear()
+    }
+
+    class TagFormatter {
+        +Hash formatters
+        +Object default_formatter
+        +default(formatter)
+        +add(names, formatter)
+        +remove(names)
+        +format(tags)
+        +clear()
+    }
+
+    class Template {
+        +String first_line_template
+        +String additional_line_template
+        +String datetime_format
+        +compile(template)
+        +call(entry)
+        +datetime_format=(format)
+    }
+
+    class Context {
+        +Hash tags
+        +initialize(parent_context)
+        +tag(tags)
+        +\[](key)
+        +\[]=(key, value)
+        +reset()
+    }
+
+    class Severity {
+        <<module>>
+        +level_to_label(severity)
+        +label_to_level(label)
+        +coerce(value)
+    }
+
+    Logger --> LogEntry : creates
+    Logger --> Device : writes to
+    Logger --> Formatter : uses
+    Logger --> TagFormatter : uses
+    Logger --> Severity : includes
+    Device --> Template : may use
+    Formatter --> LogEntry : formats message
+    TagFormatter --> LogEntry : formats tags
+    Logger <-- Context : provides tags
+```
+
+## Device Hierarchy
+
+The Device system provides a pluggable architecture for different output destinations:
+
+```mermaid
+classDiagram
+    class Device {
+        <<abstract>>
+        +write(entry)*
+        +flush()
+        +close()
+        +reopen()
+    }
+
+    class Writer {
+        +IO stream
+        +Template template
+        +Buffer buffer
+        +Integer buffer_size
+        +write(entry)
+        +flush()
+        +before_flush()
+    }
+
+    class LogFile {
+        +String file_path
+        +write(entry)
+        +reopen(file_path)
+        +close()
+    }
+
+    class RollingLogFile {
+        <<abstract>>
+        +roll_file?()
+        +roll_file!()
+        +archive_file_suffix()
+    }
+
+    class DateRollingLogFile {
+        +String roll
+        +roll_file?()
+        +archive_file_suffix()
+    }
+
+    class SizeRollingLogFile {
+        +Integer max_size
+        +Integer keep
+        +roll_file?()
+        +archive_file_suffix()
+    }
+
+    class Multi {
+        +Array~Device~ devices
+        +write(entry)
+        +flush()
+        +close()
+    }
+
+    class Null {
+        +write(entry)
+    }
+
+    Device <|-- Writer
+    Device <|-- Multi
+    Device <|-- Null
+    Writer <|-- LogFile
+    LogFile <|-- RollingLogFile
+    RollingLogFile <|-- DateRollingLogFile
+    RollingLogFile <|-- SizeRollingLogFile
+    Multi --> Device : contains multiple
+```
+
+## Data Flow
+
+The logging process follows this flow:
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Logger
+    participant Formatter
+    participant TagFormatter
+    participant LogEntry
+    participant Device
+    participant Template
+
+    Client->>Logger: info("message", tags: {key: value})
+    Logger->>Logger: Check severity level
+    Logger->>Formatter: format(message)
+    Formatter-->>Logger: formatted_message
+    Logger->>TagFormatter: format(tags)
+    TagFormatter-->>Logger: formatted_tags
+    Logger->>LogEntry: new(time, severity, message, progname, pid, tags)
+    LogEntry-->>Logger: log_entry
+    Logger->>Device: write(log_entry)
+    Device->>Template: call(log_entry) [if Writer device]
+    Template-->>Device: formatted_string
+    Device->>Device: Write to output destination
+```
+
+## Key Features
+
+### Thread Safety
+- Logger operations are thread-safe
+- Context provides thread-local tag storage
+- Devices handle concurrent writes appropriately
+
+### Structured Logging
+- LogEntry captures structured data beyond just the message
+- Tags provide key-value metadata
+- Formatters can handle complex object serialization
+
+### Pluggable Architecture
+- Device abstraction allows custom output destinations
+- Formatter system enables custom message transformation
+- TagFormatter provides specialized tag handling
+
+### Performance Optimization
+- Buffered writing in Writer devices
+- Lazy evaluation of expensive operations
+- Configurable flush intervals
+
+### ActiveSupport Compatibility
+- TaggedLoggerSupport module provides Rails compatibility
+- Compatible API with standard library Logger
+- Supports ActiveSupport::TaggedLogging interface

data/CHANGELOG.md

@@ -4,9 +4,55 @@ 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.3.0
+
+### Added
+
+- Added `Lumberjack::Formatter::TaggedMessage` to allow extracting tags from log messages via a formatter in order to better support structured logging of objects.
+- Added built in `:round` formatter to round numbers to a specified number of decimal places.
+- Added built in `:redact` formatter to redact sensitive information from log tags.
+- Added support in `Lumberjack::TagFormatter` for class formatters. Class formatters will be applied to any tag values that match the class.
+- Apply formatters to enumerable values in tags. Name formatters are applied using dot syntax when a tag value contains a hash.
+- Added support for a dedicated message formatter that can override the default formatter on the log message.
+- Added support for setting tags from the request environment in `Lumberjack::Rack::Context` middleware.
+- Added helper methods to generate global PID's and thread ids.
+- Added `Lumberjack::Logger#tag_globally` to explicitly set a global tag for all loggers.
+- Added `Lumberjack::Logger#tag_value` to get the value of a tag by name from the current tag context.
+- Added `Lumberjack::Utils.hostname` to get the hostname in UTF-8 encoding.
+- Added `Lumberjack::Utils.global_pid` to get a global process id in a consistent format.
+- Added `Lumberjack::Utils.global_thread_id` to get a thread id in a consistent format.
+- Added `Lumberjack::Utils.thread_name` to get a thread name in a consistent format.
+- Added support for `ActiveSupport::Logging.logger_outputs_to?` to check if a logger is outputting to a specific IO stream.
+- Added `Lumberjack::Logger#log_at` method to temporarily set the log level for a block of code for compatibility with ActiveSupport loggers.
+
+### Changed
+
+- Default date/time format for log entries is now ISO-8601 with microsecond precision.
+- Tags that are set to hash values will now be flattened into dot-separated keys in templates.
+
+### Removed
+
+- Removed support for Ruby versions < 2.5.
+
+### Deprecated
+
+- All unit of work related functionality from version 1.0 has been officially deprecated and will be removed in version 2.0. Use tags instead to set a global context for log entries.
+- Calling `Lumberjack::Logger#tag` without a block is deprecated. Use `Lumberjack::Logger#tag_globally` instead.
+
+## 1.2.10
+
+### Added
+
+- Added `with_level` method for compatibility with the latest standard library logger gem.
+
+### Fixed
+
+- Fixed typo in magic frozen string literal comments. (thanks @andyw8 and @steveclarke)
+
 ## 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.
@@ -14,54 +60,65 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## 1.2.8
 
 ### 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
 
 ### 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
 
 ### 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
 
 ### 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
 
 ### Added
+
 - Enhance `ActiveSupport::TaggedLogging` support so code that Lumberjack loggers can be wrapped with a tagged logger.
 
 ## 1.2.3
 
 ### Fixed
+
 - Fix structured formatter so no-recursive, duplicate references are allowed.
 
 ## 1.2.2
 
 ### Fixed
+
 - Prevent infinite loops in the structured formatter where objects have backreferences to each other.
 
 ## 1.2.1
 
 ### Fixed
+
 - Prevent infinite loops where logging a statement triggers the logger.
 
 ## 1.2.0
 
 ### 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.
@@ -78,11 +135,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## 1.1.1
 
 ### Added
+
 - Replace Procs in tag values with the value of calling the Proc in log entries.
 
 ## 1.1.0
 
 ### Added
+
 - Change `Lumberjack::Logger` to inherit from ::Logger
 - Add support for tags on log messages
 - Add global tag context for all loggers
@@ -96,59 +155,71 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add support for modules in formatters
 
 ### Removed
+
 - End support for ruby versions < 2.3
 
 ## 1.0.13
 
 ### 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
 
 ### Added
+
 - Add support for `ActionDispatch` request id for better Rails compatibility.
 
 ## 1.0.11
 
 ### Fixed
-- Fix Ruby 2.4 deprecation warning on Fixnum (thanks koic).
-- Fix gemspec files to be flat array (thanks e2).
+
+- Fix Ruby 2.4 deprecation warning on Fixnum (thanks @koic).
+- Fix gemspec files to be flat array (thanks @e2).
 
 ## 1.0.10
 
 ### Added
+
 - Expose option to manually roll log files.
 
 ### Changed
+
 - Minor code cleanup.
 
 ## 1.0.9
 
 ### Added
+
 - Add method so Formatter is compatible with `ActiveSupport` logging extensions.
 
 ## 1.0.8
 
 ### Fixed
+
 - Fix another internal variable name conflict with `ActiveSupport` logging extensions.
 
 ## 1.0.7
 
 ### Fixed
+
 - Fix broken formatter attribute method.
 
 ## 1.0.6
 
 ### Fixed
+
 - Fix internal variable name conflict with `ActiveSupport` logging extensions.
 
 ## 1.0.5
 
 ### Changed
+
 - Update docs.
 - Remove autoload calls to make thread safe.
 - Make compatible with Ruby 2.1.1 Pathname.
@@ -157,26 +228,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## 1.0.4
 
 ### Added
+
 - Add ability to supply a unit of work id for a block instead of having one generated every time.
 
 ## 1.0.3
 
 ### 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
 
 ### Fixed
+
 - Remove deprecation warnings under ruby 1.9.3.
 - Add more error checking around file rolling.
 
 ## 1.0.1
 
 ### Fixed
+
 - Writes are no longer buffered by default.
 
 ## 1.0.0
 
 ### Added
+
 - Initial release