lumberjack 1.4.2 → 2.0.0

data/README.md

@@ -4,385 +4,778 @@
 [![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. It is designed with structured logging in mind, but can be used for simple text logging as well.
+Lumberjack is an extension to the Ruby standard library `Logger` class, designed to provide advanced, flexible, and structured logging for Ruby applications. It builds on the familiar `Logger` API, adding powerful features for modern logging needs:
+
+- **Attributes for Structured Logging:** Use attributes to attach structured, machine-readable metadata to log entries, enabling better filtering, searching, and analytics.
+- **Context Isolation:** Isolate logging behavior to specific blocks of code. The attributes, level, and progname for the logger can all be changed in a context block and only impact the log messages created within that block.
+- **Formatters:** Control how objects are logged with customizable formatters for messages and attributes.
+- **Devices and Templates:** Choose from a variety of output devices and templates to define the format and destination of your logs.
+- **Forked Loggers:** Create independent logger instances that inherit context from a parent logger, allowing for isolated logging configurations in different parts of your application.
+- **Testing Tools:** Built-in testing devices and helpers make it easy to assert logging behavior in your test suite.
+
+The philosophy behind the library is to promote use of structured logging with the standard Ruby Logger API as a foundation. The developer of a piece of functionality should only need to worry about the data that needs to be logged for that functionality and not how it is logged or formatted. Loggers can be setup with global attributes and formatters that handle these concerns.
+
+## Table of Contents
+
+- [Usage](#usage)
+   - [Context Isolation](#context-isolation)
+     - [Context Blocks](#context-blocks)
+     - [Nested Context Blocks](#nested-context-blocks)
+     - [Forking Loggers](#forking-loggers)
+   - [Structured Logging With Attributes](#structured-logging-with-attributes)
+     - [Basic Attribute Logging](#basic-attribute-logging)
+     - [Adding attributes to the logger](#adding-attributes-to-the-logger)
+     - [Global Logger Attributes](#global-logger-attributes)
+     - [Nested Attributes and Complex Data](#nested-attributes-and-complex-data)
+     - [Attribute Inheritance and Merging](#attribute-inheritance-and-merging)
+     - [Working with Array Attributes](#working-with-array-attributes)
+   - [Formatters](#formatters)
+     - [Message Formatters](#message-formatters)
+     - [Attribute Formatters](#attribute-formatters)
+     - [Built-in Formatters](#built-in-formatters)
+     - [Custom Formatters](#custom-formatters)
+     - [Building An Entry Formatter](#building-an-entry-formatter)
+     - [Merging Formatters](#merging-formatters)
+   - [Devices and Templates](#devices-and-templates)
+     - [Built-in Devices](#built-in-devices)
+     - [Custom Devices](#custom-devices)
+     - [Templates](#templates)
+   - [Testing Utilities](#testing-utilities)
+   - [Using As A Stream](#using-as-a-stream)
+   - [Integrations](#integrations)
+- [Installation](#installation)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Usage
 
-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.
+### Context Isolation
+
+Lumberjack provides context isolation that allow you to temporarily modify logging behavior for specific blocks of code or create independent logger instances. This is particularly useful for isolating logging configuration in different parts of your application without affecting the global logger state.
+
+#### Context Blocks
+
+Context blocks allow you to temporarily change the logger's configuration (level, progname, and attributes) for a specific block of code. When the block exits, the logger returns to its previous state.
+
+Context blocks and forked loggers are thread and fiber-safe, maintaining isolation across concurrent operations:
 
 ```ruby
-  logger = Lumberjack::Logger.new("logs/application.log")  # Open a new log file with INFO level
-  logger.info("Begin request")
-  logger.debug(request.params)  # Message not written unless the level is set to DEBUG
-  begin
-    # do something
-  rescue => exception
-    logger.error(exception)
-    raise
-  end
-  logger.info("End request")
+logger.level = :info
+
+# Temporarily change log level for debugging a specific section
+logger.context do
+  logger.level = :debug
+  logger.debug("This debug message will be logged")
+end
+
+# Back to info level - debug messages are filtered out again
+logger.debug("This won't be logged")
 ```
 
-## Features
+You can use `with_level`, `with_progname`, and `tag` to setup a context block with a specific level, progname, or attributes.
 
-### Metadata
+As a best practice, every main unit of work in your application (i.e. HTTP request, background job, etc.) should have a context block. This ensures that any attributes or changes to the logger are scoped to that unit of work and do not leak into other parts of the application.
 
-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.
+##### Nested Context Blocks
 
-The following information is recorded for each message:
+Context blocks can be nested, with inner contexts inheriting and potentially overriding outer context settings:
 
-- 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.
+```ruby
+logger.context do
+  logger.tag(user_id: 123, service: "api")
+  logger.info("API request started") # Includes user_id: 123, service: "api"
 
-### Tags
+  logger.context(endpoint: "/users", service: "user_service") do
+    logger.tag(service: "user_service", endpoint: "/users")
+    logger.info("Processing user data") # Includes: user_id: 123, service: "user_service", endpoint: "/users"
+  end
 
-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.
+  logger.info("API request completed") # Back to: user_id: 123, service: "api"
+end
+```
+
+#### Forking Loggers
 
-Each of the logger methods includes an additional argument that can be used to specify tags on a message:
+Logger forking creates independent logger instances that inherit the parent logger's current context. Changes made to the forked logger will not affect the parent logger.
+
+Forked loggers are useful when there is a section of your application that requires different logging behavior. Forked loggers are cheap to create, so you can use them liberally.
 
 ```ruby
-logger.info("request completed", duration: elapsed_time, status: response.status)
+main_logger = Lumberjack::Logger.new
+main_logger.tag!(version: "1.0.0")
+
+# Create a forked logger for a specific component
+user_service_logger = main_logger.fork(progname: "UserService", level: :debug)
+user_service_logger.tag!(component: "user_management")
+
+user_service_logger.debug("Debug info")    # Includes version and component attributes
+main_logger.info("Main logger info")       # Includes only version attribute
+main_logger.debug("Main logger debug info") # Not logged since level is :info
 ```
 
-You can also specify tags on a logger that will be included with every log message.
+### Structured Logging With Attributes
+
+Lumberjack extends standard logging with **attributes** (structured key-value pairs) that add context and metadata to your log entries. This enables powerful filtering, searching, and analytics capabilities.
+
+#### Basic Attribute Logging
+
+Add attributes with any logging method:
 
 ```ruby
-logger.tag_globally(host: Socket.gethostname.force_encoding("UTF-8"))
+# Add attributes to individual log calls
+logger.info("User logged in", user_id: 123, ip_address: "192.168.1.100")
+logger.error("Payment failed", user_id: 123, amount: 29.99, error: "card_declined")
+
+# Attributes can be any type
+logger.debug("Processing data",
+  records_count: 1500,
+  processing_time: 2.34,
+  metadata: { batch_id: "abc-123", source: "api" },
+  timestamp: Time.now
+)
 ```
 
-You can specify tags that will only be applied to the logger in a block as well.
+> [!Note]
+> Attributes are passed in log statements in the little used `progname` argument that is defined in the standard Ruby Logger API. This attribute is normally used to set a specific program name for the log entry that overrides the default program name on the logger.
+>
+> The only difference in the API is that Lumberjack loggers can take a Hash to set attributes instead of just a string. You can still pass a string to override the program name.
+
+#### Adding attributes to the logger
+
+Use the  `tag` method to tag the the current context with attributes. The attributes will be included in all log entries within that context.
 
 ```ruby
-logger.tag(thread_id: Thread.current.object_id) do
-  logger.info("here") # Will include the `thread_id` tag
-  logger.tag(count: 15)
-  logger.info("with count") # Will include the `count` tag
+logger.context do
+  logger.tag(user_id: current_user.id, session: "abc-def")
+  logger.info("Session started")           # Includes user_id and session
+  logger.debug("Loading user preferences") # Includes user_id and session
+  logger.info("Dashboard rendered")        # Includes user_id and session
 end
-logger.info("there") # Will not include the `thread_id` or `count` tag
+
+logger.info("Outside of context") # Does not include user_id or session
 ```
 
-The block opens up a new tag context. The context applies only within a block and only for the currently executing thread. You can also open up a new context block without specifying any tags and then add tags to the context within the block.
+You can also use the `tag` method with a block to open a new context and assign attributes.
 
 ```ruby
-logger.context do # When a block is given to `context`, it opens a new empty tag context.
-  # `context` can be called without a block, to get an TagContext object for manipulating tags.
-  logger.context.tag(user_id: current_user.id, username: current_user.username)
-  logger.context["user_role"] = current_user.role # You can also use hash syntax to set tags.
-  logger.info("user logged in") # Will include the `user_id`, `username`, and `user_role` tags.
+# Apply attributes to all log entries within the block
+logger.tag(user_id: 123, session: "abc-def") do
+  logger.info("Session started")
+  logger.debug("Loading user preferences")
+  logger.info("Dashboard rendered")
 end
-logger.info("no user") # Will not include the tags
 ```
 
-You can also set tags to `Proc` objects that will be evaluated when creating a log entry.
+Calling `tag` outside of a context without a block is a no-op and has no effect on the logger.
+
+You can also use the `tag_all_contexts` method to add attributes to all parent context blocks. This can be useful in cases where you need to set an attribute that should be included in all subsequent log entries for the duration of the process defined by the outermost context.
+
+Consider this example where we want to include the `user_id` attribute in all log entries. We need to set it on all parent contexts in order to have it extend beyond the current context block.
 
 ```ruby
-logger.tag_globally(thread_id: lambda { Thread.current.object_id })
+logger.context do
+  logger.tag(request_id: "req-123") do
+    logger.info("Processing request") # Includes request_id
 
-Thread.new do
-  logger.info("inside thread") # Will include the `thread_id` tag with id of the spawned thread
-end
+    logger.tag(action: "login") do
+      user_id = login_user(params)
+
+      logger.tag(login_method: params[:login_method])
+      logger.tag_all_contexts(user_id: user_id)
 
-logger.info("outside thread") # Will include the `thread_id` tag with id of the main thread
+      logger.info("User logged in") # Includes request_id, action, login_method, and user_id
+    end
+
+    logger.info("Request completed") # Includes request_id and user_id
+  end
 ```
 
-Finally, you can specify a global logging context that applies to all loggers.
+#### Global Logger Attributes
+
+You can add global attributes that apply to all log entries with the `tag!` method.
 
 ```ruby
-Lumberjack.context do
-  Lumberjack.tag(request_id: SecureRandom.hex) # add a global context tag
-  logger.info("begin request") # Will include the `request_id` tag
-  event_logger.info("http.request") # Will also include the `request_id` tag
-end
-logger.info("no requests") # Will not include the `request_id` tag
+logger.tag!(
+  version: "1.2.3",
+  env: Rails.env,
+  request_id: -> { Current.request_id }
+)
 ```
 
-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.
+If the value of an attribute is a `Proc`, it will be evaluated at runtime when the log entries are created. So in the above example, `request_id` will be dynamically set to the current request ID whenever a log entry is created.
 
-#### Structured Logging with Tags
+Note that blank attributes are never included in the log output, so if `Current.request_id` is `nil`, the `request_id` attribute will be omitted from the log entry.
 
-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.
+There is also a global `Lumberjack` context that applies to all Lumberjack loggers.
 
 ```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"
-})
+Lumberjack.tag(version: "1.2.3") do
+  logger_1.info("Something happened")       # Includes version
+  logger_2.info("Something else happened")  # Includes version
+end
 ```
 
-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
+#### Nested Attributes and Complex Data
 
-You can also use nested structures in tags for complex data:
+Attributes support nested structures and complex data types:
 
 ```ruby
-logger.info("API request completed", {
+logger.info("API request completed",
   request: {
     method: "POST",
     path: "/api/users",
-    user_agent: request.user_agent
+    headers: { "Content-Type" => "application/json" }
   },
   response: {
     status: 201,
-    duration_ms: 150
+    duration_ms: 45.2,
+    size_bytes: 1024
   },
   user: {
-    id: current_user.id,
-    role: current_user.role
+    id: 123,
+    role: "admin",
+    permissions: ["read", "write", "delete"]
   }
-})
+)
 ```
 
-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.
+#### Attribute Inheritance and Merging
 
-#### Compatibility with ActiveSupport::TaggedLogging
+Attributes from different sources are merged together, with more specific attributes taking precedence:
 
-`Lumberjack::Logger` 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
+# Persistent logger attributes
+logger.tag!(service: "web", datacenter: "us-east-1")
+
+logger.tag(request_id: "req-123") do
+  # Block-level attributes override any conflicts
+  logger.tag(datacenter: "us-west-2") do
+    logger.info("Processing request",
+      user_id: 456,
+      datacenter: "eu-central-1"  # This takes highest precedence
+    )
+    # Final attributes: { service: "web", request_id: "req-123", user_id: 456, datacenter: "eu-central-1" }
+  end
+end
+```
+
+Attributes use dot notation for nested structures, so there is no difference between these statements:
 
 ```ruby
-logger.tagged("foo", "bar=1", "other") do
-  logger.info("here") # will include tags: {"tagged" => ["foo", "bar=1", "other"]}
+logger.info("User signed in", user: {id: 123})
+logger.info("User signed in", "user.id" => 123)
+```
+
+#### Working with Array Attributes
+
+A common practice is to add an array of values to a specific attribute. You can use the `append_to` method to append values to an array attribute in the current context. Like the `tag` method, this method can be called with a block to create a new context or without a block to update the current context.
+
+```ruby
+logger.append_to(:tags, "api", "v1") do
+  logger.info("API request started") # Includes tags: ["api", "v1"]
+
+  logger.append_to(:tags, "users")
+  logger.info("Processing user data") # Includes tags: ["api", "v1", "users"]
+end
+
+# You can also append to other array attributes
+logger.append_to(:categories, "billing", "premium") do
+  logger.info("Processing premium billing") # Includes categories: ["billing", "premium"]
 end
 ```
 
-#### Templates
+### Formatters
+
+Lumberjack provides a powerful formatting system that controls how objects are converted to strings in log entries. With this feature you can pass objects to the logger and rely on the formatters to handle formatting thereby simplifying the logging code and improving consistency.
+
+There are two types of formatters.
+
+#### Message Formatters
+
+Message formatters control how different types of objects are converted to strings when logged as messages. Message formatters are registered for specific classes or modules. When you log an object, the formatter will be looked up based on the object's class.
+
+```ruby
+logger.formatter.format_message(Array) { |arr| arr.join(", ") }
+
+logger.info([1, 2, 3]) # Logs "1, 2, 3"
+```
 
-The built in `Lumberjack::Device::Writer` class has built in support for including tags in the output using the `Lumberjack::Template` class.
+For log messages you can use the `Lumberjack::MessageAttributes` class to extract structured data from a log message. This can be used to allow logging objects directly and extracting metadata from the objects in the log attributes.
 
-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.
+```ruby
+logger.formatter.format_message(Exception) do |error|
+  Lumberjack::MessageAttributes.new(
+    error.inspect, # This will be used as the log message
+    error: { # This will be added to the log attributes
+      type: error.class.name,
+      message: error.message,
+      backtrace: error.backtrace
+    }
+  )
+end
+
+# This will now log the message as `exception.inspect` and pull
+# out the type, message, and backtrace into attributes. With this
+# you won't need to figure out how to log each exception and just
+# just log the object itself and let the formatter deal with it.
+logger.error(exception)
+```
+
+#### Attribute Formatters
+
+Attribute formatters control how attribute values (the key-value pairs in structured logging) are formatted. They provide fine-grained control over different attributes and data types.
+
+You can specify how to format object types when they are logged as attributes:
+
+```ruby
+logger.formatter.format_attributes(Time, :date_time, "%Y-%m-%d %H:%M:%S")
+logger.formatter.format_attributes([Float, BigDecimal], :round, 2)
+
+logger.info("Data processed",
+  created_at: Time.now,          # → "2025-08-22 14:30:00"
+  price: 29.099,                 # → 29.10
+)
+```
 
-### Pluggable Devices
+You can also format attributes based on the attribute name:
 
-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.
+```ruby
+# Configure attribute formatting
+logger.formatter.format_attribute_name("password") { |pwd| "[REDACTED]" }
+logger.formatter.format_attribute_name("email") { |email| email.downcase }
+logger.formatter.format_attribute_name("cost", :round, 2)
+
+# Now attributes are formatted according to the rules
+logger.info("User created",
+  email: "JOHN@EXAMPLE.COM",     # → "john@example.com"
+  password: "secret123",         # → "[REDACTED]"
+  cost: 29.129999                # → 29.13
+)
+```
 
-- 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.
+You can remap attributes to other attribute names by returning a `Lumberjack::RemapAttribute` instance.
 
-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:
+```ruby
+# Move the email attribute under the user attributes.
+logger.formatter.format_attribute_name("email") do |value|
+  Lumberjack::RemapAttribute.new("user.email" => value)
+end
+
+# Transform duration_millis and duration_micros to seconds and move to
+# the duration attribute.
+logger.formatter.format_attribute_name("duration_ms") do |value|
+  Lumberjack::RemapAttribute.new("duration" => value.to_f / 1000)
+end
+logger.formatter.format_attribute_name("duration_micros") do |value|
+  Lumberjack::RemapAttribute.new("duration" => value.to_f / 1_000_000)
+end
+```
 
-- [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.
+Finally, you can add a default formatter for all other attributes:
 
-### Customize Formatting
+```ruby
+logger.formatter.default_attribute_format { |value| value.to_s.strip[0..100] }
+```
 
-#### Formatters
+#### Built-in Formatters
 
-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.
+Lumberjack provides several predefined formatters that can be referenced by symbol:
 
 ```ruby
-  # Format all floating point numbers with three significant digits.
-  logger.formatter.add(Float) { |value| value.round(3) }
+logger = Lumberjack::Logger.new
+
+# Configure the formatter
+logger.formatter.format_class(Float, :round, 2)           # Round floats to 2 decimals
+logger.formatter.format_class(Time, :date_time, "%H:%M")  # Custom time format
 
-  # Format all enumerable objects as a comma delimited string.
-  logger.formatter.add(Enumerable) { |value| value.join(", ") }
+# Now these objects will be formatted according to the rules
+logger.info(3.14159)                             # "3.14"
+logger.info(Time.now)                            # "14:30"
 ```
 
-There are several built in classes you can add as formatters. You can use a symbol to reference built in formatters.
+**Available Built-in Formatters:**
+
+| Formatter | Purpose |
+|-----------|---------|
+| `:date_time` | Format time/date objects |
+| `:exception` | Format exceptions with stack traces |
+| `:id` | Extract object ID or specified field |
+| `:inspect` | Use Ruby's inspect method |
+| `:multiply` | Multiply numeric values |
+| `:object` | Generic object formatter |
+| `:pretty_print` | Pretty print using PP library |
+| `:redact` | Redact sensitive information |
+| `:round` | Round numeric values |
+| `:string` | Convert to string using to_s |
+| `:strip` | Strip whitespace from strings |
+| `:structured` | Recursively format collections |
+| `:tags` | Format values as tags in the format "[val1] [val2]" for arrays or "[key=value]" for hashes |
+| `:truncate` | Truncate long strings |
+
+#### Custom Formatters
+
+You can create custom formatters using blocks, callable objects, or custom classes:
 
 ```ruby
-  logger.formatter.add(Hash, :pretty_print)  # use the Formatter::PrettyPrintFormatter for all Hashes
-  logger.formatter.add(Hash, Lumberjack::Formatter::PrettyPrintFormatter.new)  # alternative using a formatter instance
+# Block-based formatters
+logger.formatter.format_class(User) { |user| "User[#{user.id}:#{user.name}]" }
+logger.formatter.format_class(BigDecimal) { |decimal| "$#{decimal.round(2)}" }
+
+# Callable object formatters
+class TimeFormatter
+  def call(time)
+    time.strftime("%Y-%m-%d %H:%M:%S")
+  end
+end
+
+logger.formatter.format_class(SecureString, PasswordFormatter.new)
 ```
 
-- `: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.).
-- `:truncate` - `Lumberjack::Formatter::TruncateFormatter` - truncates long strings to a specified length.
+Classes can also implement `to_log_format` to define how instances should be serialized for logging. This will apply to both message and attribute formatting.
 
-To define your own formatter, either provide a block or an object that responds to `call` with a single argument.
+```ruby
+class User
+  attr_accessor :id, :name
 
-#### Default Formatter
+  def to_log_format
+    "User[id: #{ id }, name: #{ name }]"
+  end
+end
+```
 
-The default formatter is applied to all objects being logged. This includes both messages and tags.
+Primitive classes (`String`, `Integer`, `Float`, `TrueClass`, `FalseClass`, `NilClass`, `BigDecimal`) will not use `to_log_format`.
 
-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.
+#### Building An Entry Formatter
 
-#### Message Formatter
+The Entry Formatter coordinates both message and attribute formatting, providing a unified configuration interface:
 
-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.
+##### Complete Entry Formatter Setup
 
 ```ruby
-logger.message_formatter.add(String, :truncate, 1000)  # Will truncate all string messages to 1000 characters
+# Build a comprehensive entry formatter
+entry_formatter = Lumberjack.build_formatter do |formatter|
+  # Format for ActiveRecord models that applies to both messages and attributes.
+  formatter.format_class(ActiveRecord::Base, :id)
+
+  # Format for the User class when it is logged as the log message.
+  formatter.format_message(User) { |user| "User[#{user.id}:#{user.username}]" }
+
+  # Attribute formatting
+  formatter.format_attributes(Time, :date_time, "%Y-%m-%d %H:%M:%S")
+  formatter.format_attributes([Float, BigDecimal], :round, 6)
+  formatter.format_attribute_name("email", :redact)
+end
+
+# Use with logger
+logger = Lumberjack::Logger.new(STDOUT, formatter: entry_formatter)
 ```
 
-##### Extracting Tags from Messages
+#### Merging Formatters
 
-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:
+You can merge other formatters into your formatter with the `include` method. Doing so will copy all of the format definitions.
 
 ```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
-  })
-})
+# Translate the duration tag to microseconds.
+duration_formatter = Lumberjack::EntryFormatter.build do |formatter|
+  formatter.format_attribute_name(:duration) { |seconds| (seconds.to_f * 1_000_000).round }
+end
 
-logger.error(exception)  # Will log the exception and add tags for the message, class, and trace.
+entry_formatter = Lumberjack::EntryFormatter.build do |formatter|
+  # Adds the duration attribute formatter
+  formatter.include(duration_formatter)
+end
 ```
 
-#### Tag Formatters
+You can also call `prepend` in which case any formats already defined will take precedence over the formats being included.
+
+### Devices and Templates
+
+Devices control where and how log entries are written. Lumberjack provides a variety of built-in devices that can write to files, streams, multiple destinations, or serve special purposes like testing. All devices implement a common interface, making them interchangeable.
+
+#### Built-in Devices
 
-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.
+##### Writer Device
 
-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.
+The `Writer` device is the foundation for most logging output, writing formatted log entries to any IO stream. It will be used if you pass an IO object to the logger.
 
 ```ruby
-# These will all do the same thing formatting all tag values with `inspect`
-logger.tag_formatter.default(Lumberjack::Formatter.new.clear.add(Object, :inspect))
-logger.tag_formatter.default(Lumberjack::Formatter::InspectFormatter.new)
-logger.tag_formatter.default { |value| value.inspect }
+logger = Lumberjack::Logger.new(STDOUT)
+```
+
+##### LogFile Device
+
+The `LogFile` device handles logging to a file. It has the same log rotation capabilities as the `Logger::LogDevice` class in the standard library logger.
 
-# 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)
+```ruby
+# Daily log rotation
+logger = Lumberjack::Logger.new("/var/log/app.log", 'daily')
+```
 
-# You can also register formatters for tag values by class
-logger.tag_formatter.add(Numeric, &:round)
+##### Multi Device
 
-# Tag formatters will be applied to nested hashes and arrays as well.
+The `Multi` device broadcasts log entries to multiple devices simultaneously. You can instantiate a multi device by passing in an array of values.
 
-# 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"}
+```ruby
+# Log to both file and STDOUT; the logs to STDOUT will only contain the log message.
+logger = Lumberjack::Logger.new(["/var/log/app.log", [:stdout, {template: "{{message}}"}]])
+
+logger.info("Application started")  # Appears in both file AND STDOUT
 ```
 
-#### Templates
+##### LoggerWrapper Device
+
+The `LoggerWrapper` device forwards entries to another Logger instance. It is most useful when you want to route logs from one logger to another, possibly with different configurations.
 
-If you use the built-in `Lumberjack::Device::Writer` derived devices, you can also customize the Template used to format the LogEntry.
+```ruby
+target_logger = Lumberjack::Logger.new("/var/log/target.log")
+logger = Lumberjack::Logger.new(target_logger)
+```
+
+> [!NOTE]
+> Note that the level of the outer logger will take precedence. So if the outer logger is set to `:warn`, then only warning messages or higher will be forwarded to the target logger.
+
+> [!TIP]
+> You can also pass in a standard Ruby `Logger` instance. This allows you to use the enhanced Lumberjack logging features with a standard library logger.
+
+##### Test Device
 
-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.
+The `Test` device logs entries in memory and is intended for use in test suites where you want to make assertions that specific log entries are recorded.
 
 ```ruby
-  # Change the format of the time in the log
-  Lumberjack::Logger.new("application.log", :time_format => "%m/%d/%Y %H:%M:%S")
+logger = Lumberjack::Logger.new(:test)
+```
+
+> [!TIP]
+> See the [testing utilities](#testing-utilities) section for more information.
 
-  # Use a simple template that only includes the time and the message
-  Lumberjack::Logger.new("application.log", :template => ":time - :message")
+##### Null Device
 
-  # Use a simple template that includes tags, but handles the `duration` tag separately.
-  # All tags will appear at the end of the message except for `duration` which will be at the beginning.
-  Lumberjack::Logger.new("application.log", :template => ":time (:duration) - :message - :tags")
+The `Null` device discards all output.
 
-  # Use a custom template as a block that only includes the first character of the severity
-  template = lambda{|e| "#{e.severity_label[0, 1]} #{e.time} - #{e.message}"}
-  Lumberjack::Logger.new("application.log", :template => template)
+```ruby
+logger = Lumberjack::Logger.new(:null)
 ```
 
-### Buffered Logging
+#### Custom Devices
 
-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 create custom devices by implementing the `write` method. The `write` method will receive a `Lumberjack::LogEntry` object and is free to process it in any way.
 
-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.
+```ruby
+class DatabaseDevice < Lumberjack::Device
+  def initialize(database_connection)
+    @db = database_connection
+  end
+
+  def write(entry)
+    @db.execute(
+      "INSERT INTO logs (timestamp, level, message, attributes, pid) VALUES (?, ?, ?, ?, ?)",
+      entry.time,
+      entry.severity_label,
+      entry.message,
+      JSON.generate(entry.attributes),
+      entry.pid
+    )
+  end
+
+  def close
+    @db.close
+  end
+end
+
+# Usage
+db_device = DatabaseDevice.new(SQLite3::Database.new("logs.db"))
+logger = Lumberjack::Logger.new(db_device)
+```
+
+There are separate gems implementing custom devices for different use cases:
 
-The built in stream based logging devices use an internal buffer. The size of the buffer (in bytes) can be set with the `:buffer_size` options when initializing a logger. The default behavior is to not buffer.
+- [lumberjack_json_device](https://github.com/bdurand/lumberjack_json_device) - Output logs to JSON
+- [lumberjack_datadog_device](https://github.com/bdurand/lumberjack_datadog) - Output logs in JSON using the Datadog standard attributes.
+- [lumberjack_capture_device](https://github.com/bdurand/lumberjack_capture_device) - Device designed for capturing logs in tests to make assertions easier
+- [lumberjack_syslog_device](https://github.com/bdurand/lumberjack_syslog_device) - Device for logging to a syslog server
+- [lumberjack_redis_device](https://github.com/bdurand/lumberjack_redis_device) - Device for logging to a Redis database
+
+You can register a custom device with Lumberjack using the device registry. This associates the device with the device class and can make using the device easier to setup since the user can pass the symbol and options when instantiating the Logger rather than having to instantiate the device separately.
 
 ```ruby
-  # Set buffer to flush after 8K has been written to the log.
-  logger = Lumberjack::Logger.new("application.log", :buffer_size => 8192)
+  Lumberjack::Device.register(:my_device, MyDevice)
 
-  # Turn off buffering so entries are immediately written to disk.
-  logger = Lumberjack::Logger.new("application.log", :buffer_size => 0)
+  # Now logger can be instantiated with the name and all options will be passed to
+  # the MyDevice constructor.
+  logger = Lumberjack::Logger.new(:my_device, autoflush: true)
 ```
 
-### Automatic Log Rolling
+#### Templates
 
-The built in devices include two that can automatically roll log files based either on date or on file size. When a log file is rolled, it will be renamed with a suffix and a new file will be created to receive new log entries. This can keep your log files from growing to unusable sizes and removes the need to schedule an external process to roll the files.
+The output devices writing to a stream or file can define templates that formats how log entries are written. Templates use mustache-style placeholders that are replaced with values from the log entry.
 
-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.
+##### Basic Template Usage
 
-## Integrations
+```ruby
+# Simple template with common fields
+logger = Lumberjack::Logger.new(STDOUT, template: "{{time}} {{severity}} {{message}}")
 
-Lumberjack has built in support for logging extensions in Rails.
+logger.info("Application started")
+# Output: 2025-09-03T14:30:15.123456 INFO Application started
+```
 
-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.
+##### Available Template Variables
 
-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.
+Templates support the following placeholder variables:
 
-## Differences from Standard Library Logger
+| Variable | Description |
+|----------|-------------|
+| `time` | Timestamp |
+| `severity` | Severity level |
+| `progname` | Program name |
+| `pid` | Process ID |
+| `message` | Log message |
+| `attributes` | Formatted attributes |
 
-`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.
+In addition you can put any attribute name in a placeholder. The attribute will be inserted in the log line where the placeholder is defined and will be removed from the general list of attributes.
 
-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.
+```ruby
+# The user_id attribute will appear separately on the log line from the
+# rest of the attributes.
+logger = Lumberjack::Logger.new(STDOUT,
+  template: "[{{time}} {{severity}} {{user_id}}] {{message}} {{attributes}}"
+)
+```
 
-The logging methods (`debug`, `info`, `warn`, `error`, `fatal`) are overloaded with an additional argument for setting tags on the log entry.
+The severity can also have an optional formatting argument added to it.
 
-## Examples
+| Variable | Description |
+|----------|-------------|
+| `severity` | Uppercase case severity label (INFO, WARN, etc.) |
+| `severity(padded)` | Severity label padded to 5 characters |
+| `severity(char)` | First character of severity label |
+| `severity(emoji)` | Emoji representation of severity level |
+| `severity(level)` | Numeric severity level |
 
-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.
+##### Template Options
 
-In a Rails application you can replace the default production logger by adding this to your config/environments/production.rb file:
+You can customize how template variables are formatted using template options:
 
 ```ruby
-  # 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 = 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)
+logger = Lumberjack::Logger.new(STDOUT,
+  template: "[{{time}} {{severity(padded)}} {{progname}}({{pid}})] [{{http.request_id}}] {{message}} {{attributes}}",
+  time_format: "%Y-%m-%d %H:%M:%S", # Custom time format
+  additional_lines: "\n> [{{http.request_id}}] {{message}}", # Template for additional lines on multiline messages
+  attribute_format: "[%s=%s]", # Format for attributes using printf syntax
+  colorize: true # Colorize log output according to entry severity
+)
+
+logger.info("Test message", user_id: 123, status: "active")
+# Output: 2025-09-03 14:30:15  INFO Test message [user_id=123] [status=active]
 ```
 
-To set up a logger to roll every day at midnight, you could use this code (you can also specify :weekly or :monthly):
+##### Built-in Templates
+
+You can use symbols to refer to built-in templates:
+
+- `:default` - The default log template. This is the same as not specifying a template.
+- `:stdlib` - A template that mimics the default format of the standard library Logger.
+- `:local` - A simple, human readable template intended for local development and test environments. This template removes the time and pid from the log line since they are generally not needed in these environments. You can also exclude attributes by setting the `exclude_attributes` option to the list of attributes names to exclude. For example, you may want to add a `host` attribute for your production logs, but this just creates clutter in development logs since it is always the same value.
 
 ```ruby
-  config.logger = Lumberjack::Logger.new(log_file_path, :roll => :daily)
+logger = Lumberjack::Logger.new(STDOUT, template: :local, exclude_attributes: ["host", "env", "version"])
 ```
 
-To set up a logger to roll log files when they get to 100Mb, you could use this:
+### Testing Utilities
+
+The `Test` device captures log entries in memory for testing and assertions:
 
 ```ruby
-  config.logger = Lumberjack::Logger.new(log_file_path, :max_size => 100.megabytes)
+logger = Lumberjack::Logger.new(:test)
+
+# Log some entries
+logger.info("User logged in", user_id: 123)
+logger.error("Payment failed", amount: 29.99)
+
+# You can make assertions against the logs (using rspec in this case)
+expect(logger.device.entries.size).to eq(2)
+expect(logger.device.last_entry.message).to eq("Payment failed")
+
+# Use pattern matching
+expect(logger.device).to include(
+  severity: :info,
+  message: "User logged in",
+  attributes: { user_id: 123 }
+)
+
+expect(logger.device).to include(severity: :error, message: /Payment/)
 ```
 
-To change the log message format, you could use this code:
+You should make sure to call `logger.device.clear` between tests to clear the captured logs on any global loggers that are using the `Test` device.
+
+> [!NOTE]
+> Log entries are captured after formatters have been applied. This provides a mechanism for including the formatting logic in your tests.
+
+> [!TIP]
+> The [lumberjack_capture_device](https://github.com/bdurand/lumberjack_capture_device) gem provides some additional testing utilities and rspec integration.
+
+You can also use the `write_to` method on the `Test` device to write the captured log entries to another logger or device. This can be useful in scenarios where you want to preserve log output for failed tests.
 
 ```ruby
-  config.logger = Lumberjack::Logger.new(log_file_path, :template => ":time - :message")
+# Set up test logger (presumably in an initializer)
+Application.logger = Lumberjack::Logger.new(:test)
+
+# Hook into your test framework; in this example using rspec.
+RSpec.configure do |config|
+  failed_test_logs = Lumberjack::Logger.new("log/test_failures.log")
+  config.around do |example|
+    # Clear the captured logs so we start with a clean slate.
+    Application.logger.clear
+
+    example.run
+
+    if example.exception
+      failed_test_logs.error("Test failed: #{example.full_description} @ #{example.location}")
+      Application.logger.device.write_to(failed_test_logs)
+    end
+  end
+end
 ```
 
-To change the log message format to output JSON, you could use this code:
+Lumberjack will catch any errors raised when logging and output the error message and backtrace to STDERR. This prevents logging errors from crashing your application. You should disable this behavior in your test suite so that logging errors are raised and can be fixed.
 
 ```ruby
-  config.logger = Lumberjack::Logger.new(log_file_path, :template => lambda{|e| JSON.dump(time: e.time, level: e.severity_label, message: e.message)})
+Lumberjack.raise_logging_errors = true
 ```
 
-To send log messages to syslog instead of to a file, you could use this (requires the lumberjack_syslog_device gem):
+### Using As A Stream
+
+Lumberjack loggers implement methods necessary for treating them like a stream. You can use this to augment output from components that write output to a stream with metadata like a timestamp and attributes.
 
 ```ruby
-  config.logger = Lumberjack::Logger.new(Lumberjack::SyslogDevice.new)
+logger = Lumberjack::Logger.new($stderr, progname: "MyApp")
+$stderr = logger
+
+# These statements will now do the same thing
+logger.unknown("Something went wrong")
+$stderr.puts "Something went wrong"
+
+# You can set the default level to set the level when using the I/O methods
+logger.default_level = :warn
+$stderr.puts "This is a warning message" # logged as a warning
 ```
 
+### Integrations
+
+#### Rails
+
+> [!WARNING]
+> If you are using Rails, you must use the [lumberjack_rails](https://github.com/bdurand/lumberjack_rails) gem.
+>
+> Rails does its own monkey patching to the standard library Logger to support tagged logging, silencing logs, and broadcast logging.
+
+#### Other Integrations
+
+- [lumberjack_sidekiq](https://github.com/bdurand/lumberjack_sidekiq) - Integrates Lumberjack with Sidekiq for background job logging.
+- [lumberjack_datadog](https://github.com/bdurand/lumberjack_datadog) - Integrates Lumberjack with Datadog by outputting logs in JSON using Datadog's standard attributes.
+- [lumberjack_local_logger](https://github.com/bdurand/lumberjack_local_logger) - Lightweight wrapper around Lumberjack::Logger that allows contextual logging with custom levels, prognames, and attributes without affecting the parent logger.
+- Check [RubyGems](https://rubygems.org/gems) for other integrations
+
 ## Installation
 
 Add this line to your application's Gemfile: