Dry Logger

https://hanakai.org/learn/dry/dry-logger/v1.2
Admin
Dry Logger is a standalone, dependency-free logging solution for Ruby applications that provides...
Tokens:15,551
Snippets:210
Trust Score:5.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Development setup with colorized output

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/examples

Configures a logger with a custom colorized template for maximum readability during development.

```ruby
require "dry/logger"

# Register a custom colorized template
Dry::Logger.register_template(
  :dev,
  "<gray>%<time>s</gray> <cyan>[%<progname>s]</cyan> " \
  "<yellow>%<severity>s</yellow> %<message>s <blue>%<payload>s</blue>"
)

logger = Dry.Logger(:my_app,
  template: :dev,
  level: :debug
)

logger.info("Server ready", port: 3000, env: "development")
# (colorized output) 2023-10-15 14:40:00 [my_app] INFO Server ready port=3000 env="development"
```

--------------------------------

### Hybrid logging setup with multiple backends

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/examples

Demonstrates configuring multiple backends for a single logger instance, including colorized console output for development, detailed file logs, JSON logs for analysis, and a dedicated error log file.

```ruby
require "dry/logger"

logger = Dry.Logger(:my_app) do |setup|
  # Colorized console for development
  setup.add_backend(
    stream: $stdout,
    formatter: :string,
    template: "<yellow>%<severity>s</yellow> %<message>s <blue>%<payload>s</blue>",
    log_if: -> (entry) { ENV["RACK_ENV"] == "development" }
  )

  # Detailed file logs
  setup.add_backend(
    stream: "logs/app.log",
    formatter: :string,
    template: :details
  )

  # JSON for analysis tools
  setup.add_backend(
    stream: "logs/app.json",
    formatter: :json
  )

  # Separate error file
  setup.add_backend(
    stream: "logs/errors.log",
    formatter: :string,
    template: :details,
    log_if: :error?
  )
end

logger.info("Application started", version: "1.2.3")
# Console: INFO Application started version="1.2.3" (colorized, development only)
# File: [my_app] [INFO] [2023-10-15 14:55:00 +0000] Application started version="1.2.3"
# JSON: {"progname":"my_app","severity":"INFO",...}
```

--------------------------------

### Colorized template example

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/templates

Example of applying multiple colors to different log fields such as progname and severity.

```ruby
logger = Dry.Logger(:my_app,
  template: "[<cyan>%<progname>s</cyan>] [<yellow>%<severity>s</yellow>] %<message>s"
)

logger.warn("Memory warning", usage: "85%")
# [my_app] [WARN] Memory warning usage="85%"
# (with colored progname and severity)
```

--------------------------------

### Configure dry-logger for multiple environments

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/examples

Uses a setup_logger method to return different logger configurations based on the provided environment string. Includes specific backend setups for production and a StringIO stream for testing to suppress output.

```ruby
require "dry/logger"

def setup_logger(env)
  case env
  when "development"
    Dry.Logger(:my_app,
      template: :dev,
      colorize: true,
      level: :debug
    )
  when "production"
    Dry.Logger(:my_app) do |setup|
      setup.add_backend(
        stream: "logs/production.json",
        formatter: :json,
        filters: production_filters
      )
      setup.add_backend(
        stream: "logs/errors.json",
        formatter: :json,
        filters: production_filters,
        log_if: :error?
      )
    end
  when "test"
    require "stringio"
    Dry.Logger(:my_app,
      stream: StringIO.new,
      level: :warn  # Suppress noise in tests
    )
  end
end

def production_filters
  [:password, :api_key, :secret_token, :ssn, :credit_card_number]
end

logger = setup_logger(ENV.fetch("RACK_ENV", "development"))
```

--------------------------------

### Production setup with JSON logging and filters

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/examples

Configures structured JSON logging with separate error files and sensitive data filtering.

```ruby
require "dry/logger"

PRODUCTION_FILTERS = [
  :password,
  :api_key,
  :secret_token,
  :access_token,
  :ssn,
  :credit_card_number
].freeze

logger = Dry.Logger(:my_app) do |setup|
  # Main JSON log file
  setup.add_backend(
    stream: "logs/production.json",
    formatter: :json,
    filters: PRODUCTION_FILTERS
  )

  # Separate error file
  setup.add_backend(
    stream: "logs/errors.json",
    formatter: :json,
    filters: PRODUCTION_FILTERS,
    log_if: :error?
  )
end

logger.info("Request processed",
  user_id: 123,
  action: "update_profile",
  duration_ms: 45,
  password: "secret"  # Filtered
)
# {"progname":"my_app","severity":"INFO","time":"2023-10-15T14:42:30Z","message":"Request processed","user_id":123,"action":"update_profile","duration_ms":45,"password":"[FILTERED]"}
```

--------------------------------

### Routing logs with multiple conditions

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/backends

Example of routing different types of logs to separate files using multiple backend configurations within a block.

```ruby
logger = Dry.Logger(:my_app) do |setup|
  # All logs in detailed format
  setup.add_backend(
    stream: "logs/all.log",
    template: :details
  )

  # Only errors in JSON format for monitoring tools
  setup.add_backend(
    stream: "logs/errors.json",
    formatter: :json,
    log_if: -> (entry) { entry.error? || entry.fatal? }
  )

  # Only HTTP requests
  setup.add_backend(
    stream: "logs/requests.log",
    formatter: :rack,
    log_if: -> (entry) { entry.key?(:verb) && entry.key?(:path) }
  )

  # Performance logs
  setup.add_backend(
    stream: "logs/performance.log",
    log_if: -> (entry) { entry.key?(:elapsed) }
  )
end
```

--------------------------------

### Per-backend templates configuration

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/templates

Configure different templates for specific backends, such as console output versus file logging, within a single logger setup.

```ruby
logger = Dry.Logger(:my_app) do |setup|
  # Colorized, detailed output for console
  setup.add_backend(
    stream: $stdout,
    template: "<cyan>[%<progname>s]</cyan> <yellow>%<severity>s</yellow> %<message>s %<payload>s"
  )

  # Plain detailed output for file
  setup.add_backend(
    stream: "logs/app.log",
    template: :details
  )

  # Minimal output for errors file
  setup.add_backend(
    stream: "logs/errors.log",
    template: "%<time>s %<message>s %<payload>s",
    log_if: :error?
  )
end
```

--------------------------------

### Best practices for request-scoped data

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/context

Example of correctly using context for data that is relevant to all logs within a single request.

```ruby
# Good - data relevant to all logs in this request
logger.context[:request_id] = request.id
logger.context[:user_id] = current_user.id
logger.context[:tenant_id] = current_tenant.id
```

--------------------------------

### Install dry-logger

Source: https://hanakai.org/learn/dry/dry-logger/v1.2

Add the gem to your Gemfile to include dry-logger in your Ruby project.

```ruby
gem "dry-logger"
```

--------------------------------

### PCI-compliant logging with filters

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/examples

Configures a logger with specific filters to redact sensitive payment and PII data. The example demonstrates how card numbers and CVV codes are automatically replaced with [FILTERED] in the JSON output.

```ruby
require "dry/logger"

# PCI compliance filters
PAYMENT_FILTERS = [
  # Card data (PCI DSS requirement)
  :card_number,
  :cvv,
  :cvc,
  :expiry,
  :card_holder,
  "payment.card_number",
  "payment.cvv",

  # Billing data
  :billing_address,
  :account_number,
  :routing_number,

  # Customer PII
  :ssn,
  :tax_id,
  :email,
  :phone
].freeze

logger = Dry.Logger(:payment_processor,
  stream: "logs/payments.log",
  formatter: :json,
  filters: PAYMENT_FILTERS
)

logger.info("Payment processed",
  transaction_id: "txn_123",
  amount: 99.99,
  card_number: "4111111111111111",  # Will be filtered
  cvv: "123",                        # Will be filtered
  status: "success"
)
# {"transaction_id":"txn_123","amount":99.99,"card_number":"[FILTERED]","cvv":"[FILTERED]","status":"success"}
```

--------------------------------

### Configure backend options

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/backends

Demonstrates the available configuration options for a backend, including output destination, formatter, template, log level, conditional logging, and rotation settings.

```ruby
logger.add_backend(
  stream: "logs/app.log",      # Output destination
  formatter: :json,             # Formatter to use (:string, :json, :rack)
  template: :details,           # Template for string formatter
  level: :warn,                 # Minimum level for this backend
  log_if: :error?,             # Conditional logging
  shift_age: 5,                # Log rotation: number of old files
  shift_size: 1048576,         # Log rotation: max file size
  colorize: true,              # Enable colorized output
  severity_colors: {           # Custom severity colors
    error: :red,
    warn: :yellow
  }
)
```

--------------------------------

### Initialize logger with StringIO

Source: https://hanakai.org/learn/dry/dry-logger/v1.2

Use StringIO for testing purposes to capture log output in a string buffer.

```ruby
require "stringio"

output = StringIO.new
logger = Dry.Logger(:my_app, stream: output)

logger.info("Test message")

puts output.string
# Test message
```

--------------------------------

### Initialize and use the :string formatter

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/formatters

The default :string formatter outputs logs in a human-readable key=value format.

```ruby
logger = Dry.Logger(:my_app, formatter: :string)

logger.info("User logged in", user_id: 42, role: "admin")
# User logged in user_id=42 role="admin"
```

--------------------------------

### Initialize and use the :rack formatter

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/formatters

The :rack formatter is specialized for logging HTTP request data in a compact format.

```ruby
logger = Dry.Logger(:my_app, formatter: :rack)

logger.info(
  verb: "GET",
  path: "/users/42",
  status: 200,
  elapsed: "12ms",
  ip: "192.168.1.1",
  length: 1024,
  params: {page: 1}
)
# [my_app] [INFO] [2023-10-15 14:25:30 +0000] GET 200 12ms 192.168.1.1 /users/42 1024
#   {"page":1}
```

--------------------------------

### Configure per-backend formatters

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/formatters

Demonstrates adding multiple backends to a logger, each using a different formatter (string, JSON, or rack) and specific configuration.

```ruby
logger = Dry.Logger(:my_app) do |setup|
  # Human-readable logs to stdout for development
  setup.add_backend(
    stream: $stdout,
    formatter: :string,
    template: :details
  )

  # JSON logs to file for production analysis
  setup.add_backend(
    stream: "logs/app.json",
    formatter: :json
  )

  # Rack-formatted HTTP logs
  setup.add_backend(
    stream: "logs/requests.log",
    formatter: :rack,
    log_if: -> (entry) { entry.key?(:verb) }
  )
end

# Now this logs to all three backends in different formats
logger.info("Starting server", port: 3000)
```

--------------------------------

### Basic context usage

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/context

Demonstrates how to set context data on a logger instance, which is then automatically included in all subsequent log entries.

```ruby
logger = Dry.Logger(:my_app)

# Set context data
logger.context[:request_id] = "req-123"
logger.context[:user_id] = 42

# All subsequent logs include context automatically
logger.info("User action", action: "login")
# User action request_id="req-123" user_id=42 action="login"

logger.info("Profile updated")
# Profile updated request_id="req-123" user_id=42
```

--------------------------------

### Configuring backends with a block

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/backends

Configuring backends within a block provides complete control and skips the creation of the default stdout backend.

```ruby
logger = Dry.Logger(:my_app) do |setup|
  setup.add_backend(stream: "logs/application.log", template: :details)
  setup.add_backend(stream: "logs/json.log", formatter: :json)
end

# Only logs to the files you configured (no stdout)
```

--------------------------------

### Custom template using all meta tokens

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/templates

Demonstrates a custom template that incorporates all available meta tokens for a detailed log entry.

```ruby
logger = Dry.Logger(:my_app,
  template: "%<time>s [%<progname>s] %<severity>s: %<message>s %<payload>s"
)

logger.warn("High memory usage", used_mb: 1024, available_mb: 512)
# 2023-10-15 14:32:00 +0000 [my_app] WARN: High memory usage used_mb=1024 available_mb=512
```

--------------------------------

### Best practices for log-specific data

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/context

Demonstrates the difference between using context for persistent data versus passing log-specific data directly to the log method.

```ruby
# Bad - this should be in the log entry itself
logger.context[:action] = "login"
logger.info("User action")  # Wrong approach

# Good - put it in the specific log entry
logger.info("User action", action: "login")
```

--------------------------------

### Initialize logger with file streams

Source: https://hanakai.org/learn/dry/dry-logger/v1.2

Direct logs to a file by providing a relative or absolute path to the stream option.

```ruby
logger = Dry.Logger(:my_app, stream: "logs/application.log")  # Relative path
logger = Dry.Logger(:my_app, stream: "/var/log/app.log")      # Absolute path
```

--------------------------------

### Initialize and use the :json formatter

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/formatters

The :json formatter outputs structured JSON, suitable for production log aggregation tools.

```ruby
logger = Dry.Logger(:my_app, formatter: :json)

logger.info("User logged in", user_id: 42, role: "admin")
# {"progname":"my_app","severity":"INFO","time":"2023-10-15T14:23:45Z","message":"User logged in","user_id":42,"role":"admin"}
```

--------------------------------

### Dry.Logger Initialization

Source: https://hanakai.org/learn/dry/dry-logger/v1.2

Configuring the logger with custom templates and formatters.

```APIDOC
## Dry.Logger(progname, options)

### Description
Initializes a new logger instance with specific formatting and template configurations.

### Parameters
- **progname** (Symbol) - Required - The identifier for the logger.
- **options** (Hash) - Optional - Configuration options including `template` and `formatter`.

### Supported Template Tokens
- `%<progname>s` - Logger identifier
- `%<severity>s` - Log level
- `%<time>s` - Timestamp
- `%<message>s` - Log message
- `%<payload>s` - Structured data

### Supported Formatters
- `:string` - Human-readable key=value format
- `:json` - Structured JSON format
- `:rack` - Optimized for HTTP request logging
```

--------------------------------

### Use Ruby standard library Logger as a backend

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/backends

Shows how to integrate Ruby's built-in Logger as a backend for dry-logger.

```ruby
require "logger"

stdlib_logger = Logger.new("logs/stdlib.log")
stdlib_logger.formatter = proc { |severity, datetime, progname, msg|
  "[#{severity}] #{msg}\n"
}

logger = Dry.Logger(:my_app).add_backend(stdlib_logger)

logger.info("Test message")
# Written to both dry-logger default output and stdlib.log
```

--------------------------------

### Inspecting configured backends

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/backends

Access the backends collection to view or count the currently configured backends for a logger.

```ruby
logger = Dry.Logger(:my_app)
  .add_backend(stream: "logs/app.log")

logger.backends
# => [#<Dry::Logger::Backends::Stream...>, #<Dry::Logger::Backends::File...>]

logger.backends.size
# => 2
```

--------------------------------

### Minimal template configuration

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/templates

A basic template configuration that outputs only the log message.

```ruby
logger = Dry.Logger(:my_app,
  template: "%<message>s"
)

logger.info("Simple message")
# Simple message
```

--------------------------------

### Configuring per-backend filters

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/filtering

Different backends can be configured with unique filter sets, allowing for more aggressive filtering in production environments.

```ruby
logger = Dry.Logger(:my_app) do |setup|
  # Development logs: minimal filtering
  setup.add_backend(
    stream: $stdout,
    filters: [:password, :api_key]
  )

  # Production logs: aggressive filtering
  setup.add_backend(
    stream: "logs/production.log",
    formatter: :json,
    filters: [
      :password, :api_key, :token, :secret,
      :ssn, :email, :phone, :address,
      :credit_card, :card_number, :cvv
    ]
  )
end
```

--------------------------------

### Testing custom formatters

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/testing

Shows how to test custom formatters by instantiating a Dry::Logger::Entry and verifying the output of the formatter's call method.

```ruby
RSpec.describe MyCustomFormatter do
  let(:formatter) { MyCustomFormatter.new }
  let(:entry) do
    Dry::Logger::Entry.new(
      clock: Dry::Logger::Clock.new,
      progname: "test",
      severity: :info,
      message: "Test message",
      payload: {user_id: 42}
    )
  end

  it "formats entries correctly" do
    output = formatter.call(:info, Time.now, "test", entry)
    expect(output).to include("Test message")
    expect(output).to include("user_id=42")
  end
end
```

--------------------------------

### Initialize and use dry-logger

Source: https://hanakai.org/learn/dry/dry-logger/v1.2

Create a logger instance and log messages at different severity levels.

```ruby
require "dry/logger"

logger = Dry.Logger(:my_app)

logger.info("Application started")
# Application started

logger.warn("Low memory warning")
# Low memory warning

logger.error("Failed to connect to database")
# Failed to connect to database
```

--------------------------------

### Adding multiple backends to a logger

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/backends

Demonstrates adding multiple backends to the default logger instance, where one backend logs everything and another is restricted by the log_if option.

```ruby
logger = Dry.Logger(:my_app)
  .add_backend(stream: "logs/application.log")
  .add_backend(stream: "logs/errors.log", log_if: :error?)

logger.info("User logged in")
# Goes to stdout and logs/application.log

logger.error("Database connection failed")
# Goes to stdout, logs/application.log, and logs/errors.log
```

--------------------------------

### Injecting loggers for testing

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/testing

Demonstrates how to make loggers injectable in a service class and how to verify log output in RSpec using a StringIO stream.

```ruby
class UserService
  def initialize(logger: Dry.Logger(:user_service))
    @logger = logger
  end

  def create_user(email:)
    @logger.info("Creating user", email: email)
    # ... create user
    @logger.info("User created", email: email)
  end
end

# In tests
RSpec.describe UserService do
  let(:log_output) { StringIO.new }
  let(:logger) { Dry.Logger(:test, stream: log_output) }
  let(:service) { UserService.new(logger: logger) }

  it "logs user creation" do
    service.create_user(email: "test@example.com")
    expect(log_output.string).to include("User created")
  end
end
```

--------------------------------

### Basic tagging with Dry.Logger

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/tagging

Demonstrates using the tagged method to wrap log entries with a specific tag.

```ruby
logger = Dry.Logger(:my_app,
  template: "[%<tags>s] %<message>s %<payload>s"
)

logger.tagged(:database) do
  logger.info("Connection opened", pool_size: 5)
  logger.info("Query executed", duration_ms: 23)
end
# [database] Connection opened pool_size=5
# [database] Query executed duration_ms=23

logger.info("Outside tagged block")
# [] Outside tagged block
```

--------------------------------

### Dry.Logger Configuration

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/formatters

Configuring backends with specific formatters.

```APIDOC
## Dry.Logger Configuration

### Description
Configures a logger instance with multiple backends, each using a specific formatter (string, json, or rack).

### Parameters
- **stream** (String/IO) - Required - The output destination (e.g., $stdout or a file path).
- **formatter** (Symbol) - Required - The formatter type: `:string`, `:json`, or `:rack`.
- **template** (Symbol) - Optional - The template name for the string formatter.
- **log_if** (Proc) - Optional - A conditional proc to determine if a log entry should be processed.
```

--------------------------------

### Configure API application logging

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/examples

Sets up API-specific logging with custom templates, comprehensive filtering for headers and request/response data, and dual-backend output.

```ruby
require "dry/logger"

# API-specific filters
API_FILTERS = [
  # Auth headers
  :authorization,
  :api_key,
  "headers.authorization",
  "headers.x-api-key",

  # Request data
  :password,
  :secret,
  :token,

  # Response data
  "response.access_token",
  "response.refresh_token"
].freeze

# Custom template for API requests
Dry::Logger.register_template(
  :api,
  "%<time>s | %<verb>s %<path>s | Status: %<status>s | %<elapsed>s"
)

logger = Dry.Logger(:api) do |setup|
  # Console output for development
  setup.add_backend(
    stream: $stdout,
    formatter: :string,
    template: :api,
    filters: API_FILTERS
  )

  # JSON logs for aggregation
  setup.add_backend(
    stream: "logs/api.json",
    formatter: :json,
    filters: API_FILTERS
  )
end

logger.info(
  verb: "POST",
  path: "/api/orders",
  status: 201,
  elapsed: "120ms",
  authorization: "Bearer secret"  # Filtered
)
# Console: 2023-10-15 14:50:00 +0000 | POST /api/orders | Status: 201 | 120ms
# JSON: {"progname":"api",...,"authorization":"[FILTERED]"}
```

--------------------------------

### Create a simple custom formatter

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/formatters

Implements a custom formatter class that must return a string from the call method.

```ruby
class CustomFormatter
  def call(_severity, _time, _progname, entry)
    # Must return a string
    "#{entry.severity} | #{entry.message} | #{entry.payload.inspect}\n"
  end
end

logger = Dry.Logger(:my_app, formatter: CustomFormatter.new)

logger.info("Test", user_id: 42)
# INFO | Test | {:user_id=>42}
```

--------------------------------

### Test multiple log entries

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/testing

Verify multiple log entries by splitting the StringIO output and parsing each line as JSON.

```ruby
RSpec.describe OrderProcessor do
  let(:log_output) { StringIO.new }
  let(:logger) { Dry.Logger(:test, stream: log_output, formatter: :json) }

  it "logs each step of order processing" do
    processor = OrderProcessor.new(logger: logger)
    processor.process(order_id: 123)

    logs = log_output.string.split("\n").map { |line| JSON.parse(line) }

    expect(logs[0]["message"]).to eq("Order received")
    expect(logs[1]["message"]).to eq("Payment processed")
    expect(logs[2]["message"]).to eq("Order completed")
  end
end
```

--------------------------------

### Hash tags for structured tagging

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/tagging

Demonstrates using a hash to provide structured tags for log entries.

```ruby
logger.tagged(component: "auth", version: "v2") do
  logger.info("Authentication attempt")
end
# [component="auth" version="v2"] Authentication attempt
```

--------------------------------

### Configure log formatters

Source: https://hanakai.org/learn/dry/dry-logger/v1.2

Set the formatter option to switch between :string, :json, or :rack formats.

```ruby
logger = Dry.Logger(:test, formatter: :rack)

logger.info verb: "GET", path: "/users", elapsed: "12ms", ip: "127.0.0.1", status: 200, length: 312, params: {}
# [test] [INFO] [2022-11-17 12:04:30 +0100] GET 200 12ms 127.0.0.1 /users 312
```

--------------------------------

### Initialize logger with standard output

Source: https://hanakai.org/learn/dry/dry-logger/v1.2

The default behavior of Dry.Logger is to log to $stdout.

```ruby
logger = Dry.Logger(:my_app)  # Logs to $stdout
```

--------------------------------

### Application-focused template configuration

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/templates

A template that includes the program name in brackets followed by the message and payload.

```ruby
logger = Dry.Logger(:my_app,
  template: "[%<progname>s] %<message>s %<payload>s"
)

logger.info("User action", action: "login", user_id: 42)
# [my_app] User action action="login" user_id=42
```

--------------------------------

### Configure Rack/Rails application logging

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/examples

Configures multiple backends for application logs, HTTP request logs, and error tracking with shared parameter filtering.

```ruby
require "dry/logger"

# Define filters for sensitive data
FILTER_PARAMS = [
  :password,
  :password_confirmation,
  :api_key,
  :secret_token,
  :access_token,
  :ssn,
  :credit_card_number
].freeze

logger = Dry.Logger(:rails_app) do |setup|
  # General application logs (string format)
  setup.add_backend(
    stream: "logs/application.log",
    formatter: :string,
    template: :details,
    filters: FILTER_PARAMS
  )

  # HTTP request logs (rack format)
  setup.add_backend(
    stream: "logs/requests.log",
    formatter: :rack,
    filters: FILTER_PARAMS,
    log_if: -> (entry) { entry.key?(:verb) && entry.key?(:path) }
  )

  # Error tracking in JSON
  setup.add_backend(
    stream: "logs/errors.json",
    formatter: :json,
    filters: FILTER_PARAMS,
    log_if: -> (entry) { entry.error? || entry.fatal? }
  )
end

# Application log
logger.info("User authenticated", user_id: 42)

# HTTP request log
logger.info(
  verb: "POST",
  path: "/api/users",
  status: 201,
  elapsed: "23ms",
  ip: "192.168.1.1",
  length: 512,
  params: {name: "John"}
)

# Error log
begin
  raise "Database timeout"
rescue => e
  logger.error(e)
end

# Use in Rails
Rails.logger = logger
```

--------------------------------

### Custom crash handler

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/crash-handling

Demonstrates how to define a custom on_crash handler to send errors to an external service and write to a local log file.

```ruby
logger = Dry.Logger(:my_app,
  on_crash: -> (progname:, exception:, message:, payload:) {
    # Send to error tracking service
    Sentry.capture_exception(exception,
      extra: {
        progname: progname,
        log_message: message,
        log_payload: payload
      }
    )

    # Also write to a separate crash log
    File.open("logs/logging_crashes.log", "a") do |f|
      f.puts "Logging crashed: #{exception.message}"
      f.puts "Progname: #{progname}"
      f.puts "Message: #{message.inspect}"
      f.puts "Payload: #{payload.inspect}"
    end
  }
)
```

--------------------------------

### Details template usage

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/templates

Uses the :details template for comprehensive logging including progname, severity, time, message, and payload.

```ruby
logger = Dry.Logger(:my_app, template: :details)
# Equivalent to: "[%<progname>s] [%<severity>s] [%<time>s] %<message>s %<payload>s"

logger.info("Server started", port: 3000)
# [my_app] [INFO] [2023-10-15 14:30:00 +0000] Server started port=3000
```

--------------------------------

### Implement time-based log rotation

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/backends

Configures log rotation based on daily, weekly, or monthly time periods.

```ruby
# Rotate daily
logger = Dry.Logger(:my_app,
  stream: "logs/app.log",
  shift_age: "daily"
)

# Rotate weekly
logger = Dry.Logger(:my_app,
  stream: "logs/app.log",
  shift_age: "weekly"
)

# Rotate monthly
logger = Dry.Logger(:my_app,
  stream: "logs/app.log",
  shift_age: "monthly"
)
```

--------------------------------

### Dry.Logger Initialization

Source: https://hanakai.org/learn/dry/dry-logger/v1.2

Initializes a new logger instance with a specified stream, such as standard output, a file path, or a StringIO object.

```APIDOC
## Dry.Logger(name, stream: nil)

### Description
Creates a new logger instance. If no stream is provided, it defaults to $stdout.

### Parameters
- **name** (Symbol) - Required - The name of the logger.
- **stream** (String/IO) - Optional - The destination for logs (path to file or IO object).

### Example
```ruby
# Standard output
logger = Dry.Logger(:my_app)

# File output
logger = Dry.Logger(:my_app, stream: "logs/application.log")

# StringIO for testing
output = StringIO.new
logger = Dry.Logger(:my_app, stream: output)
```
```

--------------------------------

### Implement size-based log rotation

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/backends

Configures log rotation based on file size, keeping a fixed number of files.

```ruby
# Keep 5 log files, 10MB each
logger = Dry.Logger(:my_app,
  stream: "logs/app.log",
  shift_age: 5,
  shift_size: 10_485_760  # 10 megabytes
)
```

--------------------------------

### Timestamp-first template configuration

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/templates

A template that prefixes log entries with a timestamp, severity level, and the message.

```ruby
logger = Dry.Logger(:my_app,
  template: "%<time>s | %<severity>s | %<message>s %<payload>s"
)

logger.error("Connection failed", host: "db.example.com")
# 2023-10-15 14:35:12 +0000 | ERROR | Connection failed host="db.example.com"
```

--------------------------------

### Entry object methods for conditional logging

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/backends

Shows available methods on the entry object when using a proc for conditional logging.

```ruby
log_if: -> (entry) {
  # Check severity
  entry.error? || entry.fatal?

  # Check for specific keys in payload
  entry.key?(:database)

  # Access payload values
  entry[:user_id] == 123

  # Check tags
  entry.tag?(:production)
}
```

--------------------------------

### String Formatter Options

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/formatters

Customizing the string formatter with templates and colorization.

```APIDOC
## String Formatter Options

### Description
Customizes the output of the string formatter using templates and terminal colorization.

### Parameters
- **template** (String) - Optional - A format string using Ruby's format syntax (e.g., "[%<severity>s] %<message>s").
- **colorize** (Boolean) - Optional - Enables terminal colorization.
- **severity_colors** (Hash) - Optional - A map of severity levels to colors (e.g., `{ debug: :gray }`).
```

--------------------------------

### Custom template with sprintf-style placeholders

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/templates

Defines a custom template using named placeholders for severity and message.

```ruby
logger = Dry.Logger(:my_app,
  template: "[%<severity>s] %<message>s"
)

logger.info("Server started")
# [INFO] Server started
```

--------------------------------

### Default template usage

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/templates

Uses the :default template, which displays the message and payload.

```ruby
logger = Dry.Logger(:my_app, template: :default)
# Equivalent to: "%<message>s %<payload>s"

logger.info("Hello", name: "World")
# Hello name="World"
```

--------------------------------

### Payload-based template with partial extraction

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/templates

Demonstrates how keys used in the template are removed from the remaining payload, which is then rendered via %<payload>s.

```ruby
logger = Dry.Logger(:api,
  template: "%<verb>s %<path>s | %<payload>s"
)

logger.info(verb: "POST", path: "/users", status: 201, user_id: 42)
# POST /users | status=201 user_id=42
# (verb and path were used in template, so only status and user_id appear in payload)
```

--------------------------------

### Multiple tags

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/tagging

Shows how to pass multiple symbols as tags to the tagged method.

```ruby
logger.tagged(:api, :production) do
  logger.info("Request processed")
end
# [api production] Request processed
```

--------------------------------

### Customize string formatter with templates

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/formatters

Uses the template option to define a custom format for string logs.

```ruby
logger = Dry.Logger(:my_app,
  formatter: :string,
  template: "[%<severity>s] %<time>s - %<message>s %<payload>s"
)

logger.info("Server started", port: 3000)
# [INFO] 2023-10-15 14:30:00 +0000 - Server started port=3000
```

--------------------------------

### logger.add_backend

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/backends

Adds a new backend to the logger instance with specific configuration options for output, formatting, and rotation.

```APIDOC
## logger.add_backend

### Description
Adds a backend to the logger instance. Supports configuration for output destination, formatting, log levels, and rotation settings.

### Parameters
- **stream** (String) - Optional - Output destination path.
- **formatter** (Symbol) - Optional - Formatter to use (:string, :json, :rack).
- **template** (Symbol) - Optional - Template for string formatter (:details).
- **level** (Symbol) - Optional - Minimum level for this backend.
- **log_if** (Symbol) - Optional - Conditional logging predicate.
- **shift_age** (Integer/String) - Optional - Log rotation: number of old files or time period ('daily', 'weekly', 'monthly').
- **shift_size** (Integer) - Optional - Log rotation: max file size in bytes.
- **colorize** (Boolean) - Optional - Enable colorized output.
- **severity_colors** (Hash) - Optional - Custom severity colors.
```

--------------------------------

### Using payload keys in templates

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/templates

Use specific payload keys in templates instead of the generic %<payload>s to make logs easier to parse.

```ruby
# Instead of this:
template: "%<message>s %<payload>s"

# Use this when you always log certain fields:
template: "%<message>s | User: %<user_id>s | Action: %<action>s"
```

--------------------------------

### Dry.Logger

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/backends

Initializes a new logger instance with specific stream and rotation settings.

```APIDOC
## Dry.Logger

### Description
Initializes a logger instance. Supports file-based backends with size-based or time-based rotation.

### Parameters
- **stream** (String) - Optional - Output destination path.
- **shift_age** (Integer/String) - Optional - Rotation frequency or count.
- **shift_size** (Integer) - Optional - Max file size for rotation.
- **shift_period_suffix** (String) - Optional - Custom timestamp format for rotated files.
```

--------------------------------

### Use block-based logging

Source: https://hanakai.org/learn/dry/dry-logger/v1.2

Use blocks to defer message computation until the log level is confirmed to be active.

```ruby
logger = Dry.Logger(:my_app, level: :info)

# Block is NOT evaluated (debug < info)
logger.debug { expensive_debug_info }

# Block IS evaluated
logger.info { "User count: #{User.count}" }
# User count: 42
```

--------------------------------

### Registering standard templates

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/templates

Register standard templates in config/logger_templates.rb to maintain consistency across team projects.

```ruby
# config/logger_templates.rb
Dry::Logger.register_template(:app_default, :details)
Dry::Logger.register_template(:app_console, "<cyan>[%<severity>s]</cyan> %<message>s")
Dry::Logger.register_template(:app_api, "%<verb>s %<path>s %<status>s %<elapsed>s")
```

--------------------------------

### Add backends to default logger

Source: https://hanakai.org/learn/dry/dry-logger/v1.2

Use add_backend to append additional logging destinations to the default stdout logger.

```ruby
logger = Dry.Logger(:test, template: :details)
  .add_backend(stream: "logs/test.log")

logger.info "Hello World"
# Logs to both $stdout and logs/test.log
# [test] [INFO] [2022-11-17 11:46:12 +0100] Hello World
```

--------------------------------

### Format exceptions with string formatter

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/formatters

Configures the logger to use the string formatter with the details template to output full exception information.

```ruby
logger = Dry.Logger(:my_app, formatter: :string, template: :details)

begin
  File.read("missing.txt")
rescue => e
  logger.error(e)
end

# [my_app] [ERROR] [2023-10-15 14:35:12 +0000]
#   No such file or directory @ rb_sysopen - missing.txt (Errno::ENOENT)
#   /path/to/file.rb:10:in `read'
#   /path/to/file.rb:10:in `<main>'
```

--------------------------------

### Customize log format with sprintf-style templates

Source: https://hanakai.org/learn/dry/dry-logger/v1.2

Use the template option to define a custom log format string. Supported tokens include severity, message, time, progname, and payload.

```ruby
logger = Dry.Logger(:test, template: "[%<severity>s] %<message>s")

logger.info "Hello World"
# [INFO] Hello World
```

--------------------------------

### Payload-based template with specific keys

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/templates

Extracts specific keys from the payload to format them directly in the log template.

```ruby
logger = Dry.Logger(:api,
  template: "[%<severity>s] %<verb>s %<path>s - %<status>s"
)

logger.info(verb: "GET", path: "/users/42", status: 200)
# [INFO] GET /users/42 - 200
```

--------------------------------

### Default crash behavior

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/crash-handling

Shows the default output format when a logging crash occurs.

```ruby
logger = Dry.Logger(:my_app)

# If logging crashes, you'll see something like:
# [my_app] [FATAL] [2023-10-15 14:00:00 +0000] Logging crashed
#   Original message
#   Error details (ExceptionClass)
#   Backtrace...
```

--------------------------------

### Enable colorized string output

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/formatters

Enables colorization for the string formatter to improve terminal readability.

```ruby
logger = Dry.Logger(:my_app,
  formatter: :string,
  colorize: true
)

logger.debug("Debug message")  # Cyan
logger.info("Info message")    # Magenta
logger.warn("Warning")         # Yellow
logger.error("Error")          # Red
logger.fatal("Fatal error")    # Red
```

--------------------------------

### Registering colorized templates

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/templates

Register a template with color tags globally for consistent styling across the application.

```ruby
Dry::Logger.register_template(
  :dev,
  "<cyan>[%<progname>s]</cyan> <yellow>[%<severity>s]</yellow> %<message>s %<payload>s"
)

logger = Dry.Logger(:my_app, template: :dev)
```

--------------------------------

### Configure log levels

Source: https://hanakai.org/learn/dry/dry-logger/v1.2

Set the minimum severity level to filter log output. Levels range from :debug to :unknown.

```ruby
logger = Dry.Logger(:my_app, level: :warn)

logger.debug("Debug message")  # Won't be logged
logger.info("Info message")    # Won't be logged
logger.warn("Warning message") # Will be logged
logger.error("Error message")  # Will be logged
```

--------------------------------

### add_backend

Source: https://hanakai.org/learn/dry/dry-logger/v1.2

Adds an additional logging backend to an existing logger instance.

```APIDOC
## add_backend(stream: nil, template: nil, log_if: nil)

### Description
Adds a new backend to the logger. When using a block for configuration, the default stdout backend is skipped.

### Parameters
- **stream** (String) - Optional - The file path for the backend.
- **template** (Symbol) - Optional - The template format for log entries.
- **log_if** (Symbol/Proc) - Optional - A condition to determine if a log entry should be written to this backend.

### Example
```ruby
logger = Dry.Logger(:test)
  .add_backend(stream: "logs/test.log")
```
```

--------------------------------

### Registering custom templates

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/templates

Register a template globally using Dry::Logger.register_template to reuse it across different logger instances.

```ruby
Dry::Logger.register_template(
  :my_template,
  "[%<severity>s] %<time>s - %<message>s"
)

logger = Dry.Logger(:my_app, template: :my_template)

logger.info("Using custom template")
# [INFO] 2023-10-15 14:40:00 +0000 - Using custom template
```

--------------------------------

### Rack template configuration

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/templates

The rack formatter uses this specialized template for HTTP requests.

```ruby
# Automatically used by formatter: :rack
"[%<progname>s] [%<severity>s] [%<time>s] " \
"%<verb>s %<status>s %<elapsed>s %<ip>s %<path>s %<length>s %<payload>s\n" \
"  %<params>s"
```

--------------------------------

### Request-scoped context in Rack middleware

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/context

Shows how to use thread-local context in a web application to track request-specific metadata, ensuring the context is cleared after the request completes.

```ruby
# In your Rack middleware or Rails controller
class RequestLogger
  def call(env)
    request = Rack::Request.new(env)

    logger.context[:request_id] = request.request_id
    logger.context[:ip] = request.ip
    logger.context[:method] = request.request_method
    logger.context[:path] = request.path

    logger.info("Request started")
    # Request started request_id="..." ip="192.168.1.1" method="GET" path="/users"

    @app.call(env)
  ensure
    # Context automatically clears when thread ends
    logger.context.clear
  end
end
```

--------------------------------

### Closing backends with logger.close

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/backends

Use the close method to flush buffers and release file handles when finished with a logger instance.

```ruby
logger = Dry.Logger(:my_app, stream: "logs/app.log")

logger.info("Final message")

logger.close  # Flushes and closes all backends
```

--------------------------------

### Return structured data from blocks

Source: https://hanakai.org/learn/dry/dry-logger/v1.2

Blocks can return hashes to be logged as structured data.

```ruby
logger.info { {action: "cache_miss", key: "user:123"} }
# action="cache_miss" key="user:123"
```

--------------------------------

### Apply color tags to templates

Source: https://hanakai.org/learn/dry/dry-logger/v1.2

Use color tags like <blue> or <green> within the template string to improve readability in the terminal.

```ruby
logger = Dry.Logger(:test, template: "[%<severity>s] <blue>%<verb>s</blue> <green>%<path>s</green>")

logger.info verb: "GET", path: "/users"
# [INFO] GET /users (with blue verb and green path)
```

--------------------------------

### Test string format log content

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/testing

Perform human-readable assertions on logs formatted as strings with specific templates.

```ruby
RSpec.describe UserService do
  let(:log_output) { StringIO.new }
  let(:logger) do
    Dry.Logger(:test,
      stream: log_output,
      formatter: :string,
      template: :details
    )
  end

  it "logs user creation" do
    service = UserService.new(logger: logger)
    service.create_user(email: "test@example.com")

    expect(log_output.string).to include("User created")
    expect(log_output.string).to include('email="test@example.com"')
  end
end
```

--------------------------------

### Log structured data

Source: https://hanakai.org/learn/dry/dry-logger/v1.2

Attach key-value pairs to log entries for structured output.

```ruby
logger = Dry.Logger(:my_app)

# Log with structured data
logger.info("User logged in", user_id: 42, ip: "192.168.1.1")
# User logged in user_id=42 ip="192.168.1.1"

# Log only structured data (no message)
logger.info(action: "signup", user_id: 123, plan: "premium")
# action="signup" user_id=123 plan="premium"
```

--------------------------------

### Suppress logs using null device

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/testing

Redirect logs to File::NULL in spec_helper.rb to discard all output during tests.

```ruby
# spec/spec_helper.rb
RSpec.configure do |config|
  config.around(:each) do |example|
    # Suppress all logging during tests
    logger = Dry.Logger(:test, stream: File.open(File::NULL, "w"))

    # Make it available to your app
    allow(MyApp).to receive(:logger).and_return(logger)

    example.run
  end
end
```

--------------------------------

### Basic filtering with the filters option

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/filtering

Use the filters option to specify keys that should be redacted from log payloads. Filtered values are replaced with the string "[FILTERED]".

```ruby
logger = Dry.Logger(:my_app,
  filters: [:password, :api_key, :ssn]
)

logger.info("User signup",
  email: "user@example.com",
  password: "secret123",
  api_key: "sk_live_1234567890"
)
# email="user@example.com" password="[FILTERED]" api_key="[FILTERED]"
```

--------------------------------

### Tagged logging template

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/templates

Include the %<tags>s token in your template when using tagged logging.

```ruby
logger = Dry.Logger(:my_app,
  template: "[%<tags>s] %<message>s %<payload>s"
)

logger.tagged(:production, :web) do
  logger.info("Request received", path: "/")
end
# [production web] Request received path="/"
```

--------------------------------

### Test logging with StringIO

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/testing

Use a StringIO object to capture and inspect log output during RSpec tests.

```ruby
require "stringio"

RSpec.describe MyClass do
  let(:log_output) { StringIO.new }
  let(:logger) { Dry.Logger(:test, stream: log_output) }

  it "logs the operation" do
    subject = MyClass.new(logger: logger)
    subject.perform

    expect(log_output.string).to include("Operation completed")
  end
end
```
Tokens:
Raw