blob: 25b4a408afbcff4d835e9070e3bbaaabdf8488cf [file]
#!/usr/bin/env fuchsia-vendored-python
# Copyright 2026 The Fuchsia Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.
"""Linux procfs (/proc) parsing and process inspection utilities."""
import os
from collections.abc import Iterator, Mapping, Sequence
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any
DEFAULT_PROC_ROOT: Path = Path("/proc")
@dataclass(frozen=True, slots=True)
class ProcessStat:
"""Parsed attributes from /proc/<pid>/stat."""
pid: int
comm: str
state: str
ppid: int
pgrp: int
utime: int = 0
stime: int = 0
@dataclass(frozen=True, slots=True)
class ProcessInfo:
"""Snapshot of process metadata read from /proc/<pid>/."""
pid: int
ppid: int
comm: str
state: str
pgrp: int | None = None
cmdline: list[str] = field(default_factory=list)
wchan: str | None = None
utime: int = 0
stime: int = 0
def cmdline_str(self) -> str:
"""Returns the command line as a single line string, falling back to [comm]."""
return format_cmdline(self.cmdline, self.comm)
def parse_stat_file(content: str) -> ProcessStat | None:
"""Parses /proc/<pid>/stat file content.
The executable name (comm) is enclosed in parentheses, which may themselves
contain spaces or nested parentheses.
Returns:
ProcessStat instance, or None if parsing failed.
"""
lparen = content.find("(")
rparen = content.rfind(")")
if lparen == -1 or rparen == -1 or rparen < lparen:
return None
try:
pid = int(content[:lparen].strip())
except ValueError:
return None
comm = content[lparen + 1 : rparen]
rest = content[rparen + 1 :].strip().split()
if len(rest) < 3:
return None
state = rest[0]
try:
ppid = int(rest[1])
pgrp = int(rest[2])
except ValueError:
return None
utime = 0
stime = 0
if len(rest) >= 13:
try:
utime = int(rest[11])
stime = int(rest[12])
except ValueError:
pass
return ProcessStat(
pid=pid,
comm=comm,
state=state,
ppid=ppid,
pgrp=pgrp,
utime=utime,
stime=stime,
)
def parse_cmdline_file(
cmdline_bytes: bytes, fallback_comm: str = ""
) -> list[str]:
"""Parses NUL-separated argument bytes from /proc/<pid>/cmdline.
Args:
cmdline_bytes: Raw bytes read from cmdline file.
fallback_comm: Optional fallback process name to use if cmdline is empty (e.g. kernel threads).
Returns:
List of decoded argument strings.
"""
trimmed = cmdline_bytes.rstrip(b"\0")
if not trimmed:
return [f"[{fallback_comm}]"] if fallback_comm else []
return [
arg.decode("utf-8", errors="replace") for arg in trimmed.split(b"\0")
]
def format_cmdline(cmdline: Sequence[str], fallback_comm: str = "") -> str:
"""Formats a command line argument list into a clean single line string.
Embedded newlines and carriage returns are escaped so output lines
remain on a single line per process. Falls back to '[comm]' if empty.
"""
if cmdline:
sanitized = [
arg.replace("\n", "\\n").replace("\r", "\\r") for arg in cmdline
]
return " ".join(sanitized)
return f"[{fallback_comm}]" if fallback_comm else ""
def read_process_stat(
pid: int, proc_root: Path = DEFAULT_PROC_ROOT
) -> ProcessStat | None:
"""Reads and parses /proc/<pid>/stat for a given PID.
Args:
pid: The process ID to inspect.
proc_root: Path to the procfs filesystem (default: DEFAULT_PROC_ROOT).
Returns:
ProcessStat instance, or None if the process does not exist or is inaccessible.
"""
proc_dir = proc_root / str(pid)
try:
stat_text = (proc_dir / "stat").read_text(
encoding="utf-8", errors="replace"
)
except (FileNotFoundError, ProcessLookupError, PermissionError):
return None
return parse_stat_file(stat_text)
def read_process_comm(
pid: int, proc_root: Path = DEFAULT_PROC_ROOT
) -> str | None:
"""Reads the process command name from /proc/<pid>/comm."""
try:
return (
(proc_root / str(pid) / "comm")
.read_text(encoding="utf-8", errors="replace")
.rstrip("\n")
)
except OSError:
return None
def read_process_cwd(
pid: int, proc_root: Path = DEFAULT_PROC_ROOT
) -> Path | None:
"""Resolves the working directory symlink /proc/<pid>/cwd."""
try:
return (proc_root / str(pid) / "cwd").resolve(strict=True)
except OSError:
return None
def read_process_environ(
pid: int, proc_root: Path = DEFAULT_PROC_ROOT
) -> dict[str, str] | None:
"""Reads and parses NUL-separated KEY=VALUE entries from /proc/<pid>/environ."""
try:
text = (proc_root / str(pid) / "environ").read_text(
encoding="utf-8", errors="replace"
)
except OSError:
return None
env: dict[str, str] = {}
for entry in text.split("\0"):
if "=" in entry:
k, _, v = entry.partition("=")
env[k] = v
return env
def read_process_info(
pid: int, proc_root: Path = DEFAULT_PROC_ROOT
) -> ProcessInfo | None:
"""Reads process metadata for a given PID from procfs.
Args:
pid: The process ID to inspect.
proc_root: Path to the procfs filesystem (default: DEFAULT_PROC_ROOT).
Returns:
ProcessInfo instance, or None if the process does not exist or is inaccessible.
"""
proc_dir = proc_root / str(pid)
parsed_stat = read_process_stat(pid, proc_root=proc_root)
if not parsed_stat:
return None
cmdline_args: list[str] = []
try:
cmdline_bytes = (proc_dir / "cmdline").read_bytes()
cmdline_args = parse_cmdline_file(cmdline_bytes, parsed_stat.comm)
except (FileNotFoundError, ProcessLookupError, PermissionError):
cmdline_args = [f"[{parsed_stat.comm}]"]
wchan: str | None = None
try:
wchan_text = (
(proc_dir / "wchan")
.read_text(encoding="utf-8", errors="replace")
.strip()
)
if wchan_text and wchan_text != "0":
wchan = wchan_text
except (FileNotFoundError, ProcessLookupError, PermissionError):
pass
return ProcessInfo(
pid=parsed_stat.pid,
ppid=parsed_stat.ppid,
comm=parsed_stat.comm,
state=parsed_stat.state,
pgrp=parsed_stat.pgrp,
cmdline=cmdline_args,
wchan=wchan,
utime=parsed_stat.utime,
stime=parsed_stat.stime,
)
def iter_pids(proc_root: Path = DEFAULT_PROC_ROOT) -> Iterator[int]:
"""Yields integer process IDs discovered under proc_root."""
try:
with os.scandir(proc_root) as it:
for entry in it:
try:
# In /proc, only numeric directory names correspond to processes.
# Ephemeral processes may exit concurrently mid-traversal, so check
# entry.is_dir() and safely skip missing or non-directory entries.
if entry.name.isdigit() and entry.is_dir():
yield int(entry.name)
except (OSError, ValueError):
continue
except (FileNotFoundError, PermissionError):
return
def read_all_processes(
proc_root: Path = DEFAULT_PROC_ROOT,
) -> dict[int, ProcessInfo]:
"""Reads and returns a mapping of pid to ProcessInfo for all discovered processes."""
processes: dict[int, ProcessInfo] = {}
for pid in iter_pids(proc_root):
info = read_process_info(pid, proc_root=proc_root)
if info:
processes[info.pid] = info
return processes
def read_ppid_map(proc_root: Path = DEFAULT_PROC_ROOT) -> dict[int, int]:
"""Reads a mapping of PID to parent PID (PPID) for all active processes.
Only parses lightweight /proc/[PID]/stat files, avoiding reading
cmdline or wchan for every process on the system.
"""
ppid_map: dict[int, int] = {}
for pid in iter_pids(proc_root):
stat = read_process_stat(pid, proc_root=proc_root)
if stat:
ppid_map[pid] = stat.ppid
return ppid_map
def count_process_fds(pid: int, proc_root: Path = DEFAULT_PROC_ROOT) -> int:
"""Counts the number of open file descriptors for a given process PID."""
try:
# Avoid materializing the full directory list in memory when processes
# have thousands of open file descriptors.
return sum(1 for _ in (proc_root / str(pid) / "fd").iterdir())
except (
FileNotFoundError,
PermissionError,
ProcessLookupError,
NotADirectoryError,
):
# A process may exit or close its file descriptors concurrently while
# we are counting, in which case returning 0 is the correct fallback.
return 0
def find_descendant_pids(
root_pid: int,
ppid_map: Mapping[int, int] | None = None,
proc_root: Path = DEFAULT_PROC_ROOT,
) -> set[int]:
"""Returns a set of all active descendant PIDs (including root_pid) under root_pid."""
if ppid_map is None:
ppid_map = read_ppid_map(proc_root=proc_root)
descendants = {root_pid}
children_map: dict[int, list[int]] = {}
for pid, ppid in ppid_map.items():
children_map.setdefault(ppid, []).append(pid)
queue = [root_pid]
while queue:
curr = queue.pop()
for child in children_map.get(curr, []):
if child not in descendants:
descendants.add(child)
queue.append(child)
return descendants
@dataclass(frozen=True, slots=True)
class LoadAvgData:
"""1-minute, 5-minute, and 15-minute system load averages."""
load1: float
load5: float
load15: float
def parse_loadavg(content: str) -> LoadAvgData | None:
"""Parses 1-min, 5-min, and 15-min load averages from /proc/loadavg."""
parts = content.strip().split()
if len(parts) < 3:
return None
try:
return LoadAvgData(float(parts[0]), float(parts[1]), float(parts[2]))
except ValueError:
return None
@dataclass(frozen=True, slots=True)
class CpuInfo:
"""CPU hardware information parsed from /proc/cpuinfo."""
model_name: str
logical_processors: int
physical_cores: int
def to_dict(self) -> dict[str, Any]:
"""Converts the CPU info record to a clean JSON-serializable dictionary."""
return {
"model_name": self.model_name,
"logical_processors": self.logical_processors,
"physical_cores": self.physical_cores,
}
def parse_cpuinfo(content: str) -> CpuInfo:
"""Parses /proc/cpuinfo content and returns a CpuInfo record."""
model_name = "Unknown"
logical_processors = 0
physical_cores = 0
for line in content.splitlines():
if ":" in line:
key, val = [parts.strip() for parts in line.split(":", 1)]
if key == "processor":
logical_processors += 1
elif key == "model name" and model_name == "Unknown":
model_name = val
elif key == "cpu cores" and physical_cores == 0:
try:
physical_cores = int(val)
except ValueError:
pass
if physical_cores == 0:
physical_cores = logical_processors
return CpuInfo(
model_name=model_name,
logical_processors=logical_processors,
physical_cores=physical_cores,
)
@dataclass(frozen=True, slots=True)
class MountEntry:
"""Filesystem mount entry parsed from /proc/mounts."""
device: str
mount_point: str
fstype: str
options: str
def parse_mounts(content: str) -> Iterator[MountEntry]:
"""Parses /proc/mounts content and yields MountEntry records."""
for line in content.splitlines():
parts = line.split()
if len(parts) >= 4:
yield MountEntry(
device=parts[0],
mount_point=parts[1],
fstype=parts[2],
options=parts[3],
)
def parse_meminfo_bytes(content: str, key: str = "MemTotal") -> int:
"""Parses a byte count for a given key from /proc/meminfo content (e.g. 'MemTotal').
Values in /proc/meminfo typically include a unit suffix like 'kB' (1024 bytes).
Handles 'kB', 'MB', 'GB', or raw bytes if unspecified.
"""
target = f"{key}:"
for line in content.splitlines():
if line.startswith(target):
parts = line.split()
if len(parts) >= 2:
try:
val = int(parts[1])
unit = parts[2].lower() if len(parts) >= 3 else "kb"
multipliers = {
"b": 1,
"kb": 1024,
"kib": 1024,
"mb": 1024 * 1024,
"gb": 1024 * 1024 * 1024,
}
return val * multipliers.get(unit, 1024)
except ValueError:
pass
break
return 0
def _tokenize_proc_lines(lines: Sequence[str]) -> dict[str, list[str]]:
"""Maps the first token (key) of each line to its remaining tokens.
Ignores trailing colons on keys (e.g. 'MemTotal:' -> 'MemTotal') and skips empty lines.
"""
tokens: dict[str, list[str]] = {}
for line in lines:
parts = line.split()
if parts:
tokens[parts[0].rstrip(":")] = parts[1:]
return tokens
def _parse_proc_ints(lines: Sequence[str]) -> dict[str, int]:
"""Parses whitespace/colon-separated key-integer lines into a dictionary.
Safely skips non-numeric lines or truncated fields.
"""
result: dict[str, int] = {}
for line in lines:
parts = line.split()
if len(parts) >= 2:
try:
result[parts[0].rstrip(":")] = int(parts[1])
except ValueError:
# Silently ignore non-numeric fields (e.g. headers or strings).
pass
return result
@dataclass(frozen=True, slots=True)
class ProcStatData:
"""System-wide CPU ticks and scheduler metrics parsed from /proc/stat."""
cpu_ticks: list[int]
procs_running: int | None
procs_blocked: int | None
intr: int | None
ctxt: int | None
def parse_proc_stat(lines: list[str]) -> ProcStatData:
"""Parses /proc/stat lines into ProcStatData.
Args:
lines: Raw list of lines read from /proc/stat.
Returns:
A ProcStatData instance containing parsed CPU ticks, runnable/blocked
process counts, context switches, and interrupt counts.
"""
tokens = _tokenize_proc_lines(lines)
def _get_int(key: str) -> int | None:
values = tokens.get(key)
if values:
try:
return int(values[0])
except ValueError:
# If /proc/stat line is corrupted or non-numeric, leave field as None.
return None
return None
def _get_int_list(key: str) -> list[int]:
values = tokens.get(key)
if not values:
return []
try:
return [int(x) for x in values]
except ValueError:
return []
return ProcStatData(
cpu_ticks=_get_int_list("cpu"),
procs_running=_get_int("procs_running"),
procs_blocked=_get_int("procs_blocked"),
intr=_get_int("intr"),
ctxt=_get_int("ctxt"),
)
@dataclass(frozen=True, slots=True)
class MemInfoData:
"""System memory allocation metrics parsed from /proc/meminfo."""
free: int
buffers: int
cached: int
swap_used: int
dirty: int
writeback: int
def parse_proc_meminfo(lines: list[str]) -> MemInfoData:
"""Parses /proc/meminfo lines into MemInfoData.
Values in /proc/meminfo are in kB (kibibytes); converted to bytes (* 1024).
Args:
lines: Raw list of lines read from /proc/meminfo.
Returns:
A MemInfoData instance with calculated values in bytes representing free,
buffered, cached, swap used, dirty, and writeback memory.
"""
mem_kb = _parse_proc_ints(lines)
free = mem_kb.get("MemFree", 0) * 1024
buffers = mem_kb.get("Buffers", 0) * 1024
cached = (
mem_kb.get("Cached", 0)
+ mem_kb.get("SReclaimable", 0)
- mem_kb.get("Shmem", 0)
) * 1024
swap_used = (mem_kb.get("SwapTotal", 0) - mem_kb.get("SwapFree", 0)) * 1024
dirty = mem_kb.get("Dirty", 0) * 1024
writeback = mem_kb.get("Writeback", 0) * 1024
return MemInfoData(
free=free,
buffers=buffers,
cached=cached,
swap_used=swap_used,
dirty=dirty,
writeback=writeback,
)
@dataclass(frozen=True, slots=True)
class VmStatData:
"""Virtual memory paging and swap statistics parsed from /proc/vmstat."""
pgpgin: int
pgpgout: int
pswpin: int
pswpout: int
def parse_proc_vmstat(lines: list[str]) -> VmStatData:
"""Parses /proc/vmstat lines into VmStatData.
Args:
lines: Raw list of lines read from /proc/vmstat.
Returns:
A VmStatData instance containing page in/out and swap in/out counts in bytes.
"""
vm_dict = _parse_proc_ints(lines)
# pgpgin/pgpgout are in KiB, convert to Bytes
pg_in = vm_dict.get("pgpgin", 0) * 1024
pg_out = vm_dict.get("pgpgout", 0) * 1024
# pswpin/pswpout are in pages (typically 4KiB), convert to Bytes
pswp_in = vm_dict.get("pswpin", 0) * 4096
pswp_out = vm_dict.get("pswpout", 0) * 4096
return VmStatData(
pgpgin=pg_in,
pgpgout=pg_out,
pswpin=pswp_in,
pswpout=pswp_out,
)
@dataclass(frozen=True, slots=True)
class FileNrData:
"""File descriptor allocation metrics parsed from /proc/sys/fs/file-nr."""
allocated: int
free_allocated: int
def parse_file_nr(content: str) -> FileNrData | None:
"""Parses /proc/sys/fs/file-nr content into FileNrData.
Args:
content: The text content of /proc/sys/fs/file-nr.
Returns:
A FileNrData instance containing system-wide allocated and free allocated
file descriptors, or None if the content is malformed or empty.
"""
parts = content.split()
if len(parts) < 2:
return None
try:
return FileNrData(allocated=int(parts[0]), free_allocated=int(parts[1]))
except ValueError:
# Return None rather than fabricating zero counts if format is non-numeric.
return None
@dataclass(frozen=True, slots=True)
class PressureLine:
"""10-second, 60-second, and 300-second pressure stall averages."""
avg10: float
avg60: float
avg300: float
@dataclass(frozen=True, slots=True)
class PressureData:
"""Pressure Stall Information (PSI) for 'some' and 'full' categories."""
some: PressureLine | None
full: PressureLine | None
def parse_pressure_file(lines: list[str]) -> PressureData:
"""Parses a pressure file (e.g. /proc/pressure/cpu) into PressureData.
Args:
lines: Raw list of lines read from a pressure stall information file.
Returns:
A PressureData instance containing 10s, 60s, 300s avg stalls for 'some'
and 'full' categories, where applicable.
"""
some: PressureLine | None = None
full: PressureLine | None = None
for line in lines:
parts = line.split()
if not parts:
continue
prefix = parts[0]
metrics: dict[str, float] = {}
for item in parts[1:]:
if "=" in item:
k, v = item.split("=", 1)
try:
metrics[k] = float(v)
except ValueError:
pass
if "avg10" in metrics and "avg60" in metrics and "avg300" in metrics:
line_data = PressureLine(
avg10=metrics["avg10"],
avg60=metrics["avg60"],
avg300=metrics["avg300"],
)
if prefix == "some":
some = line_data
elif prefix == "full":
full = line_data
return PressureData(some=some, full=full)
@dataclass(frozen=True, slots=True)
class InterfaceNetworkData:
"""Network interface transfer statistics parsed from /proc/net/dev."""
ifname: str
rx_bytes: int
rx_packets: int
tx_bytes: int
tx_packets: int
def parse_net_dev(lines: list[str]) -> list[InterfaceNetworkData]:
"""Parses /proc/net/dev lines into a list of InterfaceNetworkData.
Filters out loopback, virtual, and completely inactive interfaces.
Args:
lines: Raw list of lines read from /proc/net/dev.
Returns:
A list of InterfaceNetworkData instances, one per active physical interface.
"""
results: list[InterfaceNetworkData] = []
for line in lines[2:]:
parts = line.split()
if len(parts) < 17:
continue
ifname = parts[0].strip(":")
if ifname == "lo" or ifname.startswith(
("veth", "docker", "br-", "virbr", "dummy", "tun", "tap")
):
continue
try:
rx_bytes, rx_packets = int(parts[1]), int(parts[2])
tx_bytes, tx_packets = int(parts[9]), int(parts[10])
except ValueError:
continue
if rx_bytes == 0 and tx_bytes == 0:
continue
results.append(
InterfaceNetworkData(
ifname=ifname,
rx_bytes=rx_bytes,
rx_packets=rx_packets,
tx_bytes=tx_bytes,
tx_packets=tx_packets,
)
)
return results