leecannon/std_log.md

## std_log.md

      
    Raw
  

              std_log.md
            
          
    Out of date

This is an updated fork of this gist.
A simple overview of Zig's std.log

Logging functionality that supports:

If a log message should be printed is determined at comptime, meaning zero overhead for unprinted messages (so just leave the code peppered with debug logs, but when it makes sense scope them; so downstream users can filter them out)
Scoped log messages
Different log levels per scope
Overrideable log output (write to file, database, etc.)
All the standard std.fmt formatting magic

Basic Usage:

Just call std.log.X where X is the desired log level, for example:
std.log.info("This is an info message", .{});
std.log.crit("This is an crit message - {}", .{42});
Output:
info: This is an info message
critical: This is an crit message - 42

Log Levels:

The log level of a message determines if it will be printed.
Only if the level of the message is of an equal or greater severity than the global log level will it be printed (there is also overriding of the log level per scope to take into account, see below).
The log levels are, in order of severity:

emerg - Emergency: a condition that cannot be handled, usually followed by a panic.
alert - Alert: a condition that should be corrected immediately (e.g. database corruption)
crit - Critical: A bug has been detected or something has gone wrong and it will have an effect on the operation of the program.
err - Error: A bug has been detected or something has gone wrong but it is recoverable.
warn - Warning: it is uncertain if something has gone wrong or not, but the circumstances would be worth investigating.
notice- Notice: non-error but significant conditions.
info - Informational: general messages about the state of the program.
debug - Debug: messages only useful for debugging.

But what is the global log level?

The default log level is determined by the build mode like this:
/// The default log level is based on build mode.
pub const default_level: Level = switch (builtin.mode) {
    .Debug => .debug,
    .ReleaseSafe => .notice,
    .ReleaseFast => .err,
    .ReleaseSmall => .err,
};
Overriding this is easy just define a public log_level decl in the root file (where ever main is), like this:
pub const log_level: std.log.Level = .debug;
Scopes

All log messages include a scope.
When using the simple std.log.info and friends the scope default is used implicitly, the default log output function does not print the scope for messages with default as the scope.
In order to produce log messages with a different scope a scoped log needs to be created:
const my_log = std.log.scoped(.my_scope);

my_log.info("Hello from my_scope", .{});
std.log.info("Hello from default scope", .{});
Output:
info(my_scope): Hello from my_scope
info: Hello from default scope

Different log levels per scope

When a system gets large it naturally breaks down into sub-systems, it makes sense to use different log scopes per sub-system.
When debuging one of these sub-systems it makes sense to output a lot of debug log messages, however setting the global log level to debug will result in debug logs (and all other levels) from every log scope.
To resolve this std.log supports overriding the global log level on a per scope basis, in order to do so define a public scope_levels decl in the root file (where ever main is), like this:
pub const scope_levels = [_]std.log.ScopeLevel{
    .{ .scope = .library_a, .level = .debug },
    .{ .scope = .library_b, .level = .crit },
};
This will print all log messages from scope library_a, crit and higher from library_b and all other scopes will be printed based on the global log level as normal.
Overriding the log output

Overriding the log output allows great flexibility, libraries you use can just blindly log and the application decides where these message go; whether that is to stdout/stderr, file, database, socket, serial port, etc.
To to do so define a public log function in the root file (where ever main is), like this:
pub fn log(
    comptime message_level: std.log.Level,
    comptime scope: @Type(.EnumLiteral),
    comptime format: []const u8,
    args: anytype,
) void {
    // Implementation here   
}
Checking the global log level and per scope log level is already done for you, meaning this function will only be called when there is a log message that should be output.
~~