qpanda3_runtime.toolbox.tracker.tracker_ui#

Classes#

Tracker

User interface for tracking operations with three usage patterns.

TrackerRef

Reference wrapper for tracker instances in decorator scenarios.

Functions#

tracker(service[, ref, data])

Decorator for automatic function tracking.

Module Contents#

class qpanda3_runtime.toolbox.tracker.tracker_ui.Tracker(service: qpanda3_runtime.toolbox.tracker.tracker_system.TrackerSystem, name: str = None, data: Dict[str, Any] = None)#

User interface for tracking operations with three usage patterns.

This class provides a unified interface for tracking operations with support for manual tracking, context manager usage, and decorator-based tracking.

Variables:

is_active (bool) – Indicates whether the tracker is currently active.

Examples

>>> # Manual tracking
>>> tracker = Tracker(service)
>>> tracker.start("operation_name")
>>> tracker.record({"key": "value"})
>>> tracker.end()

>>> # Context manager usage
>>> with Tracker(service, name="operation") as t:
...     t.record({"data": 123})

>>> # Decorator usage
>>> @tracker(service)
... def my_function():
...     pass
start(context_name: str, labels: List[str] = None, data: Dict[str, Any] = None) → Tracker#

Start tracking an operation.

Parameters:

  • context_name (str) – Name of the operation or context being tracked.

  • labels (List[str], optional) – List of labels to categorize the tracking session.

  • data (Dict[str, Any], optional) – Initial data to record for this tracking session.

Returns:

Self reference for method chaining.

Return type:

Tracker

Raises:

RuntimeError – If the tracker is already active or service is not available.

end(result_data: Dict[str, Any] = None, labels: List[str] = None) → Tracker#

End the current tracking session.

Parameters:

  • result_data (Dict[str, Any], optional) – Result data to record at the end of the operation.

  • labels (List[str], optional) – Additional labels to apply to the end record.

Returns:

Self reference for method chaining.

Return type:

Tracker

Notes

If the tracker is not active, this method does nothing and returns the tracker instance unchanged.

record(data: Dict[str, Any], labels: List[str] = None) → Tracker#

Record data during an active tracking session.

Parameters:

  • data (Dict[str, Any]) – Data to record in the current tracking session.

  • labels (List[str], optional) – Labels to associate with this data record.

Returns:

Self reference for method chaining.

Return type:

Tracker

Raises:

RuntimeError – If the tracker is not active when attempting to record data.

exit_broken_context() → None#

Exit a broken context when used as a context manager.

This method is called internally when a context manager exits due to an exception. It ensures proper cleanup of tracking state.

property is_active: bool#

Check if the tracker is currently active.

Returns:

True if the tracker is actively tracking, False otherwise.

Return type:

bool

get_current_record() → qpanda3_runtime.toolbox.tracker.tracker_trace.TrackerTrace#

Get the current tracking record.

Returns:

The current trace record if tracking is active.

Return type:

TrackerTrace

Notes

Returns None if no tracking session is active or if the service does not have a current trace.

class qpanda3_runtime.toolbox.tracker.tracker_ui.TrackerRef(name: str = '')#

Reference wrapper for tracker instances in decorator scenarios.

This class provides a way to reference a tracker instance from within a decorated function without direct access to the tracker object.

Variables:

  • name (str) – Reference name for identification.

  • is_active (bool) – Indicates whether the referenced tracker is currently active.

Examples

>>> ref = TrackerRef("my_tracker")
>>> @tracker(service, ref=ref)
... def my_function():
...     ref.record({"data": "value"})
name = ''#
tracker = None#
record(data: Dict[str, Any], labels: List[str] = None) → None#

Record data through the referenced tracker.

Parameters:

  • data (Dict[str, Any]) – Data to record in the current tracking session.

  • labels (List[str], optional) – Labels to associate with this data record.

Raises:

RuntimeError – If the tracker reference is not properly initialized or if no tracker is currently active.

property is_active: bool#

Check if the referenced tracker is active.

Returns:

True if the referenced tracker exists and is active.

Return type:

bool

qpanda3_runtime.toolbox.tracker.tracker_ui.tracker(service: qpanda3_runtime.toolbox.tracker.tracker_system.TrackerSystem, ref: TrackerRef | None = None, data: Any = None)#

Decorator for automatic function tracking.

This decorator automatically tracks function execution including start time, end time, and any exceptions that occur.

Parameters:

  • service (TrackerSystem) – The tracking system service to use.

  • ref (TrackerRef, optional) – Tracker reference for accessing the tracker from within the decorated function.

  • data (Any, optional) – Additional data to associate with the tracking session.

Returns:

Decorator function that wraps the original function.

Return type:

function

Examples

>>> @tracker(service)
... def process_data(data):
...     return data * 2

>>> ref = TrackerRef()
>>> @tracker(service, ref=ref)
... def complex_operation():
...     ref.record({"step": "started"})
...     # operation logic