module robocorp.log

Source: __init__.py:0

Variables

• protocols
• version_info

function critical

Source: __init__.py:105

Adds a new logging message with a critical (error) level.

Args:

• message: The message which should be logged.

Example:

Note:

Formatting converts all objects given to str. If you need custom formatting please pre-format the string. i.e.: critical(f'Failed because {obj!r} is not {expected!r}.')

Note:

A new line is automatically added at the end of the message.

Note:

See: setup_log() for configurations which may filter out the logged calls and also print it to a stream (such stdout/stderr).

function warn

Source: __init__.py:132

Adds a new logging message with a warn level.

Args:

• message: The message which should be logged.

Example:

Note:

Formatting converts all objects given to str. If you need custom formatting please pre-format the string. i.e.: warn(f'Did not expect {obj!r}.')

Note:

A new line is automatically added at the end of the message.

Note:

See: setup_log() for configurations which may filter out the logged calls and also print it to a stream (such stdout/stderr).

function info

Source: __init__.py:159

Adds a new logging message with an info level.

Args:

• message: The message which should be logged.

Example:

Note:

Formatting converts all objects given to str. If you need custom formatting please pre-format the string. i.e.: info(f'Received value {obj!r}.')

Note:

A new line is automatically added at the end of the message.

Note:

See: setup_log() for configurations which may filter out the logged calls and also print it to a stream (such stdout/stderr).

function debug

Source: __init__.py:187

Adds a new logging message with an debug level.

Args:

• message: The message which should be logged.

Example:

Note:

Formatting converts all objects given to str. If you need custom formatting please pre-format the string. i.e.: debug(f'Received value {obj!r}.')

Note:

A new line is automatically added at the end of the message.

Note:

See: setup_log() for configurations which may filter out the logged calls and also print it to a stream (such stdout/stderr).

function exception

Source: __init__.py:215

Adds to the logging the exceptions that's currently raised.

Args:

• message: If given an additional error message to be shown.

Note:

In general this method does NOT need to be called as exceptions found are automatically tracked by the framework.

Note:

A new line is automatically added at the end of the message (if a message was given for logging).

function html

Source: __init__.py:239

Adds html contents to the log.

Args:

• html: The html content to be embedded in the page.
• level: The level of the message ("INFO", "WARN" or "ERROR")

Example adding an image:

function process_snapshot

Source: __init__.py:259

Makes a process snapshot and adds it to the logs.

A process snapshot can include details on the python process and subprocesses and should add a thread dump with the stack of all running threads.

function console_message

Source: __init__.py:302

Shows a message in the console and also adds it to the log output.

Args:

Messages from the framework: - "regular": Some regular message. - "important": Some message which deserves a bit more attention. - "task_name": The task name is being written. - "error": Some error message. - "traceback": Some traceback message. - stream: If specified this is the stream where the message should also be written. - if not specified (_SentinelUseStdout) it's written to sys.stdout by default. - if None it's not written. - flush: Whether we should flush after sending the message (if None it's flushed if the end char ends with '').

function suppress_methods

Source: __init__.py:409

Can be used as a context manager or decorator so that methods are not logged.

i.e.:

or

function suppress_variables

Source: __init__.py:430

Can be used as a context manager or decorator so that variables are not logged.

i.e.:

or

function suppress

Source: __init__.py:479

API to suppress logging to be used as a context manager or decorator.

By default suppresses everything and its actual API is something as:

def suppress(variables:bool = True, methods:bool = True): ...

Args:

• variables: Whether variables should be suppressed in the scope.

• methods: Whether method calls should be suppressed in the scope.

Usage as a decorator:

Usage as a decorator suppressing only variables:

Usage as a context manager:

function is_sensitive_variable_name

Source: __init__.py:528

Returns true if the given variable name should be considered sensitive.

Args:

• variable_name: The variable name to be checked.

Returns: True if the given variable name is considered to be sensitive (in whichcase its value should be redacted) and False otherwise.

function add_sensitive_variable_name

Source: __init__.py:542

Marks a given variable name as sensitive

(in this case any variable containing the given variable_name will be redacted).

Note that this will add a patterns where any variable containing the given variable name even as a substring will be considered sensitive.

Args:

• variable_name: The variable name to be considered sensitive.

function add_sensitive_variable_name_pattern

Source: __init__.py:558

Adds a given pattern to consider a variable name as sensitive.

Any variable name matching the given pattern will have its value redacted.

Args:

• variable_name_pattern: The variable name pattern to be consideredsensitive.

function hide_from_output

Source: __init__.py:571

Should be called to hide sensitive information from appearing in the output.

Note that any variable assign or argument which is set to a name containing the string:

'password' or 'passwd'

Will be automatically hidden and it's also possible to add new names to be automatically redacted withe the methods: add_sensitive_variable_name and add_sensitive_variable_name_pattern.

Args:

• string_to_hide: The string that should be hidden from the output.

function start_run

Source: __init__.py:595

Starts a run session (adds the related event to the log).

Args:

• name: The name of the run.

Note: robocorp-tasks calls this method automatically.

function end_run

Source: __init__.py:609

Finishes a run session (adds the related event to the log).

Args:

• name: The name of the run.
• status: The run status.

Note: robocorp-tasks calls this method automatically.

function start_task

Source: __init__.py:624

Starts a task (adds the related event to the log).

Args:

• name: The name of the task.
• libname: The library (module name) where the task is defined.
• source: The source of the task.
• lineno: The line number of the task in the given source.
• doc: The documentation for the task.

Note: robocorp-tasks calls this method automatically.

function end_task

Source: __init__.py:644

Ends a task (adds the related event to the log).

Args:

• name: The name of the task.
• libname: The library (module name) where the task is defined.
• status: The source of the task.
• message: The line number of the task in the given source.

Note: robocorp-tasks calls this method automatically.

function iter_decoded_log_format_from_stream

Source: __init__.py:664

Iterates stream contents and decodes those as dicts.

Args:

• stream: The stream which should be iterated in (anything with a readlines() method which should provide the messages encoded in the internal format).

Returns: An iterator which will decode the messages and provides a dictionary foreach message found.

Example of messages provided:

• Note: the exact format of the messages provided is not stable acrossreleases.

function iter_decoded_log_format_from_log_html

Source: __init__.py:695

Reads the data saved in the log html and provides decoded messages (dicts).

Returns: An iterator which will decode the messages and provides a dictionary for each message found.

Example of messages provided:

• Note: the exact format of the messages provided is not stable acrossreleases.

function verify_log_messages_from_messages_iterator

Source: __init__.py:755

Helper for checking that the expected messages are found in the given messages iterator.

Can also check if a message is not found.

Args:

• messages_iterator: An iterator over the messages found.
• expected: The messages which are expected to be found. If some message expected to be found is not found an AssertionError will be raised.
• not_expected: The messages that should not appear.

Example:

Note: if one of the key entries is __check__ the value will be considered a callable which should return True or False to determine if a match was made.

Example:

function verify_log_messages_from_decoded_str

Source: __init__.py:836

Verifies whether the given messages are available or not in the decoded messages.

Args:

• s: A string with the messages already decoded (where messages areseparated by lines and each message is a json string to be decoded).
• expected: The messages expected.
• not_expected: The messages that should not appear.

See: verify_log_messages_from_messages_iterator for more details on the matching of messages.

function verify_log_messages_from_log_html

Source: __init__.py:894

Verifies whether the given messages are available or not in the decoded messages.

Args:

• log_html: The path to the log_html where messages were embedded.
• expected: The messages expected.
• not_expected: The messages that should not appear.

See: verify_log_messages_from_messages_iterator for more details on the matching of messages.

function verify_log_messages_from_stream

Source: __init__.py:914

Verifies whether the given messages are available or not in the decoded messages.

Args:

• stream: A stream from where the encoded messages are expected to be read from.
• expected: The messages expected.
• not_expected: The messages that should not appear.

See: verify_log_messages_from_messages_iterator for more details on the matching of messages.

function setup_log

Source: __init__.py:970

Setups the log "general" settings.

Args:

• max_value_repr_size: This is the maximum number of chars which may be used for a repr (values are clipped if a repr(obj) would return a bigger representation). May be passed directly as the value as an int or a string with the value and associated unit.
• Accepted units are: k, m.
• Example: "1000k", "1m".

The default value for this setting is "200k".

• log_level: Messages with a level higher or equal to the one specified will be logged in the log.html.

The default value for this setting is "FilterLogLevel.DEBUG", so, any message logged with log.debug, log.info, log.warn and log.critical will be shown.

• output_log_level: Messages with a level higher or equal to the one specified will be printed to the output_stream configured.

The default value for this setting is "FilterLogLevel.NONE", so, any message logged with log.debug, log.info, log.warn and log.critical is not shown in the output.

• output_stream: It's possible to specify the stream to output contents to be printed in the log.debug, log.info, log.warn and log.critical calls. If all messages should be streamed to the same place it can be the output stream (or its name) or it can be a dict mapping each level to a different stream (or its name).
• Note: if sys.stdout/sys.stderr are used it's preferred to pass it asa literal ("stdout" or "stderr") as if the stream is redirected it'llstill print to the current sys.stdout / sys.stderr.

Returns: A context manager, so, it's possible to use this method with a with statementso that the configuration is reverted to a previous configuration whenthe context manager exits (if not called with a with statement thenthe values won't be reverted).

Example:

Setting the max repr size:

Example:

Configuring to log only log.critical:

Example:

Configuring to print log.warn messages to sys.stdout and log.criticalmessages to sys.stderr:

function setup_auto_logging

Source: __init__.py:1104

Sets up automatic logging.

This must be called prior to actually importing the modules which should be automatically logged.

Args:

• config: The configuration specifying how modules should be automatically logged.

If not passed, by default all files which are library files (i.e.: in the python Lib or site-packages) won't be logged and all files which are not library files will be fully logged.

Returns a context manager which will stop applying the auto-logging to new loaded modules. Note that modules which are already being tracked won't stop being tracked.

function add_log_output

Source: __init__.py:1137

Adds a log output which will write the contents to the given output directory.

Optionally it's possible to collect all the output when the run is finished and put it into a log.html file.

Args:

• output_dir: The output directory where the log contents should be saved.
• max_file_size: The maximum file size for one log file (as a string with
• the value and the unit -- accepted units are: b, kb, mb, gbif no unit is passed it's considered b (bytes)).Note that the max size is not a hard guarantee, rather it's aguideline that the logging tries to follow (usually it's very close,although on degenerate cases it can be considerably different).
• max_files: The maximum amount of files which can be added (if more would be needed the oldest one is erased).
• log_html: If given this is the path (file) where the log.html contents should be written (the log.html will include all the logs from the run along with a viewer for such logs).
• log_html_style: The style to be used for the log.html.
• min_messages_per_file: This is the minimum number of messages that need to be added to a file for it to be rotated (if messages are too big this may make the max_file_size be surpassed). This is needed to prevent a case where a whole new file could be created after just a single message if the message was too big for the max file size.

Note:

It's Ok to add more than one log output, but if 2 log outputs point to the same directory there will be conflicts (in the future this should generate an error).

function close_log_outputs

Source: __init__.py:1201

This method must be called to close loggers.

Note that some loggers such as the one which outputs html needs to bo closed to actually write the output.

function add_in_memory_log_output

Source: __init__.py:1218

Adds a log output which is in-memory (receives a callable).

Args:

• write: A callable which will be called as write(msg) whenevera message is sent from the logging.

Returns: A context manager which can be used to automatically remove andclose the related logger.

class ConsoleMessageKind

Source: __init__.py:271

enum FilterLogLevel

Source: __init__.py:939

An enumeration.

Values

• DEBUG = debug
• WARN = warn
• INFO = info
• CRITICAL = critical
• NONE = none

class IContextManager

Source: __init__.py:950

Typing for a "generic" context manager.