class Log

• Log
• Reference
• Object

Overview

TheLog class provides a logging utility that you can use to output messages.

The messages, orLog::Entry have associated levels, such asInfo orError that indicate their importance. SeeLog::Severity.

To log a message use the#trace,#debug,#info,#notice,#warn, #error, and#fatal methods. They expect a block that will evaluate to the message of the entry:

NOTE To useLog, you must explicitly import it withrequire "log"

require "log"

Log.info { "Program started" }

Data can be associated with a log entry via theLog::Emitter yielded in the logging methods.

Log.info &.emit("User logged in", user_id: 42)

If you want to log an exception, you can indicate it in theexception: named argument.

Log.warn(exception: e) { "Oh no!" }
Log.warn exception: e, &.emit("Oh no!", user_id: 42)

The block is only evaluated if the current message is to be emitted to someLog::Backend.

To add structured information to the message you can use theLog::Context.

When creating log messages they belong to asource. If the top-levelLog is used as in the above examples its source is the empty string.

The source can be used to identify the module or part of the application that is logging. You can configure for each source a different level to filter the messages.

A recommended pattern is to declare aLog constant in the namespace of your shard or module as follows:

module DB
  Log = ::Log.for("db") # Log for db source

  def do_something
    Log.info { "this is logged in db source" }
  end
end

DB::Log.info { "this is also logged in db source" }
Log.for("db").info { "this is also logged in db source" }
Log.info { "this is logged in top-level source" }

That way, anyLog.info call within theDB module will use thedb source. And not the top-level::Log.info.

Sources can be nested. Continuing the last example, to declare aLog constantdb.pool source you can do as follows:

class DB::Pool
  Log = DB::Log.for("pool") # Log for db.pool source
end

ALog will emit the messages to theLog::Backends attached to it as long as the configured severity filter#level permits it.

Logs can also be created from a type directly. For the typeDB::Pool the sourcedb.pool will be used. For generic types asFoo::Bar(Baz) the sourcefoo.bar will be used (i.e. without generic arguments).

module DB
  Log = ::Log.for(self) # Log for db source
end

Default logging configuration

By default entries from all sources withInfo and above severity will be logged toSTDOUT using theLog::IOBackend.

If you need to change the default level, backend or sources callLog.setup upon startup.

NOTE Calling.setup will override previous.setup calls.

Log.setup(:debug)                     # Log debug and above for all sources to STDOUT
Log.setup("myapp.*, http.*", :notice) # Log notice and above for myapp.* and http.* sources only, and log nothing for any other source.
backend_with_formatter = Log::IOBackend.new(formatter: custom_formatter)
Log.setup(:debug, backend_with_formatter) # Log debug and above for all sources to using a custom backend

Configure logging explicitly in the code

UseLog.setup methods to indicate which sources should go to which backends.

You can indicate actual sources or patterns.

• the empty string matches only the top-level source
• * matches all the sources
• foo.bar.* matchesfoo.bar and every nested source
• foo.bar matchesfoo.bar, but not its nested sources
• Any comma separated combination of the above

The following configuration will setup for all sources to emit warnings (or higher) toSTDOUT, allow any of thedb.* and nested source to emit debug (or higher), and to also emit for all sources errors (or higher) to an elasticsearch backend.

Log.setup do |c|
  backend = Log::IOBackend.new

  c.bind "*", :warn, backend
  c.bind "db.*", :debug, backend
  c.bind "*", :error, ElasticSearchBackend.new("http://localhost:9200")
end

Configure logging from environment variables

Include the following line to allow configuration from environment variables.

Log.setup_from_env

The environment variableLOG_LEVEL is used to indicate which severity level to emit. By default entries from all sources withInfo and above severity will be logged toSTDOUT using theLog::IOBackend.

To change the level and sources change the environment variable value:

$ LOG_LEVEL=DEBUG ./bin/app

You can tweak the default values (used whenLOG_LEVEL variable is not defined):

Log.setup_from_env(default_level: :error)

Defined in:

Constructors

• .for(source : String, level : Severity | Nil = nil) : Log

  Creates aLog for the given source.

• .for(type : Class, level : Severity | Nil = nil) : Log

  Creates aLog for the given type.

Class Method Summary

• .builder : Log::Builder

  Returns the defaultLog::Builder used forLog.for calls.

• .capture(source : String = "*", level : Severity = Log::Severity::Trace, *, builder = Log.builder, &)

  Returns and yields anEntriesChecker that allows checking specific log entries were emitted.

• .capture(level : Log::Severity = Log::Severity::Trace, *, builder : Log::Builder = Log.builder, &)

  Returns and yields anEntriesChecker that allows checking specific log entries were emitted.

• .context : Log::Context

  Returns the current fiber logging context.

• .context=(value : Log::Metadata) : Log::Metadata

  Sets the current fiber logging context.

• .context=(value : Log::Context) : Log::Metadata

  Sets the current fiber logging context.

• .debug(*, exception : Exception) : Nil

  SeeLog#debug.

• .debug(*, exception : Exception | Nil = nil, &)

  SeeLog#debug.

• .error(*, exception : Exception) : Nil

  SeeLog#error.

• .error(*, exception : Exception | Nil = nil, &)

  SeeLog#error.

• .fatal(*, exception : Exception) : Nil

  SeeLog#fatal.

• .fatal(*, exception : Exception | Nil = nil, &)

  SeeLog#fatal.

• .info(*, exception : Exception) : Nil

  SeeLog#info.

• .info(*, exception : Exception | Nil = nil, &)

  SeeLog#info.

• .notice(*, exception : Exception) : Nil

  SeeLog#notice.

• .notice(*, exception : Exception | Nil = nil, &)

  SeeLog#notice.

• .progname

  The program name used for log entries

• .progname=(progname : String)

  The program name used for log entries

• .setup(*, builder : Log::Builder = Log.builder, &)

  Setups logging bindings discarding all previous configurations.

• .setup(sources : String = "*", level : Log::Severity = Log::Severity::Info, backend : Log::Backend = IOBackend.new, *, builder : Log::Builder = Log.builder) : Nil

  Setups logging forsources using the specifiedlevel,backend.

• .setup(level : Log::Severity = Log::Severity::Info, backend : Log::Backend = IOBackend.new, *, builder : Log::Builder = Log.builder)

  Setups logging for all sources using the specifiedlevel,backend.

• .setup_from_env(*, builder : Log::Builder = Log.builder, default_level : Log::Severity = Log::Severity::Info, default_sources : String = "*", log_level_env : String = "LOG_LEVEL", backend : Log::Backend = Log::IOBackend.new)

  Setups logging based onLOG_LEVEL environment variable.

• .trace(*, exception : Exception) : Nil

  SeeLog#trace.

• .trace(*, exception : Exception | Nil = nil, &)

  SeeLog#trace.

• .warn(*, exception : Exception) : Nil

  SeeLog#warn.

• .warn(*, exception : Exception | Nil = nil, &)

  SeeLog#warn.

• .with_context(values, &)

  Method to save and restore the current logging context.

• .with_context(**kwargs, &)

  Method to save and restore the current logging context.

Macro Summary

• define_formatter(name, pattern)

  Generate subclasses ofLog::StaticFormatter from a string with interpolations

Instance Method Summary

• #backend : Backend | Nil
• #context : Log::Context

  Returns the current fiber logging context.

• #context=(value : Log::Metadata | Log::Context)

  Sets the current fiber logging context.

• #debug(*, exception : Exception) : Nil

  Logs the givenexception if the logger's current severity is lower than or equal toSeverity::Debug.

• #debug(*, exception : Exception | Nil = nil, &)

  Logs a message if the logger's current severity is lower than or equal toSeverity::Debug.

• #error(*, exception : Exception) : Nil

  Logs the givenexception if the logger's current severity is lower than or equal toSeverity::Error.

• #error(*, exception : Exception | Nil = nil, &)

  Logs a message if the logger's current severity is lower than or equal toSeverity::Error.

• #fatal(*, exception : Exception) : Nil

  Logs the givenexception if the logger's current severity is lower than or equal toSeverity::Fatal.

• #fatal(*, exception : Exception | Nil = nil, &)

  Logs a message if the logger's current severity is lower than or equal toSeverity::Fatal.

• #finalize : Nil
• #for(child_source : String, level : Severity | Nil = nil) : Log

  Creates aLog for the given nested source.

• #for(type : Class, level : Severity | Nil = nil) : Log

  Creates aLog for the given type.

• #info(*, exception : Exception) : Nil

  Logs the givenexception if the logger's current severity is lower than or equal toSeverity::Info.

• #info(*, exception : Exception | Nil = nil, &)

  Logs a message if the logger's current severity is lower than or equal toSeverity::Info.

• #level : Severity
• #level=(value : Severity) : Log::Severity

  Change this log severity level filter.

• #notice(*, exception : Exception) : Nil

  Logs the givenexception if the logger's current severity is lower than or equal toSeverity::Notice.

• #notice(*, exception : Exception | Nil = nil, &)

  Logs a message if the logger's current severity is lower than or equal toSeverity::Notice.

• #source : String
• #trace(*, exception : Exception) : Nil

  Logs the givenexception if the logger's current severity is lower than or equal toSeverity::Trace.

• #trace(*, exception : Exception | Nil = nil, &)

  Logs a message if the logger's current severity is lower than or equal toSeverity::Trace.

• #warn(*, exception : Exception) : Nil

  Logs the givenexception if the logger's current severity is lower than or equal toSeverity::Warn.

• #warn(*, exception : Exception | Nil = nil, &)

  Logs a message if the logger's current severity is lower than or equal toSeverity::Warn.

• #with_context(values, &)

  Method to save and restore the current logging context.

• #with_context(**kwargs, &)

  Method to save and restore the current logging context.

Constructor Detail

Class Method Detail

require "spec"
require "log"
require "log/spec"

Log.setup(:none)

def greet(name)
  Log.info { "Greeting #{name}" }
end

it "greets" do
  Log.capture do |logs|
    greet("Harry")
    greet("Hermione")
    greet("Ron")

    logs.check(:info, /greeting harry/i)
    logs.next(:info, /greeting hermione/i)
  end
end

require "spec"
require "log"
require "log/spec"

Log.setup(:none)

def greet(name)
  Log.info { "Greeting #{name}" }
end

it "greets" do
  Log.capture do |logs|
    greet("Harry")
    greet("Hermione")
    greet("Ron")

    logs.check(:info, /greeting harry/i)
    logs.next(:info, /greeting hermione/i)
  end
end

Log.context.set a: 1
Log.info { %(message with {"a" => 1} context) }
Log.with_context(b: 2) do
  Log.context.set c: 3
  Log.info { %(message with {"a" => 1, "b" => 2, "c" => 3} context) }
end
Log.info { %(message with {"a" => 1} context) }

Log.context.set a: 1
Log.info { %(message with {"a" => 1} context) }
Log.with_context(b: 2) do
  Log.context.set c: 3
  Log.info { %(message with {"a" => 1, "b" => 2, "c" => 3} context) }
end
Log.info { %(message with {"a" => 1} context) }

Macro Detail

Log.define_formatter MyFormat, "- #{severity}: #{message}"

Instance Method Detail

Log.debug do
  if false
    "Nothing will be logged."
  end
end

Log.error do
  if false
    "Nothing will be logged."
  end
end

Log.fatal do
  if false
    "Nothing will be logged."
  end
end

Log.info do
  if false
    "Nothing will be logged."
  end
end

Log.notice do
  if false
    "Nothing will be logged."
  end
end

Log.trace do
  if false
    "Nothing will be logged."
  end
end

Log.warn do
  if false
    "Nothing will be logged."
  end
end

Log.context.set a: 1
Log.info { %(message with {"a" => 1} context) }
Log.with_context(b: 2) do
  Log.context.set c: 3
  Log.info { %(message with {"a" => 1, "b" => 2, "c" => 3} context) }
end
Log.info { %(message with {"a" => 1} context) }

Log.context.set a: 1
Log.info { %(message with {"a" => 1} context) }
Log.with_context(b: 2) do
  Log.context.set c: 3
  Log.info { %(message with {"a" => 1, "b" => 2, "c" => 3} context) }
end
Log.info { %(message with {"a" => 1} context) }