hpcflow.sdk.monitoring.app.MonitoringMixin#

class hpcflow.sdk.monitoring.app.MonitoringMixin#

Bases: object

Connect submission monitoring to a BaseApp host.

The host provides configuration, workflow construction, scheduler adapters, logging, data directories, and the protected _get_app_func binding hook. It owns initialization and callable caching; this mixin has no initializer or separate mutable state. Workflow-reference resolution and cancellation remain the host’s responsibility.

Methods

clear_registry

Delete submission registries without loading configuration or workflows.

Attributes

get_known_submissions

Retrieve JSON-compatible snapshots from the monitoring registry.

show

Show active submissions and recent inactive history.

show_legend

Output a legend for the jobscript-element and EAR states that are displayed by the show command.

unregister

Unregister one submission part or a bulk activity selection.

clear_registry()#

Delete submission registries without loading configuration or workflows.

Remove registries for every machine name under the application’s user data directory, including legacy files that would otherwise be imported again. Discover paths directly because configured machine aliases are unavailable when configuration is broken. Missing files are harmless, and corrupt files need not be parsed. This resets local IDs; workflow files, jobs, caches, and registry lock files are left in place.

Return type:

None

property get_known_submissions: _GetKnownSubmissions#

Retrieve JSON-compatible snapshots from the monitoring registry.

Active and uncertain submissions precede recent inactive history. max_recent defaults to show_max_recent. no_update prevents registry/cache writes. as_json is retained for compatibility; results always contain plain data.

property show: _Show#

Show active submissions and recent inactive history.

Parameters:
  • workflow_ref (int, str, Path, optional) – Select all retained parts of one workflow by local ID, exact registered workflow name, or path. An explicit path can recover pruned history. -1 selects the workflow of the latest submitted registry entry. A comma-separated string selects multiple IDs, including -1. Each ID selects all registered parts of its workflow; overlaps are deduplicated. Use an explicit name type for names that look like ID lists.

  • ref_type (str, optional) – Interpret the reference as id, name, or path. Automatic interpretation prefers registered local IDs, then names, then paths.

  • template_names (str or sequence of str, optional) – Filter by original, case-sensitive template names, independently of custom workflow names. Accept comma-separated text or a sequence. Filter before scheduler queries and recent-history selection.

  • max_recent (int, optional) – Maximum inactive submissions to display; active and unknown submissions are always included. Defaults to show_max_recent for the general overview, or all matching inactive history when workflow_ref is supplied or list_only=True.

  • full (bool, default False) – Alias for view='auto' when no explicit view is supplied.

  • view ({'counts', 'tasks', 'detail', 'auto'}, optional) – Select overall state counts, task progress summaries, exact grouped patterns, or adaptive detail for Actions and Elements. The Elements task view shows per-task overall element-state totals. Defaults to auto when a workflow reference is supplied, and counts for the general overview. full=True selects auto. Explicit views override full. Disabling grouping requests detail and cannot be combined with explicit counts or tasks. Elements retain one overall state per element across iterations.

  • no_update (bool, default False) – Observe live states without writing the registry or terminal-state caches. Existing scheduler snapshots may be reused, but fresh ones are not saved, so read-only queries cannot refresh the shared interval.

  • ignore_scheduler_interval (bool, default False) – Query the scheduler even within show_scheduler_min_interval seconds of its previous query (20 by default). Otherwise reuse recent scheduler observations while still refreshing workflow states. A zero interval disables scheduler caching. This option affects live collection only.

  • use_cache (bool, default False) – Reformat saved observations without scheduler queries, workflow-file reads, or registry/cache writes. Use normal show columns and history limits, and label observations as cached. Missing-path filtering uses saved availability; template filters use saved names only. Workflows absent from the registry cannot be recovered in this mode. Run show without this option first to populate missing action summaries.

  • include_loop_skipped (bool, default False) – Include runs skipped because a loop terminated. Task-condition skips remain distinct from loop skips and upstream-failure skips.

  • list_only (bool, default False) – Use registered/cached observations without constructing workflows or querying schedulers. Template filters may read metadata headers for older records whose template names have not been saved.

  • columns (sequence of str, optional) – Override the ordered show_columns or show_list_columns setting for this call. See monitoring.columns.SHOW_COLUMNS for identifiers.

  • group_elements (bool, default True) – Group elements with identical action patterns. False shows each element separately and implies full detail without changing cached snapshots.

  • group_iterations (bool, default True) – Group iterations with identical action patterns. False shows each iteration separately and implies full detail.

  • status (bool, default True) – Update terminal table rows progressively while loading workflows, reading action states, and querying schedulers. Redirected output prints the completed table once. False suppresses the progress display.

  • include_missing (bool, default False) – Include registered workflows whose paths have been deleted or are missing. Applies to live and registry-only listings. Hidden records remain registered and their saved job references can still be cancelled.

Notes

Datetime columns use show_timezone (local by default). Suffixes are omitted only when abbreviation and offset match the machine’s current local time. The combined Times column aligns clock times and omits dates matching the submit date. Stored timestamps remain UTC.

Examples

>>> app.show(template_names=["simulation", "analysis"])
>>> app.show(workflow_ref=42, full=True, columns=["name", "elements", "times"])
>>> app.show(list_only=True, template_names="simulation,analysis")
>>> app.show(use_cache=True, columns=["name", "elements", "times"])
property show_legend: Callable[[], None]#

Output a legend for the jobscript-element and EAR states that are displayed by the show command.

property unregister: _Unregister#

Unregister one submission part or a bulk activity selection.

Pass a local ID for one entry, or all_submissions=True for all inactive records. With bulk removal, include_active=True also selects active and unknown records, using their last recorded activity. Bulk calls return the removed IDs; a single-entry call returns None. A comma-separated ID string or sequence of IDs removes those entries in one transaction and returns their IDs. -1 selects the latest registry entry. Explicit selections include inactive, active, and unknown entries.

Free IDs without cancelling jobs or deleting workflow files. Automatic pruning does not free IDs. If a selected submission is still registering jobs, reject the entire operation without removing any selected records.