lumberjack_data_dog 1.0.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1033352bd0532183f9ca57cc3ce6c6543755dbb76cae5efa1259573e42c95ae4
-  data.tar.gz: cd54d5db4c1d8599e2980331e7c6f8e9885872747d409ca8b833504ef1152536
+  metadata.gz: 1ea1beb91821ea1831d491e84701eb98ebc172a8f5cf863a7eb06dead64db440
+  data.tar.gz: f5e2eaffefff58790484d5c44ea83decda71b3be3facde69862a51765736066d
 SHA512:
-  metadata.gz: e654fe142fbf46f7565a9007049fcc897ba43d741f9759c725c3862398b2e32e2636f2ea6dfc37de04f6507f93b379353cef3fe3563df3b7a5d9d872479a2376
-  data.tar.gz: ec7d80339a8cadefa306e7074ed1e8eaf9261fcb39a08f37355268706d2ae500c46c2bff57afdd560d6416d7f28683bce779db439b68250bd765c46f1bc6c90f
+  metadata.gz: 5632752f398949fba2646745caa31818eff0beb46c1015feecdb5074fadbeee6effa1fb1f7654d5b6dd7a1c82f156a592230029c5963b9c27bf9a20663b1ed3c
+  data.tar.gz: 8966d4801e557934aed6967f84893f13142b54074b02c9dc4adf8a505ff30a73715cbc9cb3a37390b22f938c699fc23618f3ac75f69757404916e8271b96dd98

data/.github/workflows/continuous_integration.yml

@@ -3,10 +3,8 @@ name: Continuous Integration
 on:
   push:
     branches:
-      - master
+      - main
       - actions-*
-    tags:
-      - v*
   pull_request:
     branches-ignore:
       - actions-*
@@ -29,9 +27,8 @@ jobs:
             standardrb: true
           - ruby: "3.0"
           - ruby: "2.7"
-          - ruby: "2.5"
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:

data/.standard.yml

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

data/CHANGE_LOG.md

@@ -4,6 +4,32 @@ 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).
 
+## 2.0.0
+
+### Added
+
+- Added `Lumberjack::DataDog::Device` as a wrapper for `Lumberjack::JsonDevice` with mapping to Datadog standard attributes.
+- Added `Lumberjack::DataDog::EntryFormatter` to encapsulate entry formatting logic for exceptions and duration. With Lumberjack 2 this can now be merged with other formatters.
+- Added `Lumberjack::DataDog::ExceptionAttributeFormatter` to handle exception attribute extraction and formatting. This formatter can now also handle adding additional attributes from other kinds of exceptions.
+
+### Changed
+
+- **Breaking Change** Tags are now called attributes in Lumberjack 2 so some of the method names for setting up attributes have changed.
+  - `Lumberjack::DataDog::Config#allow_all_tags` is now `allow_all_attributes`.
+  - `Lumberjack::DataDog::Config#tag_mapping` is now `attribute_mapping`.
+  - `Lumberjack::DataDog#remap_tags` is now `remap_attributes`.
+- Truncated messages are now suffixed with an ellipsis ("…") character.
+
+## 1.1.0
+
+### Added
+
+- Support for Lumberjack 2.0.
+
+### Removed
+
+- Support for Ruby < 2.7
+
 ## 1.0.1
 
 ### Added

data/README.md

@@ -1,136 +1,147 @@
-# Lumberjack DataDog
+# Lumberjack Datadog
 
-[![Continuous Integration](https://github.com/bdurand/lumberjack_data_dog/actions/workflows/continuous_integration.yml/badge.svg)](https://github.com/bdurand/lumberjack_data_dog/actions/workflows/continuous_integration.yml)
+[![Continuous Integration](https://github.com/bdurand/lumberjack_datadog/actions/workflows/continuous_integration.yml/badge.svg)](https://github.com/bdurand/lumberjack_datadog/actions/workflows/continuous_integration.yml)
 [![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
-[![Gem Version](https://badge.fury.io/rb/lumberjack_data_dog.svg)](https://badge.fury.io/rb/lumberjack_data_dog)
+[![Gem Version](https://badge.fury.io/rb/lumberjack_datadog.svg)](https://badge.fury.io/rb/lumberjack_datadog)
 
-This gem provides a logging setup for using the [lumberjack](https://github.com/bdurand/lumberjack) gem with DataDog. It sets up JSON logging and maps values to DataDog's [standard attributes](https://docs.datadoghq.com/logs/processing/attributes_naming_convention/).
+This gem provides a logging setup for using the [lumberjack](https://github.com/bdurand/lumberjack) gem with Datadog. It sets up JSON logging and maps values to Datadog's [standard attributes](https://docs.datadoghq.com/logs/processing/attributes_naming_convention/).
 
 ## Features
 
-- **DataDog Standard Attribute Mapping**: Automatically maps Lumberjack log fields to DataDog's standard attributes:
+- **Datadog Standard Attribute Mapping**: Automatically maps Lumberjack log fields to Datadog's standard attributes:
   - `time` → `timestamp`
   - `severity` → `status`
   - `progname` → `logger.name`
   - `pid` → `pid`
 - **Exception Handling**: Structured exception logging with `kind`, `message`, and `stack` fields
-- **Duration Logging**: Automatic conversion of duration values to nanoseconds for DataDog
+- **Duration Logging**: Automatic conversion of duration values to nanoseconds for Datadog
 - **Configurable Message Truncation**: Limit message length to prevent oversized logs
-- **Thread Information**: Optional thread name logging
-- **Tag Remapping**: Flexible tag transformation and remapping
-- **Pretty JSON**: Optional pretty-printed JSON output for development
+- **Attribute Remapping**: Flexible attribute transformation and remapping
 
 ## Usage
 
 ### Basic Setup
 
 ```ruby
-require 'lumberjack_data_dog'
-
 # Create a logger that outputs to STDOUT
-logger = Lumberjack::DataDog.setup
+logger = Lumberjack::Logger.new(:datadog)
 
-# Log messages
-logger.info("Application started")
-logger.warn("This is a warning", user_id: 123)
-logger.error("Something went wrong", request_id: "abc-123")
+# Create a logger that outputs to a file
+logger = Lumberjack::Logger.new(:datadog, output: "/var/log/app.log")
 ```
 
 ### Advanced Configuration
 
+You can pass options to the logger during initialization to further customize how entries are formatted:
+
 ```ruby
-# The output device and logger options can be passed in the setup method.
-# These are passed through to Lumberjack::Logger.new.
-logger = Lumberjack::DataDog.setup(log_device, level: :info) do |config|
-  # Truncate messages longer than 1000 characters
-  config.max_message_length = 1000
-
-  # Include thread information
-  config.thread_name = true  # or :global for global thread ID
-
-  # Disable PID logging
-  config.pid = false
-
-  # Remap custom tags to DataDog attributes
-  config.remap_tags(
-    user_id: "usr.id",
-    request_id: "http.request_id"
-  )
+logger = Lumberjack::Logger.new(:datadog,
+  output: "/var/log/app.log",
+  max_message_length: 1000,         # Truncate messages longer than 1000 characters
+  allow_all_attributes: false,      # Only include explicitly mapped attributes
+  attribute_mapping: {              # Custom attribute mapping
+    request_id: "trace_id",         # Map request_id to trace_id
+    user_id: "usr.id"               # Map user_id to nested usr.id
+  }
+)
+```
 
-  # Add a backtrace cleaner to remove unnecessary noise when logging exceptions.
-  # The cleaner object must respond to `clean` method.
-  config.backtrace_cleaner = Rails.backtrace_cleaner
+#### Configuration Options
 
-  # Enable pretty JSON for development
-  config.pretty = true
-end
-```
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `max_message_length` | Integer or nil | `nil` | Maximum length for log messages. Messages longer than this will be truncated with an ellipsis. |
+| `allow_all_attributes` | Boolean | `true` | Whether to include all log entry attributes at the root level of the JSON output. When false, only explicitly mapped attributes are included. |
+| `attribute_mapping` | Hash | `{}` | Custom mapping of attribute names. Keys are original names (symbols), values can be strings, arrays (for nested attributes), or procs for custom formatting. |
+| `pid` | Boolean or Symbol | `true` | Process ID handling: `true` (include current PID), `false` (exclude PID), or `:global` (globally unique PID with hostname). |
+| `backtrace_cleaner` | Object or nil | `nil` | Optional backtrace cleaner that responds to `#clean` method for cleaning exception stack traces. |
+
+> [!TIP]
+> You can also pass `pretty: true` in development mode to have more human readable logs if you aren't sending them to Datadog.
 
-### Logging to a File
+#### Configuration Block
+
+Alternatively, you can use the `setup` method with a configuration block for complex setups. Note that this approach is maintained for compatibility, but the direct constructor approach shown above is generally preferred for new code.
 
 ```ruby
-# Log to a file instead of STDOUT
-File.open("/var/log/app.log", "a") do |file|
-  logger = Lumberjack::DataDog.setup(file)
-  logger.info("Logged to file")
+logger = Lumberjack::DataDog.setup($stdout, level: :info) do |config|
+  # Message truncation
+  config.max_message_length = 500
+
+  # Process ID options
+  config.pid = true           # Include current process ID (default)
+  config.pid = false          # Don't include process ID
+  config.pid = :global        # Use a globally unique process ID (includes hostname)
+
+  # Attribute handling
+  config.allow_all_attributes = true  # Include all log attributes at root level (default)
+  config.allow_all_attributes = false # Only include explicitly mapped attributes
+
+  # Custom attribute mapping and formatting
+  config.remap_attributes(
+    request_id: "trace_id",  # Simple remapping
+    user_id: "usr.id"        # Nested attribute mapping
+  )
+
+  # Pretty print JSON (useful for development)
+  config.pretty = true
+
+  # Custom backtrace cleaner for exceptions
+  config.backtrace_cleaner = MyCustomBacktraceCleaner.new
 end
 ```
 
+### Entry Formatter
+
+The Datadog device automatically includes the entry formatter to add helpers for logging exceptions and durations. You don't need to specify it explicitly.
+
 ### Exception Logging
 
-Exceptions are automatically structured with DataDog's error attributes:
+Exceptions are automatically structured with Datadog's standard error attributes.
 
 ```ruby
 begin
-  raise StandardError, "Something went wrong"
+  do_something
 rescue => e
-  # Results in structured error with error.kind, error.message, and error.stack fields
+  # Results in logging `e.inspect` as the log message along with @error.kind, @error.message, and @error.stack
   logger.error(e)
+
+  # You can also log a different message and put the error in the attributes. The standard attributes
+  # will still be parsed out of the error object.
+  logger.error("Something went wrong", error: e)
 end
 ```
 
+You can pass in a custom backtrace cleaner for exceptions. This can be any object that responds to the `clean` method that takes an array of strings and returns an array of strings. If you are in a Rails environment, you can pass in `Rails.backtrace_cleaner`.
+
+```ruby
+logger = Lumberjack::Logger.new(:datadog, backtrace_cleaner: Rails.backtrace_cleaner)
+```
+
 ### Duration Logging
 
-Duration values are automatically converted to nanoseconds:
+Duration values are automatically converted to nanoseconds in the Datadog standard `duration` attribute from the `duration` attribute. This keeps the Ruby code clean since Ruby measures time in seconds. There are helpers for logging durations in milliseconds, microseconds, and nanoseconds.
 
 ```ruby
-# Log execution time
-start_time = Time.now
-# ... do some work ...
-duration = Time.now - start_time
+duration = Benchmark.realtime do
+  do_something
+end
 
+# duration is automatically converted to nanoseconds in the logs.
 logger.info("Operation completed", duration: duration)
-# duration is automatically converted to nanoseconds
 
-# You can also use specific duration units
+# You can also use specific duration units.
 logger.info("DB query", duration_ms: 150.5)      # milliseconds
 logger.info("API call", duration_micros: 1500)   # microseconds
 logger.info("Function", duration_ns: 1500000)    # nanoseconds
 ```
 
-### Custom Tag Transformation
-
-```ruby
-logger = Lumberjack::DataDog.setup do |config|
-  config.remap_tags(
-    # Simple remapping
-    correlation_id: "trace.correlation_id",
-
-    # Transform with a lambda
-    user_email: ->(email) { {"usr.email" => email.downcase} }
-  )
-end
-
-logger.info("User logged in", user_email: "USER@EXAMPLE.COM")
-# Results in usr.email: "user@example.com"
-```
-
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem "lumberjack_data_dog"
+gem "lumberjack_datadog"
 ```
 
 And then execute:
@@ -140,7 +151,7 @@ $ bundle install
 
 Or install it yourself as:
 ```bash
-$ gem install lumberjack_data_dog
+$ gem install lumberjack_datadog
 ```
 
 ## Contributing

data/VERSION

@@ -1 +1 @@
-1.0.1
+2.0.0

data/lib/lumberjack/data_dog/config.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+##
+# Configuration for Datadog logging
+# @!parse
+#   class Lumberjack::DataDog::Config; end
+module Lumberjack::DataDog
+  # Configuration options for Datadog logger setup.
+  #
+  # This class provides a configuration object for customizing the behavior
+  # of Datadog loggers when using the {Lumberjack::DataDog.setup} method.
+  #
+  # @!attribute [rw] max_message_length
+  #   @return [Integer, nil] Maximum length for log messages. Messages longer than this
+  #     will be truncated with an ellipsis. Default is nil (no truncation).
+  # @!attribute [rw] backtrace_cleaner
+  #   @return [Object, nil] Optional backtrace cleaner that responds to #clean method.
+  #     Used for cleaning exception stack traces. Default is nil.
+  # @!attribute [rw] pid
+  #   @return [Boolean, Symbol] Process ID inclusion option. Can be true (include current PID),
+  #     false (exclude PID), or :global (use globally unique PID). Default is true.
+  # @!attribute [rw] allow_all_attributes
+  #   @return [Boolean] Whether to include all log entry attributes at the root level
+  #     of the JSON output. Default is true.
+  # @!attribute [r] attribute_mapping
+  #   @return [Hash] Custom mapping of attribute names. Use {#remap_attributes} to modify.
+  # @!attribute [rw] pretty
+  #   @return [Boolean] Whether to pretty-print JSON output. Useful for development.
+  #     Default is false.
+  class Config
+    attr_accessor :max_message_length
+    attr_accessor :backtrace_cleaner
+    attr_accessor :pid
+    attr_accessor :allow_all_attributes
+    attr_reader :attribute_mapping
+    attr_accessor :pretty
+
+    def initialize
+      @max_message_length = nil
+      @backtrace_cleaner = nil
+      @thread_name = false
+      @pid = true
+      @allow_all_attributes = true
+      @attribute_mapping = {}
+      @pretty = false
+    end
+
+    # Add the thread name to the `logger.thread_name` attribute. This setting is deprecated.
+    # Call logger.tag!("logger.thread_name" => -> { Lumberjack::Utils.global_thread_id }) instead.
+    #
+    # @param value [Boolean, Symbol] Thread name option. Pass :global to use the global thread ID.
+    # @return [void]
+    # @deprecated
+    def thread_name=(value)
+      message = "Setting @logger.thread_name through the logger setup is deprecated and will be removed in version 2.1.; call logger.tag!(\"logger.thread_name\" => -> { Lumberjack::Utils.global_thread_id }) instead."
+      Lumberjack::Utils.deprecated(:thread_name=, message) do
+        @thread_name = value
+      end
+    end
+
+    # @deprecated
+    attr_reader :thread_name
+
+    # Remap log attributes by merging additional attribute mappings.
+    #
+    # @param attribute_mapping [Hash] Additional attribute mappings to merge.
+    #   Keys are the original attribute names (symbols), values are the target
+    #   field names (strings, arrays for nested fields, or procs for custom formatting).
+    # @return [Hash] The updated attribute mapping hash
+    # @example Simple attribute remapping
+    #   config.remap_attributes(request_id: "trace_id", user_id: "usr.id")
+    def remap_attributes(attribute_mapping)
+      @attribute_mapping = @attribute_mapping.merge(attribute_mapping)
+    end
+
+    # Validate configuration options to ensure they are properly set.
+    #
+    # Checks that:
+    # - max_message_length is nil or a positive integer
+    # - backtrace_cleaner is nil or responds to #clean method
+    #
+    # @raise [ArgumentError] if max_message_length is not nil or a positive integer
+    # @raise [ArgumentError] if backtrace_cleaner doesn't respond to #clean
+    # @return [void]
+    def validate!
+      if !max_message_length.nil? && (!max_message_length.is_a?(Integer) || max_message_length <= 0)
+        raise ArgumentError, "max_message_length must be a positive integer"
+      end
+
+      unless backtrace_cleaner.nil? || backtrace_cleaner.respond_to?(:clean)
+        raise ArgumentError, "backtrace_cleaner must respond to #clean"
+      end
+    end
+  end
+end

data/lib/lumberjack/data_dog/device.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+##
+# Datadog device for Lumberjack logging
+# @!parse
+#   class Lumberjack::DataDog::Device < Lumberjack::JsonDevice; end
+module Lumberjack::DataDog
+  # Device for sending logs to Datadog with automatic attribute mapping and formatting.
+  #
+  # This device extends Lumberjack::JsonDevice to provide Datadog-specific functionality
+  # including standard attribute mapping, exception formatting, and duration conversion.
+  # It automatically registers itself as the :datadog device type.
+  #
+  # @example Basic usage
+  #   logger = Lumberjack::Logger.new(:datadog, output: $stdout)
+  #
+  # @example With custom options
+  #   logger = Lumberjack::Logger.new(:datadog,
+  #     output: "/var/log/app.log",
+  #     max_message_length: 1000,
+  #     allow_all_attributes: false
+  #   )
+  class Device < Lumberjack::JsonDevice
+    Lumberjack::DeviceRegistry.add(:datadog, self)
+
+    # Initialize the Datadog device with Datadog-specific formatting.
+    #
+    # @param options [Hash] Device options including Datadog-specific configuration
+    # @option options [Boolean, Symbol] :pid Include process ID in logs
+    # @option options [Hash] :attribute_mapping Custom attribute name mapping
+    # @option options [Boolean] :allow_all_attributes Include all log entry attributes
+    # @option options [Integer, nil] :max_message_length Maximum message length
+    # @option options [Object, nil] :backtrace_cleaner Backtrace cleaner for exceptions
+    def initialize(options = {})
+      datadog_options = options.dup
+
+      mapping_options = {}
+      mapping_options[:pid] = datadog_options.delete(:pid)
+      mapping_options[:attribute_mapping] = datadog_options.delete(:attribute_mapping)
+      mapping_options[:allow_all_attributes] = datadog_options.delete(:allow_all_attributes)
+      mapping_options[:max_message_length] = datadog_options.delete(:max_message_length)
+      datadog_options[:mapping] ||= Lumberjack::DataDog.json_mapping(**mapping_options.compact)
+
+      backtrace_cleaner = datadog_options.delete(:backtrace_cleaner)
+      @entry_formatter = Lumberjack::DataDog.entry_formatter(backtrace_cleaner: backtrace_cleaner)
+
+      super(datadog_options)
+    end
+
+    # Write a log entry with Datadog-specific formatting applied.
+    #
+    # This method applies the configured entry formatter to transform
+    # the log entry's message and attributes before passing it to the
+    # parent JSON device for output.
+    #
+    # @param entry [Lumberjack::LogEntry] The log entry to write
+    # @return [void]
+    def write(entry)
+      message, attributes = @entry_formatter.format(entry.message, entry.attributes)
+      entry.message = message
+      entry.attributes = attributes
+      super
+    end
+  end
+end

data/lib/lumberjack/data_dog/exception_attribute_formatter.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+##
+# Datadog integration for exception attribute formatting
+# @!parse
+#   module Lumberjack::DataDog; end
+module Lumberjack::DataDog
+  # Formats exception attributes for Datadog logs.
+  #
+  # This formatter converts Exception objects into structured attributes
+  # that follow Datadog's error tracking conventions.
+  class ExceptionAttributeFormatter
+    # Initialize the exception attribute formatter.
+    #
+    # @param backtrace_cleaner [Object, nil] Optional backtrace cleaner that responds to #clean
+    # @param additional_attributes [Hash] Additional attributes to extract from exception
+    def initialize(backtrace_cleaner: nil, additional_attributes: {})
+      @backtrace_cleaner = backtrace_cleaner
+      @additional_attributes = additional_attributes
+    end
+
+    # Format exception attributes for logging.
+    #
+    # Converts an Exception object into a hash of attributes suitable for Datadog
+    # error tracking, including the exception class name, message, and stack trace.
+    #
+    # @param error [Exception] The exception to format
+    # @return [Hash] Formatted exception attributes with the following keys:
+    #   - 'kind': Exception class name
+    #   - 'message': Exception message
+    #   - 'stack': Array of stack trace strings (if backtrace available)
+    #   - Additional keys from @additional_attributes if specified
+    def call(error)
+      error_attributes = {"kind" => error.class.name, "message" => error.message}
+
+      backtrace = error.backtrace
+      if backtrace
+        backtrace = @backtrace_cleaner.clean(backtrace) if @backtrace_cleaner
+        error_attributes["stack"] = backtrace
+      end
+
+      @additional_attributes.each do |key, method|
+        next unless error.respond_to?(method)
+
+        error_attributes[key.to_s] = error.public_send(method)
+      end
+
+      error_attributes
+    end
+  end
+end

data/lib/lumberjack/data_dog.rb

@@ -2,7 +2,40 @@
 
 require "lumberjack_json_device"
 
+# Datadog integration for Lumberjack logging.
+#
+# This module provides JSON logging functionality specifically designed for Datadog,
+# automatically mapping standard log attributes to Datadog's naming conventions
+# and providing structured exception and duration logging.
+#
+# @example Basic usage
+#   logger = Lumberjack::Logger.new(:datadog)
+#   logger.info("Application started")
+#
+# @example Advanced configuration
+#   logger = Lumberjack::Logger.new(:datadog,
+#     max_message_length: 1000,
+#     allow_all_attributes: false,
+#     attribute_mapping: { request_id: "trace_id" }
+#   )
+#
+# @see Device
+# @see Config
 module Lumberjack::DataDog
+  # Version of the lumberjack_datadog gem
+  # @return [String] The current version string
+  VERSION = ::File.read(::File.join(__dir__, "..", "..", "VERSION")).strip.freeze
+
+  # Standard mapping of log attributes to Datadog fields.
+  #
+  # This constant defines the default attribute mapping used to transform
+  # Lumberjack log entries into Datadog-compatible format.
+  #
+  # @return [Hash] Mapping hash with the following transformations:
+  #   - :time → "timestamp"
+  #   - :severity → "status"
+  #   - :progname → ["logger", "name"] (nested attribute)
+  #   - :pid → "pid"
   STANDARD_ATTRIBUTE_MAPPING = {
     time: "timestamp",
     severity: "status",
@@ -10,135 +43,147 @@ module Lumberjack::DataDog
     pid: "pid"
   }.freeze
 
-  class Config
-    attr_accessor :max_message_length
-    attr_accessor :backtrace_cleaner
-    attr_accessor :thread_name
-    attr_accessor :pid
-    attr_accessor :allow_all_tags
-    attr_reader :tag_mapping
-    attr_accessor :pretty
-
-    def initialize
-      @max_message_length = nil
-      @backtrace_cleaner = nil
-      @thread_name = false
-      @pid = true
-      @allow_all_tags = true
-      @tag_mapping = {}
-      @pretty = false
-    end
+  class << self
+    # Returns a mapping of log attributes to JSON fields for Datadog.
+    #
+    # This method creates the attribute mapping configuration used by the JSON device
+    # to transform log entries into Datadog-compatible format.
+    #
+    # @param pid [Boolean, Symbol] Include process ID in logs. Options:
+    #   - true: Include current process ID (default)
+    #   - false: Exclude process ID
+    #   - :global: Use globally unique process ID
+    # @param attribute_mapping [Hash] Custom attribute name mapping. Keys are original
+    #   attribute names (symbols), values can be strings, arrays (for nested attributes),
+    #   or procs for custom formatting.
+    # @param allow_all_attributes [Boolean] Whether to include all log entry attributes
+    #   at the root level of JSON output. Default is true.
+    # @param max_message_length [Integer, nil] Maximum message length. Messages longer
+    #   than this will be truncated. Default is nil (no truncation).
+    # @return [Hash] Complete mapping configuration for the JSON device
+    def json_mapping(pid: true, attribute_mapping: {}, allow_all_attributes: true, max_message_length: nil)
+      mapping = STANDARD_ATTRIBUTE_MAPPING.dup
+
+      if pid == :global
+        mapping[:pid] = ->(pid) { {"pid" => Lumberjack::Utils.global_pid(pid)} }
+      else
+        mapping.delete(:pid) unless pid
+      end
 
-    def remap_tags(tag_mapping)
-      @tag_mapping = @tag_mapping.merge(tag_mapping)
-    end
+      mapping.merge!(attribute_mapping.transform_keys(&:to_sym))
 
-    def validate!
-      if !max_message_length.nil? && (!max_message_length.is_a?(Integer) || max_message_length <= 0)
-        raise ArgumentError, "max_message_length must be a positive integer"
-      end
+      mapping[:attributes] = "*" if allow_all_attributes
 
-      unless backtrace_cleaner.nil? || backtrace_cleaner.respond_to?(:clean)
-        raise ArgumentError, "backtrace_cleaner must respond to #clean"
+      mapping[:message] = if max_message_length
+        truncate_message_transformer(max_message_length)
+      else
+        true
       end
-    end
-  end
-
-  class << self
-    def setup(stream = $stdout, options = {}, &block)
-      config = Config.new
-      yield(config) if block_given?
-      config.validate!
 
-      new_logger(stream, options, config)
+      mapping.transform_keys!(&:to_s)
     end
 
-    private
+    def entry_formatter(backtrace_cleaner: nil)
+      Lumberjack::EntryFormatter.build do |formatter|
+        formatter.format_class(Exception) do |error|
+          Lumberjack::MessageAttributes.new(error.inspect, error: error)
+        end
 
-    def new_logger(stream, options, config)
-      logger = Lumberjack::Logger.new(json_device(stream, config), options)
+        formatter.format_attributes(Exception, Lumberjack::DataDog::ExceptionAttributeFormatter.new(backtrace_cleaner: backtrace_cleaner))
 
-      # Add the error to the error tag if an exception is logged as the message.
-      logger.message_formatter.add(Exception, message_exception_formatter)
+        formatter.format_attribute_name(:duration) do |seconds|
+          (seconds.to_f * 1_000_000_000).round
+        end
 
-      # Split the error tag up into standard attributes if it is an exception.
-      logger.tag_formatter.add(Exception, exception_tag_formatter(config))
+        formatter.format_attribute_name(:duration_ms) do |millis|
+          nanoseconds = (millis.to_f * 1_000_000).round
+          Lumberjack::RemapAttribute.new("duration" => nanoseconds)
+        end
 
-      if config.thread_name
-        if config.thread_name == :global
-          logger.tag_globally("logger.thread_name" => -> { Lumberjack::Utils.global_thread_id })
-        else
-          logger.tag_globally("logger.thread_name" => -> { Lumberjack::Utils.thread_name })
+        formatter.format_attribute_name(:duration_micros) do |micros|
+          nanoseconds = (micros.to_f * 1_000).round
+          Lumberjack::RemapAttribute.new("duration" => nanoseconds)
         end
-      end
 
-      if config.pid == :global
-        logger.tag_globally("pid" => -> { Lumberjack::Utils.global_pid })
+        formatter.format_attribute_name(:duration_ns) do |ns|
+          Lumberjack::RemapAttribute.new("duration" => ns.to_i)
+        end
       end
-
-      logger
     end
 
-    def json_device(stream, config)
-      Lumberjack::JsonDevice.new(stream, mapping: json_mapping(config), pretty: config.pretty)
-    end
-
-    def json_mapping(config)
-      mapping = config.tag_mapping.transform_keys(&:to_sym)
-      mapping = mapping.merge(STANDARD_ATTRIBUTE_MAPPING)
-
-      mapping.delete(:pid) if !config.pid || config.pid == :global
-
-      mapping[:tags] = "*" if config.allow_all_tags
-
-      mapping[:message] = if config.max_message_length
-        truncate_message_transformer(config.max_message_length)
-      else
-        "message"
-      end
-
-      mapping[:duration] = duration_nanosecond_transformer(1_000_000_000)
-      mapping[:duration_ms] = duration_nanosecond_transformer(1_000_000)
-      mapping[:duration_micros] = duration_nanosecond_transformer(1_000)
-      mapping[:duration_ns] = duration_nanosecond_transformer(1)
+    # Convenience method for setting up a Datadog logger with a block configuration.
+    #
+    # This method provides a block-based configuration approach that was more useful
+    # in earlier versions of Lumberjack. With Lumberjack 2+, you can achieve the same
+    # results more directly using {Lumberjack::Logger.new} with the :datadog device.
+    #
+    # @param stream [IO, String, Pathname] Output stream or path for log output.
+    #   Default is $stdout.
+    # @param options [Hash] Additional logger options passed to Lumberjack::Logger.new
+    # @yield [Lumberjack::DataDog::Config] Block for configuring the logger behavior
+    # @return [Lumberjack::Logger] Configured logger instance
+    #
+    # @example Block configuration
+    #   logger = Lumberjack::DataDog.setup($stdout, level: :info) do |config|
+    #     config.max_message_length = 500
+    #     config.pretty = true
+    #   end
+    #
+    # @see Config
+    # @see Device
+    def setup(stream = $stdout, options = {}, &block)
+      config = Config.new
+      yield(config) if block_given?
+      config.validate!
 
-      mapping.transform_keys!(&:to_s)
+      new_logger(stream, options, config)
     end
 
+    private
+
+    # Creates a transformer lambda that truncates messages to a maximum length.
+    #
+    # @param max_length [Integer] Maximum message length
+    # @return [Proc] Message truncation transformer
     def truncate_message_transformer(max_length)
       lambda do |msg|
         msg = msg.inspect unless msg.is_a?(String)
-        msg = msg[0, max_length] if msg.is_a?(String) && msg.length > max_length
+        msg = "#{msg[0, max_length - 1]}…" if msg.length > max_length
         {"message" => msg}
       end
     end
 
-    def duration_nanosecond_transformer(multiplier)
-      lambda do |duration|
-        if duration.is_a?(Numeric)
-          {"duration" => (duration * multiplier).round}
-        else
-          {"duration" => nil}
-        end
-      end
-    end
+    # Creates a new logger instance with the provided configuration.
+    #
+    # @param stream [IO, String, Pathname] Output stream or path
+    # @param options [Hash] Logger options to pass to Lumberjack::Logger.new
+    # @param config [Lumberjack::DataDog::Config] Configuration object with settings
+    # @return [Lumberjack::Logger] Configured logger instance
+    def new_logger(stream, options, config)
+      mapping = json_mapping(
+        pid: config.pid,
+        attribute_mapping: config.attribute_mapping,
+        allow_all_attributes: config.allow_all_attributes,
+        max_message_length: config.max_message_length
+      )
 
-    def message_exception_formatter
-      lambda do |error|
-        Lumberjack::Formatter::TaggedMessage.new(error.inspect, error: error)
-      end
-    end
+      options = options.merge(output: stream, mapping: mapping, pretty: config.pretty)
+      logger = Lumberjack::Logger.new(:datadog, **options)
 
-    def exception_tag_formatter(config)
-      lambda do |error|
-        error_tags = {"kind" => error.class.name, "message" => error.message}
-        trace = error.backtrace
-        if trace
-          trace = config.backtrace_cleaner.clean(trace) if config.backtrace_cleaner
-          error_tags["stack"] = trace
+      # Deprecated behavior
+      if config.thread_name
+        if config.thread_name == :global
+          logger.tag!("logger.thread_name" => -> { Lumberjack::Utils.global_thread_id })
+        else
+          logger.tag!("logger.thread_name" => -> { Lumberjack::Utils.thread_name })
         end
-        error_tags
       end
+
+      logger
     end
   end
 end
+
+require_relative "data_dog/config"
+require_relative "data_dog/device"
+require_relative "data_dog/exception_attribute_formatter"

data/lumberjack_data_dog.gemspec

@@ -8,6 +8,12 @@ Gem::Specification.new do |spec|
   spec.homepage = "https://github.com/bdurand/lumberjack_data_dog"
   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_json_device", ">= 2.0.0"
+  spec.add_dependency "lumberjack_json_device", ">= 3.0.0"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: lumberjack_data_dog
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 2.0.0
 platform: ruby
 authors:
 - Brian Durand
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-07-19 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lumberjack_json_device
@@ -16,15 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.0
+        version: 3.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.0
-description:
+        version: 3.0.0
 email:
 - bbdurand@gmail.com
 executables: []
@@ -39,13 +37,18 @@ files:
 - README.md
 - VERSION
 - lib/lumberjack/data_dog.rb
+- lib/lumberjack/data_dog/config.rb
+- lib/lumberjack/data_dog/device.rb
+- lib/lumberjack/data_dog/exception_attribute_formatter.rb
 - lib/lumberjack_data_dog.rb
 - lumberjack_data_dog.gemspec
 homepage: https://github.com/bdurand/lumberjack_data_dog
 licenses:
 - MIT
-metadata: {}
-post_install_message:
+metadata:
+  homepage_uri: https://github.com/bdurand/lumberjack_data_dog
+  source_code_uri: https://github.com/bdurand/lumberjack_data_dog
+  changelog_uri: https://github.com/bdurand/lumberjack_data_dog/blob/main/CHANGE_LOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -53,15 +56,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.9
 specification_version: 4
 summary: Lumberjack logging device that outputs JSON formatted for DataDog with standard
   attribute mapping.