Module: Lumberjack

Extended by:
ContextLocals
Defined in:
lib/lumberjack.rb,
lib/lumberjack/rack.rb,
lib/lumberjack/tags.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/tag_context.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/tag_formatter.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/tagged_message.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/device/date_rolling_log_file.rb,
lib/lumberjack/device/size_rolling_log_file.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, TagContext, TagFormatter, Tags, 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.



153
154
155
 
# File 'lib/lumberjack.rb', line 153

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:



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

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



88
89
90
 
# File 'lib/lumberjack.rb', line 88

def context(&block)
  use_context(Context.new(current_context), &block)
end

.context? ⇒ Boolean

Returns:

  • (Boolean) 


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

def context?
  Utils.deprecated("Lumberjack.context?", "Lumberjack.context? is deprecated and will be removed in version 2.1; use in_context? instead.") do
    in_context?
  end
end

.context_attributes ⇒ Hash?

Return attributes that will be applied to all Lumberjack loggers.

Returns:

  • (Hash, nil) 


138
139
140
 
# File 'lib/lumberjack.rb', line 138

def context_attributes
  current_context&.attributes
end

.context_tags ⇒ Hash?

Deprecated.

Use context_attributes

Alias for context_attributes to provide API compatibility with version 1.x. This method will eventually be removed.

Returns:

  • (Hash, nil) 


160
161
162
163
164
 
# File 'lib/lumberjack.rb', line 160

def context_tags
  Utils.deprecated("Lumberjack.context_tags", "Lumberjack.context_tags is deprecated and will be removed in version 2.1; use context_attributes instead.") do
    context_attributes
  end
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.



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

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.



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

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.



96
97
98
99
100
101
102
 
# File 'lib/lumberjack.rb', line 96

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) 


125
126
127
 
# File 'lib/lumberjack.rb', line 125

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.



220
221
222
 
# File 'lib/lumberjack.rb', line 220

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.



226
227
228
 
# File 'lib/lumberjack.rb', line 226

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.



171
172
173
174
175
176
177
178
179
180
 
# File 'lib/lumberjack.rb', line 171

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.



109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/lumberjack.rb', line 109

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