CPU time

Satella’s cpu_time helps your processes play nice with the overall CPU usage, ie. deferring non-critical tasks to until CPU usage falls lower than the average.

You can even check how much CPU is your process using.

cpu_time does this by periodically monitoring CPU’s usage and building your usage profile. The profile is refreshed each X minutes.

Warning

Note that running the following procedures will launch a background daemonic thread spawning to gather data. This thread will run only once, and it will be daemonic, but it will use some of the CPU. If you don’t call any of these, the thread won’t be spawned.

satella.instrumentation.cpu_time.calculate_occupancy_factor()

Get the average load between now and the time it was last called as a float, where 0.0 is LA=0 and 1.0 is LA=max_cores.

This will be the average between now and the time it was last called.

Warning

This in rare cases (being called the first or the second time) may block for up to 0.1 seconds

Returns:

a float between 0 and 1 telling you how occupied CPU-wise is your system.

Return type:

float

satella.instrumentation.cpu_time.sleep_cpu_aware(seconds, of_below=None, of_above=None, check_each=1)

Sleep for specified number of seconds.

Quit earlier if the occupancy factor goes below of_below or above of_above :param seconds: time to sleep in seconds, or a time string :param of_below: occupancy factor below which the sleep will return :param of_above: occupancy factor above which the sleep will return :param check_each: amount of seconds to sleep at once :return: whether was awoken due to CPU time condition

Parameters:
  • seconds (Union[str, float]) –

  • of_below (Optional[float]) –

  • of_above (Optional[float]) –

  • check_each (float) –

Return type:

bool

Here’s the primary thread you can use to work with things:

class satella.instrumentation.cpu_time.CPUTimeManager
static percentile(percent)

Return given percentile of current CPU time’s profile :param percent: float between 0 and 1 :return: the value of the percentile

Parameters:

percent (float) –

Return type:

float

static set_refresh_each(refresh)

Change the refresh interval for the CPU usage collection thread

Parameters:

refresh (Union[str, float, int]) –

Return type:

None

static set_window_size(window_size)

Set the time that should be observed in order to build an execution profile.

Parameters:

window_size (float) – time, in seconds

Return type:

None

And here’s a helpful variant of satella.coding.concurrent.IntervalTerminableThread:

class satella.instrumentation.cpu_time.CPUTimeAwareIntervalTerminableThread(seconds, max_sooner=None, percentile=0.3, wakeup_interval='3s', *args, **kwargs)

An IntervalTerminableThread that can call the loop a bit faster than usual, based of current CPU time metrics.

Parameters:
  • seconds (Union[str, float]) – time that a single looping through should take. This will include the time spent on calling .loop(), the rest of this time will be spent safe_sleep()ing. Can be alternatively a time string

  • max_sooner (Optional[float]) – amount of seconds that is ok to call this earlier. Default is 10% seconds.

  • percentile (float) – percentile that CPU usage has to fall below to call it earlier.

  • wakeup_interval (Union[str, float]) – amount of seconds to wake up between to check for _terminating status. Can be also a time string

Same concerns for terminate_on as in TerminableThread apply.

Note that this is called in the constructor’s thread. Use .prepare() to run statements that should be ran in new thread.

Parameters:
  • terminate_on – if provided, and loop() throws one of it, swallow it and terminate the thread by calling terminate(). Note that the subclass check will be done via isinstance so you can use the metaclass magic :) Note that SystemExit will be automatically added to list of terminable exceptions.

  • seconds (Union[str, float]) –

  • max_sooner (Optional[float]) –

  • percentile (float) –

  • wakeup_interval (Union[str, float]) –

abstract loop()

Override me!

Return type:

None

run()

Calls self.loop() indefinitely, until terminating condition is met

satella.instrumentation.cpu_time.get_own_cpu_usage()

Return own CPU usage (this process only)

Returns:

None if data not ready (just try again in some time), or a a namedtuple of (user, system, children_user, children_system, iowait) divided by number of seconds that passed since the last measure. The result is divided by passed time, so a 1 means 100% during the time, and 0.5 means exactly 50% of the CPU used.

Return type:

Optional[pcputimes]

satella.instrumentation.cpu_time.pCPUtimes

alias of pcputimes