Logging Plugin

A Logging Plugin records messages to an arbitrary sink (console, file, network, etc.) with four severity levels: ERROR, WARN, INFO, and DEBUG.

API Overview

The LoggingPlugin API (pntos-api/src/pntos/api/plugins/logging.py) only defines one method beyond CommonPlugin:

    def log(
        self,
        source_plugin_type: PluginType,
        source_plugin_identifier: str,
        level: LoggingLevel,
        message: str,
    ) -> None:
        """
        Log a string to the logging plugin's sink.

        Args:
            source_plugin_type (PluginType): Information on the plugin that sent the logout.
            source_plugin_identifier (str): Information on the plugin that sent the logout.
            level (LoggingLevel): The event severity.
            message (str): The string contents to be logged.
        """
        pass

The LoggingPlugin.log() method accepts a message along with context: source_plugin_type, source_plugin_identifier, and log level.

Logging Levels

Level	Value	Description
`ERROR`	0	Program error state requiring inspection.
`WARN`	1	Possible unintended state that may indicate a bug.
`INFO`	2	Informational output indicating correct operation.
`DEBUG`	3	Detailed debugging information about plugin state and behavior.

Logging From Another Plugin

Plugins log messages through Mediator.log_message():

    @abstractmethod
    def log_message(self, level: LoggingLevel, message: str) -> None:
        """
        Log a message.

        Send a loggable message to the system, to be logged through the current
        logging infrastructure enabled (e.g. the console, a logfile, etc.).

        Args:
            level (LoggingLevel)
            message (str)
        """
        pass

This is almost identical to LoggingPlugin.log() except that Mediator.log_message omits the first two parameters since it already knows the plugin’s type and identifier. For example, when any plugin (e.g., a UiPlugin) calls:

mediator.log_message(LoggingLevel.INFO, "Ui initialized.")

The Mediator could internally call:

logging_plugin.log(UiPlugin, "Cobra Ui Plugin", LoggingLevel.INFO, "Ui initialized.")

Note

There may be cases where a Mediator implementation does not use the logging plugin. For instance, the StandardMediator will simply print log messages to the terminal until a LoggingPlugin.log() is initialized.

Cobra Implementation: StandardLoggingPlugin

The StandardLoggingPlugin (pntos-cobra/src/pntos/cobra/standard_plugins/StandardLoggingPlugin.py) logs to the console. Given:

logging_plugin.log(UiPlugin, "Cobra Ui Plugin", LoggingLevel.INFO, "Ui initialized.")

The terminal output is:

[01/02/2025 12:30:45] [UiPlugin] [INFO] Ui initialized.

Configuration parameters:

The following configuration parameters are passed into the constructor of the StandardLoggingPlugin:

Parameter	Type	Default	Description
`colorize`	`bool`	`True`	Prints colored log messages if true, uncolored if false.
`global_log_level`	`LoggingLevel`	`INFO`	Selects which log levels get printed. Any messages with a level greater than `global_log_level` will not be logged.
`date_time_format`	`str`	`'%d/%m/%Y %H:%M:%S'`	Specifies the date-time format according to the available format specifiers. See time.strftime() documentation for more info on supported formats.

Understanding `global_log_level`

The global_log_level filters messages by severity. A message prints only if its level is less than or equal to global_log_level:

`global_log_level`	ERROR	WARN	INFO	DEBUG
`ERROR` (0)	✓	✗	✗	✗
`WARN` (1)	✓	✓	✗	✗
`INFO` (2)	✓	✓	✓	✗
`DEBUG` (3)	✓	✓	✓	✓

For example, global_log_level=INFO (default) prints ERROR, WARN, and INFO but suppresses DEBUG messages. Set to DEBUG for verbose output during development, or WARN for minimal production output.

Note

All off-the-shelf Cobra apps using their default configurations should not have WARN messages. Recommended settings: WARN (minimal output) or INFO (basic feedback).