FakeNOS Service Inspect Networks Task

task api name: inspect_networks

The FakeNOS service inspect_networks task returns status and host information for one or all running FakeNOS virtual networks. It can return a simple list of network names or rich per-network details including process metrics and host inventories.

FakeNOS Inspect Networks Task Overview

The inspect_networks task provides the following features:

• Network Summary: Returns a list of running network names when details=False.
• Detailed View: When details=True, queries each child process for its host list and enriches the result with process-level metrics from psutil (CPU, memory, uptime, thread count).
• Selective Query: Optionally scope the result to a single named network.

FakeNOS Inspect Networks Task Arguments

Argument	Type	Default	Description
network	str or None	None	Name of the network to inspect. If None, all running networks are returned.
details	bool	True	When True, returns full host and process information. When False, returns only the list of network names.

FakeNOS Inspect Networks Task Return Data

Detailed mode (details=True)

Returns a dict keyed by network name. Each value is a dict with the following fields:

Field	Type	Description
pid	int	OS process ID of the child process running the network.
alive	bool	Whether the child process is still running.
hosts	list	List of host dicts, each with name, platform, port, username, password.
hosts_count	int	Number of hosts in the network.
status	str	Process status from psutil (e.g. sleeping, running).
uptime_seconds	int	Seconds elapsed since the network was started.
cpu_percent	float	CPU usage percentage of the child process.
memory_rss_mb	float	Resident set size memory in MB.
memory_vms_mb	float	Virtual memory size in MB.
num_threads	int	Number of threads in the child process.

Note

The status, uptime_seconds, cpu_percent, memory_rss_mb, memory_vms_mb, and num_threads fields are populated via psutil. If the child process is not accessible (e.g. access denied), these fields will be absent and a warning is logged.

Summary mode (details=False)

Returns a list of strings — one entry per running network name.

FakeNOS Inspect Networks Command Shell Reference

NorFab shell supports these command options for Netbox create_prefix task:

nf#man tree show.fakenos.networks

R - required field, M - supports multiline input, D - dynamic key

root
└── show:    NorFab show commands
    └── fakenos:    Show FakeNOS service
        └── networks:    show FakeNOS networks details
            ├── network:    FakeNOS network name to show; shows all networks if omitted
            └── details:    show network details, default 'False'
nf#

Python API Reference

Return status information for one or all FakeNOS networks.

When details is True each network entry includes the child process PID, liveness flag, and a list of host dicts retrieved from the child process. When details is False only the list of network names is returned.

Parameters:

Name	Type	Description	Default
job	Job	NorFab job context injected by the @Task decorator.	required
network	Union[str, None]	Name of the network to inspect. If None (default), all networks tracked by this worker are inspected.	None
details	bool	When True (default) query each network process for its host list and return extended per-network dicts. When False return only the list of network names.	True

Source code in norfab\workers\fakenos_worker\fakenos_worker.py

@Task(
    input=FakeNOSListNetworksInput,
    output=FakeNOSInspectNetworksResult,
    fastapi={"methods": ["GET"]},
    mcp={
        "annotations": {
            "title": "Inspect FakeNOS Networks",
            "readOnlyHint": True,
            "destructiveHint": False,
            "idempotentHint": True,
            "openWorldHint": False,
        }
    },
)
def inspect_networks(
    self, job: Job, network: Union[str, None] = None, details: bool = True
) -> Result:
    """
    Return status information for one or all FakeNOS networks.

    When *details* is ``True`` each network entry includes the child
    process PID, liveness flag, and a list of host dicts retrieved from
    the child process.  When *details* is ``False`` only the list of
    network names is returned.

    Args:
        job: NorFab job context injected by the ``@Task`` decorator.
        network: Name of the network to inspect.  If ``None`` (default),
            all networks tracked by this worker are inspected.
        details: When ``True`` (default) query each network process for
            its host list and return extended per-network dicts.  When
            ``False`` return only the list of network names.
    """
    ret = Result()

    names = [network] if network else list(self.networks)

    if details:
        ret.result = {}
        for net_name in names:
            entry = self.networks[net_name]
            process = entry["process"]
            hosts = self.call_network(net_name, "_get_hosts_as_list")
            proc_info = {
                "pid": process.pid,
                "alive": process.is_alive(),
                "hosts": hosts,
                "hosts_count": len(hosts),
            }
            try:
                ps = psutil.Process(process.pid)
                mem = ps.memory_info()
                uptime = round(
                    time.time() - entry.get("start_time", ps.create_time())
                )
                proc_info.update(
                    {
                        "status": ps.status(),
                        "uptime_seconds": uptime,
                        "cpu_percent": ps.cpu_percent(interval=0.1),
                        "memory_rss_mb": round(mem.rss / 1024 / 1024, 2),
                        "memory_vms_mb": round(mem.vms / 1024 / 1024, 2),
                        "num_threads": ps.num_threads(),
                    }
                )
            except (psutil.NoSuchProcess, psutil.AccessDenied) as e:
                log.warning(f"{net_name} - Psutil metrics unavailable: {e}")
            ret.result[net_name] = proc_info
    else:
        ret.result = names

    return ret