Module: Lumberjack

Extended by:
ContextLocals
Defined in:
lib/lumberjack.rb,
lib/lumberjack/rack.rb,
lib/lumberjack/utils.rb,
lib/lumberjack/device.rb,
lib/lumberjack/logger.rb,
lib/lumberjack/context.rb,
lib/lumberjack/severity.rb,
lib/lumberjack/template.rb,
lib/lumberjack/formatter.rb,
lib/lumberjack/log_entry.rb,
lib/lumberjack/device/null.rb,
lib/lumberjack/device/test.rb,
lib/lumberjack/device/multi.rb,
lib/lumberjack/rack/context.rb,
lib/lumberjack/device/buffer.rb,
lib/lumberjack/device/writer.rb,
lib/lumberjack/forked_logger.rb,
lib/lumberjack/context_locals.rb,
lib/lumberjack/context_logger.rb,
lib/lumberjack/device/log_file.rb,
lib/lumberjack/device_registry.rb,
lib/lumberjack/entry_formatter.rb,
lib/lumberjack/remap_attribute.rb,
lib/lumberjack/io_compatibility.rb,
lib/lumberjack/attributes_helper.rb,
lib/lumberjack/log_entry_matcher.rb,
lib/lumberjack/template_registry.rb,
lib/lumberjack/formatter_registry.rb,
lib/lumberjack/local_log_template.rb,
lib/lumberjack/message_attributes.rb,
lib/lumberjack/attribute_formatter.rb,
lib/lumberjack/device/logger_wrapper.rb,
lib/lumberjack/formatter/id_formatter.rb,
lib/lumberjack/formatter/tags_formatter.rb,
lib/lumberjack/formatter/round_formatter.rb,
lib/lumberjack/formatter/strip_formatter.rb,
lib/lumberjack/formatter/object_formatter.rb,
lib/lumberjack/formatter/redact_formatter.rb,
lib/lumberjack/formatter/string_formatter.rb,
lib/lumberjack/formatter/inspect_formatter.rb,
lib/lumberjack/formatter/multiply_formatter.rb,
lib/lumberjack/formatter/truncate_formatter.rb,
lib/lumberjack/formatter/date_time_formatter.rb,
lib/lumberjack/formatter/exception_formatter.rb,
lib/lumberjack/formatter/structured_formatter.rb,
lib/lumberjack/formatter/pretty_print_formatter.rb

Overview

Lumberjack is a flexible logging framework for Ruby that extends the standard Logger functionality with structured logging, context isolation, and advanced formatting capabilities.

The main features include:

  • Structured logging with attributes for machine-readable metadata
  • Context isolation for scoping logging behavior to specific code blocks
  • Flexible formatters for customizing log output
  • Multiple output devices and templates
  • Built-in testing utilities

Examples:

Basic usage

logger = Lumberjack::Logger.new(STDOUT)
logger.info("Hello world")

Using contexts

Lumberjack.context do
  Lumberjack.tag(user_id: 123)
  logger.info("User action") # Will include user_id: 123
end

See Also:

Defined Under Namespace

Modules: ContextLocals, ContextLogger, DeviceRegistry, FormatterRegistry, IOCompatibility, Rack, Severity, Utils Classes: AttributeFormatter, AttributesHelper, Context, DeprecationError, Device, EntryFormatter, ForkedLogger, Formatter, LocalLogTemplate, LogEntry, LogEntryMatcher, Logger, MessageAttributes, RemapAttribute, Template, TemplateRegistry

Constant Summary collapse

VERSION = 
File.read(File.join(__dir__, "..", "VERSION")).strip.freeze
LINE_SEPARATOR = 
((RbConfig::CONFIG["host_os"] =~ /mswin/i) ? "\r\n" : "\n")

Class Attribute Summary collapse

Class Method Summary collapse

Methods included from ContextLocals

isolation_level, isolation_level=

Class Attribute Details

.isolation_level ⇒ Symbol

Returns The current isolation level.

Returns:

  • (Symbol) —

    The current isolation level.



144
145
146
 
# File 'lib/lumberjack.rb', line 144

def isolation_level
  @isolation_level
end

Class Method Details

.build_formatter(&block) ⇒ Lumberjack::EntryFormatter

Helper method to build an entry formatter.

Parameters:

  • block (Proc) —

    The block to use for building the entry formatter.

Returns:

See Also:



167
168
169
 
# File 'lib/lumberjack.rb', line 167

def build_formatter(&block)
  EntryFormatter.build(&block)
end

.context(&block) ⇒ Object

Contexts can be used to store attributes that will be attached to all log entries in the block. The context will apply to all Lumberjack loggers that are used within the block.

If this method is called with a block, it will set a logging context for the scope of a block. If there is already a context in scope, a new one will be created that inherits all the attributes of the parent context.

Otherwise, it will return the current context. If one doesn't exist, it will return a new one but that context will not be in any scope.

Returns:

  • (Object) —

    The result of the block



83
84
85
86
87
 
# File 'lib/lumberjack.rb', line 83

def context(&block)
  return current_context || Context.new unless block

  use_context(current_context, &block)
end

.context_attributes ⇒ Hash?

Return attributes that will be applied to all Lumberjack loggers.

Returns:

  • (Hash, nil) 


129
130
131
 
# File 'lib/lumberjack.rb', line 129

def context_attributes
  current_context&.attributes
end

.deprecation_mode ⇒ Symbol

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns The current deprecation mode.

Returns:

  • (Symbol) —

    The current deprecation mode.



187
188
189
 
# File 'lib/lumberjack.rb', line 187

def deprecation_mode
  @deprecation_mode ||= ENV.fetch("LUMBERJACK_DEPRECATION_WARNINGS", "normal").to_sym
end

.deprecation_mode=(value) ⇒ Object

Control how use of deprecated methods is handled. The default is to print a warning the first time a deprecated method is called. Setting this to :verbose will print a warning every time a deprecated method is called. Setting this to :silent will suppress all deprecation warnings. Setting this to :raise will raise an exception when a deprecated method is called.

The default value can be set with the LUMBERJACK_DEPRECATION_WARNINGS environment variable.

Parameters:

  • value (Symbol, String, nil) —

    The deprecation mode to set. Valid values are :normal, :verbose, :silent, and :raise.



181
182
183
 
# File 'lib/lumberjack.rb', line 181

def deprecation_mode=(value)
  @deprecation_mode = value&.to_sym
end

.ensure_context(&block) ⇒ Object

Ensure that the block of code is wrapped by a global context. If there is not already a context in scope, one will be created.

Returns:

  • (Object) —

    The result of the block.



93
94
95
96
97
98
99
 
# File 'lib/lumberjack.rb', line 93

def ensure_context(&block)
  if in_context?
    yield
  else
    context(&block)
  end
end

.in_context? ⇒ Boolean

Return true if inside a context block.

Returns:

  • (Boolean) 


122
123
124
 
# File 'lib/lumberjack.rb', line 122

def in_context?
  !current_context.nil?
end

.raise_logger_errors=(value) ⇒ void

This method returns an undefined value.

Set whether errors encountered while logging entries should be raised. The default behavior is to rescue these errors and print them to standard error. Otherwise there can be no way to record the error since it cannot be logged.

You can set this to true in you test and development environments to catch logging errors before they make it to production.

Parameters:

  • value (Boolean) —

    Whether to raise logger errors.



200
201
202
 
# File 'lib/lumberjack.rb', line 200

def raise_logger_errors=(value)
  @raise_logger_errors = !!value
end

.raise_logger_errors? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns Whether logger errors should be raised.

Returns:

  • (Boolean) —

    Whether logger errors should be raised.



206
207
208
 
# File 'lib/lumberjack.rb', line 206

def raise_logger_errors?
  @raise_logger_errors
end

.tag(attributes, &block) ⇒ void

This method returns an undefined value.

Tag all loggers with attributes on the current context.

Parameters:

  • attributes (Hash) —

    The attributes to set.

  • block (Proc) —

    optional context block in which to set the attributes.



151
152
153
154
155
156
157
158
159
160
 
# File 'lib/lumberjack.rb', line 151

def tag(attributes, &block)
  if block
    context do
      current_context.assign_attributes(attributes)
      block.call
    end
  else
    current_context&.assign_attributes(attributes)
  end
end

.use_context(context, &block) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Set the context to use within a block.

Parameters:

Returns:

  • (Object) —

    The result of the block.



106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/lumberjack.rb', line 106

def use_context(context, &block)
  unless block_given?
    raise ArgumentError, "A block must be provided to the context method"
  end

  new_context = Context.new(context)
  new_context.parent = current_context
  new_context_locals do |locals|
    locals.context = new_context
    yield
  end
end