class Log

• Log
• Reference
• Object

Overview

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

The messages, or Log::Entry have associated levels, such as Info or Error that indicate their importance. See Log::Severity.

To log a message #debug, #verbose, #info, #warn, #error, and #fatal methods can be used. They expect a block that will evaluate to the message of the entry.

require "log"

Log.info { "Program started" }

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

Log.warn(exception: e) { "Oh no!" }

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

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

When creating log messages they belong to a source. If the top-level Log 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 a Log 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, any Log.info call within the DB module will use the db source. And not the top-level ::Log.info.

Sources can be nested. Continuing the last example, to declare a Log constant db.pool source you can do as follows:

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

A Log will emit the messages to the Log::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 type DB::Pool the source db.pool will be used. For generic types as Foo::Bar(Baz) the source foo.bar will be used (i.e. without generic arguments).

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

Configure logging explicitly in the code

Use Log.builder 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.* matches foo.bar and every nested source
• foo.bar matches foo.bar, but not its nested sources

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

backend = Log::IOBackend.new
Log.builder.bind "*", :warning, backend
Log.builder.bind "db.*", :debug, backend
Log.builder.bind "*", :error, ElasticSearchBackend.new("http://localhost:9200")

Configure logging from environment variables

Include the following line to allow configuration from environment variables.

Log.setup_from_env

The environment variables CRYSTAL_LOG_LEVEL and CRYSTAL_LOG_SOURCES are used to indicate which severity level to emit (defaults to INFO; use NONE to skip all messages) and to restrict which sources you are interested in.

The valid values for CRYSTAL_LOG_SOURCES are:

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

The logs are emitted to STDOUT using a Log::IOBackend.

If Log.setup_from_env is called on startup you can tweak the logging as:

Defined in:

Constructors

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

  Creates a Log for the given source.

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

  Creates a Log for the given type.

Class Method Summary

• .builder

  Returns the default Log::Builder used for Log.for calls.

• .context : Log::Context

  Returns the current fiber logging context.

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

  Sets the current fiber logging context.

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

  See Log#debug.

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

  See Log#error.

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

  See Log#fatal.

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

  See Log#info.

• .setup_from_env(*, builder : Log::Builder = Log.builder, level = ENV.fetch("CRYSTAL_LOG_LEVEL", "INFO"), sources = ENV.fetch("CRYSTAL_LOG_SOURCES", ""), backend = Log::IOBackend.new)

  Setups builder based on CRYSTAL_LOG_LEVEL and CRYSTAL_LOG_SOURCES environment variables.

• .verbose(*, exception : Exception? = nil, &)

  See Log#verbose.

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

  See Log#warn.

• .with_context(&)

  Method to save and restore the current logging context.

Instance Method Summary

• #backend : Backend?
• #context : Log::Context

  Returns the current fiber logging context.

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

  Sets the current fiber logging context.

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

  Logs a message if the logger's current severity is lower or equal to 0.

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

  Logs a message if the logger's current severity is lower or equal to 4.

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

  Logs a message if the logger's current severity is lower or equal to 5.

• #for(child_source : String, level : Severity? = nil) : Log

  Creates a Log for the given nested source.

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

  Creates a Log for the given type.

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

  Logs a message if the logger's current severity is lower or equal to 2.

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

  Change this log severity level filter.

• #source : String
• #verbose(*, exception : Exception? = nil, &)

  Logs a message if the logger's current severity is lower or equal to 1.

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

  Logs a message if the logger's current severity is lower or equal to 3.

Constructor Detail

Class Method Detail

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

Instance Method Detail