lumberjack 1.2.10 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5ab13ef762e8cdcb989ce1937c117fdbf938edc723c48f338b74edcd5d8e776
-  data.tar.gz: a003d08ef71531551083e4794807d3469fd9691abdc0686e5cc36e6859199922
+  metadata.gz: c72bca9355bd37fb691a06a4cea4a341b6905b7b5c15429d41061b2b0afd3813
+  data.tar.gz: 49a18195fadf1de9b2cf43e3ce95c1f5e49d3d81dd4384a722e8f685187f6bbc
 SHA512:
-  metadata.gz: b0b527513bd37ca507bfe63c83cd00831f544a9ecdcedc13aeb566a3e74ae4ff0469eefed220da79c7cbeb385aa0fcff249b2480d74c95a1ff21899a8e723afb
-  data.tar.gz: 109411706ed4976f9711d6fcc17dd93bd7700cf72e01f40eaadba5701284e4175aa3791a311a19ab78eaedc34270ff9b16cd4ca394bb01a90b6c29d8e295f8e0
+  metadata.gz: 5d58e6244cad6396bf702759c05a130e279d4def0d7bee491817b373fbee79420fa0df776264485e7387657a7dd28bab7e4690b7b0a677d878b98f611432a7f7
+  data.tar.gz: d2c2c8f1765230b39df298c68c89bad1db520acbaabfee7da7381d75336de91ff9c3f709e501683fb2502f6b5f7b61eef89c8814f13fda6c2235c3ac43ef5959

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,6 +4,90 @@ 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.4.0
+
+### Changed
+
+- Tags are consistently flattened internally to dot notation keys. This makes tag handling more consistent when using nested hashes as tag values. This changes how nested tags are merged, though. Now when new nested tags are set they will be merged into the existing tags rather than replacing them entirely. So `logger.tag(foo: {bar: "baz"})` will now merge the `foo.bar` tag into the existing tags rather than replacing the entire `foo` tag.
+- The `Lumberjack::Logger#context` method can now be called without a block. When called with a block it sets up a new tag context for the block. When called without a block, it returns the current tag context in a `Lumberjack::TagContext` object which can be used to add tags to the current context.
+- Tags in `Lumberjack::LogEntry` are now always stored as a hash of flattened keys. This means that when tags are set on a log entry, they will be automatically flattened to dot notation keys. The `tag` method will return a hash of sub-tags if the tag name is a tag prefix.
+
+### Added
+
+- Added `Lumberjack::LogEntry#nested_tags` method to return the tags as a nested hash structure.
+
+## 1.3.4
+
+### Added
+
+- Added `Lumberjack::Logger#with_progname` alias for `set_progname` to match the naming convention used for setting temporary levels.
+
+### Fixed
+
+- Ensure that the safety check for circular calls to `Lumberjack::Logger#add_entry` cannot lose state.
+
+## 1.3.3
+
+### Added
+
+- Added `Lumberjack::Utils#expand_tags` method to expand a hash of tags that may contain nested hashes or dot notation keys.
+
+### Changed
+
+- Updated `Lumberjack::Utils#flatten_tags` to convert all keys to strings.
+
+## 1.3.2
+
+### Fixed
+
+- Fixed `NoMethodError` when setting the device via the `Lumberjack::Logger#device=` method.
+
+## 1.3.1
+
+### Added
+
+- Added `Lumberjack::Logger#context` method to set up a context block for the logger. This is the same as calling `Lumberjack::Logger#tag` with an empty hash.
+- Log entries now remove empty tag values so they don't have to be removed downstream.
+
+### Fixed
+
+- ActiveSupport::TaggedLogger now calls `Lumberjack::Logger#tag_globally` to prevent deprecation warnings.
+
+## 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