diff --git a/lib/std/log.zig b/lib/std/log.zig new file mode 100644 index 0000000000..706c2b2378 --- /dev/null +++ b/lib/std/log.zig @@ -0,0 +1,202 @@ +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 +//! 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. +//! +//! An example root.log might look something like this: +//! +//! ``` +//! const std = @import("std"); +//! +//! // Set the log level to warning +//! pub const log_level: std.log.Level = .warn; +//! +//! // Define root.log to override the std implementation +//! pub fn log( +//! comptime level: std.log.Level, +//! comptime scope: @TypeOf(.EnumLiteral), +//! comptime format: []const u8, +//! args: var, +//! ) void { +//! // Ignore all non-critical logging from sources other than +//! // .my_project and .nice_library +//! const scope_prefix = "(" ++ switch (scope) { +//! .my_project, .nice_library => @tagName(scope), +//! else => if (@enumToInt(level) <= @enumToInt(std.log.Level.crit)) +//! @tagName(scope) +//! else +//! return, +//! } ++ "): "; +//! +//! const prefix = "[" ++ @tagName(level) ++ "] " ++ scope_prefix; +//! +//! // Print the message to stderr, silently ignoring any errors +//! const held = std.debug.getStderrMutex().acquire(); +//! defer held.release(); +//! const stderr = std.debug.getStderrStream(); +//! nosuspend stderr.print(prefix ++ format, args) catch return; +//! } +//! +//! pub fn main() void { +//! // Won't be printed as log_level is .warn +//! std.log.info(.my_project, "Starting up.\n", .{}); +//! std.log.err(.nice_library, "Something went very wrong, sorry.\n", .{}); +//! // Won't be printed as it gets filtered out by our log function +//! std.log.err(.lib_that_logs_too_much, "Added 1 + 1\n", .{}); +//! } +//! ``` +//! Which produces the following output: +//! ``` +//! [err] (nice_library): Something went very wrong, sorry. +//! ``` + +pub const Level = enum { + /// Emergency: a condition that cannot be handled, usually followed by a + /// panic. + emerg, + /// Alert: a condition that should be corrected immediately (e.g. database + /// corruption). + alert, + /// Critical: A bug has been detected or something has gone wrong and it + /// will have an effect on the operation of the program. + crit, + /// Error: A bug has been detected or something has gone wrong but it is + /// recoverable. + err, + /// Warning: it is uncertain if something has gone wrong or not, but the + /// circumstances would be worth investigating. + warn, + /// Notice: non-error but significant conditions. + notice, + /// Informational: general messages about the state of the program. + info, + /// Debug: messages only useful for debugging. + debug, +}; + +/// The default log level is based on build mode. Note that in ReleaseSmall +/// builds the default level is emerg but no messages will be stored/logged +/// by the default logger to save space. +pub const default_level: Level = switch (builtin.mode) { + .Debug => .debug, + .ReleaseSafe => .notice, + .ReleaseFast => .err, + .ReleaseSmall => .emerg, +}; + +/// The current log level. This is set to root.log_level if present, otherwise +/// log.default_level. +pub const level: Level = if (@hasDecl(root, "log_level")) + root.log_level +else + default_level; + +fn log( + comptime message_level: Level, + comptime scope: @Type(.EnumLiteral), + comptime format: []const u8, + args: var, +) void { + if (@enumToInt(message_level) <= @enumToInt(level)) { + if (@hasDecl(root, "log")) { + root.log(message_level, scope, format, args); + } else if (builtin.mode != .ReleaseSmall) { + const held = std.debug.getStderrMutex().acquire(); + defer held.release(); + const stderr = io.getStdErr().writer(); + nosuspend stderr.print(format, args) catch return; + } + } +} + +/// Log an emergency message to stderr. 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), + comptime format: []const u8, + args: var, +) void { + @setCold(true); + log(.emerg, scope, format, args); +} + +/// Log an alert message to stderr. 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), + comptime format: []const u8, + args: var, +) void { + @setCold(true); + log(.alert, scope, format, args); +} + +/// Log a critical message to stderr. 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 scope: @Type(.EnumLiteral), + comptime format: []const u8, + args: var, +) void { + @setCold(true); + log(.crit, scope, format, args); +} + +/// Log an error message to stderr. 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), + comptime format: []const u8, + args: var, +) void { + @setCold(true); + log(.err, scope, format, args); +} + +/// Log a warning message to stderr. 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 scope: @Type(.EnumLiteral), + comptime format: []const u8, + args: var, +) void { + log(.warn, scope, format, args); +} + +/// Log a notice message to stderr. This log level is intended to be used for +/// non-error but significant conditions. +pub fn notice( + comptime scope: @Type(.EnumLiteral), + comptime format: []const u8, + args: var, +) void { + log(.notice, scope, format, args); +} + +/// Log an info message to stderr. This log level is intended to be used for +/// general messages about the state of the program. +pub fn info( + comptime scope: @Type(.EnumLiteral), + comptime format: []const u8, + args: var, +) void { + log(.info, scope, format, args); +} + +/// Log a debug message to stderr. This log level is intended to be used for +/// messages which are only useful for debugging. +pub fn debug( + comptime scope: @Type(.EnumLiteral), + comptime format: []const u8, + args: var, +) void { + log(.debug, scope, format, args); +} diff --git a/lib/std/std.zig b/lib/std/std.zig index b1cab77109..0961991ea6 100644 --- a/lib/std/std.zig +++ b/lib/std/std.zig @@ -49,6 +49,7 @@ pub const heap = @import("heap.zig"); pub const http = @import("http.zig"); pub const io = @import("io.zig"); pub const json = @import("json.zig"); +pub const log = @import("log.zig"); pub const macho = @import("macho.zig"); pub const math = @import("math.zig"); pub const mem = @import("mem.zig");