You're reading the documentation of the v0.11. For the latest released version, please have a look at v0.12.

Logging

To log with Perceval you can either use a built-in Perceval logger or the python one. By default, our logger will be used.

To log the perceval messages with the python logger, use this method:

from perceval.utils import use_python_logger
use_python_logger()

To switch back to using perceval logger, use:

from perceval.utils import use_perceval_logger
use_perceval_logger()

Note

If you use the python logger, use directly the module logging of python to configure it (except for channel configuration)

This module defines functions and classes which implement a flexible event logging system for any Perceval script.

It is build to work similarly as the python logging module.

Logger

A logger instance is created the first time Perceval is imported.

In order to use it you’ll just need to import it:

from perceval.utils import get_logger

To log a message, you can use it the same way as the python logger:

from perceval.utils import get_logger
get_logger().info('I log something as info')
# or
logger = get_logger()
logger.info('1st message')
logger.info('2nd message')

Saving log to file

By default the log are not saved in a file.

If order to enable / disable the writing of logs in a file, use the following methods:

from perceval.utils import get_logger
get_logger().enable_file()
get_logger().disable_file()

When this feature is enabled, log files are written to Perceval persistent data folder and the path of the file will be printed when your script starts writing inside it.

Levels

You can use the logger to log message at different level. Each level represent a different type of message.

The level are listed by ascending order of importance in the following table.

Log level	Perceval call	Usage
DEBUG	`level.debug`	Detailed technical information, typically of interest only when diagnosing problems.
INFO	`level.info`	Confirmation of things working as expected.
WARNING	`level.warn`	An indication that something unexpected happened, or indicative of some problem in the near future. The software is still working as expected.
ERROR	`level.err`	Due to a more serious problem, the software has not been able to perform some function.
CRITICAL	`level.critical`	A serious error, indicating that the program itself is unable to continue running normally or has crashed.

Example

from perceval.utils import get_logger
get_logger().info('I log something as info')
get_logger().critical('I log something as critical')

Channels

You can also log in a specific channel. A channel is like a category. Each channel can have its own configuration, which means each channel can have a different level. If the channel is not specified, the message is logged in the user channel.

Note

If you are a Perceval user, you should only write log in the channel user.

Channel	Default level	Usage
`general`	off	General info: Technical info, track the usage of features
`resources`	off	Usage info about our backends or remote platform GPU (exqalibur)
`user`	warning	Channel to use as a Perceval user & warnings (such as deprecated methods or arguments)

Example

from perceval.utils.logging import get_logger, channel
get_logger().info('I log something as info in channel user', channel.user)

To set a level for a channel, use the following method:

from perceval.utils import get_logger
get_logger().set_level(level, channel)

Example

from perceval.utils.logging import get_logger, level, channel
get_logger().set_level(level.info, channel.general)

Logger configuration

For logging to be useful, it needs to be configured, meaning setting the levels for each channel and if log are saved in a file. Setting a level for a channel means that any log with a less important level will not be displayed/saved.

In most cases, only the user & general channel needs to be so configured, since all relevant messages will be logged here.

Example

from perceval.utils.logging import get_logger, channel, level
logger = get_logger()
logger.enable_file()
logger.set_level(level.info, channel.resources)
logger.set_level(level.err, channel.general)

Note

The logger configuration can be saved on your hard drive so you don’t have to configure the logger each time you use perceval. When saved, it is written to a file in Perceval persistent data folder.

In order to configure it you have to use the LoggerConfig.

class perceval.utils.logging.config.LoggerConfig

This class represent the logger configuration as a dictionary and can be used to save it into persistent data. On class initialization, the configuration will be loaded from persistent data.

disable_file()

Disable to save the log into a file in the configuration

Warning: this will not change the current logger file saving, but only the file saving of the current LoggerConfig instance

enable_file()

Enable to save the log into a file in the configuration

Warning: this will not change the current logger file saving, but only the file saving of the current LoggerConfig instance

reset(): Reset the logger configuration to its default value, which is: - Disable file - Channel user at level warning - Channels general & resources off

save(): Save the current logger configuration in the persistent data

set_level(level, channel)

Set the level of a channel in the configuration

Warning: this will not change the current logger level but only the level of the channel in the current LoggerConfig instance

Parameters:

level (level) – _description_
channel (channel) – _description_

use_perceval_logger()

Set the config to use the perceval logger

Warning: this will not change the current logger level, but only the level of the channel in the current LoggerConfig instance

use_python_logger()

Set the config to use the python logger

Warning: this will not change the current logger level but only the level of the channel in the current LoggerConfig instance

After configuring your LoggerConfig, you can apply it to the current logger:

from perceval.utils.logging import get_logger, LoggerConfig, level, channel
logger_config = LoggerConfig()
logger_config.enable_file()
logger_config.set_level(level.info, channel.user)
get_logger().apply_config(logger_config)

Log format

On the console the log will appear with the format:

[log_level] message

In the file, the log will be save to the format:

[yyyy-mm-dd HH:MM:SS.fff]channel_first_letter[level_first_letter] message

Log exceptions

If the general channel level is at least on critical and save in file is enable, uncaught exception will be logged and saved on disk with their callstack.