Project 1: Process Explorer Dashboard

Build a terminal dashboard that explains every process field by reading /proc and correlating with ps.

Quick Reference

Attribute	Value
Difficulty	Beginner
Time Estimate	Weekend
Language	Bash (Alternatives: Python, Go, Rust)
Prerequisites	Basic shell scripting, file I/O
Key Topics	/proc, process states, CPU accounting

1. Learning Objectives

By completing this project, you will:

Parse /proc/<pid>/stat and /proc/<pid>/status safely.
Build a process tree from PPID relationships.
Compute CPU usage from jiffies and elapsed time.
Explain ps columns in terms of kernel data sources.

2. Theoretical Foundation

2.1 Core Concepts

/proc as a kernel view: /proc is a virtual filesystem exposing live kernel data structures such as task_struct.
Process states: R, S, D, Z, T encode scheduler state; D (uninterruptible) is often I/O wait.
CPU accounting: utime and stime in /proc/<pid>/stat are measured in clock ticks (jiffies) and must be sampled twice.

2.2 Why This Matters

Most monitoring tools are wrappers around /proc. Understanding it removes the mystery behind ps, top, and similar tools.

2.3 Historical Context / Background

/proc originated as a simple way to expose kernel internals without special tooling. Modern Linux expands it into a comprehensive process and system API.

2.4 Common Misconceptions

“/proc is a real disk”: It is virtual and generated on read.
“CPU% is a single read”: It requires two samples and wall-clock time.

3. Project Specification

3.1 What You Will Build

A terminal dashboard that lists processes with PID, PPID, state, CPU%, memory, time, and a basic process tree.

3.2 Functional Requirements

Read process metadata from /proc/<pid>/stat and /proc/<pid>/status.
Build a parent-child tree based on PPID.
Refresh data on an interval and handle disappearing processes.

3.3 Non-Functional Requirements

Performance: Handle hundreds of PIDs without noticeable lag.
Reliability: Ignore processes that vanish mid-read.
Usability: Provide a stable, readable table output.

3.4 Example Usage / Output

$ ./procexplorer
PID  PPID STATE  CPU%  RSS   COMMAND
1    0    S      0.0   3M    systemd
521  1    S      0.1   9M    sshd
1234 521  R      5.2   22M   python3 server.py

3.5 Real World Outcome

You will run the script and see a live process list and tree derived from /proc with calculated CPU%. Example:

$ ./procexplorer
PID  PPID STATE  CPU%  RSS   COMMAND
1    0    S      0.0   3M    systemd
521  1    S      0.1   9M    sshd
1234 521  R      5.2   22M   python3 server.py

4. Solution Architecture

4.1 High-Level Design

/proc scan -> parse stat/status -> compute deltas -> build tree -> render table

4.2 Key Components

Component	Responsibility	Key Decisions
Proc scanner	List numeric PIDs	Ignore permission errors
Parser	Extract fields	Handle stat field with command in parentheses
CPU calculator	Compute delta jiffies	Sample at fixed intervals
Renderer	Print table/tree	Keep fixed columns

4.3 Data Structures

# PID -> struct-like map in bash
PID_STAT[pid]="ppid,state,utime,stime,rss,cmd"

4.4 Algorithm Overview

Key Algorithm: CPU Percentage

Read utime+stime for each PID.
Sleep for interval.
Read again and compute delta.

Complexity Analysis:

Time: O(n) per refresh, n = number of processes
Space: O(n)

5. Implementation Guide

5.1 Development Environment Setup

bash --version

5.2 Project Structure

project-root/
├── procexplorer.sh
└── README.md

5.3 The Core Question You’re Answering

“Where does ps get its information, and what do those columns actually mean?”

5.4 Concepts You Must Understand First

Stop and research these before coding:

/proc Layout
- /proc/<pid>/stat field meanings.
- /proc/<pid>/status key-value data.
Process States
- R/S/D/Z/T meanings and implications.
CPU Accounting
- What a jiffy is and how to convert ticks to seconds.

5.5 Questions to Guide Your Design

Before implementing, think through these:

How will you handle processes that disappear between reads?
Do you prefer tree output or flat list first?
What columns must always fit in 80 columns?

5.6 Thinking Exercise

Map ps to /proc

Pick one PID, run ps -o pid,ppid,state,comm -p <pid>, then find each value in /proc/<pid>/stat and /proc/<pid>/status.

5.7 The Interview Questions They’ll Ask

Prepare to answer these:

“What is /proc, and why is it useful?”
“Why can’t a D-state process be killed?”
“How is CPU% calculated for a process?”

5.8 Hints in Layers

Hint 1: Parse stat carefully The command name is inside parentheses and may contain spaces.

Hint 2: Use two samples Store previous utime+stime values for each PID.

Hint 3: Skip unreadable PIDs Permission errors are normal; ignore them.

5.9 Books That Will Help

Topic	Book	Chapter
/proc	“The Linux Programming Interface”	Ch. 12
Process states	“Operating Systems: Three Easy Pieces”	Ch. 4-6
CPU accounting	“Linux System Programming”	Ch. 5

5.10 Implementation Phases

Phase 1: Foundation (Half day)

Goals:

Parse /proc/<pid>/stat for a single PID.

Tasks:

Read and split stat fields.
Print PID, PPID, state, utime, stime.

Checkpoint: Values match ps output for the same PID.

Phase 2: Core Functionality (1 day)

Goals:

Scan all PIDs and compute CPU%.

Tasks:

List numeric directories in /proc.
Sample twice and compute CPU%.

Checkpoint: CPU% looks plausible vs top.

Phase 3: Polish & Edge Cases (Half day)

Goals:

Build a tree view and handle missing processes.

Tasks:

Build PID->children map.
Render tree with indentation.

Checkpoint: Tree shows correct parent-child relationships.

5.11 Key Implementation Decisions

Decision	Options	Recommendation	Rationale
Data source	/proc vs ps	/proc	Direct kernel data
Output mode	Tree vs table	Table first	Easier to validate

6. Testing Strategy

6.1 Test Categories

Category	Purpose	Examples
Parsing	Validate field extraction	Compare with `ps`
CPU calc	Validate deltas	Compare with `top`
Tree	Validate relationships	Compare with `pstree`

6.2 Critical Test Cases

PID vanishes during read; tool skips without crashing.
CPU% updates between samples.
PPID tree matches pstree.

6.3 Test Data

Sample PID: 1 -> systemd

7. Common Pitfalls & Debugging

7.1 Frequent Mistakes

Pitfall	Symptom	Solution
Wrong stat parsing	Garbage fields	Handle parentheses correctly
Single-sample CPU%	0 or huge values	Use two samples
Permission errors	Script exits	Ignore unreadable PIDs

7.2 Debugging Strategies

Print raw /proc/<pid>/stat lines for a known PID.
Cross-check with ps -o pid,ppid,state,comm.

7.3 Performance Traps

Large /proc scans every 0.1s can be expensive; 1s is enough for a dashboard.

8. Extensions & Challenges

8.1 Beginner Extensions

Add RSS and VSZ columns.
Add a filter by user.

8.2 Intermediate Extensions

Add a simple sort by CPU%.
Add a mode to watch a single PID tree.

8.3 Advanced Extensions

Add an ncurses UI.
Export data as JSON.

9. Real-World Connections

9.1 Industry Applications

Real-time incident triage and process inspection.

procps: https://gitlab.com/procps-ng/procps
htop: https://htop.dev

9.3 Interview Relevance

Process state and /proc knowledge is a common systems interview topic.

10. Resources

10.1 Essential Reading

/proc(5) - man 5 proc
ps(1) - man 1 ps

10.2 Video Resources

Linux process model overview (search “Linux process /proc”)

10.3 Tools & Documentation

pstree(1) - man 1 pstree

System Health Monitor: use process data in system metrics.

11. Self-Assessment Checklist

11.1 Understanding

I can map ps columns to /proc fields.
I can explain process states.
I can compute CPU% from jiffies.

11.2 Implementation

The dashboard updates without crashing.
CPU% values are plausible.
The process tree is correct.

11.3 Growth

I can explain my tool to a teammate.
I can adapt it to a new output format.

12. Submission / Completion Criteria

Minimum Viable Completion:

Parse /proc for PID/state/command.
Display a refreshed process list.

Full Completion:

Compute CPU% and build a tree view.
Handle disappearing processes without errors.

Excellence (Going Above & Beyond):

Add sorting and filtering.
Provide JSON export for later analysis.

This guide was generated from LINUX_SYSTEM_TOOLS_MASTERY.md. For the complete learning path, see the parent directory.

Project 1: Process Explorer Dashboard

Quick Reference

1. Learning Objectives

2. Theoretical Foundation

2.1 Core Concepts

2.2 Why This Matters

2.3 Historical Context / Background

2.4 Common Misconceptions

3. Project Specification

3.1 What You Will Build

3.2 Functional Requirements

3.3 Non-Functional Requirements

3.4 Example Usage / Output

3.5 Real World Outcome

4. Solution Architecture

4.1 High-Level Design

4.2 Key Components

4.3 Data Structures

4.4 Algorithm Overview

5. Implementation Guide

5.1 Development Environment Setup

5.2 Project Structure

5.3 The Core Question You’re Answering

5.4 Concepts You Must Understand First

5.5 Questions to Guide Your Design

5.6 Thinking Exercise

Map ps to /proc

5.7 The Interview Questions They’ll Ask

5.8 Hints in Layers

5.9 Books That Will Help

5.10 Implementation Phases

Phase 1: Foundation (Half day)

Phase 2: Core Functionality (1 day)

Phase 3: Polish & Edge Cases (Half day)

5.11 Key Implementation Decisions

6. Testing Strategy

6.1 Test Categories

6.2 Critical Test Cases

6.3 Test Data

7. Common Pitfalls & Debugging

7.1 Frequent Mistakes

7.2 Debugging Strategies

7.3 Performance Traps

8. Extensions & Challenges

8.1 Beginner Extensions

8.2 Intermediate Extensions

8.3 Advanced Extensions

9. Real-World Connections

9.1 Industry Applications

9.2 Related Open Source Projects

9.3 Interview Relevance

10. Resources

10.1 Essential Reading

10.2 Video Resources

10.3 Tools & Documentation

10.4 Related Projects in This Series

11. Self-Assessment Checklist

11.1 Understanding

11.2 Implementation

11.3 Growth

12. Submission / Completion Criteria