log #

Description

log provides your application logging services. You can log to file or to the console and use different logging levels, so that you are not overwhelmed by the logs.

Basic usage

The log module creates a default Log instance by default, and provides utility functions, that you can use to access it.

Note: the default Log instance is thread safe.

That makes it very convenient to use in subsystems, without having to thread a log instance everywhere:

import log

fn abc() {
    log.info('some information')
    log.warn('a warning')
}

// this will not be visible, the default log level is .info:
log.debug('a debug message')

log.set_level(.debug)

// this will be now visible, the log level was changed to .debug:
log.debug('a debug message')

abc()

Advanced usage

You can also create your own log instances, with different options applied to them:

import log

fn main() {
    mut l := log.Log{}
    l.set_level(.info)
    l.set_full_logpath('./info.log')
    l.log_to_console_too()

    l.info('info')
    l.warn('warn')
    l.error('error')
    l.fatal('fatal') // panic, marked as [noreturn]
}

Backwards compatibility

After 2025/01/21, the log module outputs to stderr by default. Before that, it used stdout by default.

If you want to restore the previous behaviour, you have to explicitly call log.use_stdout() :

import os
import log

fn main() {
    // log.info('this will be printed to stderr after 2025/01/21 by default')
    log.use_stdout()
    log.info('this will be printed to stdout')
}

If you want to just silence the note about the stdout -> stderr, during the transition period, call l.set_output_stream(os.stderr()) explicitly.

fn debug(s string)

debug logs a debug message, using the default Logger instance

fn error(s string)

error logs an error message, using the default Logger instance

fn fatal(s string)

fatal logs a fatal message, using the default Logger instance

fn get_level() Level

get_level returns the log level of the default Logger instance

fn get_logger() &Logger

get_logger returns a pointer to the current default logger instance

fn info(s string)

info logs an info message, using the default Logger instance

fn level_from_tag(tag string) ?Level

level_from_tag returns the log level from the given string. It returns none when it does not find a match.

fn new_thread_safe_log() &ThreadSafeLog

new_thread_safe_log returns a new log structure, whose methods are safe to call by multiple threads.

fn set_always_flush(should_flush_on_every_message bool)

set_always_flush called with true, will make the log flush after every single .fatal(), .error(), .warn(), .info(), .debug() call.

fn set_level(level Level)

set_level changes the log level of the default Logger instance

fn set_logger(logger &Logger)

set_logger changes the default logger instance to the one provided by the user. The existing logger will be freed, after the change is done.

fn target_from_label(label string) ?LogTarget

target_from_label returns the log target from the given string. It returns none when it does not find a match.

fn use_stdout()

use_stdout will restore the old behaviour of logging to stdout, instead of stderr. It will also silence the deprecation note in the transition period.

fn warn(s string)

error logs a warning message, using the default Logger instance

interface Logger {
	get_level() Level
mut:
	fatal(s string)
	error(s string)
	warn(s string)
	info(s string)
	debug(s string)
	// utility methods:
	set_level(level Level)
	set_always_flush(should_flush bool)
	free()
}

Logger is an interface that describes a generic Logger

enum Level {
	disabled = 0   // lowest level, disables everything else
	fatal // disables error, warn, info and debug
	error // disables warn, info and debug
	warn  // disables info and debug
	info  // disables debug
	debug
}

Level defines the possible log levels, used by Log.set_level()

enum LogTarget {
	console
	file
	both
}

LogTarget defines the possible log targets, that Log supports

enum TimeFormat {
	tf_ss_micro      // YYYY-MM-DD HH:mm:ss.123456 (24h)
	tf_default       // YYYY-MM-DD HH:mm (24h)
	tf_ss            // YYYY-MM-DD HH:mm:ss (24h)
	tf_ss_milli      // YYYY-MM-DD HH:mm:ss.123 (24h)
	tf_ss_nano       // YYYY-MM-DD HH:mm:ss.123456789 (24h)
	tf_rfc3339       // YYYY-MM-DDTHH:mm:ss.123Z (24 hours, see https://www.rfc-editor.org/rfc/rfc3339.html)
	tf_rfc3339_micro // default, YYYY-MM-DDTHH:mm:ss.123456Z (24 hours, see https://www.rfc-editor.org/rfc/rfc3339.html)
	tf_rfc3339_nano  // YYYY-MM-DDTHH:mm:ss.123456789Z (24 hours, see https://www.rfc-editor.org/rfc/rfc3339.html)
	tf_hhmm          // HH:mm (24h)
	tf_hhmmss        // HH:mm:ss (24h)
	tf_hhmm12        // hh:mm (12h)
	tf_ymmdd         // YYYY-MM-DD
	tf_ddmmy         // DD.MM.YYYY
	tf_md            // MMM D
	tf_custom_format // 'MMMM Do YY N kk:mm:ss A' output like: January 1st 22 AD 13:45:33 PM
}

TimeFormat define the log time string format, come from time/format.v

struct C.log__Logger {
mut:
	_object voidptr
}

Todo: remove this hack, when the language has a way to access the raw pointer to an interface value directly:

struct Log {
mut:
	level              Level = .debug
	output_label       string
	ofile              os.File
	output_target      LogTarget // output to console (stdout/stderr) or file or both.
	time_format        TimeFormat = .tf_rfc3339_micro
	custom_time_format string     = 'MMMM Do YY N kk:mm:ss A' // timestamp with custom format
	short_tag          bool
	always_flush       bool // flush after every single .fatal(), .error(), .warn(), .info(), .debug() call
	output_stream      io.Writer = stderr
pub mut:
	output_file_name string // log output to this file
}

Log represents a logging object

fn (l &Log) get_level() Level

get_level gets the internal logging level.

fn (mut l Log) set_level(level Level)

set_level sets the logging level to level. Messages for levels above it will skipped. For example, after calling log.set_level(.info), log.debug('message') will produce nothing. Call log.set_level(.disabled) to turn off the logging of all messages.

fn (mut l Log) set_full_logpath(full_log_path string)

set_full_logpath sets the output label and output path from full_log_path.

fn (mut l Log) set_output_label(label string)

set_output_label sets the label for the output.

fn (mut l Log) set_output_path(output_file_path string)

set_output_path sets the file to which output is logged to.

fn (mut l Log) set_output_stream(stream io.Writer)

set_output_stream sets the output stream to write log e.g. stderr, stdout, etc.

fn (mut l Log) log_to_console_too()

log_to_console_too turns on logging to the console too, in addition to logging to a file. You have to call it after calling .set_output_path(output_file_path).

fn (mut l Log) flush()

flush writes the log file content to disk.

fn (mut l Log) close()

close closes the log file.

fn (mut l Log) reopen() !

reopen reopens the log file. Useful for log rotation. This does nothing if you are only writing to the console.

fn (mut l Log) send_output(s &string, level Level)

send_output writes log line s with level to either the log file or the console according to the value of the .output_target field.

fn (mut l Log) fatal(s string)

fatal logs line s via send_output if Log.level is greater than or equal to the Level.fatal category. Note that this method performs a panic at the end, even if log level is not enabled.

fn (mut l Log) error(s string)

error logs line s via send_output if Log.level is greater than or equal to the Level.error category.

fn (mut l Log) warn(s string)

warn logs line s via send_output if Log.level is greater than or equal to the Level.warn category.

fn (mut l Log) info(s string)

info logs line s via send_output if Log.level is greater than or equal to the Level.info category.

fn (mut l Log) debug(s string)

debug logs line s via send_output if Log.level is greater than or equal to the Level.debug category.

fn (mut f Log) free()

free frees the given Log instance

fn (mut l Log) set_time_format(f TimeFormat)

set_time_format will set the log time format to a pre-defined format

fn (mut l Log) set_always_flush(should_flush_every_time bool)

set_always_flush called with true, will make the log flush after every single .fatal(), .error(), .warn(), .info(), .debug() call. That can be much slower, if you plan to do lots of frequent calls, but if your program exits early or crashes, your logs will be more complete.

fn (l Log) get_time_format() TimeFormat

get_time_format will get the log time format

fn (mut l Log) set_custom_time_format(f string)

set_custom_time_format will set the log custom time format refer to time/custom_format() for more information eg. 'MMMM Do YY N kk:mm:ss A' output like: January 1st 22 AD 13:45:33 PM

fn (l Log) get_custom_time_format() string

get_custom_time_format will get the log custom time format

fn (mut l Log) set_short_tag(enabled bool)

set_short_tag will set the log tag to it's short version eg. '[FATAL]'=>'[F]', '[ERROR]'=>'[E]','[WARN ]'=>'[W]','[INFO ]'=>'[I]','[DEBUG]'=>'[D]'

fn (l Log) get_short_tag() bool

get_short_tag will get the log short tag enable state

struct ThreadSafeLog {
	Log
pub mut:
	mu &sync.Mutex = sync.new_mutex()
}

ThreadSafeLog embeds Log, and adds a mutex field. It uses the mutex to synchronise accesses to the embedded Log.

fn (mut x ThreadSafeLog) free()

free frees the given ThreadSafeLog instance.

fn (mut x ThreadSafeLog) set_level(level Level)

set_level changes the log level

fn (mut x ThreadSafeLog) set_always_flush(should_flush bool)

set_always_flush called with true, will make the log flush after every single .fatal(), .error(), .warn(), .info(), .debug() call. That can be much slower, if you plan to do lots of frequent calls, but if your program exits early or crashes, your logs will be more complete.

fn (mut x ThreadSafeLog) debug(s string)

debug logs a debug message

fn (mut x ThreadSafeLog) info(s string)

info logs an info messagep

fn (mut x ThreadSafeLog) warn(s string)

warn logs a warning message

fn (mut x ThreadSafeLog) error(s string)

error logs an error message

fn (mut x ThreadSafeLog) fatal(s string)

fatal logs a fatal message, and panics