Skip to content

std.log: add scoped logging struct#6039

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
andrewrk merged 3 commits into from
Aug 12, 2020
+110 −9
Merged

std.log: add scoped logging struct #6039

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7db2c11
std.log: add scoped logging struct
heidezomp Aug 12, 2020
2560707
std.log: add documentation for scoped logging
heidezomp Aug 12, 2020
bf2ed0f
std.log: don't state in docs that messages are logged to stderr
heidezomp Aug 12, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
119 changes: 110 additions & 9 deletions lib/std/log.zig
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -2,12 +2,16 @@ const std = @import("std.zig");
const builtin = std.builtin;
const root = @import("root");

//! std.log is standardized interface for logging which allows for the logging
//! std.log is a standardized interface for logging which allows for the logging
//! of programs and libraries using this interface to be formatted and filtered
//! by the implementer of the root.log function.
//!
//! The scope parameter should be used to give context to the logging. For
//! example, a library called 'libfoo' might use .libfoo as its scope.
//! This parameter can either be passed explicitly to the logging functions
//! provided here, or a scoped logging namespace can be created
//! using the `log.scoped` function. If logging scopes are not relevant for
//! your use case, the `log.default` scope namespace can be used.
//!
//! An example root.log might look something like this:
//!
Expand DownExpand Up@@ -44,16 +48,26 @@ const root = @import("root");
//! }
//!
//! pub fn main() void {
//! // Using explicit scopes:
//! // Won't be printed as log_level is .warn
//! std.log.info(.my_project, "Starting up.", .{});
//! std.log.err(.nice_library, "Something went very wrong, sorry.", .{});
//! // Won't be printed as it gets filtered out by our log function
//! std.log.err(.lib_that_logs_too_much, "Added 1 + 1", .{});
//!
//! // Using a scoped logging namespace:
//! const scoped_log = std.log.scoped(.my_project);
//! scoped_log.alert("The scope for this message is implicitly .my_project", .{});
//!
//! // Using the default namespace:
//! // Won't be printed as log_level is .warn
//! std.log.default.info("I don't care about my namespace", .{});
//! }
//! ```
//! Which produces the following output:
//! ```
//! [err] (nice_library): Something went very wrong, sorry.
//! [alert] (my_project): The scope for this message is implicitly .my_project
//! ```

pub const Level = enum {
Expand DownExpand Up@@ -115,7 +129,7 @@ fn log(
}
}

/// Log an emergency message to stderr. This log level is intended to be used
/// Log an emergency message. This log level is intended to be used
/// for conditions that cannot be handled and is usually followed by a panic.
pub fn emerg(
comptime scope: @Type(.EnumLiteral),
Expand All@@ -126,7 +140,7 @@ pub fn emerg(
log(.emerg, scope, format, args);
}

/// Log an alert message to stderr. This log level is intended to be used for
/// Log an alert message. This log level is intended to be used for
/// conditions that should be corrected immediately (e.g. database corruption).
pub fn alert(
comptime scope: @Type(.EnumLiteral),
Expand All@@ -137,7 +151,7 @@ pub fn alert(
log(.alert, scope, format, args);
}

/// Log a critical message to stderr. This log level is intended to be used
/// Log a critical message. This log level is intended to be used
/// when a bug has been detected or something has gone wrong and it will have
/// an effect on the operation of the program.
pub fn crit(
Expand All@@ -149,7 +163,7 @@ pub fn crit(
log(.crit, scope, format, args);
}

/// Log an error message to stderr. This log level is intended to be used when
/// Log an error message. This log level is intended to be used when
/// a bug has been detected or something has gone wrong but it is recoverable.
pub fn err(
comptime scope: @Type(.EnumLiteral),
Expand All@@ -160,7 +174,7 @@ pub fn err(
log(.err, scope, format, args);
}

/// Log a warning message to stderr. This log level is intended to be used if
/// Log a warning message. This log level is intended to be used if
/// it is uncertain whether something has gone wrong or not, but the
/// circumstances would be worth investigating.
pub fn warn(
Expand All@@ -171,7 +185,7 @@ pub fn warn(
log(.warn, scope, format, args);
}

/// Log a notice message to stderr. This log level is intended to be used for
/// Log a notice message. This log level is intended to be used for
/// non-error but significant conditions.
pub fn notice(
comptime scope: @Type(.EnumLiteral),
Expand All@@ -181,7 +195,7 @@ pub fn notice(
log(.notice, scope, format, args);
}

/// Log an info message to stderr. This log level is intended to be used for
/// Log an info message. This log level is intended to be used for
/// general messages about the state of the program.
pub fn info(
comptime scope: @Type(.EnumLiteral),
Expand All@@ -191,7 +205,7 @@ pub fn info(
log(.info, scope, format, args);
}

/// Log a debug message to stderr. This log level is intended to be used for
/// Log a debug message. This log level is intended to be used for
/// messages which are only useful for debugging.
pub fn debug(
comptime scope: @Type(.EnumLiteral),
Expand All@@ -200,3 +214,90 @@ pub fn debug(
) void {
log(.debug, scope, format, args);
}

/// Returns a scoped logging namespace that logs all messages using the scope
/// provided here.
pub fn scoped(comptime scope: @Type(.EnumLiteral)) type {
return struct {
/// Log an emergency message. This log level is intended to be used
/// for conditions that cannot be handled and is usually followed by a panic.
pub fn emerg(
comptime format: []const u8,
args: anytype,
) void {
@setCold(true);
log(.emerg, scope, format, args);
}

/// Log an alert message. This log level is intended to be used for
/// conditions that should be corrected immediately (e.g. database corruption).
pub fn alert(
comptime format: []const u8,
args: anytype,
) void {
@setCold(true);
log(.alert, scope, format, args);
}

/// Log a critical message. This log level is intended to be used
/// when a bug has been detected or something has gone wrong and it will have
/// an effect on the operation of the program.
pub fn crit(
comptime format: []const u8,
args: anytype,
) void {
@setCold(true);
log(.crit, scope, format, args);
}

/// Log an error message. This log level is intended to be used when
/// a bug has been detected or something has gone wrong but it is recoverable.
pub fn err(
comptime format: []const u8,
args: anytype,
) void {
@setCold(true);
log(.err, scope, format, args);
}

/// Log a warning message. This log level is intended to be used if
/// it is uncertain whether something has gone wrong or not, but the
/// circumstances would be worth investigating.
pub fn warn(
comptime format: []const u8,
args: anytype,
) void {
log(.warn, scope, format, args);
}

/// Log a notice message. This log level is intended to be used for
/// non-error but significant conditions.
pub fn notice(
comptime format: []const u8,
args: anytype,
) void {
log(.notice, scope, format, args);
}

/// Log an info message. This log level is intended to be used for
/// general messages about the state of the program.
pub fn info(
comptime format: []const u8,
args: anytype,
) void {
log(.info, scope, format, args);
}

/// Log a debug message. This log level is intended to be used for
/// messages which are only useful for debugging.
pub fn debug(
comptime format: []const u8,
args: anytype,
) void {
log(.debug, scope, format, args);
}
};
}

/// The default scoped logging namespace.
pub const default = scoped(.default);