class Log
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 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 use Log
, you must explicitly import it with require "log"
require "log"
Log.info { "Program started" }
Data can be associated with a log entry via the Log::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 the exception:
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 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::Backend
s 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
Default logging configuration
By default entries from all sources with Info
and above severity will
be logged to STDOUT
using the Log::IOBackend
.
If you need to change the default level, backend or sources call Log.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
Use Log.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 sourcesfoo.bar.*
matchesfoo.bar
and every nested sourcefoo.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) 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.
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 variable LOG_LEVEL
is used to indicate which severity level to emit.
By default entries from all sources with Info
and above severity will
be logged to STDOUT
using the Log::IOBackend
.
To change the level and sources change the environment variable value:
$ LOG_LEVEL=DEBUG ./bin/app
You can tweak the default values (used when LOG_LEVEL
variable is not defined):
Log.setup_from_env(default_level: :error)
Defined in:
log.crlog/dispatch.cr
log/format.cr
log/log.cr
log/main.cr
log/setup.cr
log/spec.cr
Constructors
-
.for(source : String, level : Severity | Nil = nil) : Log
Creates a
Log
for the given source. -
.for(type : Class, level : Severity | Nil = nil) : Log
Creates a
Log
for the given type.
Class Method Summary
-
.builder : Log::Builder
Returns the default
Log::Builder
used forLog.for
calls. -
.capture(source : String = "*", level : Severity = Log::Severity::Trace, *, builder = Log.builder, &)
Returns and yields an
EntriesChecker
that allows checking specific log entries were emitted. -
.capture(level : Log::Severity = Log::Severity::Trace, *, builder : Log::Builder = Log.builder, &)
Returns and yields an
EntriesChecker
that allows checking specific log entries were emitted. -
.context : Log::Context
Returns the current fiber logging context.
-
.context=(value : Log::Metadata)
Sets the current fiber logging context.
-
.context=(value : Log::Context)
Sets the current fiber logging context.
-
.debug(*, exception : Exception | Nil = nil, &)
See
Log#debug
. -
.error(*, exception : Exception | Nil = nil, &)
See
Log#error
. -
.fatal(*, exception : Exception | Nil = nil, &)
See
Log#fatal
. -
.info(*, exception : Exception | Nil = nil, &)
See
Log#info
. -
.notice(*, exception : Exception | Nil = nil, &)
See
Log#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)
Setups logging for sources using the specified level, 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 specified level, backend.
-
.setup_from_env(*, builder : Log::Builder = Log.builder, default_level : Log::Severity = Log::Severity::Info, default_sources = "*", log_level_env = "LOG_LEVEL", backend = Log::IOBackend.new)
Setups logging based on
LOG_LEVEL
environment variable. -
.trace(*, exception : Exception | Nil = nil, &)
See
Log#trace
. -
.warn(*, exception : Exception | Nil = nil, &)
See
Log#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.
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 = nil, &)
Logs a message if the logger's current severity is lower than or equal to
Severity::Debug
. -
#error(*, exception : Exception | Nil = nil, &)
Logs a message if the logger's current severity is lower than or equal to
Severity::Error
. -
#fatal(*, exception : Exception | Nil = nil, &)
Logs a message if the logger's current severity is lower than or equal to
Severity::Fatal
. -
#for(child_source : String, level : Severity | Nil = nil) : Log
Creates a
Log
for the given nested source. -
#for(type : Class, level : Severity | Nil = nil) : Log
Creates a
Log
for the given type. -
#info(*, exception : Exception | Nil = nil, &)
Logs a message if the logger's current severity is lower than or equal to
Severity::Info
. - #level : Severity
-
#level=(value : Severity)
Change this log severity level filter.
-
#notice(*, exception : Exception | Nil = nil, &)
Logs a message if the logger's current severity is lower than or equal to
Severity::Notice
. - #source : String
-
#trace(*, exception : Exception | Nil = nil, &)
Logs a message if the logger's current severity is lower than or equal to
Severity::Trace
. -
#warn(*, exception : Exception | Nil = nil, &)
Logs a message if the logger's current severity is lower than or equal to
Severity::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 of
Log::StaticFormatter
from a string with interpolations
Instance methods inherited from class Reference
==(other : self)==(other : JSON::Any)
==(other : YAML::Any)
==(other) ==, dup dup, hash(hasher) hash, initialize initialize, inspect(io : IO) : Nil inspect, object_id : UInt64 object_id, pretty_print(pp) : Nil pretty_print, same?(other : Reference) : Bool
same?(other : Nil) same?, to_s(io : IO) : Nil to_s
Constructor methods inherited from class Reference
new
new,
unsafe_construct(address : Pointer, *args, **opts) : self
unsafe_construct
Class methods inherited from class Reference
pre_initialize(address : Pointer)
pre_initialize
Instance methods inherited from class Object
! : Bool
!,
!=(other)
!=,
!~(other)
!~,
==(other)
==,
===(other : JSON::Any)===(other : YAML::Any)
===(other) ===, =~(other) =~, as(type : Class) as, as?(type : Class) as?, class class, dup dup, hash(hasher)
hash hash, in?(collection : Object) : Bool
in?(*values : Object) : Bool in?, inspect(io : IO) : Nil
inspect : String inspect, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, not_nil!(message)
not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, responds_to?(name : Symbol) : Bool responds_to?, tap(&) tap, to_json(io : IO) : Nil
to_json : String to_json, to_pretty_json(indent : String = " ") : String
to_pretty_json(io : IO, indent : String = " ") : Nil to_pretty_json, to_s(io : IO) : Nil
to_s : String to_s, to_yaml(io : IO) : Nil
to_yaml : String to_yaml, try(&) try, unsafe_as(type : T.class) forall T unsafe_as
Class methods inherited from class Object
from_json(string_or_io, root : String)from_json(string_or_io) from_json, from_yaml(string_or_io : String | IO) from_yaml
Constructor Detail
Creates a Log
for the given source.
If level is given, it will override the configuration.
Creates a Log
for the given type.
A type Foo::Bar(Baz)
corresponds to the source foo.bar
.
If level is given, it will override the configuration.
Class Method Detail
Returns and yields an EntriesChecker
that allows checking specific log entries
were emitted.
This capture will even work if there are currently no backends configured, effectively adding a temporary backend.
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
By default logs of all sources and severities will be captured.
Use level to only capture of the given severity or above.
Use source to narrow which source are captured. Values that represent single pattern like http.*
are allowed.
The EntriesChecker
will hold a list of emitted entries.
EntriesChecker#check
will find the next entry which matches the level and message.
EntriesChecker#next
will validate that the following entry in the list matches the given level and message.
EntriesChecker#clear
will clear the emitted and captured entries.
With these methods it is possible to express expected traces in either a strict or loose way, while checking ordering.
EntriesChecker#entry
returns the last matched Entry
. Useful to check additional entry properties other than the message.
EntriesChecker#empty
validates there are no pending entries to match.
Using the yielded EntriesChecker
allows clearing the entries between statements.
Invocations can be nested in order to capture each source in their own EntriesChecker
.
Returns and yields an EntriesChecker
that allows checking specific log entries
were emitted.
This capture will even work if there are currently no backends configured, effectively adding a temporary backend.
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
By default logs of all sources and severities will be captured.
Use level to only capture of the given severity or above.
Use source to narrow which source are captured. Values that represent single pattern like http.*
are allowed.
The EntriesChecker
will hold a list of emitted entries.
EntriesChecker#check
will find the next entry which matches the level and message.
EntriesChecker#next
will validate that the following entry in the list matches the given level and message.
EntriesChecker#clear
will clear the emitted and captured entries.
With these methods it is possible to express expected traces in either a strict or loose way, while checking ordering.
EntriesChecker#entry
returns the last matched Entry
. Useful to check additional entry properties other than the message.
EntriesChecker#empty
validates there are no pending entries to match.
Using the yielded EntriesChecker
allows clearing the entries between statements.
Invocations can be nested in order to capture each source in their own EntriesChecker
.
The program name used for log entries
Defaults to the executable name
Setups logging bindings discarding all previous configurations.
Setups logging for sources using the specified level, backend.
Setups logging for all sources using the specified level, backend.
Setups logging based on LOG_LEVEL
environment variable.
Method to save and restore the current logging context. Temporary context for the duration of the block can be set via arguments.
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) }
Method to save and restore the current logging context. Temporary context for the duration of the block can be set via arguments.
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) }
Instance Method Detail
Sets the current fiber logging context.
Logs a message if the logger's current severity is lower than or equal to
Severity::Debug
.
The block is not called unless the current severity level would emit a message.
Blocks which return nil
do not emit anything:
Log.debug do
if false
"Nothing will be logged."
end
end
Logs a message if the logger's current severity is lower than or equal to
Severity::Error
.
The block is not called unless the current severity level would emit a message.
Blocks which return nil
do not emit anything:
Log.error do
if false
"Nothing will be logged."
end
end
Logs a message if the logger's current severity is lower than or equal to
Severity::Fatal
.
The block is not called unless the current severity level would emit a message.
Blocks which return nil
do not emit anything:
Log.fatal do
if false
"Nothing will be logged."
end
end
Creates a Log
for the given nested source.
If level is given, it will override the configuration.
Creates a Log
for the given type.
A type Foo::Bar(Baz)
corresponds to the source foo.bar
.
If level is given, it will override the configuration.
Logs a message if the logger's current severity is lower than or equal to
Severity::Info
.
The block is not called unless the current severity level would emit a message.
Blocks which return nil
do not emit anything:
Log.info do
if false
"Nothing will be logged."
end
end
Logs a message if the logger's current severity is lower than or equal to
Severity::Notice
.
The block is not called unless the current severity level would emit a message.
Blocks which return nil
do not emit anything:
Log.notice do
if false
"Nothing will be logged."
end
end
Logs a message if the logger's current severity is lower than or equal to
Severity::Trace
.
The block is not called unless the current severity level would emit a message.
Blocks which return nil
do not emit anything:
Log.trace do
if false
"Nothing will be logged."
end
end
Logs a message if the logger's current severity is lower than or equal to
Severity::Warn
.
The block is not called unless the current severity level would emit a message.
Blocks which return nil
do not emit anything:
Log.warn do
if false
"Nothing will be logged."
end
end
Method to save and restore the current logging context. Temporary context for the duration of the block can be set via arguments.
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) }
Method to save and restore the current logging context. Temporary context for the duration of the block can be set via arguments.
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
Generate subclasses of Log::StaticFormatter
from a string with interpolations
Example:
Log.define_formatter MyFormat, "- #{severity}: #{message}"
See Log::StaticFormatter
for the available methods that can
be called within the interpolations.