lumberjack_json_device 2.2.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5056428eb1c260cf68a1742064c824645ef8df0c71164a20fd8f03bb5b3f1bbc
-  data.tar.gz: 69ff5c7d4c88a90b5be63b9d77724b4c36f090a109791c0819bbe0f97934d0f7
+  metadata.gz: 93f11eda1a4055d1cc3b6ee2b9577e28f0a26ae937f88e49bc5c07aa0c1b327d
+  data.tar.gz: 96d500179158ea397ed2f52a3a096520125350cc673e5de5dbe352203b607d3f
 SHA512:
-  metadata.gz: 03f44e6637e5fd9df15ccef421ebafcc035498ff272afae0c3845997bfd63099a11bc2425051fa4a94e8bf20eef7419ee961511b6fcba1a675537fc8ebaf28f3
-  data.tar.gz: a5a0bfdc425825484dd1cd0c95ea788919189c594cf5fb7ed55107e14655b7be55a2826f71758b2b1c93e91695c2506f84eeacc690e88919b579da339abddba0
+  metadata.gz: 00773c4aa83e49275b69fa0d400d8c17783008aa013a0b84b881acd868ab9e3ce6f39e5fc183b8d1ce2584c7e306363cfb7aa60d9045edacd100c66821601d85
+  data.tar.gz: 396d28c5697ded1ef621a959287c356b71a2e33942510cc72c88d32bd41e77c548d0d359df852e41a7ebeff1b60b839c092954e654a7dbbd6b2bc322b207eb1b

data/.github/workflows/continuous_integration.yml

@@ -5,8 +5,6 @@ on:
     branches:
       - main
       - actions-*
-    tags:
-      - v*
   pull_request:
     branches-ignore:
       - actions-*
@@ -27,9 +25,9 @@ jobs:
         include:
           - ruby: "ruby"
             standardrb: true
+            yard: true
           - ruby: "3.0"
           - ruby: "2.7"
-          - ruby: "2.5"
     steps:
     - uses: actions/checkout@v4
     - name: Set up Ruby
@@ -44,3 +42,6 @@ jobs:
     - name: standardrb
       if: matrix.standardrb
       run:  bundle exec standardrb
+    - name: yard
+      if: matrix.yard
+      run:  bundle exec yard --fail-on-warning

data/.standard.yml

@@ -1,4 +1,4 @@
-ruby_version: 2.5
+ruby_version: 2.7
 
 format: progress
 

data/CHANGE_LOG.md

@@ -4,6 +4,44 @@ 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).
 
+## 3.0.0
+
+### Added
+
+- Support for Lumberjack 2.0.
+- **Breaking Change** The constructor now takes an options hash rather than keyword arguments.
+- Added the `:output` key to the constructor options hash to specify the output stream. This argument can take either a stream or a file path.
+- Added `:utc` option to force timestamps to be in UTC.
+
+### Changed
+
+- **Breaking Change** Tags are now called attributes and are put in the `"attributes"` JSON field by default. If you want to keep the old behavior, you will need to set the mapping to:
+
+```ruby
+  {
+    time: true,
+    severity: true,
+    progname: true,
+    pid: true,
+    message: true,
+    attributes: ["tags"]
+  }
+```
+
+### Deprecated
+
+- Deprecated passing in the output stream as the first positional argument. The output stream should now be specified using the `:output` key in the options hash.
+
+### Removed
+
+- Support for Ruby versions less than 2.7
+
+## 2.2.1
+
+## Changed
+
+- Added error handling for JSON serialization. This ensures that logs can still be written to even if an error occurs during serialization.
+
 ## 2.2.0
 
 ### Changed
@@ -29,9 +67,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- Tag structure is now consistently expanded from dot notation into nested hashes in the `tag` field. Previoulsly this was only done when the template copied tags to the root level of the JSON document.
+- Tag structure is now consistently expanded from dot notation into nested hashes in the `attribute` field. Previoulsly this was only done when the template copied attributes to the root level of the JSON document.
 - The mapping options now supports setting the value to `false` to exclude a field from the JSON output.
-- Tag mapping can now be set to `"*"` to copy all tags into the root of the JSON document.
+- Tag mapping can now be set to `"*"` to copy all attributes into the root of the JSON document.
 
 ### Removed
 

data/README.md

@@ -4,43 +4,49 @@
 [![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_json_device.svg)](https://badge.fury.io/rb/lumberjack_json_device)
 
-This gem provides a logging device for the [lumberjack](https://github.com/bdurand/lumberjack) gem that outputs JSON formatted log entries to a stream with one JSON document per line. This format is ideal for structured logging pipelines and can be easily consumed by log aggregation services, search engines, and monitoring tools.
+This gem provides a logging device for the [lumberjack](https://github.com/bdurand/lumberjack) gem that outputs [JSONL](https://jsonlines.org/) formatted log entries to a stream. This format with one JSON document per line is ideal for structured logging pipelines and can be easily consumed by log aggregation services, search engines, and monitoring tools.
 
-## Quick Start
+## Usage
+
+### Quick Start
 
 ```ruby
 require 'lumberjack_json_device'
 
 # Create a logger with JSON output to STDOUT
-logger = Lumberjack::Logger.new(Lumberjack::JsonDevice.new(STDOUT))
+logger = Lumberjack::Logger.new(Lumberjack::JsonDevice.new(output: STDOUT))
 
-# Log a message with tags
+# Log a message with attributes
 logger.info("User logged in", user_id: 123, session_id: "abc")
-# Output: {"time":"2020-01-02T19:47:45.123455-0800","severity":"INFO","progname":null,"pid":12345,"message":"User logged in","tags":{"user_id":123,"session_id":"abc"}}
 ```
 
-## Output Destinations
+This will output JSON like:
+
+```
+{ "time":"2020-01-02T19:47:45.123456-0800","severity":"INFO","progname":null,"pid":12345,"message":"User logged in","attributes":{ "user_id":123,"session_id":"abc" } }
+```
+
+### Output Destinations
 
 You can send the JSON output to either a stream or to another Lumberjack device.
 
 ```ruby
-# Send to STDOUT
-device = Lumberjack::JsonDevice.new(STDOUT)
+# Send to stream (STDOUT is the default)
+device = Lumberjack::JsonDevice.new(output: STDOUT)
 
-# Send to another logging device
-log_file = Lumberjack::Device::LogFile.new("/var/log/app.log")
-device = Lumberjack::JsonDevice.new(log_file)
+# Send to a log file
+device = Lumberjack::JsonDevice.new(output: "/var/log/app.log")
 ```
 
-## JSON Structure
+### JSON Structure
 
 By default, the JSON document maps to the `Lumberjack::LogEntry` data structure and includes all standard fields:
 
-```json
-{"time": "2020-01-02T19:47:45.123455-0800", "severity": "INFO", "progname": "web", "pid": 101, "message": "test", "tags": {"foo": "bar"}}
+```
+{ "time": "2020-01-02T19:47:45.123456-0800", "severity": "INFO", "progname": "web", "pid": 101, "message": "test", "attributes": { "foo": "bar" } }
 ```
 
-### Custom Field Mapping
+#### Custom Field Mapping
 
 You can customize the JSON document structure by providing a mapping that specifies how log entry fields should be transformed. The mapping supports several different value types:
 
@@ -50,117 +56,146 @@ You can customize the JSON document structure by providing a mapping that specif
 - **`false`**: Excludes the field from the JSON output
 - **Callable**: Transforms the value using custom logic
 
-You can map the standard field names (`time`, `severity`, `progname`, `pid`, `message`, and `tags`) as well as extract specific tags by name.
+You can map the standard field names (`time`, `severity`, `progname`, `pid`, `message`, and `attributes`) as well as extract specific attributes by name.
 
 ```ruby
-device = Lumberjack::JsonDevice.new(STDOUT, mapping: {
-  time: "timestamp",
-  severity: "level",
-  progname: ["app", "name"],
-  pid: ["app", "pid"],
-  message: "message",
-  duration: "duration",  # Extracts the "duration" tag
-  tags: "tags"
-})
+device = Lumberjack::JsonDevice.new(
+  output: STDOUT,
+  mapping: {
+    time: "timestamp",
+    severity: "level",
+    progname: ["app", "name"],
+    pid: ["app", "pid"],
+    message: "message",
+    duration: "duration",  # Extracts the "duration" attribute
+    attributes: "attributes"
+  }
+)
 ```
 
-```json
-{"timestamp": "2020-01-02T19:47:45.123455-0800", "level": "INFO", "app": {"name": "web", "pid": 101}, "message": "test", "duration": 5, "tags": {"foo": "bar"}}
+Example output:
+
+```
+{ "timestamp": "2020-01-02T19:47:45.123456-0800", "level": "INFO", "app": { "name": "web", "pid": 101 }, "message": "test", "duration": 5, "attributes": { "foo": "bar" } }
 ```
 
-### Excluding Fields
+#### Excluding Fields
 
 If you omit fields from the mapping or set them to `false`, they will not appear in the JSON output:
 
 ```ruby
-device = Lumberjack::JsonDevice.new(STDOUT, mapping: {
-  time: "timestamp",
-  severity: "level",
-  message: "message",
-  pid: false  # Exclude PID from output
-})
+device = Lumberjack::JsonDevice.new(
+  output: STDOUT,
+  mapping: {
+    time: "timestamp",
+    severity: "level",
+    message: "message",
+    pid: false  # Exclude PID from output
+  }
+)
 ```
 
-```json
-{"timestamp": "2020-01-02T19:47:45.123455-0800", "level": "INFO", "message": "test"}
+Example output:
+
+```
+{ "timestamp": "2020-01-02T19:47:45.123456-0800", "level": "INFO", "message": "test" }
 ```
 
-### Custom Transformations
+#### Custom Transformations
 
 You can provide a callable object (proc, lambda, or any object responding to `call`) to transform field values. The callable receives the original value and should return a hash that will be merged into the JSON document:
 
 ```ruby
-device = Lumberjack::JsonDevice.new(STDOUT, mapping: {
-  time: lambda { |val| {timestamp: (val.to_f * 1000).round} },
-  severity: "level",
-  message: "message",
-})
+device = Lumberjack::JsonDevice.new(
+  output: STDOUT,
+  mapping: {
+    time: lambda { |val| { timestamp: (val.to_f * 1000).round } },
+    severity: "level",
+    message: "message"
+  }
+)
 ```
 
-```json
-{"timestamp": 1578125375588, "level": "INFO", "message": "test"}
+Example output:
+
+```
+{ "timestamp": 1578125375588, "level": "INFO", "message": "test" }
 ```
 
-### Shortcut Mapping
+#### Shortcut Mapping
 
 Use `true` as a shortcut to map a field to the same name:
 
 ```ruby
-device = Lumberjack::JsonDevice.new(STDOUT, mapping: {
-  time: "timestamp",
-  severity: true,      # Maps to "severity"
-  progname: true,      # Maps to "progname"
-  pid: false,          # Excluded from output
-  message: "message",
-  tags: true          # Maps to "tags"
-})
+device = Lumberjack::JsonDevice.new(
+  output: STDOUT,
+  mapping: {
+    time: "timestamp",
+    severity: true,      # Maps to "severity"
+    progname: true,      # Maps to "progname"
+    pid: false,          # Excluded from output
+    message: "message",
+    attributes: true     # Maps to "attributes"
+  }
+)
 ```
 
-### Tag Extraction and Dot Notation
+#### Tag Extraction and Dot Notation
 
-You can extract specific tags from the log entry and map them to custom locations in the JSON. Tags with dot notation in their names are automatically expanded into nested structures:
+You can extract specific attributes from the log entry and map them to custom locations in the JSON. Tags with dot notation in their names are automatically expanded into nested structures:
 
 ```ruby
-device = Lumberjack::JsonDevice.new(STDOUT, mapping: {
-  "message" => true,
-  "http.status" => true,    # Extracts "http.status" tag
-  "http.method" => true,    # Extracts "http.method" tag
-  "http.path" => true,      # Extracts "http.path" tag
-  "tags" => true
-})
+device = Lumberjack::JsonDevice.new(
+  output: STDOUT,
+  mapping: {
+    message: true,
+    "http.status": true,    # Extracts "http.status" attribute
+    "http.method": true,    # Extracts "http.method" attribute
+    "http.path": true,      # Extracts "http.path" attribute
+    attributes: true
+  }
+)
 ```
 
-```json
-{"message": "test", "http": {"status": 200, "method": "GET", "path": "/resource"}, "tags": {"other": "values"}}
+Example output:
+
+```
+{ "message": "test", "http": { "status": 200, "method": "GET", "path": "/resource" }, "attributes": { "other": "values" } }
 ```
 
-**Important**: All tags are automatically expanded from dot notation into nested hash structures, not just extracted tags. For example, if you have a tag named `"user.profile.name"`, it will automatically become `{"user": {"profile": {"name": "value"}}}` in the tags section.
+**Important**: All attributes are automatically expanded from dot notation into nested hash structures, not just extracted attributes. For example, if you have an attribute named `"user.profile.name"`, it will automatically become `{"user": {"profile": {"name": "value"}}}` in the attributes section.
 
-### Flattening Tags to Root Level
+#### Flattening Tags to Root Level
 
-Use `"*"` as the tags mapping value to copy all remaining tags directly to the root level of the JSON document:
+Use `"*"` as the attributes mapping value to copy all remaining attributes directly to the root level of the JSON document:
 
 ```ruby
-device = Lumberjack::JsonDevice.new(STDOUT, mapping: {
-  "message" => true,
-  "tags" => "*"
-})
+device = Lumberjack::JsonDevice.new(
+  output: STDOUT,
+  mapping: {
+    message: true,
+    attributes: "*"
+  }
+)
 ```
 
-```json
-{"message": "test", "tag1": "value", "tag2": "value"}
+Example output:
+
+```
+{ "message": "test", "attribute1": "value", "attribute2": "value" }
 ```
 
-## Data Formatting
+### Data Formatting
 
 The device includes a `Lumberjack::Formatter` that formats objects before serializing them as JSON. You can add custom formatters for specific classes or supply your own formatter when creating the device.
 
 ```ruby
-device.formatter.add(Exception, Lumberjack::Formatter::InspectFormatter.new)
-device.formatter.add(ActiveRecord::Base, Lumberjack::Formatter::IdFormatter.new)
+device.formatter.add(Exception, :inspect)
+device.formatter.add(ActiveRecord::Base, :id)
+device.formatter.add("User") { |user| user.username }
 ```
 
-### Dynamic Mapping
+#### Dynamic Mapping
 
 You can incrementally add field mappings after creating the device using the `map` method:
 
@@ -168,7 +203,7 @@ You can incrementally add field mappings after creating the device using the `ma
 device.map(duration: "response_time", user_id: ["user", "id"])
 ```
 
-### DateTime Formatting
+#### DateTime Formatting
 
 You can specify the `datetime_format` that will be used to serialize Time and DateTime objects:
 
@@ -176,24 +211,29 @@ You can specify the `datetime_format` that will be used to serialize Time and Da
 device.datetime_format = "%Y-%m-%dT%H:%M:%S.%3N"
 ```
 
-### Post Processing
+The default format is [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) with millisecond precision.
+
+#### Post Processing
 
 You can provide a post processor that will be called on the hash before it is serialized to JSON. This allows you to modify any aspect of the log entry:
 
 ```ruby
 # Filter out sensitive elements using Rails parameter filter
 param_filter = ActiveSupport::ParameterFilter.new(Rails.application.config.filter_parameters)
-device = Lumberjack::JsonDevice.new(STDOUT, post_processor: ->(data) { param_filter.filter(data) }
+device = Lumberjack::JsonDevice.new(
+  output: STDOUT,
+  post_processor: ->(data) { param_filter.filter(data) }
+)
 ```
 
 Note that all hash keys will be strings and the values will be JSON-safe. If the post processor does not return a hash, it will be ignored.
 
-### Pretty Printing
+#### Pretty Printing
 
 For development or debugging, you can format the JSON output with indentation and newlines by setting the `pretty` option to `true`:
 
 ```ruby
-device = Lumberjack::JsonDevice.new(STDOUT, pretty: true)
+device = Lumberjack::JsonDevice.new(output: STDOUT, pretty: true)
 ```
 
 This will format each log entry as multi-line JSON instead of single-line output. You can check if pretty formatting is enabled using the `pretty?` method:
@@ -202,24 +242,26 @@ This will format each log entry as multi-line JSON instead of single-line output
 device.pretty?  # => true or false
 ```
 
-### Empty Messages
+#### Empty Messages
 
 Log entries with empty or nil messages will not be written to the output.
 
-## Configuration Options
+### Configuration Options
 
 The `JsonDevice` constructor accepts the following options:
 
+- **`output`**: The output stream, file path, or Lumberjack device to write to (default: STDOUT)
 - **`mapping`**: Hash defining how log fields should be mapped to JSON (default: maps all standard fields)
 - **`formatter`**: Custom `Lumberjack::Formatter` instance for formatting values before JSON serialization
 - **`datetime_format`**: String format for Time/DateTime objects (default: `"%Y-%m-%dT%H:%M:%S.%6N%z"`)
 - **`post_processor`**: Callable that receives and can modify the final hash before JSON serialization
 - **`pretty`**: Boolean to enable pretty-printed JSON output (default: `false`)
+- **`utc`**: Boolean to force timestamps to UTC before formatting (default: `false`)
 
 ```ruby
 device = Lumberjack::JsonDevice.new(
-  STDOUT,
-  mapping: { time: "timestamp", message: true, tags: "*" },
+  output: STDOUT,
+  mapping: { time: "timestamp", message: true, attributes: "*" },
   datetime_format: "%Y-%m-%d %H:%M:%S",
   pretty: true,
   post_processor: lambda { |data| data.merge(app: "myapp") }

data/VERSION

@@ -1 +1 @@
-2.2.0
+3.0.0

data/lib/lumberjack/json_device.rb

@@ -0,0 +1,382 @@
+# frozen_string_literal: true
+
+require "lumberjack"
+require "json"
+require "time"
+
+# Lumberjack is a simple, powerful, and fast logging library for Ruby that
+# provides a consistent interface for logging across different output streams.
+module Lumberjack
+  # This Lumberjack device logs output to another device as JSON formatted text with one document per line.
+  # This format (JSONL) is ideal for structured logging pipelines and can be easily consumed by log
+  # aggregation services, search engines, and monitoring tools.
+  #
+  # The device supports flexible field mapping to customize the JSON structure, datetime formatting,
+  # post-processing, and pretty printing for development use.
+  #
+  # @example Basic usage
+  #   device = Lumberjack::JsonDevice.new(output: STDOUT)
+  #   logger = Lumberjack::Logger.new(device)
+  #   logger.info("User logged in", user_id: 123)
+  #
+  # @example Custom field mapping
+  #   device = Lumberjack::JsonDevice.new(
+  #     output: STDOUT,
+  #     mapping: {
+  #       time: "timestamp",
+  #       severity: "level",
+  #       message: true,
+  #       attributes: "*"
+  #     }
+  #   )
+  #
+  # The mapping parameter can be used to define the JSON data structure. To define the structure pass in a
+  # hash with key indicating the log entry field and the value indicating the JSON document key.
+  #
+  # The standard entry fields are mapped with the following keys:
+  #
+  # * :time
+  # * :severity
+  # * :progname
+  # * :pid
+  # * :message
+  # * :attributes
+  #
+  # Any additional keys will be pulled from the attributes. If any of the standard keys are missing or have a nil
+  # mapping, the entry field will not be included in the JSON output.
+  #
+  # You can create a nested JSON structure by specifying an array as the JSON key.
+  class JsonDevice < Device
+    VERSION = File.read(File.join(__dir__, "..", "..", "VERSION")).strip.freeze
+
+    # Default mapping for standard log entry fields to JSON keys.
+    DEFAULT_MAPPING = {
+      time: true,
+      severity: true,
+      message: true,
+      progname: true,
+      pid: true,
+      attributes: true
+    }.freeze
+
+    # Default ISO 8601 datetime format with microsecond precision and timezone offset.
+    DEFAULT_TIME_FORMAT = "%Y-%m-%dT%H:%M:%S.%6N%z"
+
+    # Classes that can be serialized directly to JSON without transformation.
+    JSON_NATIVE_CLASSES = [String, NilClass, Numeric, TrueClass, FalseClass].freeze
+    private_constant :JSON_NATIVE_CLASSES
+
+    # Valid options that can be passed to the JsonDevice constructor.
+    JSON_OPTIONS = [:output, :mapping, :formatter, :datetime_format, :post_processor, :pretty, :utc].freeze
+    private_constant :JSON_OPTIONS
+
+    # Register the JsonDevice with the device registry for easier instantiation.
+    DeviceRegistry.add(:json, self)
+
+    # @!attribute [rw] formatter
+    #   @return [Lumberjack::Formatter] The formatter used to format log entry values before JSON serialization.
+    attr_accessor :formatter
+
+    # @!attribute [rw] post_processor
+    #   @return [Proc, nil] A callable object that can modify the log entry hash before JSON serialization.
+    attr_accessor :post_processor
+
+    # @!attribute [w] pretty
+    #   @param value [Boolean] Whether to enable pretty-printed JSON output.
+    attr_writer :pretty
+
+    # @!attribute [r] mapping
+    #   @return [Hash] The current field mapping configuration.
+    attr_reader :mapping
+
+    # Create a new JsonDevice instance.
+    #
+    # @param options [Hash<Symbol, Object>] The options for the JSON device.
+    # @param deprecated_options [Hash<Symbol, Object>] The device options for the JSON device if the output
+    #   stream or device is specified in the first argument. This is deprecated behavior for backward
+    #   compatibility with version 2.x.
+    # @option options [IO, Lumberjack::Device, Symbol, String, Pathname, nil] :output The output stream or
+    #   Lumberjack device to write the JSON formatted log entries to. If this is a string or Pathname,
+    #   then the output will be written to that file path. The values :stdout and :stderr can be used
+    #   to write to STDOUT and STDERR respectively. Defaults to STDOUT.
+    # @option options [Hash] :mapping A hash where the key is the log entry field name and the value indicates how
+    #   to map the field if it exists. If the value is `true`, the field will be mapped to the same name.
+    #   If the value is a String, the field will be mapped to that key name.
+    #   If the value is an Array, it will be mapped to a nested structure that follows the array elements.
+    #   If the value is a callable object, it will be called with the value and is expected to return
+    #   a hash that will be merged into the JSON document.
+    #   If the value is `false` or `nil`, the field will not be included in the JSON output.
+    #   Special value `"*"` for `:attributes` will flatten all remaining attributes to the root level.
+    # @option options [Lumberjack::Formatter] :formatter An optional formatter to use for formatting the log entry data.
+    # @option options [String] :datetime_format An optional datetime format string to use for formatting the log timestamp.
+    #   Defaults to ISO 8601 format with microsecond precision.
+    # @option options [Proc] :post_processor An optional callable object that will be called with the log entry hash
+    #   before it is written to the output stream. This can be used to modify the log entry data
+    #   before it is serialized to JSON. The callable should return a Hash or the result will be ignored.
+    # @option options [Boolean] :pretty If true, the output will be formatted as pretty JSON with indentation and newlines.
+    #   The default is false, which writes each log entry as a single line JSON document.
+    # @option options [Boolean] :utc If true, all times will be converted to UTC before formatting.
+    def initialize(options = {}, deprecated_options = nil)
+      unless options.is_a?(Hash)
+        Lumberjack::Utils.deprecated(:new, "Passing a stream or device as the first argument is no longer supported and will be removed in version 3.1; specify the output stream in the :output key of the options hash.") do
+          options = (deprecated_options || {}).merge(output: options)
+        end
+      end
+
+      @mutex = Mutex.new
+
+      stream_options = options.dup
+      JSON_OPTIONS.each { |key| stream_options.delete(key) }
+      @output = output_stream(options[:output], stream_options)
+
+      self.mapping = options.fetch(:mapping, DEFAULT_MAPPING)
+
+      @force_utc = options.fetch(:utc, false)
+      @formatter = default_formatter
+      self.datetime_format = options.fetch(:datetime_format, DEFAULT_TIME_FORMAT)
+      @formatter.include(options[:formatter]) if options[:formatter]
+
+      @post_processor = options[:post_processor]
+
+      @pretty = !!options[:pretty]
+    end
+
+    # Write a log entry to the output stream as JSON.
+    # Each entry is written as a single line JSON document (JSONL format) unless pretty printing is enabled.
+    # Empty log entries (nil or empty message) are ignored.
+    #
+    # @param entry [Lumberjack::LogEntry] The log entry to write.
+    # @return [void]
+    def write(entry)
+      return if entry.empty?
+
+      data = entry_as_json(entry)
+      json = @pretty ? JSON.pretty_generate(data) : JSON.generate(data)
+      @output.write("#{json}\n")
+    end
+
+    # Get the underlying device from the output stream.
+    #
+    # @return [Object] The underlying device.
+    def dev
+      @output.dev
+    end
+
+    # Flush the output stream.
+    #
+    # @return [void]
+    def flush
+      @output.flush
+    end
+
+    # @!attribute [r] datetime_format
+    #   @return [String] The current datetime format string.
+    attr_reader :datetime_format
+
+    # Set the datetime format for the log timestamp.
+    #
+    # @param format [String] The datetime format string to use for formatting the log timestamp.
+    def datetime_format=(format)
+      @datetime_format = format
+      fmttr = time_formatter(datetime_format: format, force_utc: @force_utc)
+      @formatter.add(Time, fmttr)
+      @formatter.add(DateTime, fmttr)
+    end
+
+    # Return true if the output is written in a multi-line pretty format. The default is to write each
+    # log entry as a single line JSON document.
+    #
+    # @return [Boolean]
+    def pretty?
+      !!@pretty
+    end
+
+    # Set the mapping for how to map an entry to a JSON object.
+    #
+    # @param mapping [Hash] A hash where the key is the log entry field name and the value is the JSON key.
+    #   If the value is `true`, the field will be mapped to the same name
+    #   If the value is an array, it will be mapped to a nested structure.
+    #   If the value is a callable object, it will be called with the value and should return a hash that will be merged into the JSON document.
+    #   If the value is `false`, the field will not be included in the JSON output.
+    # @return [void]
+    def mapping=(mapping)
+      @mutex.synchronize do
+        keys = {}
+        mapping.each do |key, value|
+          if value == true
+            value = key.to_s.split(".")
+            value = value.first if value.size == 1
+          end
+          keys[key.to_sym] = value if value
+        end
+
+        @time_key = keys.delete(:time)
+        @severity_key = keys.delete(:severity)
+        @message_key = keys.delete(:message)
+        @progname_key = keys.delete(:progname)
+        @pid_key = keys.delete(:pid)
+        @attributes_key = keys.delete(:attributes)
+        @custom_keys = keys.map do |name, key|
+          [name.to_s.split("."), key]
+        end.to_h
+
+        @mapping = mapping
+      end
+    end
+
+    # Add a field mapping to the existing mappings.
+    #
+    # @param field_mapping [Hash] A hash where the key is the log entry field name and the value is the JSON key.
+    #   If the value is `true`, the field will be mapped to the same name
+    #   If the value is an array, it will be mapped to a nested structure.
+    #   If the value is a callable object, it will be called with the value and should return a hash that will be merged into the JSON document.
+    #   If the value is `false`, the field will not be included in the JSON output.
+    # @return [void]
+    def map(field_mapping)
+      new_mapping = field_mapping.transform_keys(&:to_sym)
+      self.mapping = mapping.merge(new_mapping)
+    end
+
+    # Convert a Lumberjack::LogEntry to a Hash using the specified field mapping.
+    #
+    # @param entry [Lumberjack::LogEntry] The log entry to convert.
+    # @return [Hash] A hash representing the log entry in JSON format.
+    def entry_as_json(entry)
+      data = {}
+      set_attribute(data, @time_key, entry.time) if @time_key
+      set_attribute(data, @severity_key, entry.severity_label) if @severity_key
+      set_attribute(data, @message_key, json_safe(entry.message)) if @message_key
+      set_attribute(data, @progname_key, json_safe(entry.progname)) if @progname_key && entry.progname
+      set_attribute(data, @pid_key, entry.pid) if @pid_key
+
+      attributes = entry.attributes.transform_values { |value| json_safe(value) } if entry.attributes
+
+      if @custom_keys.size > 0 && attributes && !attributes&.empty?
+        @custom_keys.each do |name, key|
+          name = name.is_a?(Array) ? name.join(".") : name.to_s
+          value = attributes.delete(name)
+          next if value.nil?
+
+          value = Lumberjack::Utils.expand_attributes(value) if value.is_a?(Hash)
+          set_attribute(data, key, value)
+        end
+      end
+
+      if @attributes_key && !attributes&.empty?
+        attributes = Lumberjack::Utils.expand_attributes(attributes)
+        if @attributes_key == "*"
+          attributes.each { |k, v| data[k] = v unless data.include?(k) }
+        else
+          set_attribute(data, @attributes_key, attributes)
+        end
+      end
+
+      data = @formatter.format(data) if @formatter
+      if @post_processor
+        processed_result = @post_processor.call(data)
+        data = processed_result if processed_result.is_a?(Hash)
+      end
+
+      data
+    end
+
+    private
+
+    def output_stream(output, options)
+      output ||= $stdout
+
+      if output.is_a?(Lumberjack::Device)
+        output
+      elsif output.is_a?(String) || (defined?(Pathname) && output.is_a?(Pathname))
+        options = options.slice(:binmode, :autoflush, :shift_age, :shift_size, :shift_period_suffix)
+        Lumberjack::Device::LogFile.new(output, options)
+      else
+        if output == :stdout
+          output = $stdout
+        elsif output == :stderr
+          output = $stderr
+        end
+        options = options.slice(:binmode, :autoflush)
+        Lumberjack::Device::Writer.new(output, options)
+      end
+    end
+
+    def default_formatter
+      Lumberjack::Formatter.build do |formatter|
+        formatter.add(::Enumerable, Lumberjack::Formatter::StructuredFormatter.new(formatter))
+        formatter.add(::Object) { |value| json_safe(value) }
+      end
+    end
+
+    def time_formatter(datetime_format: nil, force_utc: false)
+      lambda do |time|
+        time = time.utc if force_utc && !time.utc?
+        datetime_format ? time.strftime(datetime_format) : time
+      end
+    end
+
+    def set_attribute(data, key, value)
+      return if value.nil?
+
+      key = key.split(".") if key.is_a?(String) && key.include?(".")
+
+      if key.is_a?(Array)
+        unless key.empty?
+          if key.size == 1
+            data[key.first] = value
+          else
+            data[key.first] ||= {}
+            set_attribute(data[key.first], key[1, key.size], value)
+          end
+        end
+      elsif key.respond_to?(:call)
+        hash = key.call(value)
+        if hash.is_a?(Hash)
+          deep_merge!(data, hash)
+        end
+      else
+        data[key.to_s] = value unless key.nil?
+      end
+    end
+
+    def deep_merge!(hash, other_hash, &block)
+      other_hash = other_hash.transform_keys(&:to_s)
+      hash.merge!(other_hash) do |key, this_val, other_val|
+        if this_val.is_a?(Hash) && other_val.is_a?(Hash)
+          deep_merge!(this_val, other_val, &block)
+        elsif block
+          block.call(key, this_val, other_val)
+        else
+          other_val
+        end
+      end
+    end
+
+    def json_safe(value, seen = nil)
+      return value if JSON_NATIVE_CLASSES.include?(value.class)
+      return nil if seen&.include?(value.object_id)
+
+      # Check if the as_json method is defined and takes no parameters
+      as_json_arity = value.method(:as_json).arity if !value.nil? && value.respond_to?(:as_json)
+
+      if as_json_arity == 0 || as_json_arity == -1
+        value.as_json
+      elsif !value.is_a?(Enumerable)
+        value
+      else
+        seen ||= Set.new
+        seen << value.object_id
+        if value.is_a?(Hash)
+          value.transform_values { |v| json_safe(v, seen) }
+        else
+          value.collect { |v| json_safe(v, seen) }
+        end
+      end
+    rescue SystemStackError, StandardError => e
+      error_message = e.class.name
+      error_message = "#{error_message} #{e.message}" if e.message && e.message != ""
+      warn("<Error serializing #{value.class} to JSON: #{error_message}>")
+      "<Error serializing #{value.class} to JSON: #{error_message}>"
+    end
+  end
+end

data/lib/lumberjack_json_device.rb

@@ -1,283 +1,3 @@
 # frozen_string_literal: true
 
-require "lumberjack"
-require "json"
-require "time"
-
-module Lumberjack
-  # This Lumberjack device logs output to another device as JSON formatted text with one document per line.
-  #
-  # The mapping parameter can be used to define the JSON data structure. To define the structure pass in a
-  # hash with key indicating the log entry field and the value indicating the JSON document key.
-  #
-  # The standard entry fields are mapped with the following keys:
-  #
-  # * :time
-  # * :severity
-  # * :progname
-  # * :pid
-  # * :message
-  # * :tags
-  #
-  # Any additional keys will be pulled from the tags. If any of the standard keys are missing or have a nil
-  # mapping, the entry field will not be included in the JSON output.
-  #
-  # You can create a nested JSON structure by specifying an array as the JSON key.
-  class JsonDevice < Device
-    DEFAULT_MAPPING = {
-      time: true,
-      severity: true,
-      progname: true,
-      pid: true,
-      message: true,
-      tags: true
-    }.freeze
-
-    DEFAULT_TIME_FORMAT = "%Y-%m-%dT%H:%M:%S.%6N%z"
-
-    attr_accessor :formatter
-    attr_accessor :post_processor
-    attr_writer :pretty
-    attr_reader :mapping
-
-    # @param stream_or_device [IO, Lumberjack::Device] The output stream or Lumberjack device to write
-    #  the JSON formatted log entries to.
-    # @param mapping [Hash] A hash where the key is the log entry field name and the value indicates how
-    #   to map the field if it exists. If the value is `true`, the field will be mapped to the same name.
-    #   If the value is an array, it will be mapped to a nested structure that follows the array elements.
-    #   If the value is a callable object, it will be called with the value and is expected to return
-    #   a hash that will be merged into the JSON document.
-    #   If the value is `false`, the field will not be included in the JSON output.
-    # @param formatter [Lumberjack::Formatter] An optional formatter to use for formatting the log entry data.
-    # @param datetime_format [String] An optional datetime format string to use for formatting the log timestamp.
-    # @param post_processor [Proc] An optional callable object that will be called with the log entry hash
-    #   before it is written to the output stream. This can be used to modify the log entry data
-    #   before it is serialized to JSON.
-    # @param pretty [Boolean] If true, the output will be formatted as pretty JSON with indentation and newlines.
-    #   The default is false, which writes each log entry as a single line JSON document.
-    def initialize(stream_or_device, mapping: DEFAULT_MAPPING, formatter: nil, datetime_format: nil, post_processor: nil, pretty: false)
-      @mutex = Mutex.new
-
-      @device = if stream_or_device.is_a?(Device)
-        stream_or_device
-      else
-        Lumberjack::Device::Writer.new(stream_or_device)
-      end
-
-      self.mapping = mapping
-
-      if formatter
-        @formatter = formatter
-      else
-        @formatter = default_formatter
-        datetime_format = DEFAULT_TIME_FORMAT if datetime_format.nil?
-      end
-      add_datetime_formatter!(datetime_format) unless datetime_format.nil?
-
-      @post_processor = post_processor
-
-      @pretty = !!pretty
-    end
-
-    def write(entry)
-      return if entry.empty?
-
-      data = entry_as_json(entry)
-      json = @pretty ? JSON.pretty_generate(data) : JSON.generate(data)
-      @device.write(json)
-    end
-
-    def flush
-      @device.flush
-    end
-
-    attr_reader :datetime_format
-
-    # Set the datetime format for the log timestamp.
-    #
-    # @param format [String] The datetime format string to use for formatting the log timestamp.
-    def datetime_format=(format)
-      add_datetime_formatter!(format)
-    end
-
-    # Return true if the output is written in a multi-line pretty format. The default is to write each
-    # log entry as a single line JSON document.
-    #
-    # @return [Boolean]
-    def pretty?
-      !!@pretty
-    end
-
-    # Set the mapping for how to map an entry to a JSON object.
-    #
-    # @param mapping [Hash] A hash where the key is the log entry field name and the value is the JSON key.
-    #   If the value is `true`, the field will be mapped to the same name
-    #   If the value is an array, it will be mapped to a nested structure.
-    #   If the value is a callable object, it will be called with the value and should return a hash that will be merged into the JSON document.
-    #   If the value is `false`, the field will not be included in the JSON output.
-    # @return [void]
-    def mapping=(mapping)
-      @mutex.synchronize do
-        keys = {}
-        mapping.each do |key, value|
-          if value == true
-            value = key.to_s.split(".")
-            value = value.first if value.size == 1
-          end
-          keys[key.to_sym] = value if value
-        end
-
-        @time_key = keys.delete(:time)
-        @severity_key = keys.delete(:severity)
-        @progname_key = keys.delete(:progname)
-        @pid_key = keys.delete(:pid)
-        @message_key = keys.delete(:message)
-        @tags_key = keys.delete(:tags)
-        @custom_keys = keys.map do |name, key|
-          [name.to_s.split("."), key]
-        end.to_h
-        @mapping = mapping
-      end
-    end
-
-    # Add a field mapping to the existing mappings.
-    #
-    # @param field_mapping [Hash] A hash where the key is the log entry field name and the value is the JSON key.
-    #   If the value is `true`, the field will be mapped to the same name
-    #   If the value is an array, it will be mapped to a nested structure.
-    #   If the value is a callable object, it will be called with the value and should return a hash that will be merged into the JSON document.
-    #   If the value is `false`, the field will not be included in the JSON output.
-    # @return [void]
-    def map(field_mapping)
-      new_mapping = field_mapping.transform_keys(&:to_sym)
-      self.mapping = mapping.merge(new_mapping)
-    end
-
-    # Convert a Lumberjack::LogEntry to a Hash using the specified field mapping.
-    #
-    # @param entry [Lumberjack::LogEntry] The log entry to convert.
-    # @return [Hash] A hash representing the log entry in JSON format.
-    def entry_as_json(entry)
-      data = {}
-      set_attribute(data, @time_key, entry.time) if @time_key
-      set_attribute(data, @severity_key, entry.severity_label) if @severity_key
-      set_attribute(data, @message_key, json_safe(entry.message)) if @message_key
-      set_attribute(data, @progname_key, json_safe(entry.progname)) if @progname_key && entry.progname
-      set_attribute(data, @pid_key, entry.pid) if @pid_key
-
-      tags = entry.tags.transform_values { |value| json_safe(value) } if entry.tags
-
-      extracted_tags = nil
-      if @custom_keys.size > 0 && !tags&.empty?
-        extracted_tags = []
-        @custom_keys.each do |name, key|
-          name = name.is_a?(Array) ? name.join(".") : name.to_s
-          value = tags.delete(name)
-          next if value.nil?
-
-          value = Lumberjack::Utils.expand_tags(value) if value.is_a?(Hash)
-          set_attribute(data, key, value)
-          extracted_tags << name
-        end
-      end
-
-      if @tags_key && !tags&.empty?
-        tags = Lumberjack::Utils.expand_tags(tags)
-        if @tags_key == "*"
-          tags.each { |k, v| data[k] = v unless data.include?(k) }
-        else
-          set_attribute(data, @tags_key, tags)
-        end
-      end
-
-      data = @formatter.format(data) if @formatter
-      if @post_processor
-        processed_result = @post_processor.call(data)
-        data = processed_result if processed_result.is_a?(Hash)
-      end
-
-      data
-    end
-
-    private
-
-    def set_attribute(data, key, value)
-      return if value.nil?
-
-      if (value.is_a?(Time) || value.is_a?(DateTime)) && @time_formatter
-        value = @time_formatter.call(value)
-      end
-
-      key = key.split(".") if key.is_a?(String) && key.include?(".")
-
-      if key.is_a?(Array)
-        unless key.empty?
-          if key.size == 1
-            data[key.first] = value
-          else
-            data[key.first] ||= {}
-            set_attribute(data[key.first], key[1, key.size], value)
-          end
-        end
-      elsif key.respond_to?(:call)
-        hash = key.call(value)
-        if hash.is_a?(Hash)
-          deep_merge!(data, Lumberjack::Tags.stringify_keys(hash))
-        end
-      else
-        data[key.to_s] = value unless key.nil?
-      end
-    end
-
-    def default_formatter
-      formatter = Formatter.new.clear
-      object_formatter = Lumberjack::Formatter::ObjectFormatter.new
-      formatter.add(String, object_formatter)
-      formatter.add(Object, object_formatter)
-      formatter.add(Enumerable, Formatter::StructuredFormatter.new(formatter))
-      formatter
-    end
-
-    def add_datetime_formatter!(datetime_format)
-      if datetime_format
-        @datetime_format = datetime_format
-        time_formatter = Lumberjack::Formatter::DateTimeFormatter.new(datetime_format)
-        formatter.add(Time, time_formatter)
-        formatter.add(Date, time_formatter)
-      else
-        @datetime_format = nil
-        formatter.remove(Time)
-        formatter.remove(Date)
-      end
-    end
-
-    def deep_merge!(hash, other_hash, &block)
-      hash.merge!(other_hash) do |key, this_val, other_val|
-        if this_val.is_a?(Hash) && other_val.is_a?(Hash)
-          deep_merge!(this_val, other_val, &block)
-        elsif block
-          block.call(key, this_val, other_val)
-        else
-          other_val
-        end
-      end
-    end
-
-    def json_safe(value)
-      return nil if value.nil?
-
-      # Check if the as_json method is defined takes no parameters
-      as_json_arity = value.method(:as_json).arity if value.respond_to?(:as_json)
-
-      if as_json_arity == 0 || as_json_arity == -1
-        value.as_json
-      elsif value.is_a?(Hash)
-        value.transform_values { |v| json_safe(v) }
-      elsif value.is_a?(Enumerable)
-        value.collect { |v| json_safe(v) }
-      else
-        value
-      end
-    end
-  end
-end
+require_relative "lumberjack/json_device"

data/lumberjack_json_device.gemspec

@@ -8,6 +8,12 @@ Gem::Specification.new do |spec|
   spec.homepage = "https://github.com/bdurand/lumberjack_json_device"
   spec.license = "MIT"
 
+  spec.metadata = {
+    "homepage_uri" => spec.homepage,
+    "source_code_uri" => spec.homepage,
+    "changelog_uri" => "#{spec.homepage}/blob/main/CHANGE_LOG.md"
+  }
+
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   ignore_files = %w[
@@ -26,7 +32,7 @@ Gem::Specification.new do |spec|
 
   spec.require_paths = ["lib"]
 
-  spec.required_ruby_version = ">= 2.5"
+  spec.required_ruby_version = ">= 2.7"
 
-  spec.add_dependency "lumberjack", ">=1.4"
+  spec.add_dependency "lumberjack", ">=2.0"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: lumberjack_json_device
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Brian Durand
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-08-22 00:00:00.000000000 Z
+date: 2025-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lumberjack
@@ -16,15 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.4'
-description:
+        version: '2.0'
 email:
 - bbdurand@gmail.com
 executables: []
@@ -38,13 +36,16 @@ files:
 - MIT_LICENSE.txt
 - README.md
 - VERSION
+- lib/lumberjack/json_device.rb
 - lib/lumberjack_json_device.rb
 - lumberjack_json_device.gemspec
 homepage: https://github.com/bdurand/lumberjack_json_device
 licenses:
 - MIT
-metadata: {}
-post_install_message:
+metadata:
+  homepage_uri: https://github.com/bdurand/lumberjack_json_device
+  source_code_uri: https://github.com/bdurand/lumberjack_json_device
+  changelog_uri: https://github.com/bdurand/lumberjack_json_device/blob/main/CHANGE_LOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -52,15 +53,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: A logging device for the lumberjack gem that writes log entries as JSON documents
   for use with structured logging.