Lumberjack DataDog

This gem provides a logging setup for using the lumberjack gem with DataDog. It sets up JSON logging and maps values to DataDog's standard attributes.

Features

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
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

Usage

Basic Setup

require 'lumberjack_data_dog'

# Create a logger that outputs to STDOUT
logger = Lumberjack::DataDog.setup

# Log messages
logger.info("Application started")
logger.warn("This is a warning", user_id: 123)
logger.error("Something went wrong", request_id: "abc-123")

Advanced Configuration

# 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"
  )

  # 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

  # Enable pretty JSON for development
  config.pretty = true
end

Logging to a File

# 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")
end

Exception Logging

Exceptions are automatically structured with DataDog's error attributes:

begin
  raise StandardError, "Something went wrong"
rescue => e
  # Results in structured error with error.kind, error.message, and error.stack fields
  logger.error(e)
end

Duration Logging

Duration values are automatically converted to nanoseconds:

# Log execution time
start_time = Time.now
# ... do some work ...
duration = Time.now - start_time

logger.info("Operation completed", duration: duration)
# duration is automatically converted to nanoseconds

# 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

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:

gem "lumberjack_data_dog"

And then execute:

$ bundle install

Or install it yourself as:

$ gem install lumberjack_data_dog

Contributing

Open a pull request on GitHub.

Please use the standardrb syntax and lint your code with standardrb --fix before submitting.

License

The gem is available as open source under the terms of the MIT License.