robocorp-log
module robocorp.log
Variables
- protocols
- version_info
Functions
critical
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).
warn
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).
info
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).
debug
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).
exception
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).
html
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:
process_snapshot
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.
console_message
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 '').
suppress_methods
Can be used as a context manager or decorator so that methods are not logged.
i.e.:
or
suppress_variables
Can be used as a context manager or decorator so that variables are not logged.
i.e.:
or
suppress
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:
is_sensitive_variable_name
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.
add_sensitive_variable_name
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.
add_sensitive_variable_name_pattern
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.
hide_from_output
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.
hide_strings_config
Can be used to configure heuristics on what should be hidden and what should not be hidden from the logs.
Example:
start_run
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.
end_run
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.
start_task
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.
end_task
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 pass/fail status of the taskmessage
: The message for a failed task
Note: robocorp-tasks calls this method automatically.
iter_decoded_log_format_from_stream
Iterates stream contents and decodes those as dicts.
Args:
stream
: The stream which should be iterated in (anything with areadlines()
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.
iter_decoded_log_format_from_log_html
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.
iter_decoded_log_format_from_log_html_contents
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.
verify_log_messages_from_messages_iterator
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:
verify_log_messages_from_decoded_str
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.
verify_log_messages_from_log_html
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.
verify_log_messages_from_stream
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.
setup_log
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 arepr(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 thelog.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 thelog.debug
,log.info
,log.warn
andlog.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 currentsys.stdout
/sys.stderr
.
Returns:
A context manager, so, it's possible to use this method with a with statement
so 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:
setup_auto_logging
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.
add_log_output
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
,gb
if no unit is passed it's consideredb
(bytes)). Note that the max size is not a hard guarantee, rather it's a guideline 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).
close_log_outputs
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.
add_in_memory_log_output
Adds a log output which is in-memory (receives a callable).
Args:
write
: A callable which will be called aswrite(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
Class IContextManager
Typing for a "generic" context manager.
Class IRedactConfiguration
Properties
dont_hide_strings
This provides the set of strings that should not be hidden from the logs.
The default strings that should not be hidden are: 'None', 'True', 'False'
hide_strings
This provides the set of strings that should be hidden from the logs.
Enums
FilterLogLevel
An enumeration.
Values
- DEBUG = debug
- WARN = warn
- INFO = info
- CRITICAL = critical
- NONE = none