nvitop.process module
|
Represent an OS process with the given PID. |
|
Represent a process with the given PID running on the given GPU device. |
|
Return a shell-escaped string from command line arguments. |
The live classes for process running on the host and the GPU devices.
- class nvitop.HostProcess(pid: int | None = None)[source]
Bases:
Process
Represent an OS process with the given PID.
If PID is omitted current process PID (
os.getpid()
) is used. The instance will be cache during the lifetime of the process.Examples
>>> HostProcess() # the current process HostProcess(pid=12345, name='python3', status='running', started='00:55:43')
>>> p1 = HostProcess(12345) >>> p2 = HostProcess(12345) >>> p1 is p2 # the same instance True
>>> import copy >>> copy.deepcopy(p1) is p1 # the same instance True
>>> p = HostProcess(pid=12345) >>> p.cmdline() ['python3', '-c', 'import IPython; IPython.terminal.ipapp.launch_new_instance()'] >>> p.command() # the result is in shell-escaped format 'python3 -c "import IPython; IPython.terminal.ipapp.launch_new_instance()"'
>>> p.as_snapshot() HostProcessSnapshot( real=HostProcess(pid=12345, name='python3', status='running', started='00:55:43'), cmdline=['python3', '-c', 'import IPython; IPython.terminal.ipapp.launch_new_instance()'], command='python3 -c "import IPython; IPython.terminal.ipapp.launch_new_instance()"', connections=[], cpu_percent=0.3, cpu_times=pcputimes(user=2.180019456, system=0.18424464, children_user=0.0, children_system=0.0), create_time=1656608143.31, cwd='/home/panxuehai', environ={...}, ... )
- INSTANCE_LOCK: threading.RLock = <unlocked _thread.RLock object owner=0 count=0>
- INSTANCES: WeakValueDictionary[int, HostProcess] = <WeakValueDictionary>
- static __new__(cls, pid: int | None = None) Self [source]
Return the cached instance of
HostProcess
.
- username() str [source]
The name of the user that owns the process.
On UNIX this is calculated by using real process uid.
- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
- cmdline() list[str] [source]
The command line this process has been called with.
- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
- command() str [source]
Return a shell-escaped string from command line arguments.
- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
- running_time() timedelta [source]
The elapsed time this process has been running in
datetime.timedelta
.- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
- running_time_human() str [source]
The elapsed time this process has been running in human readable format.
- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
- running_time_in_seconds() float [source]
The elapsed time this process has been running in seconds.
- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
- elapsed_time() timedelta
The elapsed time this process has been running in
datetime.timedelta
.- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
- elapsed_time_human() str
The elapsed time this process has been running in human readable format.
- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
- elapsed_time_in_seconds() float
The elapsed time this process has been running in seconds.
- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
- rss_memory() int [source]
The used resident set size (RSS) memory of the process in bytes.
- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
- parent() HostProcess | None [source]
Return the parent process as a
HostProcess
instance orNone
if there is no parent.- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
- children(recursive: bool = False) list[HostProcess] [source]
Return the children of this process as a list of
HostProcess
instances.If recursive is
True
return all the descendants.- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
- oneshot() Generator[None, None, None] [source]
A utility context manager which considerably speeds up the retrieval of multiple process information at the same time.
Internally different process info (e.g. name, ppid, uids, gids, …) may be fetched by using the same routine, but only one information is returned and the others are discarded. When using this context manager the internal routine is executed once (in the example below on
name()
) and the other info are cached.The cache is cleared when exiting the context manager block. The advice is to use this every time you retrieve more than one information about the process.
Examples
>>> from nvitop import HostProcess >>> p = HostProcess() >>> with p.oneshot(): ... p.name() # collect multiple info ... p.cpu_times() # return cached value ... p.cpu_percent() # return cached value ... p.create_time() # return cached value
- as_snapshot(attrs: Iterable[str] | None = None, ad_value: Any | None = None) Snapshot [source]
Return a onetime snapshot of the process.
- as_dict(attrs=None, ad_value=None)
Utility method returning process information as a hashable dictionary. If attrs is specified it must be a list of strings reflecting available Process class’ attribute names (e.g. [‘cpu_times’, ‘name’]) else all public (read only) attributes are assumed. ad_value is the value which gets assigned in case AccessDenied or ZombieProcess exception is raised when retrieving that particular process information.
- connections(kind='inet')
Return socket connections opened by process as a list of (fd, family, type, laddr, raddr, status) namedtuples. The kind parameter filters for connections that match the following criteria:
Kind Value
Connections using
inet inet4 inet6 tcp tcp4 tcp6 udp udp4 udp6 unix all
IPv4 and IPv6 IPv4 IPv6 TCP TCP over IPv4 TCP over IPv6 UDP UDP over IPv4 UDP over IPv6 UNIX socket (both UDP and TCP protocols) the sum of all the possible families and protocols
- cpu_affinity(cpus=None)
Get or set process CPU affinity. If specified, cpus must be a list of CPUs for which you want to set the affinity (e.g. [0, 1]). If an empty list is passed, all egible CPUs are assumed (and set). (Windows, Linux and BSD only).
- cpu_num()
Return what CPU this process is currently running on. The returned number should be <= psutil.cpu_count() and <= len(psutil.cpu_percent(percpu=True)). It may be used in conjunction with psutil.cpu_percent(percpu=True) to observe the system workload distributed across CPUs.
- cpu_percent(interval=None)
Return a float representing the current process CPU utilization as a percentage.
When interval is 0.0 or None (default) compares process times to system CPU times elapsed since last call, returning immediately (non-blocking). That means that the first time this is called it will return a meaningful 0.0 value.
When interval is > 0.0 compares process times to system CPU times elapsed before and after the interval (blocking).
In this case is recommended for accuracy that this function be called with at least 0.1 seconds between calls.
A value > 100.0 can be returned in case of processes running multiple threads on different CPU cores.
The returned value is explicitly NOT split evenly between all available logical CPUs. This means that a busy loop process running on a system with 2 logical CPUs will be reported as having 100% CPU utilization instead of 50%.
Examples
>>> import psutil >>> p = psutil.Process(os.getpid()) >>> # blocking >>> p.cpu_percent(interval=1) 2.0 >>> # non-blocking (percentage since last call) >>> p.cpu_percent(interval=None) 2.9 >>>
- cpu_times()
Return a (user, system, children_user, children_system) namedtuple representing the accumulated process time, in seconds. This is similar to os.times() but per-process. On macOS and Windows children_user and children_system are always set to 0.
- create_time()
The process creation time as a floating point number expressed in seconds since the epoch. The return value is cached after first call.
- cwd()
Process current working directory as an absolute path.
- environ()
The environment variables of the process as a dict. Note: this might not reflect changes made after the process started.
- exe()
The process executable as an absolute path. May also be an empty string. The return value is cached after first call.
- gids()
Return process GIDs as a (real, effective, saved) namedtuple.
- io_counters()
Return process I/O statistics as a (read_count, write_count, read_bytes, write_bytes) namedtuple. Those are the number of read/write calls performed and the amount of bytes read and written by the process.
- ionice(ioclass=None, value=None)
Get or set process I/O niceness (priority).
On Linux ioclass is one of the IOPRIO_CLASS_* constants. value is a number which goes from 0 to 7. The higher the value, the lower the I/O priority of the process.
On Windows only ioclass is used and it can be set to 2 (normal), 1 (low) or 0 (very low).
Available on Linux and Windows > Vista only.
- is_running()
Return whether this process is running. It also checks if PID has been reused by another process in which case return False.
- kill()
Kill the current process with SIGKILL pre-emptively checking whether PID has been reused.
- memory_full_info()
This method returns the same information as memory_info(), plus, on some platform (Linux, macOS, Windows), also provides additional metrics (USS, PSS and swap). The additional metrics provide a better representation of actual process memory usage.
Namely USS is the memory which is unique to a process and which would be freed if the process was terminated right now.
It does so by passing through the whole process address. As such it usually requires higher user privileges than memory_info() and is considerably slower.
- memory_info()
Return a namedtuple with variable fields depending on the platform, representing memory information about the process.
The “portable” fields available on all platforms are rss and vms.
All numbers are expressed in bytes.
- memory_info_ex()
memory_info_ex() is deprecated and will be removed; use memory_info() instead
- memory_maps(grouped=True)
Return process’ mapped memory regions as a list of namedtuples whose fields are variable depending on the platform.
If grouped is True the mapped regions with the same ‘path’ are grouped together and the different memory fields are summed.
If grouped is False every mapped region is shown as a single entity and the namedtuple will also include the mapped region’s address space (‘addr’) and permission set (‘perms’).
- memory_percent(memtype='rss')
Compare process memory to total physical system memory and calculate process memory utilization as a percentage. memtype argument is a string that dictates what type of process memory you want to compare against (defaults to “rss”). The list of available strings can be obtained like this:
>>> psutil.Process().memory_info()._fields ('rss', 'vms', 'shared', 'text', 'lib', 'data', 'dirty', 'uss', 'pss')
- name()
The process name. The return value is cached after first call.
- nice(value=None)
Get or set process niceness (priority).
- num_ctx_switches()
Return the number of voluntary and involuntary context switches performed by this process.
- num_fds()
Return the number of file descriptors opened by this process (POSIX only).
- num_threads()
Return the number of threads used by this process.
- open_files()
Return files opened by process as a list of (path, fd) namedtuples including the absolute file name and file descriptor number.
- parents()
Return the parents of this process as a list of Process instances. If no parents are known return an empty list.
- property pid
The process PID.
- ppid()
The process parent PID. On Windows the return value is cached after first call.
- resume()
Resume process execution with SIGCONT pre-emptively checking whether PID has been reused. On Windows this has the effect of resuming all process threads.
- rlimit(resource, limits=None)
Get or set process resource limits as a (soft, hard) tuple.
resource is one of the RLIMIT_* constants. limits is supposed to be a (soft, hard) tuple.
See “man prlimit” for further info. Available on Linux and FreeBSD only.
- send_signal(sig)
Send a signal sig to process pre-emptively checking whether PID has been reused (see signal module constants) . On Windows only SIGTERM is valid and is treated as an alias for kill().
- status()
The process current status as a STATUS_* constant.
- suspend()
Suspend process execution with SIGSTOP pre-emptively checking whether PID has been reused. On Windows this has the effect of suspending all process threads.
- terminal()
The terminal associated with this process, if any, else None.
- terminate()
Terminate the process with SIGTERM pre-emptively checking whether PID has been reused. On Windows this is an alias for kill().
- threads()
Return threads opened by process as a list of (id, user_time, system_time) namedtuples representing thread id and thread CPU times (user/system). On OpenBSD this method requires root access.
- uids()
Return process UIDs as a (real, effective, saved) namedtuple.
- wait(timeout=None)
Wait for process to terminate and, if process is a children of os.getpid(), also return its exit code, else None. On Windows there’s no such limitation (exit code is always returned).
If the process is already terminated immediately return None instead of raising NoSuchProcess.
If timeout (in seconds) is specified and process is still alive raise TimeoutExpired.
To wait for multiple Process(es) use psutil.wait_procs().
- class nvitop.GpuProcess(pid: int | None, device: Device, *, gpu_memory: int | NaType | None = None, gpu_instance_id: int | NaType | None = None, compute_instance_id: int | NaType | None = None, type: str | NaType | None = None)[source]
Bases:
object
Represent a process with the given PID running on the given GPU device.
The instance will be cache during the lifetime of the process.
The same host process can use multiple GPU devices. The
GpuProcess
instances representing the same PID on the host but different GPU devices are different.- INSTANCE_LOCK: threading.RLock = <unlocked _thread.RLock object owner=0 count=0>
- INSTANCES: WeakValueDictionary[tuple[int, Device], GpuProcess] = <WeakValueDictionary>
- static __new__(cls, pid: int | None, device: Device, *, gpu_memory: int | NaType | None = None, gpu_instance_id: int | NaType | None = None, compute_instance_id: int | NaType | None = None, type: str | NaType | None = None) Self [source]
Return the cached instance of
GpuProcess
.
- __init__(pid: int | None, device: Device, *, gpu_memory: int | NaType | None = None, gpu_instance_id: int | NaType | None = None, compute_instance_id: int | NaType | None = None, type: str | NaType | None = None) None [source]
Initialize the instance returned by
__new__()
.
- __getattr__(name: str) Any | Callable[..., Any] [source]
Get a member from the instance or fallback to the host process instance if missing.
- Raises:
AttributeError – If the attribute is not defined in either
GpuProcess
norHostProcess
.host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
- property host: HostProcess
The process instance running on the host.
- property device: Device
The GPU device the process running on.
The same host process can use multiple GPU devices. The
GpuProcess
instances representing the same PID on the host but different GPU devices are different.
- gpu_instance_id() int | NaType [source]
The GPU instance ID of the MIG device, or
nvitop.NA
if not applicable.
- compute_instance_id() int | NaType [source]
The compute instance ID of the MIG device, or
nvitop.NA
if not applicable.
- gpu_memory_human() str | NaType [source]
The used GPU memory in human readable format, or
nvitop.NA
if not applicable.
- gpu_memory_percent() float | NaType [source]
The percentage of used GPU memory by the process, or
nvitop.NA
if not applicable.
- gpu_sm_utilization() int | NaType [source]
The utilization rate of SM (Streaming Multiprocessor), or
nvitop.NA
if not applicable.
- gpu_memory_utilization() int | NaType [source]
The utilization rate of GPU memory bandwidth, or
nvitop.NA
if not applicable.
- gpu_encoder_utilization() int | NaType [source]
The utilization rate of the encoder, or
nvitop.NA
if not applicable.
- gpu_decoder_utilization() int | NaType [source]
The utilization rate of the decoder, or
nvitop.NA
if not applicable.
- set_gpu_utilization(gpu_sm_utilization: int | NaType | None = None, gpu_memory_utilization: int | NaType | None = None, gpu_encoder_utilization: int | NaType | None = None, gpu_decoder_utilization: int | NaType | None = None) None [source]
Set the GPU utilization rates.
- property type: str | NaType
The type of the GPU context.
- The type is one of the following:
'C'
: compute context'G'
: graphics context'C+G'
: both compute context and graphics context'N/A'
: not applicable
- status() str [source]
The process current status.
- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
Note
To return the fallback value rather than raise an exception, please use the context manager
GpuProcess.failsafe()
. See alsotake_snapshots()
andfailsafe()
.
- create_time() float | NaType [source]
The process creation time as a floating point number expressed in seconds since the epoch.
- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
Note
To return the fallback value rather than raise an exception, please use the context manager
GpuProcess.failsafe()
. See alsotake_snapshots()
andfailsafe()
.
- running_time() datetime.timedelta | NaType [source]
The elapsed time this process has been running in
datetime.timedelta
.- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
Note
To return the fallback value rather than raise an exception, please use the context manager
GpuProcess.failsafe()
. See alsotake_snapshots()
andfailsafe()
.
- running_time_human() str | NaType [source]
The elapsed time this process has been running in human readable format.
- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
Note
To return the fallback value rather than raise an exception, please use the context manager
GpuProcess.failsafe()
. See alsotake_snapshots()
andfailsafe()
.
- running_time_in_seconds() float | NaType [source]
The elapsed time this process has been running in seconds.
- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
Note
To return the fallback value rather than raise an exception, please use the context manager
GpuProcess.failsafe()
. See alsotake_snapshots()
andfailsafe()
.
- elapsed_time() datetime.timedelta | NaType
The elapsed time this process has been running in
datetime.timedelta
.- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
Note
To return the fallback value rather than raise an exception, please use the context manager
GpuProcess.failsafe()
. See alsotake_snapshots()
andfailsafe()
.
- elapsed_time_human() str | NaType
The elapsed time this process has been running in human readable format.
- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
Note
To return the fallback value rather than raise an exception, please use the context manager
GpuProcess.failsafe()
. See alsotake_snapshots()
andfailsafe()
.
- elapsed_time_in_seconds() float | NaType
The elapsed time this process has been running in seconds.
- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
Note
To return the fallback value rather than raise an exception, please use the context manager
GpuProcess.failsafe()
. See alsotake_snapshots()
andfailsafe()
.
- username() str | NaType [source]
The name of the user that owns the process.
- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
Note
To return the fallback value rather than raise an exception, please use the context manager
GpuProcess.failsafe()
. See alsotake_snapshots()
andfailsafe()
.
- name() str | NaType [source]
The process name.
- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
Note
To return the fallback value rather than raise an exception, please use the context manager
GpuProcess.failsafe()
. See alsotake_snapshots()
andfailsafe()
.
- cpu_percent() float | NaType [source]
Return a float representing the current process CPU utilization as a percentage.
- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
Note
To return the fallback value rather than raise an exception, please use the context manager
GpuProcess.failsafe()
. See alsotake_snapshots()
andfailsafe()
.
- memory_percent() float | NaType [source]
Compare process RSS memory to total physical system memory and calculate process memory utilization as a percentage.
- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
Note
To return the fallback value rather than raise an exception, please use the context manager
GpuProcess.failsafe()
. See alsotake_snapshots()
andfailsafe()
.
- host_memory_percent() float | NaType
Compare process RSS memory to total physical system memory and calculate process memory utilization as a percentage.
- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
Note
To return the fallback value rather than raise an exception, please use the context manager
GpuProcess.failsafe()
. See alsotake_snapshots()
andfailsafe()
.
- host_memory() int | NaType [source]
The used resident set size (RSS) memory of the process in bytes.
- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
Note
To return the fallback value rather than raise an exception, please use the context manager
GpuProcess.failsafe()
. See alsotake_snapshots()
andfailsafe()
.
- host_memory_human() str | NaType [source]
The used resident set size (RSS) memory of the process in human readable format.
- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
Note
To return the fallback value rather than raise an exception, please use the context manager
GpuProcess.failsafe()
. See alsotake_snapshots()
andfailsafe()
.
- rss_memory() int | NaType
The used resident set size (RSS) memory of the process in bytes.
- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
Note
To return the fallback value rather than raise an exception, please use the context manager
GpuProcess.failsafe()
. See alsotake_snapshots()
andfailsafe()
.
- cmdline() list[str] [source]
The command line this process has been called with.
- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
Note
To return the fallback value rather than raise an exception, please use the context manager
GpuProcess.failsafe()
. See alsotake_snapshots()
andfailsafe()
.
- command() str [source]
Return a shell-escaped string from command line arguments.
- Raises:
host.NoSuchProcess – If the process is gone.
host.AccessDenied – If the user do not have read privilege to the process’ status file.
Note
To return the fallback value rather than raise an exception, please use the context manager
GpuProcess.failsafe()
. See alsotake_snapshots()
andfailsafe()
.
- as_snapshot(*, host_process_snapshot_cache: dict[int, Snapshot] | None = None) Snapshot [source]
Return a onetime snapshot of the process on the GPU device.
Note
To return the fallback value rather than raise an exception, please use the context manager
GpuProcess.failsafe()
. Also, consider using the batched version to take snapshots withGpuProcess.take_snapshots()
, which caches the results and reduces redundant queries. See alsotake_snapshots()
andfailsafe()
.
- classmethod take_snapshots(gpu_processes: Iterable[GpuProcess], *, failsafe: bool = False) list[Snapshot] [source]
Take snapshots for a list of
GpuProcess
instances.If failsafe is
True
, then if any method fails, the fallback value inauto_garbage_clean()
will be used.
- classmethod failsafe() Generator[None, None, None] [source]
A context manager that enables fallback values for methods that fail.
Examples
>>> p = GpuProcess(pid=10000, device=Device(0)) # process does not exist >>> p GpuProcess(pid=10000, gpu_memory=N/A, type=N/A, device=PhysicalDevice(index=0, name="NVIDIA GeForce RTX 3070", total_memory=8192MiB), host=HostProcess(pid=10000, status='terminated')) >>> p.cpu_percent() Traceback (most recent call last): ... NoSuchProcess: process no longer exists (pid=10000)
>>> # Failsafe to the fallback value instead of raising exceptions ... with GpuProcess.failsafe(): ... print('fallback: {!r}'.format(p.cpu_percent())) ... print('fallback (float cast): {!r}'.format(float(p.cpu_percent()))) # `nvitop.NA` can be cast to float or int ... print('fallback (int cast): {!r}'.format(int(p.cpu_percent()))) # `nvitop.NA` can be cast to float or int fallback: 'N/A' fallback (float cast): nan fallback (int cast): 0