Process Management #

Version Compatibility: XyPriss v6.0.0 and above

Overview #

The Process Management API provides comprehensive access to system process information, enabling applications to monitor running processes, track resource consumption, and identify system bottlenecks.

API Reference #

`$processes(options?: ProcessOptions): ProcessInfo[] | ProcessInfo | ProcessStats` #

Retrieves process information with flexible filtering options.

Parameters:

options - (Optional) Filter and query options

Options:

interface ProcessOptions {
    pid?: number; // Get specific process by PID
    topCpu?: number; // Get top N processes by CPU usage
    topMem?: number; // Get top N processes by memory usage
}

Returns:

ProcessInfo[] - Array of processes (default or with top filters)
ProcessInfo - Single process (when pid specified)
ProcessStats - Process statistics summary

Return Types #

ProcessInfo #

Detailed information about a single process.

interface ProcessInfo {
    pid: number; // Process ID
    name: string; // Process name
    exe?: string; // Executable path
    cmd: string[]; // Command line arguments
    cpu_usage: number; // CPU usage percentage
    memory: number; // Memory usage in bytes
    virtual_memory: number; // Virtual memory in bytes
    status: string; // Process status (Running, Sleeping, etc.)
    start_time: number; // Start timestamp
    run_time: number; // Runtime in seconds
    parent_pid?: number; // Parent process ID
    user_id?: string; // User ID running the process
    disk_read: number; // Bytes read from disk
    disk_write: number; // Bytes written to disk
}

ProcessStats #

Aggregate statistics about all processes.

interface ProcessStats {
    total_processes: number; // Total number of processes
    running: number; // Number of running processes
    sleeping: number; // Number of sleeping processes
    stopped: number; // Number of stopped processes
    zombie: number; // Number of zombie processes
}

Usage Examples #

Get All Processes #

const processes = __sys__.$processes() as ProcessInfo[];

console.log(`Total processes: ${processes.length}`);

processes.slice(0, 10).forEach((proc) => {
    console.log(
        `${proc.pid}: ${proc.name} (CPU: ${proc.cpu_usage.toFixed(1)}%)`
    );
});

Find Top CPU Consumers #

const topCpu = __sys__.$processes({ topCpu: 5 }) as ProcessInfo[];

console.log("=== Top 5 CPU Consumers ===");
topCpu.forEach((proc, index) => {
    console.log(`${index + 1}. ${proc.name}`);
    console.log(`   PID: ${proc.pid}`);
    console.log(`   CPU: ${proc.cpu_usage.toFixed(2)}%`);
    console.log(`   Memory: ${(proc.memory / 1024 ** 2).toFixed(2)} MB`);
});

Find Top Memory Consumers #

const topMem = __sys__.$processes({ topMem: 5 }) as ProcessInfo[];

console.log("=== Top 5 Memory Consumers ===");
topMem.forEach((proc, index) => {
    const memoryMB = proc.memory / 1024 ** 2;
    console.log(`${index + 1}. ${proc.name}: ${memoryMB.toFixed(2)} MB`);
});

Get Specific Process #

const currentPid = process.pid;
const currentProc = __sys__.$processes({ pid: currentPid }) as ProcessInfo;

if (currentProc) {
    console.log("Current Process Info:");
    console.log(`  Name: ${currentProc.name}`);
    console.log(`  PID: ${currentProc.pid}`);
    console.log(`  CPU: ${currentProc.cpu_usage.toFixed(2)}%`);
    console.log(`  Memory: ${(currentProc.memory / 1024 ** 2).toFixed(2)} MB`);
    console.log(`  Runtime: ${currentProc.run_time} seconds`);
}

Common Patterns #

Process Monitoring #

class ProcessMonitor {
    private pid: number;
    private thresholds = {
        cpu: 80, // 80% CPU
        memory: 1024, // 1GB memory
    };

    constructor(pid: number) {
        this.pid = pid;
    }

    check(): void {
        const proc = __sys__.$processes({ pid: this.pid }) as ProcessInfo;

        if (!proc) {
            console.error(`Process ${this.pid} not found`);
            return;
        }

        if (proc.cpu_usage > this.thresholds.cpu) {
            console.warn(`High CPU usage: ${proc.cpu_usage.toFixed(1)}%`);
        }

        const memoryMB = proc.memory / 1024 ** 2;
        if (memoryMB > this.thresholds.memory) {
            console.warn(`High memory usage: ${memoryMB.toFixed(2)} MB`);
        }
    }
}

const monitor = new ProcessMonitor(process.pid);
setInterval(() => monitor.check(), 5000);

Find Processes by Name #

function findProcessesByName(name: string): ProcessInfo[] {
    const allProcesses = __sys__.$processes() as ProcessInfo[];

    return allProcesses.filter((proc) =>
        proc.name.toLowerCase().includes(name.toLowerCase())
    );
}

const nodeProcesses = findProcessesByName("node");
console.log(`Found ${nodeProcesses.length} Node.js processes`);

Resource Usage Report #

function generateResourceReport(): string {
    const topCpu = __sys__.$processes({ topCpu: 3 }) as ProcessInfo[];
    const topMem = __sys__.$processes({ topMem: 3 }) as ProcessInfo[];

    let report = "=== System Resource Usage ===\n\n";

    report += "Top CPU Consumers:\n";
    topCpu.forEach((proc, i) => {
        report += `  ${i + 1}. ${proc.name} (${proc.cpu_usage.toFixed(1)}%)\n`;
    });

    report += "\nTop Memory Consumers:\n";
    topMem.forEach((proc, i) => {
        const mb = (proc.memory / 1024 ** 2).toFixed(2);
        report += `  ${i + 1}. ${proc.name} (${mb} MB)\n`;
    });

    return report;
}

console.log(generateResourceReport());

Detect Resource Hogs #

interface ResourceHog {
    process: ProcessInfo;
    reason: string;
}

function detectResourceHogs(): ResourceHog[] {
    const processes = __sys__.$processes() as ProcessInfo[];
    const hogs: ResourceHog[] = [];

    processes.forEach((proc) => {
        // High CPU usage
        if (proc.cpu_usage > 75) {
            hogs.push({
                process: proc,
                reason: `High CPU usage: ${proc.cpu_usage.toFixed(1)}%`,
            });
        }

        // High memory usage (>1GB)
        if (proc.memory > 1024 ** 3) {
            hogs.push({
                process: proc,
                reason: `High memory usage: ${(proc.memory / 1024 ** 3).toFixed(
                    2
                )} GB`,
            });
        }

        // High disk I/O (>100MB)
        const totalIO = proc.disk_read + proc.disk_write;
        if (totalIO > 100 * 1024 ** 2) {
            hogs.push({
                process: proc,
                reason: `High disk I/O: ${(totalIO / 1024 ** 2).toFixed(2)} MB`,
            });
        }
    });

    return hogs;
}

const hogs = detectResourceHogs();
if (hogs.length > 0) {
    console.warn(`Found ${hogs.length} resource hogs:`);
    hogs.forEach((hog) => {
        console.warn(
            `  ${hog.process.name} (PID ${hog.process.pid}): ${hog.reason}`
        );
    });
}

Process Tree Analysis #

interface ProcessTree {
    process: ProcessInfo;
    children: ProcessTree[];
}

function buildProcessTree(rootPid: number): ProcessTree | null {
    const allProcesses = __sys__.$processes() as ProcessInfo[];
    const root = allProcesses.find((p) => p.pid === rootPid);

    if (!root) return null;

    const children = allProcesses
        .filter((p) => p.parent_pid === rootPid)
        .map((child) => buildProcessTree(child.pid))
        .filter((tree): tree is ProcessTree => tree !== null);

    return { process: root, children };
}

function printProcessTree(tree: ProcessTree, indent: string = ""): void {
    console.log(`${indent}${tree.process.name} (${tree.process.pid})`);
    tree.children.forEach((child) => {
        printProcessTree(child, indent + "  ");
    });
}

const tree = buildProcessTree(process.pid);
if (tree) {
    printProcessTree(tree);
}

Long-Running Process Detection #

function findLongRunningProcesses(minHours: number = 24): ProcessInfo[] {
    const processes = __sys__.$processes() as ProcessInfo[];
    const minSeconds = minHours * 3600;

    return processes.filter((proc) => proc.run_time > minSeconds);
}

const longRunning = findLongRunningProcesses(48);
console.log(`Processes running for more than 48 hours: ${longRunning.length}`);
longRunning.forEach((proc) => {
    const hours = (proc.run_time / 3600).toFixed(1);
    console.log(`  ${proc.name} (${hours}h)`);
});

Best Practices #

1. Cache Process Lists #

class ProcessCache {
    private cache: ProcessInfo[] = [];
    private lastUpdate = 0;
    private ttl = 5000; // 5 seconds

    getProcesses(): ProcessInfo[] {
        const now = Date.now();

        if (now - this.lastUpdate > this.ttl) {
            this.cache = __sys__.$processes() as ProcessInfo[];
            this.lastUpdate = now;
        }

        return this.cache;
    }
}

const cache = new ProcessCache();
const processes = cache.getProcesses(); // Uses cache if recent

2. Filter Early #

// Good: Use built-in filters
const topCpu = __sys__.$processes({ topCpu: 10 }) as ProcessInfo[];

// Avoid: Getting all processes then filtering
const all = __sys__.$processes() as ProcessInfo[];
const filtered = all.sort((a, b) => b.cpu_usage - a.cpu_usage).slice(0, 10);

3. Handle Missing Processes #

function getProcessSafely(pid: number): ProcessInfo | null {
    try {
        const proc = __sys__.$processes({ pid }) as ProcessInfo;
        return proc || null;
    } catch (error) {
        console.warn(`Process ${pid} not found or inaccessible`);
        return null;
    }
}

4. Aggregate Statistics #

function getProcessStatistics(): {
    total: number;
    totalCpu: number;
    totalMemory: number;
    avgCpu: number;
    avgMemory: number;
} {
    const processes = __sys__.$processes() as ProcessInfo[];

    const totalCpu = processes.reduce((sum, p) => sum + p.cpu_usage, 0);
    const totalMemory = processes.reduce((sum, p) => sum + p.memory, 0);

    return {
        total: processes.length,
        totalCpu,
        totalMemory,
        avgCpu: totalCpu / processes.length,
        avgMemory: totalMemory / processes.length,
    };
}

5. Monitor Critical Processes #

const criticalProcesses = ["nginx", "postgres", "redis"];

function checkCriticalProcesses(): void {
    const allProcesses = __sys__.$processes() as ProcessInfo[];

    criticalProcesses.forEach((name) => {
        const found = allProcesses.some((p) =>
            p.name.toLowerCase().includes(name.toLowerCase())
        );

        if (!found) {
            console.error(`Critical process not running: ${name}`);
        }
    });
}

setInterval(checkCriticalProcesses, 30000);

Platform Considerations #

Linux #

Full process information available
Accurate CPU and memory metrics
Complete disk I/O statistics

macOS #

Full process information available
Accurate metrics
Some fields may be unavailable for system processes

Windows #

Full process information available
Process names may differ from Unix systems
User ID format differs

Performance Impact #

Process querying operations:

All Processes: ~10-50ms (depends on process count)
Top N Processes: ~10-50ms (sorted at native level)
Single Process: ~1-5ms
Memory Overhead: ~1KB per process

Troubleshooting #

Process Not Found #

const proc = __sys__.$processes({ pid: 12345 }) as ProcessInfo;

if (!proc) {
    console.error(
        "Process not found - may have terminated or insufficient permissions"
    );
}

Permission Denied #

// Some process information may require elevated privileges
try {
    const processes = __sys__.$processes() as ProcessInfo[];
    console.log(`Found ${processes.length} accessible processes`);
} catch (error) {
    console.error("Insufficient permissions to query processes");
}

Version: XyPriss v6.0.0+
Last Updated: 2026-01-12

api/system/path-operations api/system/search-filter