Monitor Utils

M

class djem.utils.mon.M(name, parent=None)

An individual monitor instance, typically created and managed by Mon.

Tracks runtime, memory usage, and database query counts occurring between calls to start() and stop().

Parameters:

• name – The name of the monitor.

• parent – An optional parent M instance.

start()

Start the monitor.

stop()

Stop the monitor.

get_runtime()

Return the elapsed time in seconds between the start and end of the monitor.

Returns:

Elapsed time in seconds.

Raises:

RuntimeError – If the monitor has not been stopped.

get_mem_usage()

Return the memory usage (in MB) between the start and end of the monitor.

Returns:

Memory usage in MB.

Raises:

RuntimeError – If the monitor has not been stopped.

get_query_count()

Return the number of database queries executed between the start and end of the monitor.

Returns:

Number of database queries.

Raises:

RuntimeError – If the monitor has not been stopped.

reset()

Reset the start and end values of tracked metrics to allow reuse of the monitor instance. Gathered statistics are preserved.

get_total_string(include_name=True)

Return a summary string of the total runtime, query count, and memory usage of the monitor.

Parameters:

include_name – Whether to include the monitor’s name in the output.

Returns:

The summary string.

get_results(time=True, queries=False, mem=False)

Return formatted results for this monitor and its children.

If the monitor has no children, output is equivalent to get_total_string().

If the monitor has children, output is a formatted table showing statistics for each child, for each of the requested metrics. Children under each metric are sorted by the percentage of the parent’s total that is represented by that child. By default, only timing statistics are included in the table.

Parameters:

• time – Whether to include timing statistics in the table.

• queries – Whether to include database query statistics in the table.

• mem – Whether to include memory usage statistics in the table.

Returns:

The formatted results string.

Mon

class djem.utils.mon.Mon

A management class for individual monitors (M instances).

Allows simple start/stop operations by name, and supports nesting monitors to provide more in-depth profiling of code sections. Any number of nested monitors are supported, they can be included in loops, etc. Parent monitors will accumulate statistics from their child monitors, including number of times called and min/max/avg values for time, queries, and memory usage.

The stop() method returns the stopped M instance for the named monitor, allowing access to its statistics and results.

Basic usage:

from djem import Mon

Mon.start('my_monitor')
# ... code to monitor ...
print(Mon.stop('my_monitor'))

Nested usage:

from djem import Mon

Mon.start('outer_monitor')
# ... code to monitor ...

Mon.start('inner_monitor')
# ... code to monitor ...
Mon.stop('inner_monitor')

print(Mon.stop('outer_monitor').get_results())

classmethod start(name)

Start a new monitor with the given name. Another monitor with the same name cannot be active at the same time.

If another monitor is already active, it will become the parent of the new monitor being started. The new monitor will become the parent of any subsequently started monitors, until it is stopped.

Parameters:

name – The name of the monitor to start.

Raises:

RuntimeError – If a monitor with the given name is already active.

classmethod stop(name)

Stop the monitor with the given name and return the M instance.

The stopped monitor’s parent, if any, becomes the current parent for subsequently started monitors.

Parameters:

name – The name of the monitor to stop.

Returns:

The stopped M instance.

Raises:

RuntimeError – If no monitor with the given name is active.

classmethod start_qlog()

Start logging database queries to the console.

Configure the django.db.backends logger to output at DEBUG level.

classmethod stop_qlog()

Stop logging database queries to the console.

Revert the django.db.backends logger to its original level.

classmethod reset()

Discard all active monitors.

mon()

djem.utils.mon.mon(name, allow_recursion=False)

A decorator to monitor the execution of a function using Mon.

When the function is called, a monitor with the given name is started. The monitor is stopped after the function completes, and the results are printed to the console.

If a monitor with the given name is already running (for example, due to recursion), a RuntimeError is raised, unless allow_recursion is set to True. In that case, a unique name is generated for each recursive invocation by appending an incrementing integer suffix to the base name.

Usage:

from djem import mon

@mon('my_monitor')
def my_function():
    # ... code to monitor ...

Any usage of Mon within the context of the decorated function will be nested within the monitor created by the decorator.

Parameters:

• name – The name of the monitor.

• allow_recursion – Whether to allow recursive invocations by generating unique monitor names.

Raises:

RuntimeError – If a monitor with the given name is already running and allow_recursion is False.