acme.runtime.Logging.Logging

class documentation

class Logging:

Wrapper class for the logging subsystem. This class wraps the initialization of the logging subsystem and provides convenience methods for printing log, error and warning messages to a logfile and to the console.

Static Method	`configUpdate`	Handle configuration update.
Static Method	`console`	Print a message or object to the console.
Static Method	`consoleClear`	Clear the console screen.
Static Method	`consolePrompt`	Read a line from the console. Catch EOF (^D) and Keyboard Interrup (^C). In that case None is returned.
Static Method	`consoleStatusWait`	Return and show a progress spinner and message while waiting for a block to complete.
Static Method	`consoleSyntax`	Print a piece of code or data with syntax highlighting to the console. This function does not format the code.
Static Method	`consoleWidth`	Return the current console width.
Static Method	`finit`	End logging.
Static Method	`init`	Init the logging system.
Static Method	`inspect`	Output a very comprehensive description of an object.
Static Method	`log`	Print a log message with log-level INFO.
Static Method	`logDebug`	Print a log message with log-level DEBUG.
Static Method	`logDivider`	Add a divider line to the log.
Static Method	`logErr`	Print a log message with log-level ERROR.
Static Method	`loggingActor`	Actor method to handle logging in the background.
Static Method	`logRequest`	Log request.
Static Method	`logWarn`	Print a log message with log-level WARNING.
Static Method	`logWithLevel`	Fallback log method when the level is a directly given argument. # TODO
Static Method	`off`	Switch logging off. Remember the last logLevel
Static Method	`on`	Switch logging on. Enable the last logLevel.
Static Method	`queueOff`	Disable the logging queue. This can be used to get immediate feedback, e.g during startup.
Static Method	`queueOn`	Enable the logging queue. Whether the usage of the queue really happens depends on the configured queue size.
Static Method	`setEnableScreenLogging`	Set the `enableScreenLogging` attribute via a method call.
Static Method	`setLogLevel`	Set a new log level to the logging system.
Static Method	`stacktrace`	Output the current stacktrace to the log.
Class Variable	`enableBindingsLogging`	Flag to enable low-level logging in protocol bindings.
Class Variable	`enableFileLogging`	Flag to indicate whether file logging is enabled.
Class Variable	`enableQueue`	Flag to indicate whether the logging queue is enabled. Can be used to enable/disable the logging queue.
Class Variable	`enableScreenLogging`	Flag to indicate whether screen logging is enabled.
Class Variable	`filterSources`	List of log sources that will be filtered out. This is used to remove unwanted log messages from the output.
Class Variable	`isDebug`	Flag to indicate whether the log level is set to DEBUG.
Class Variable	`isInfo`	Flag to indicate whether the log level is set to INFO.
Class Variable	`isWarn`	Flag to indicate whether the log level is set to WARNING.
Class Variable	`lastLogLevel`	The last log level that was set. This is used to determine whether the log level has changed.
Class Variable	`logger`	The main logger for the logging subsystem.
Class Variable	`loggerConsole`	The rich console logger for the logging subsystem.
Class Variable	`maxLogMessageLength`	Maximum length of a log message. If the message is longer than this, it will be truncated.
Class Variable	`queue`	The queue for the logging messages. This is used to handle the logging processing in the background.
Class Variable	`queueSize`	The size of the logging queue. This is used to limit the number of log messages in the queue.
Class Variable	`ringBufferHandler`	The ring buffer handler for the logging subsystem. This is used to store log messages in a ring buffer.
Class Variable	`stackTraceOnError`	Flag to indicate whether to include stack traces in error logs.
Class Variable	`tableRowStyle`	Style for the table row background.
Class Variable	`terminalStyle`	Style for the terminal text in dark mode.
Class Variable	`terminalStyleError`	Style for the terminal error text.
Class Variable	`terminalStyleRGBTupple`	RGB tuple for the terminal text color.
Class Variable	`utcTime`	Flag to indicate whether to use UTC time for logging.
Class Variable	`worker`	The worker that handles the logging in the background.
Static Method	`_configureColors`	Configure the colors for the terminal output based on the given theme.
Static Method	`_log`	Internally adding various information to the log output.
Static Method	`_logMessageToLoggerConsole`	Log a message to the console logger. This is used to log messages to the console with the correct formatting.
Class Variable	`_basenames`	Dictionary to store the basenames of the source files. This is used to optimize the log output.
Class Variable	`_console`	The rich console object for the logging subsystem.
Class Variable	`_eventLogError`	Event handler for logging errors. This is used to trigger an event when an error is logged.
Class Variable	`_eventLogWarning`	Event handler for logging warnings. This is used to trigger an event when a warning is logged.
Class Variable	`_handlers`	List of log handlers for the logging subsystem. This is used to store the log handlers for the logging subsystem.
Class Variable	`_logWorker`	The background worker for the logging subsystem. This is used to handle the logging in the background.
Class Variable	`_richHandler`	The rich handler for the logging subsystem. This is used to format the log messages for the console.

@staticmethod

def configUpdate(eventData: EventData): ¶

Handle configuration update.

@staticmethod

Print a message or object to the console.

@staticmethod

def consoleClear(): ¶

Clear the console screen.

@staticmethod

def consolePrompt(prompt: str, nl: bool | None = True, default: str | None = None) -> str: ¶

Read a line from the console. Catch EOF (^D) and Keyboard Interrup (^C). In that case None is returned.

@staticmethod

def consoleStatusWait(msg: str) -> Status: ¶

Return and show a progress spinner and message while waiting for a block to complete.

Example

with consoleStatusWait('waiting...'):: . . .

Parameters
msg:`str`	Message to display

Returns
`Status`	Status object.

@staticmethod

def consoleSyntax(code: str, language: str): ¶

Print a piece of code or data with syntax highlighting to the console. This function does not format the code.

Parameters
code:`str`	A string with formatted code or data.
language:`str`	The language or type of data.

@staticmethod

def consoleWidth() -> int: ¶

Return the current console width.

@staticmethod

def finit(): ¶

End logging.

@staticmethod

def init(): ¶

Init the logging system.

@staticmethod

def inspect(obj: Any, immediate: bool = False): ¶

Output a very comprehensive description of an object.

Parameters
obj:`Any`	The object to inspect.
immediate:`bool`	Immediately log the message, don't put it into the log queue.

@staticmethod

def log(msg: Any, stackOffset: int | None = 0) -> str: ¶

Print a log message with log-level INFO.

Parameters
msg:`Any`	The log message.
stackOffset:`int \| None`	Optional offset for printing stacktraces.

Returns
`str`	Return the log msg again.

@staticmethod

def logDebug(msg: Any, stackOffset: int | None = 0) -> str: ¶

Print a log message with log-level DEBUG.

Parameters
msg:`Any`	The log message.
stackOffset:`int \| None`	Optional offset for printing stacktraces.

Returns
`str`	Return the log msg again.

@staticmethod

def logDivider(level: int | None = None, message: str | None = ''): ¶

Add a divider line to the log.

Parameters
level:`int \| None`	Loglevel for the message. If None, the the current log level is taken
message:`str \| None`	Optional message that is centered on the line.

@staticmethod

def logErr(msg: Any, showStackTrace: bool | None = True, exc: Exception | None = None, stackOffset: int | None = 0) -> str: ¶

Print a log message with log-level ERROR.

Parameters
msg:`Any`	The log message.
showStackTrace:`bool \| None`	Optional indicates whether a stacktrace shall be logged together with the error as well.
exc:`Exception \| None`	Optional exception to log.
stackOffset:`int \| None`	Optional offset for printing stacktraces.

Returns
`str`	Return the log msg again.

@staticmethod

def loggingActor() -> bool: ¶

Actor method to handle logging in the background.

Returns
`bool`	True if the actor should continue running, False otherwise.

@staticmethod

def logRequest(result: Result, data: bytes | JSON): ¶

Log request.

Parameters
result:`Result`	The result of the request.
data:`bytes \| JSON`	The request data. Either bytes or JSON dictionary.

@staticmethod

def logWarn(msg: Any, stackOffset: int | None = 0) -> str: ¶

Print a log message with log-level WARNING.

Parameters
msg:`Any`	The log message.
stackOffset:`int \| None`	Optional offset for printing stacktraces.

Returns
`str`	Return the log msg again.

@staticmethod

def logWithLevel(level: int, msg: Any, showStackTrace: bool | None = False, stackOffset: int | None = 0) -> str: ¶

Fallback log method when the level is a directly given argument. # TODO

@staticmethod

def off(): ¶

Switch logging off. Remember the last logLevel

@staticmethod

def on(): ¶

Switch logging on. Enable the last logLevel.

@staticmethod

def queueOff(): ¶

Disable the logging queue. This can be used to get immediate feedback, e.g during startup.

@staticmethod

def queueOn(): ¶

Enable the logging queue. Whether the usage of the queue really happens depends on the configured queue size.

@staticmethod

def setEnableScreenLogging(value: bool): ¶

Set the enableScreenLogging attribute via a method call.

Parameters
value:`bool`	New value for `enableScreenLogging`.

@staticmethod

def setLogLevel(logLevel: LogLevel): ¶

Set a new log level to the logging system.

Parameters
logLevel:`LogLevel`	New log level

@staticmethod

def stacktrace(startFrame: int | None = -10, skipEndFrames: int | None = 1): ¶

Output the current stacktrace to the log.

Parameters
startFrame:`int \| None`	Skip over a number of uninteresting frames at the beginning of the stack trace. The default is -10, meaning only log the last 10 stack frames.
skipEndFrames:`int \| None`	Number of stack frames to skip at the end of the stack trace. The default of 1 means to ignore the call to this logging function.

enableBindingsLogging: bool = ¶

Flag to enable low-level logging in protocol bindings.

enableFileLogging: bool = ¶

Flag to indicate whether file logging is enabled.

enableQueue: bool = ¶

Flag to indicate whether the logging queue is enabled. Can be used to enable/disable the logging queue.

enableScreenLogging: bool = ¶

Flag to indicate whether screen logging is enabled.

filterSources: tuple[str, ...] = ¶

List of log sources that will be filtered out. This is used to remove unwanted log messages from the output.

isDebug: bool = ¶

Flag to indicate whether the log level is set to DEBUG.

isInfo: bool = ¶

Flag to indicate whether the log level is set to INFO.

isWarn: bool = ¶

Flag to indicate whether the log level is set to WARNING.

lastLogLevel: LogLevel = ¶

The last log level that was set. This is used to determine whether the log level has changed.

logger = ¶

The main logger for the logging subsystem.

loggerConsole = ¶

The rich console logger for the logging subsystem.

maxLogMessageLength: int = ¶

Maximum length of a log message. If the message is longer than this, it will be truncated.

queue: Queue = ¶

The queue for the logging messages. This is used to handle the logging processing in the background.

queueSize: int = ¶

The size of the logging queue. This is used to limit the number of log messages in the queue.

ringBufferHandler: ACMERingBufferLogHandler = ¶

The ring buffer handler for the logging subsystem. This is used to store log messages in a ring buffer.

stackTraceOnError: bool = ¶

Flag to indicate whether to include stack traces in error logs.

tableRowStyle: Style = ¶

Style for the table row background.

terminalStyle: Style = ¶

Style for the terminal text in dark mode.

terminalStyleError: Style = ¶

Style for the terminal error text.

terminalStyleRGBTupple: tuple[int, ...] = ¶

RGB tuple for the terminal text color.

utcTime: bool = ¶

Flag to indicate whether to use UTC time for logging.

worker = ¶

The worker that handles the logging in the background.

@staticmethod

def _configureColors(theme: str): ¶

Configure the colors for the terminal output based on the given theme.

Parameters
theme:`str`	The name of the theme to use. Supported values are 'dark' and 'light'.

@staticmethod

def _log(level: int, msg: Any, stackOffset: int | None = 0, immediate: bool | None = False) -> str: ¶

Internally adding various information to the log output.

The stackOffset is used to determine the correct caller. It is set by a calling method in case the log information are re-routed.

Parameters
level:`int`	The log level.
msg:`Any`	The log message.
stackOffset:`int \| None`	Optional offset in the stack frame.
immediate:`bool \| None`	Immediately log the message, don't put it into the log queue.

Returns
`str`	The log msg.

@staticmethod

def _logMessageToLoggerConsole(level: int, msg: str, caller: inspect.Traceback, threadName: str): ¶

Log a message to the console logger. This is used to log messages to the console with the correct formatting.

Parameters
level:`int`	The log level of the message.
msg:`str`	The log message.
caller:`inspect.Traceback`	The caller information from the stack frame. The caller information is used to determine the source file and line number of the log message.
threadName:`str`	The name of the current thread.

_basenames: dict[str, str] = ¶

Dictionary to store the basenames of the source files. This is used to optimize the log output.

_console: Console = ¶

The rich console object for the logging subsystem.

_eventLogError = ¶

Event handler for logging errors. This is used to trigger an event when an error is logged.

_eventLogWarning = ¶

Event handler for logging warnings. This is used to trigger an event when a warning is logged.

_handlers: list[Any] = ¶

List of log handlers for the logging subsystem. This is used to store the log handlers for the logging subsystem.

_logWorker: BackgroundWorker = ¶

The background worker for the logging subsystem. This is used to handle the logging in the background.

_richHandler: ACMERichLogHandler = ¶

The rich handler for the logging subsystem. This is used to format the log messages for the console.