Meters

Base Meter

Abstract base class for performance anomaly detection meters.

Defines Meter, which all concrete meters extend. Meters measure specific aspects of QGIS performance, emit anomalies when thresholds are exceeded, and can optionally record results into the profiler.

class qgis_profiler.meters.meter.MeterContext(name, group)[source]

Bases: NamedTuple

Context of a meter.

Parameters:

name (str)
group (str)

name: str: Alias for field number 0

group: str: Alias for field number 1

with_meter_suffix(suffix)[source]

Return a new context with the given suffix appended to the name.

Parameters:: suffix (str)
Return type:: MeterContext

class qgis_profiler.meters.meter.MeterAnomaly(context, duration_seconds)[source]

Bases: NamedTuple

Anomaly detected by a meter.

Parameters:

context (MeterContext)
duration_seconds (float)

context: MeterContext: Alias for field number 0

duration_seconds: float: Alias for field number 1

class qgis_profiler.meters.meter.Meter(supports_continuous_measurement=False)[source]

Bases: _QObjectStub

Abstract base class for meters to detect anomalies in QGIS performance.

Each concrete meter can be used as a decorator via the monitor() class method:

from qgis_profiler.meters.recovery_measurer import RecoveryMeasurer
from qgis_profiler.meters.thread_health_checker import MainThreadHealthChecker

@RecoveryMeasurer.monitor(name="Load Layers")
def load_layers():
    # Recovery time is measured after this function returns
    pass

@MainThreadHealthChecker.monitor(name="Heavy Processing")
def heavy_processing():
    # Thread health is monitored during execution
    pass

Parameters:: supports_continuous_measurement (bool)

anomaly_detected = <_qgis_stubs._StubSignal object>

abstract classmethod get()[source]

Get a singleton instance of the meter.

Return type:: Meter

classmethod monitor(function=None, *, name=None, group=None, name_args=None, connect_to_profiler=True, start_continuous_measuring=True, measure_after_call=False)[source]

Decorate a function to monitor it with this meter.

Set the meter context within a function call, start continuous measuring if supported, and optionally measure the meter after the function call. If the meter is disabled, nothing is done.

If you want to profile the anomalies found during the function call, connect to profiler using the connect_to_profiler argument.

Parameters:

function (Callable | None) – Provided here to support both @monitor and @monitor() syntax.
name (str | None) – Optional name for this context. If not provided, the name of the function being wrapped will be used.
group (str | None) – Optional group name for the context. If not provided, the group name is read from settings.
name_args (list[str] | None) – Optional list of argument names to include in the context name. If specified, the context name will include these argument values.
connect_to_profiler (bool) – Optional flag to connect to meter to a profiler if not yet connected.
start_continuous_measuring (bool) – Optional flag to start continuous measuring.
measure_after_call (bool) – Optional flag to measure the meter after the function call. For some meters this might be expensive.

Returns:

A callable decorator function that wraps the given function to set the meter context during the function call.

Return type:

Callable

property current_context: MeterContext: return The current context of the meter.

property is_connected_to_profiler: bool: return Whether the meter is connected to the profiler.

property supports_continuous_measuring: bool: Return whether the meter supports continuous measurement.

property enabled: bool: return Whether the meter is enabled.

property is_measuring: bool: Return whether the meter is currently measuring.

context(name, group)[source]

Context manager for the meter in certain context.

Parameters:

name (str)
group (str)

Return type:

Generator[MeterContext, None, None]

add_context(name, group)[source]

Add context to the context stack.

Parameters:

name (str)
group (str)

Return type:

None

pop_context()[source]

Remove the last context from the context stack if it exists.

Returns:: Context or None if context stack is empty.
Return type:: MeterContext | None

connect_to_profiler()[source]

Connect anomaly detection signal to profiler’s anomaly handling.

Establish a connection between the anomaly_detected signal and the _profile_anomaly handler to ensure anomalies are routed correctly.

Returns:: None
Return type:: None

measure()[source]

Measure once with the meter.

Signal anomaly_detected will be emitted if applicable.

Returns:: Duration in seconds or None if meter is disabled.
Return type:: float | None

start_measuring()[source]

Start the measurement process.

Returns:: A boolean indicating if the measurement process was initiated successfully.
Return type:: bool

stop_measuring()[source]

Stop the continuous measurement process if applicable.

Return type:: None

cleanup()[source]

Cleanup the meter and stop measuring if continuous measuring is supported.

Return type:: None

abstract reset_parameters()[source]

Reset the meter parameters based on setting values.

Return type:: None

Recovery Measurer

Meter that measures how long QGIS takes to recover after a freeze.

Contains RecoveryMeasurer, which repeatedly processes main-thread events and reports an anomaly when the recovery time exceeds a configurable threshold.

class qgis_profiler.meters.recovery_measurer.RecoveryMeasurer(process_event_count, threshold_s, timeout_s)[source]

Bases: Meter

Measure how long QGIS takes to become fully responsive after a freeze.

Parameters:

process_event_count (int)
threshold_s (int)
timeout_s (int)

classmethod get()[source]

Return the singleton RecoveryMeasurer instance.

Return type:: RecoveryMeasurer

reset_parameters()[source]

Reset measurement parameters from current settings.

Return type:: None

Thread Health Checker

Meter that monitors main thread responsiveness.

Contains MainThreadHealthChecker, which polls the main thread from a background thread and reports an anomaly when the response time exceeds a configurable threshold.

class qgis_profiler.meters.thread_health_checker.ThreadPoller(poll_interval_ms)[source]

Bases: _QObjectStub

Poll the main thread at regular intervals from a background thread.

Parameters:: poll_interval_ms (int)

poll = <_qgis_stubs._StubSignal object>

start()[source]

Start polling.

Return type:: None

stop()[source]

Stop polling.

Return type:: None

elapsed_ms_after_last_ping()[source]

Return elapsed milliseconds since last ping.

Return type:: int

set_poll_finished()[source]

Mark polling as finished.

Return type:: None

class qgis_profiler.meters.thread_health_checker.MainThreadHealthChecker(poll_interval_s, threshold_s)[source]

Bases: Meter

Monitors the health of the main application thread.

Provides mechanisms to measure delays between thread pings and detect anomalies based on a defined threshold.

Parameters:

poll_interval_s (float)
threshold_s (float)

classmethod get()[source]

Return the singleton MainThreadHealthChecker instance.

Return type:: MainThreadHealthChecker

classmethod monitor(function=None, *, name=None, group=None, name_args=None, connect_to_profiler=True, start_continuous_measuring=True, measure_after_call=False)[source]

Decorate a function to monitor it, warning if measure_after_call is used.

Parameters:

function (Callable | None)
name (str | None)
group (str | None)
name_args (list[str] | None)
connect_to_profiler (bool)
start_continuous_measuring (bool)
measure_after_call (bool)

Return type:

Callable

reset_parameters()[source]

Reset measurement parameters from current settings.

Return type:: None

Map Rendering Meter

Meter that monitors map canvas rendering times.

Contains MapRenderingMeter, which listens to map canvas render signals and reports an anomaly when rendering exceeds a configurable time threshold.

class qgis_profiler.meters.map_rendering.MapRenderingMeter(threshold_s)[source]

Bases: Meter

Measures the time it takes to fully render the map.

Parameters:: threshold_s (float)

classmethod get()[source]

Return the singleton MapRenderingMeter instance.

Return type:: MapRenderingMeter

reset_parameters()[source]

Reset measurement parameters from current settings.

Return type:: None