Procfs support

Procpath supports the following Procfs files. stat and cmdline are the default ones. /proc/{pid}/cmdline is represented as a plain string, and the structure of the rest is documented below.

procpath.procfile.Stat(pid, comm, state, ...)

Representation of /proc/{pid}/stat, see man proc.

procpath.procfile.Io(rchar, wchar, syscr, ...)

Representation of /proc/{pid}/io, see man proc.

procpath.procfile.Status(name, umask, state, ...)

Representation of /proc/{pid}/status, see man proc.

procpath.procfile.Fd([anon, dir, chr, blk, ...])

Counts of file descriptor types in /proc/{pid}/fd/*.

procpath.procfile.SmapsRollup(rss, pss, ...)

Representation of /proc/{pid}/smaps_rollup.
class procpath.procfile.Stat

Representation of /proc/{pid}/stat, see man proc.

Fields are read up until rss plus the range from delayacct_blkio_ticks to cguest_time. Other fields don’t seem to be useful for the monitoring purposes.

Formats of the fields are defined in C printf syntax.

pid: int

The process ID.

Format:

%d

comm: str

The filename of the executable. This is visible whether or not the executable is swapped out.

Format:

%s

state: str

One of the following characters, indicating process state:

R Running

S Sleeping in an interruptible wait

D Waiting in uninterruptible disk sleep

Z Zombie

T Stopped (on a signal) or (before Linux 2.6.33)

trace stopped

t Tracing stop (Linux 2.6.33 onward)

W Paging (only before Linux 2.6.0)

X Dead (from Linux 2.6.0 onward)

x Dead (Linux 2.6.33 to 3.13 only)

K Wakekill (Linux 2.6.33 to 3.13 only)

W Waking (Linux 2.6.33 to 3.13 only)

P Parked (Linux 3.9 to 3.13 only)

Format:

%c

ppid: int

The PID of the parent of this process.

Format:

%d

pgrp: int

The process group ID of the process.

Format:

%d

session: int

The session ID of the process.

Format:

%d

tty_nr: int

The controlling terminal of the process. (The minor device number is contained in the combination of bits 31 to 20 and 7 to 0; the major device number is in bits 15 to 8.)

Format:

%d

tpgid: int

The ID of the foreground process group of the controlling terminal of the process.

Format:

%d

flags: int

The kernel flags word of the process. For bit meanings, see the PF_* defines in the Linux kernel source file include/linux/sched.h. Details depend on the kernel version.

The format for this field was %lu before Linux 2.6.

Format:

%u

minflt: int

The number of minor faults the process has made which have not required loading a memory page from disk.

Format:

%lu

cminflt: int

The number of minor faults that the process’s waited-for children have made.

Format:

%lu

majflt: int

The number of major faults the process has made which have required loading a memory page from disk.

Format:

%lu

cmajflt: int

The number of major faults that the process’s waited-for children have made.

Format:

%lu

utime: int

Amount of time that this process has been scheduled in user mode, measured in clock ticks (divide by sysconf(_SC_CLK_TCK)). This includes guest time, guest_time (time spent running a virtual CPU, see below), so that applications that are not aware of the guest time field do not lose that time from their calculations.

Format:

%lu

stime: int

Amount of time that this process has been scheduled in kernel mode, measured in clock ticks (divide by sysconf(_SC_CLK_TCK)).

Format:

%lu

cutime: int

Amount of time that this process’s waited-for children have been scheduled in user mode, measured in clock ticks (divide by sysconf(_SC_CLK_TCK)). (See also times(2).) This includes guest time, cguest_time (time spent running a virtual CPU, see below).

Format:

%ld

cstime: int

Amount of time that this process’s waited-for children have been scheduled in kernel mode, measured in clock ticks (divide by sysconf(_SC_CLK_TCK)).

Format:

%ld

priority: int

(Explanation for Linux 2.6) For processes running a real-time scheduling policy (policy below; see sched_setscheduler(2)), this is the negated schedul‐ ing priority, minus one; that is, a number in the range -2 to -100, corresponding to real-time priori‐ ties 1 to 99. For processes running under a non- real-time scheduling policy, this is the raw nice value (setpriority(2)) as represented in the kernel. The kernel stores nice values as numbers in the range 0 (high) to 39 (low), corresponding to the user-visible nice range of -20 to 19.

Before Linux 2.6, this was a scaled value based on the scheduler weighting given to this process.

Format:

%ld

nice: int

The nice value (see setpriority(2)), a value in the range 19 (low priority) to -20 (high priority).

Format:

%ld

num_threads: int

Number of threads in this process (since Linux 2.6). Before kernel 2.6, this field was hard coded to 0 as a placeholder for an earlier removed field.

Format:

%ld

itrealvalue: int

The time in jiffies before the next SIGALRM is sent to the process due to an interval timer. Since kernel 2.6.17, this field is no longer maintained, and is hard coded as 0.

Format:

%ld

starttime: int

The time the process started after system boot. In kernels before Linux 2.6, this value was expressed in jiffies. Since Linux 2.6, the value is expressed in clock ticks (divide by sysconf(_SC_CLK_TCK)).

The format for this field was %lu before Linux 2.6.

Format:

%llu

vsize: int

Virtual memory size in bytes.

Format:

%lu

rss: int

Resident Set Size: number of pages the process has in real memory. This is just the pages which count toward text, data, or stack space. This does not include pages which have not been demand-loaded in, or which are swapped out.

Format:

%ld

delayacct_blkio_ticks: int

Aggregated block I/O delays, measured in clock ticks (centiseconds). Available since Linux 2.6.18.

Format:

%llu

guest_time: int

Guest time of the process (time spent running a virtual CPU for a guest operating system), measured in clock ticks (divide by sysconf(_SC_CLK_TCK)). Available since Linux 2.6.24.

Format:

%lu

cguest_time: int

Guest time of the process’s children, measured in clock ticks (divide by sysconf(_SC_CLK_TCK)). Available since Linux 2.6.24.

Format:

%ld

class procpath.procfile.Io

Representation of /proc/{pid}/io, see man proc.

rchar: int

I/O counter: chars read.

The number of bytes which this task has caused to be read from storage. This is simply the sum of bytes which this process passed to read() and pread(). It includes things like tty IO and it is unaffected by whether or not actual physical disk IO was required (the read might have been satisfied from pagecache).

wchar: int

I/O counter: chars written.

The number of bytes which this task has caused, or shall cause to be written to disk. Similar caveats apply here as with rchar.

syscr: int

I/O counter: read syscalls.

Attempt to count the number of read I/O operations, i.e. syscalls like read() and pread().

syscw: int

I/O counter: write syscalls.

Attempt to count the number of write I/O operations, i.e. syscalls like write() and pwrite().

read_bytes: int

I/O counter: bytes read.

Attempt to count the number of bytes which this process really did cause to be fetched from the storage layer. Done at the submit_bio() level, so it is accurate for block-backed filesystems.

write_bytes: int

I/O counter: bytes written.

Attempt to count the number of bytes which this process caused to be sent to the storage layer. This is done at page-dirtying time.

cancelled_write_bytes: int

The big inaccuracy here is truncate. If a process writes 1MB to a file and then deletes the file, it will in fact perform no writeout. But it will have been accounted as having caused 1MB of write. In other words: The number of bytes which this process caused to not happen, by truncating pagecache. A task can cause “negative” IO too. If this task truncates some dirty pagecache, some IO which another task has been accounted for (in its write_bytes) will not be happening. We _could_ just subtract that from the truncating task’s write_bytes, but there is information loss in doing that.

class procpath.procfile.Status

Representation of /proc/{pid}/status, see man proc.

name: str

Command run by this process. Strings longer than TASK_COMM_LEN (16) characters (including the terminating null byte) are silently truncated.

umask: Optional[int]

Process umask; see umask(2) (since Linux 4.7).

state: str

Current state of the process. One of:

  • R (running)

  • S (sleeping)

  • D (disk sleep)

  • T (stopped)

  • t (tracing stop)

  • Z (zombie)

  • X (dead)

Only the letter code is kept.

tgid: int

Thread group ID (i.e., Process ID).

ngid: Optional[int]

NUMA group ID (0 if none; since Linux 3.13).

pid: int

Thread ID (see gettid(2)).

ppid: int

PID of parent process.

tracerpid: int

PID of process tracing this process (0 if not being traced).

uid: List[int]

Real, effective, saved set, and filesystem UIDs.

gid: List[int]

Real, effective, saved set, and filesystem GIDs.

fdsize: int

Number of file descriptor slots currently allocated.

groups: List[int]

Supplementary group list.

nstgid: Optional[List[int]]

Thread group ID (i.e., PID) in each of the PID namespaces of which [pid] is a member. The leftmost entry shows the value with respect to the PID namespace of the process that mounted this procfs (or the root namespace if mounted by the kernel), followed by the value in successively nested inner namespaces (since Linux 4.1).

nspid: Optional[List[int]]

Thread ID in each of the PID namespaces of which [pid] is a member. The fields are ordered as for NStgid (since Linux 4.1).

nspgid: Optional[List[int]]

Process group ID in each of the PID namespaces of which [pid] is a member. The fields are ordered as for NStgid (since Linux 4.1).

nssid: Optional[List[int]]

Descendant namespace session ID hierarchy Session ID in each of the PID namespaces of which [pid] is a member. The fields are ordered as for NStgid (since Linux 4.1).

vmpeak: Optional[int]

Peak virtual memory size, in kB.

vmsize: Optional[int]

Virtual memory size, in kB.

vmlck: Optional[int]

Locked memory size, in kB (see mlock(2)).

vmpin: Optional[int]

Pinned memory size (since Linux 3.2). These are pages that can’t be moved because something needs to directly access physical memory, in kB.

vmhwm: Optional[int]

Peak resident set size, in kB (“high water mark”).

vmrss: Optional[int]

Resident set size, in kB. Note that the value here is the sum of RssAnon, RssFile, and RssShmem.

rssanon: Optional[int]

Size of resident anonymous memory, in kB (since Linux 4.5).

rssfile: Optional[int]

Size of resident file mappings, in kB (since Linux 4.5).

rssshmem: Optional[int]

Size of resident shared memory, in kB (includes System V shared memory, mappings from tmpfs(5), and shared anonymous mappings). (since Linux 4.5).

vmdata: Optional[int]

Size of data, in kB.

vmstk: Optional[int]

Size of stack, in kB.

vmexe: Optional[int]

Size of text segments, in kB.

vmlib: Optional[int]

Shared library code size, in kB.

vmpte: Optional[int]

Page table entries size, in kB (since Linux 2.6.10).

vmpmd: Optional[int]

Size of second-level page tables, in kB (added in Linux 4.0; removed in Linux 4.15).

vmswap: Optional[int]

Swapped-out virtual memory size by anonymous private pages, in kB; shmem swap usage is not included (since Linux 2.6.34).

hugetlbpages: Optional[int]

Size of hugetlb memory portions, in kB (since Linux 4.4).

coredumping: Optional[int]

Contains the value 1 if the process is currently dumping core, and 0 if it is not (since Linux 4.15). This information can be used by a monitoring process to avoid killing a process that is currently dumping core, which could result in a corrupted core dump file.

threads: int

Number of threads in process containing this thread.

sigq: List[int]

This field contains two numbers that relate to queued signals for the real user ID of this process. The first of these is the number of currently queued signals for this real user ID, and the second is the resource limit on the number of queued signals for this process (see the description of RLIMIT_SIGPENDING in getrlimit(2)).

sigpnd: int

Mask of signals pending for thread (see pthreads(7) and signal(7)).

shdpnd: int

Mask of signals pending for process as a whole (see pthreads(7) and signal(7)).

sigblk: int

Masks indicating signals being blocked (see signal(7)).

sigign: int

Masks indicating signals being ignored (see signal(7)).

sigcgt: int

Masks indicating signals being caught (see signal(7)).

capinh: int

Masks of capabilities enabled in inheritable sets (see capabilities(7)).

capprm: int

Masks of capabilities enabled in permitted sets (see capabilities(7)).

capeff: int

Masks of capabilities enabled in effective sets (see capabilities(7)).

capbnd: Optional[int]

Capability bounding set (since Linux 2.6.26, see capabilities(7)).

capamb: Optional[int]

Ambient capability set (since Linux 4.3, see capabilities(7)).

nonewprivs: Optional[int]

Value of the no_new_privs bit (since Linux 4.10, see prctl(2)).

seccomp: Optional[int]

Seccomp mode of the process (since Linux 3.8, see seccomp(2)).

  • 0 means SECCOMP_MODE_DISABLED

  • 1 means SECCOMP_MODE_STRICT

  • 2 means SECCOMP_MODE_FILTER

This field is provided only if the kernel was built with the CONFIG_SECCOMP kernel configuration option enabled.

speculation_store_bypass: Optional[str]

Speculation flaw mitigation state (since Linux 4.17, see prctl(2)).

cpus_allowed: Optional[int]

Mask of CPUs on which this process may run (since Linux 2.6.24, see cpuset(7)).

cpus_allowed_list: Optional[str]

Same as previous, but in “list format” (since Linux 2.6.26, see cpuset(7)).

mems_allowed: Optional[List[int]]

Mask of memory nodes allowed to this process (since Linux 2.6.24, see cpuset(7)).

mems_allowed_list: Optional[str]

Same as previous, but in “list format” (since Linux 2.6.26, see cpuset(7)).

voluntary_ctxt_switches: Optional[int]

Number of voluntary context switches (since Linux 2.6.23).

nonvoluntary_ctxt_switches: Optional[int]

Number of involuntary context switches (since Linux 2.6.23).

class procpath.procfile.Fd

Counts of file descriptor types in /proc/{pid}/fd/*.

For more details see man proc and man fstat.

anon: int

For file descriptors that have no corresponding inode (e.g., file descriptors produced by epoll_create(2), eventfd(2), inotify_init(2), signalfd(2), and timerfd(2)), the entry will be a symbolic link with contents of the form:

anon_inode:<file-type>

In some cases, the file-type is surrounded by square brackets like:

  • anon_inode:[eventfd]

  • anon_inode:[eventpoll]

  • anon_inode:[timerfd]

  • anon_inode:[signalfd]

  • anon_inode:inotify

  • anon_inode:dmabuf

  • anon_inode:sync_fence

dir: int

Directory.

chr: int

Character device.

blk: int

Block device.

reg: int

Regular file.

fifo: int

FIFO (named pipe).

lnk: int

Symbolic link.

sock: int

Socket file.

class procpath.procfile.SmapsRollup

Representation of /proc/{pid}/smaps_rollup.

This file was added to the Kernel in version 4.14. It provides pre-summed memory information for a process, and contains most of the fields of /proc/{pid}/smaps.

All fields are expressed in kB. Kernel threads have the file empty.

rss: Optional[int]

Resident Set Size. Sum of the mappings that are currently resident in RAM.

pss: Optional[int]

Proportional Set Size. The process’ proportional share of its mappings. If a process has 100 unshared pages(USS), and 100 shared with another process, its PSS will be 150.

shared_clean: Optional[int]

The number of clean shared pages in process’ mappings.

shared_dirty: Optional[int]

The number of dirty shared pages in process’ mappings.

private_clean: Optional[int]

The number of clean private pages in process’ mappings.

private_dirty: Optional[int]

The number of dirty private pages in process’ mappings.

referenced: Optional[int]

It indicates the amount of memory currently marked as referenced or accessed.

anonymous: Optional[int]

It shows the amount of memory that does not belong to any file.

lazyfree: Optional[int]

It shows the amount of memory which is marked by madvise(MADV_FREE). The memory isn’t freed immediately with madvise(). It’s freed in memory pressure if the memory is clean.

anonhugepages: Optional[int]

It shows the amount of memory backed by transparent huge pages.

shmempmdmapped: Optional[int]

It shows the amount of shared (shmem/tmpfs) memory backed by huge pages.

shared_hugetlb: Optional[int]

It shows the amount of memory backed by hugetlbfs page which is not counted in rss or pss fields for historical reasons. And it is not included in shared_clean and shared_dirty fields.

private_hugetlb: Optional[int]

It shows the amount of memory backed by hugetlbfs page which is not counted in rss or pss fields for historical reasons. And it is not included in private_clean and private_dirty fields.

swap: Optional[int]

It shows how much would-be-anonymous memory is also used, but out on swap.

swappss: Optional[int]

It shows proportional swap share of process’ mappings. Unlike swap, this does not take into account swapped out page of underlying shmem objects.

locked: Optional[int]

It indicates the mappings that are locked in memory.