nanshe.util.prof module

The module prof provides support tracing and profiling.

Overview

The module prof provides a few primitives for tracing function calls and memory usage. In particular, it provides a trace logger that gives us feedback about arguments passed, the run time, the exception raised, etc. Decorators are available for wrapping functions and classes (all methods). In addition to the trace logger, a memory profiler is also provided, which can be run in a separate thread to get information about memory usage. The memory profiler requires psutil.

API

nanshe.util.prof.getSpecialLogger(logger_prefix, name, *args, **kwargs)

A fancy version of logging.getLogger, which takes a prefix and a name, which it joins together as the returned logger’s name.

Parameters:

• logger_prefix (str) – Prefix name to use to describe all loggers of this type.
• name (str) – The name of the function or module being logged.
• *args – Other arguments to pass through to getLogger. Currently, it takes no others.
• *kwargs – Other keyword arguments to pass through to getLogger. Currently, it takes no others.

Returns:

A logger with the given prefix and

subsequent name.

Return type:

logging.Logger

nanshe.util.prof.getTraceLogger(name, *args, **kwargs)

A fancy version of logging.getLogger, which adds the prefix TRACE to the name given.

Parameters:

• name (str) – The name of the function or module being logged.
• *args – Other arguments to pass through to getLogger. Currently, it takes no others.
• *kwargs – Other keyword arguments to pass through to getLogger. Currently, it takes no others.

Returns:

A logger with the given name.

Return type:

logging.Logger

nanshe.util.prof.getTraceMetaLogger(name, *args, **kwargs)

A fancy version of logging.getLogger, which adds the prefix TRACE.META to the name given.

Parameters:

• name (str) – The name of the function or module being logged.
• *args – Other arguments to pass through to getLogger. Currently, it takes no others.
• *kwargs – Other keyword arguments to pass through to getLogger. Currently, it takes no others.

Returns:

A logger with the given name.

Return type:

logging.Logger

nanshe.util.prof.log_call(logger, to_log_call=True, to_print_args=False, to_print_time=True, to_print_exception=False)

Takes a given logger and uses it to log entering and leaving the decorated callable. Intended to be used as a decorator that takes a few arguments.

Parameters:

logger (Logger) – Used for logging entry, exit and possibly arguments.

Keyword Arguments:  

• to_log_call (bool) – Whether to log call or not. This overrides all other arguments. It will be stored as a global variable on the function, which can be changed at runtime.
• to_print_args (bool) – Whether to output the arguments and keyword arguments passed to the function. This should not automatically be true as some arguments may not be printable or may be expensive to print. Thus, it should be up to the developer to use their own discretion. Further, we don’t want to break their existing code. It will be stored as a global variable on the function, which can be changed at runtime.
• to_print_time (bool) – Prints the time it took to run the wrapped callable.
• to_print_exception (bool) – Whether to print the traceback when an exception is raise. It will be stored as a global variable on the function, which can be changed at runtime.

Returns:

For performing the actual wrapping.

Return type:

log_call_decorator

nanshe.util.prof.log_class(logger, to_log_call=True, to_print_args=False, to_print_time=True, to_print_exception=False)

Takes a given logger and uses it to log entering and leaving all methods of the decorated class. Intended to be used as a decorator that takes a few arguments.

Parameters:

logger (Logger) – Used for logging entry, exit and possibly arguments.

Keyword Arguments:  

• to_log_call (bool) – Whether to log call or not. This overrides all other arguments. It will be stored as a global variable on the methods, which can be changed at runtime.
• to_print_args (bool) – Whether to output the arguments and keyword arguments passed to the function. This should not automatically be true as some arguments may not be printable or may be expensive to print. Thus, it should be up to the developer to use their own discretion. Further, we don’t want to break their existing code. It will be stored as a global variable on the methods, which can be changed at runtime.
• to_print_time (bool) – Prints the time it took to run the wrapped callable.
• to_print_exception (bool) – Whether to print the traceback when an exception is raise. It will be stored as a global variable on the methods, which can be changed at runtime.

Returns:

log_call_decorator(for wrapping)

nanshe.util.prof.memory_profiler(*args, **kwargs)

Runs forever get information about memory usage and dumping it to the logger provided at the given interval.

Parameters:logger (Logger) – Used for logging memory profiling information. Keyword Arguments:  interval (int or float) – Number of seconds to wait before issuing more profile information.