lumberjack 1.2.10 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5ab13ef762e8cdcb989ce1937c117fdbf938edc723c48f338b74edcd5d8e776
-  data.tar.gz: a003d08ef71531551083e4794807d3469fd9691abdc0686e5cc36e6859199922
+  metadata.gz: 07e6e20fe9cf765f75723c6a3d3101f1c2387633d109a6cd4c85cb67a3a2d0ce
+  data.tar.gz: e9321f97338038f863eff17801cf3b2620f88f1685631a0a894fb219578b0b8c
 SHA512:
-  metadata.gz: b0b527513bd37ca507bfe63c83cd00831f544a9ecdcedc13aeb566a3e74ae4ff0469eefed220da79c7cbeb385aa0fcff249b2480d74c95a1ff21899a8e723afb
-  data.tar.gz: 109411706ed4976f9711d6fcc17dd93bd7700cf72e01f40eaadba5701284e4175aa3791a311a19ab78eaedc34270ff9b16cd4ca394bb01a90b6c29d8e295f8e0
+  metadata.gz: 18cf33bd3e45a2d6fa703586447c66cf7848580a4c793da67f50a1fd2bbdb0724bb4e393165e4fdcade80a71f72e7ff6751f52e883d6993d02880e53bc64ea8a
+  data.tar.gz: 4c87222be54db1f498b1d6369821df16906a0ea7d3503de4528a16af05de3ec87dde1c45dd759b233dbec451536571a5030f0f2d23b28aa3fd31214e32cda6da

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,52 @@ 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.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

data/README.md

@@ -1,15 +1,14 @@
 # Lumberjack
 
 [![Continuous Integration](https://github.com/bdurand/lumberjack/actions/workflows/continuous_integration.yml/badge.svg)](https://github.com/bdurand/lumberjack/actions/workflows/continuous_integration.yml)
-[![Regression Test](https://github.com/bdurand/lumberjack/actions/workflows/regression_test.yml/badge.svg)](https://github.com/bdurand/lumberjack/actions/workflows/regression_test.yml)
 [![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
 [![Gem Version](https://badge.fury.io/rb/lumberjack.svg)](https://badge.fury.io/rb/lumberjack)
 
-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.
+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. It is designed with structured logging in mind, but can be used for simple text logging as well.
 
 ## Usage
 
-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.
+This code aims to be extremely simple to use and matches the standard Ruby `Logger` interface. 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
@@ -24,27 +23,25 @@ This code aims to be extremely simple to use. The core interface is the Lumberja
   logger.info("End request")
 ```
 
-This is all you need to know to log messages.
-
 ## Features
 
-### Meta data
+### Metadata
 
 When messages are added to the log, additional data about the message is kept in a Lumberjack::LogEntry. This means you don't need to worry about adding the time or process id to your log messages as they will be automatically recorded.
 
 The following information is recorded for each message:
 
-* severity - The severity recorded for the message.
-* time - The time at which the message was recorded.
-* program name - The name of the program logging the message. This can be either set for all messages or customized with each message.
-* process id - The process id (pid) of the process that logged the message.
-* tags - An map of name value pairs for addition information about the log context.
+- severity - The severity recorded for the message.
+- time - The time at which the message was recorded.
+- program name - The name of the program logging the message. This can be either set for all messages or customized with each message.
+- process id - The process id (pid) of the process that logged the message.
+- tags - A map of name value pairs for additional information about the log context.
 
 ### 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 your log messages clean. You can avoid string interpolation 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. Tags enable a structured logging approach where you can add additional information to log messages without changing the message format.
 
-Each of the logger methods includes an additional argument that can be used to specify tags on a messsage:
+Each of the logger methods includes an additional argument that can be used to specify tags on a message:
 
 ```ruby
 logger.info("request completed", duration: elapsed_time, status: response.status)
@@ -89,9 +86,55 @@ logger.info("no requests") # Will not include the `request_id` tag
 
 Tag keys are always converted to strings. Tags are inherited so that message tags take precedence over block tags which take precedence over global tags.
 
+#### Structured Logging with Tags
+
+Tags are particularly powerful for structured logging, where you want to capture machine-readable data alongside human-readable log messages. Instead of embedding variable data directly in log messages (which makes parsing difficult), you can use tags to separate the static message from the dynamic data.
+
+```ruby
+# Instead of this (harder to parse)
+logger.info("User john_doe logged in from IP 192.168.1.100 in 0.25 seconds")
+
+# Do this (structured and parseable)
+logger.info("User logged in", {
+  user_id: "john_doe",
+  ip_address: "192.168.1.100",
+  duration: 0.25,
+  action: "login"
+})
+```
+
+This approach provides several benefits:
+
+- **Consistent message format** - The base message stays the same while data varies
+- **Easy filtering and searching** - You can search by specific tag values
+- **Better analytics** - Aggregate data by tag values (e.g., average login duration)
+- **Machine processing** - Automated systems can easily extract and process tag data
+
+You can also use nested structures in tags for complex data:
+
+```ruby
+logger.info("API request completed", {
+  request: {
+    method: "POST",
+    path: "/api/users",
+    user_agent: request.user_agent
+  },
+  response: {
+    status: 201,
+    duration_ms: 150
+  },
+  user: {
+    id: current_user.id,
+    role: current_user.role
+  }
+})
+```
+
+When combined with structured output devices (like [`lumberjack_json_device`](https://github.com/bdurand/lumberjack_json_device)), this creates logs that are both human-readable and machine-processable, making them ideal for log aggregation systems, monitoring, and analytics.
+
 #### Compatibility with ActiveSupport::TaggedLogging
 
-`Lumberjack::Logger` version 1.1.2 or greater is compatible with `ActiveSupport::TaggedLogging`. This is so that other code that expect to have a logger that responds to the `tagged` method will work. Any tags added with the `tagged` method will be appended to an array in the the "tagged" tag.
+`Lumberjack::Logger` version 1.1.2 or greater is compatible with `ActiveSupport::TaggedLogging`. This is so that other code that expects to have a logger that responds to the `tagged` method will work. Any tags added with the `tagged` method will be appended to an array in the "tagged" tag.
 
 ```ruby
 logger.tagged("foo", "bar=1", "other") do
@@ -103,38 +146,37 @@ end
 
 The built in `Lumberjack::Device::Writer` class has built in support for including tags in the output using the `Lumberjack::Template` class.
 
-You can specify any tag name you want in a template as well as the `:tags` macro for all tags. If a tag name has been used as it's own macro, it will not be included in the `:tags` macro.
-
-#### Unit Of Work
-
-Lumberjack 1.0 had a concept of a unit of work id that could be used to tie log messages together. This has been replaced by tags. There is still an implementation of `Lumberjack.unit_of_work`, but it is just a wrapper on the tag implementation.
+You can specify any tag name you want in a template as well as the `:tags` macro for all tags. If a tag name has been used as its own macro, it will not be included in the `:tags` macro.
 
 ### Pluggable Devices
 
 When a Logger logs a LogEntry, it sends it to a Lumberjack::Device. Lumberjack comes with a variety of devices for logging to IO streams or files.
 
-* Lumberjack::Device::Writer - Writes log entries to an IO stream.
-* Lumberjack::Device::LogFile - Writes log entries to a file.
-* Lumberjack::Device::DateRollingLogFile - Writes log entries to a file that will automatically roll itself based on date.
-* Lumberjack::Device::SizeRollingLogFile - Writes log entries to a file that will automatically roll itself based on size.
-* Lumberjack::Device::Multi - This device wraps mulitiple other devices and will write log entries to each of them.
-* Lumberjack::Device::Null - This device produces no output and is intended for testing environments.
+- Lumberjack::Device::Writer - Writes log entries to an IO stream.
+- Lumberjack::Device::LogFile - Writes log entries to a file.
+- Lumberjack::Device::DateRollingLogFile - Writes log entries to a file that will automatically roll itself based on date.
+- Lumberjack::Device::SizeRollingLogFile - Writes log entries to a file that will automatically roll itself based on size.
+- Lumberjack::Device::Multi - This device wraps multiple other devices and will write log entries to each of them.
+- Lumberjack::Device::Null - This device produces no output and is intended for testing environments.
 
-If you'd like to send you log to a different kind of output, you just need to extend the Device class and implement the +write+ method. Or check out these plugins:
+If you'd like to send your log to a different kind of output, you just need to extend the Device class and implement the `write` method. Or check out these plugins:
 
-* [lumberjack_syslog_device](https://github.com/bdurand/lumberjack_syslog_device) - send your log messages to the system wide syslog service
-* [lumberjack_mongo_device](https://github.com/bdurand/lumberjack_mongo_device) - store your log messages to a [MongoDB](http://www.mongodb.org/) NoSQL data store
-* [lumberjack-couchdb-driver](https://github.com/narkisr/lumberjack-couchdb-driver) - store your log messages to a [CouchDB](http://couchdb.apache.org/) NoSQL data store
-* [lumberjack_heroku_device](https://github.com/tonycoco/lumberjack_heroku_device) - log to Heroku's logging system
+- [lumberjack_json_device](https://github.com/bdurand/lumberjack_json_device) - output your log messages as stream of JSON objects for structured logging.
+- [lumberjack_syslog_device](https://github.com/bdurand/lumberjack_syslog_device) - send your log messages to the system wide syslog service
+- [lumberjack_mongo_device](https://github.com/bdurand/lumberjack_mongo_device) - store your log messages to a [MongoDB](http://www.mongodb.org/) NoSQL data store
+- [lumberjack_redis_device](https://github.com/bdurand/lumberjack_redis_device) - store your log messages in a [Redis](https://redis.io/) data store
+- [lumberjack-couchdb-driver](https://github.com/narkisr/lumberjack-couchdb-driver) - store your log messages to a [CouchDB](http://couchdb.apache.org/) NoSQL data store
+- [lumberjack_heroku_device](https://github.com/tonycoco/lumberjack_heroku_device) - log to Heroku's logging system
+- [lumberjack_capture_device](https://github.com/bdurand/lumberjack_capture_device) - capture log messages in memory in test environments so that you can include log output assertions in your tests.
 
 ### Customize Formatting
 
 #### Formatters
 
-The message you send to the logger can be any object type and does not need to be a string. You can specify a `Lumberjack::Formatter` to instruct the logger how to format objects before outputting them to the device. You do this by mapping classes or modules to formatter code. This code can be either a block or an object that responds to the `call` method. The formatter will be called with the object logged as the message and the returned value will be what is sent to the device.
+The message you send to the logger can be any object type and does not need to be a string. You can specify how to format different object types with a formatter. The formatter is responsible for converting the object into a string representation for logging. You do this by mapping classes or modules to formatter code. This code can be either a block or an object that responds to the `call` method. The formatter will be called with the object logged as the message and the returned value will be what is sent to the device.
 
 ```ruby
-  # Format all floating point number with three significant digits.
+  # Format all floating point numbers with three significant digits.
   logger.formatter.add(Float) { |value| value.round(3) }
 
   # Format all enumerable objects as a comma delimited string.
@@ -148,25 +190,53 @@ There are several built in classes you can add as formatters. You can use a symb
   logger.formatter.add(Hash, Lumberjack::Formatter::PrettyPrintFormatter.new)  # alternative using a formatter instance
 ```
 
-* `:object` - `Lumberjack::Formatter::ObjectFormatter` - no op conversion that returns the object itself.
-* `:string` - `Lumberjack::Formatter::StringFormatter` - calls `to_s` on the object.
-* `:strip` - `Lumberjack::Formatter::StripFormatter` - calls `to_s.strip` on the object.
-* `:inspect` - `Lumberjack::Formatter::InspectFormatter` - calls `inspect` on the object.
-* `:exception` - `Lumberjack::Formatter::ExceptionFormatter` - special formatter for exceptions which logs them as multi line statements with the message and backtrace.
-* `:date_time` - `Lumberjack::Formatter::DateTimeFormatter` - special formatter for dates and times to format them using `strftime`.
-* `:pretty_print` - `Lumberjack::Formatter::PrettyPrintFormatter` - returns the pretty print format of the object.
-* `:id` - `Lumberjack::Formatter::IdFormatter` - returns a hash of the object with keys for the id attribute and class.
-* `:structured` - `Lumberjack::Formatter::StructuredFormatter` - crawls the object and applies the formatter recursively to Enumerable objects found in it (arrays, hashes, etc.).
+- `:object` - `Lumberjack::Formatter::ObjectFormatter` - no op conversion that returns the object itself.
+- `:string` - `Lumberjack::Formatter::StringFormatter` - calls `to_s` on the object.
+- `:strip` - `Lumberjack::Formatter::StripFormatter` - calls `to_s.strip` on the object.
+- `:inspect` - `Lumberjack::Formatter::InspectFormatter` - calls `inspect` on the object.
+- `:exception` - `Lumberjack::Formatter::ExceptionFormatter` - special formatter for exceptions which logs them as multi-line statements with the message and backtrace.
+- `:date_time` - `Lumberjack::Formatter::DateTimeFormatter` - special formatter for dates and times to format them using `strftime`.
+- `:pretty_print` - `Lumberjack::Formatter::PrettyPrintFormatter` - returns the pretty print format of the object.
+- `:id` - `Lumberjack::Formatter::IdFormatter` - returns a hash of the object with keys for the id attribute and class.
+- `:structured` - `Lumberjack::Formatter::StructuredFormatter` - crawls the object and applies the formatter recursively to Enumerable objects found in it (arrays, hashes, etc.).
 
 To define your own formatter, either provide a block or an object that responds to `call` with a single argument.
 
+#### Default Formatter
+
+The default formatter is applied to all objects being logged. This includes both messages and tags.
+
 The default formatter will pass through values for strings, numbers, and booleans, and use the `:inspect` formatter for all objects except for exceptions which will be formatted with the `:exception` formatter.
 
+#### Message Formatter
+
+You can add a formatter for just the log message with the `message_formatter` method. This formatter will only apply to the message and not to any tags.
+
+```ruby
+logger.message_formatter.add(String, :truncate, 1000)  # Will truncate all string messages to 1000 characters
+```
+
+##### Extracting Tags from Messages
+
+If you are using structured logging, you can use a formatter to extract tags from the log message by adding a formatter that returns a `Lumberjack::Formatter::TaggedMessage`. For example, if you want to extract metadata from exceptions and add them as tags, you could do this:
+
+```ruby
+logger.message_formatter.add(Exception, ->(e) {
+  Lumberjack::Formatter::TaggedMessage.new(e.inspect, {
+    "error.message": e.message,
+    "error.class": e.class.name,
+    "error.trace": e.backtrace
+  })
+})
+
+logger.error(exception)  # Will log the exception and add tags for the message, class, and trace.
+```
+
 #### Tag Formatters
 
-The `logger.formatter` will only apply to log messages. You can use `logger.tag_formatter` to register formatters for tags. You can register both default formatters that will apply to all tag values, as well as tag specifice formatters that will apply only to objects with a specific tag name.
+The `logger.formatter` will only apply to log messages. You can use `logger.tag_formatter` to register formatters for tags. You can register both default formatters that will apply to all tag values, as well as tag specific formatters that will apply only to objects with a specific tag name.
 
-The fomatter values can be either a `Lumberjack::Formatter` or a block or an object that responds to `call`. If you supply a `Lumberjack::Formatter`, the tag value will be passed through the rules for that formatter. If you supply a block or other object, it will be called with the tag value.
+The formatter values can be either a `Lumberjack::Formatter` or a block or an object that responds to `call`. If you supply a `Lumberjack::Formatter`, the tag value will be passed through the rules for that formatter. If you supply a block or other object, it will be called with the tag value.
 
 ```ruby
 # These will all do the same thing formatting all tag values with `inspect`
@@ -177,11 +247,20 @@ logger.tag_formatter.default { |value| value.inspect }
 # This will register formatters only on specific tag names
 logger.tag_formatter.add(:thread) { |thread| "Thread(#{thread.name})" }
 logger.tag_formatter.add(:current_user, Lumberjack::Formatter::IdFormatter.new)
+
+# You can also register formatters for tag values by class
+logger.tag_formatter.add(Numeric, &:round)
+
+# Tag formatters will be applied to nested hashes and arrays as well.
+
+# Name formatters use dot syntax to apply to nested hashes.
+logger.tag_formatter.add("user.username", &:upcase)
+# logger.tag(user: {username: "john_doe"}) # Will log the tag as {"user" => "username" => "JOHN_DOE"}
 ```
 
 #### Templates
 
-If you use the built in `Lumberjack::Writer` derived devices, you can also customize the Template used to format the LogEntry.
+If you use the built-in `Lumberjack::Writer` derived devices, you can also customize the Template used to format the LogEntry.
 
 See `Lumberjack::Template` for a complete list of macros you can use in the template. You can also use a block that receives a `Lumberjack::LogEntry` as a template.
 
@@ -203,7 +282,7 @@ See `Lumberjack::Template` for a complete list of macros you can use in the temp
 
 ### Buffered Logging
 
-The logger has hooks for devices that support buffering to potentially increase performance by batching physical writes. Log entries are not guaranteed to be written until the Lumberjack::Logger#flush method is called. Buffering can improve performance if I/O is slow or there high overhead writing to the log device.
+The logger has hooks for devices that support buffering to potentially increase performance by batching physical writes. Log entries are not guaranteed to be written until the Lumberjack::Logger#flush method is called. Buffering can improve performance if I/O is slow or there is high overhead writing to the log device.
 
 You can use the `:flush_seconds` option on the logger to periodically flush the log. This is usually a good idea so you can more easily debug hung processes. Without periodic flushing, a process that hangs may never write anything to the log because the messages are sitting in a buffer. By turning on periodic flushing, the logged messages will be written which can greatly aid in debugging the problem.
 
@@ -223,28 +302,38 @@ The built in devices include two that can automatically roll log files based eit
 
 There is a similar feature in the standard library Logger class, but the implementation here is safe to use with multiple processes writing to the same log file.
 
-## Difference Standard Library Logger
+## Integrations
+
+Lumberjack has built in support for logging extensions in Rails.
+
+You can use the [`lumberjack_sidekiq`](https://github.com/bdurand/lumberjack_sidekiq) gem to replace Sidekiq's default logger with Lumberjack. This allows you to use all of Lumberjack's features, such as structured logging and tag support, in your Sidekiq jobs.
+
+If you are using DataDog for logging, you can use the [`lumberjack_data_dog`](https://github.com/bdurand/lumberjack_data_dog) gem to format your logs in DataDog's standard attributes format.
+
+## Differences from Standard Library Logger
 
-`Lumberjack::Logger` does not extend from the `Logger` class in the standard library, but it does implement a compantible API. The main difference is in the flow of how messages are ultimately sent to devices for output.
+`Lumberjack::Logger` does not extend from the `Logger` class in the standard library, but it does implement a compatible API. The main difference is in the flow of how messages are ultimately sent to devices for output.
 
 The standard library Logger logic converts the log entries to strings and then sends the string to the device to be written to a stream. Lumberjack, on the other hand, sends structured data in the form of a `Lumberjack::LogEntry` to the device and lets the device worry about how to format it. The reason for this flip is to better support structured data logging. Devices (even ones that write to streams) can format the entire payload including non-string objects and tags however they need to.
 
-The logging methods (`debug`, 'info', 'warn', 'error', 'fatal') are overloaded with an additional argument for setting tags on the log entry.
+The logging methods (`debug`, `info`, `warn`, `error`, `fatal`) are overloaded with an additional argument for setting tags on the log entry.
 
 ## Examples
 
-These example are for Rails applications, but there is no dependency on Rails for using this gem. Most of the examples are applicable to any Ruby application.
+These examples are for Rails applications, but there is no dependency on Rails for using this gem. Most of the examples are applicable to any Ruby application.
 
 In a Rails application you can replace the default production logger by adding this to your config/environments/production.rb file:
 
 ```ruby
-  # Use the ActionDispatch request id as the unit of work id. This will use just the first chunk of the request id.
-  # If you want to use an abbreviated request id for terseness, change the last argument to `true`
-  config.middleware.insert_after ActionDispatch::RequestId, Lumberjack::Rack::RequestId, false
-  # Use a custom unit of work id to each request
-  # config.middleware.insert(0, Lumberjack::Rack::UnitOfWork)
+  # Add the ActionDispatch request id as a global tag on all log entries.
+  config.middleware.insert_after(
+    ActionDispatch::RequestId,
+    Lumberjack::Rack::Context,
+    request_id: ->(env) { env["action_dispatch.request_id"] }
+  )
   # Change the logger to use Lumberjack
-  log_file_path = Rails.root + "log" + "#{Rails.env}.log"
+  log_file = Rails.root + "log" + "#{Rails.env}.log"
+  # log_file = $stdout # or write to stdout instead of a file
   config.logger = Lumberjack::Logger.new(log_file, :level => :warn)
 ```
 
@@ -283,12 +372,12 @@ To send log messages to syslog instead of to a file, you could use this (require
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'lumberjack'
+gem "lumberjack"
 ```
 
 And then execute:
 ```bash
-$ bundle
+$ bundle install
 ```
 
 Or install it yourself as:

data/VERSION

@@ -1 +1 @@
-1.2.10
+1.3.1