Process Health Agent

A lightweight per-node Process Health Agent that exposes local Linux process information via a REST API.

The agent reads process metadata from the Linux /proc filesystem and makes it available over HTTP so that an external system (for example, a monitoring or dashboard service) can query process health on each node.

---

Table of Contents

• Process Health Agent
• Features
• API Overview
  • Endpoints
• Example Response
• Requirements (Local Build)
• Clone the Repository
• Build and Run Locally
  • Build
  • Run
• Interact with the Agent (Local)
  • Health Check
  • List Processes
  • Get a Single Process
  • Filter by State
  • Filter by Start Time (RFC3339 UTC)
  • Sorting and Limiting
• Docker
  • Build the Image
  • Run the Container (IMPORTANT)
• Interact with the Agent (Docker)
• Notes and Limitations
• Project Structure

---

Features

• Lists running processes on the node
• Retrieves details for a single process by PID
• Supports filtering and sorting
• Uses Linux /proc as the single source of truth
• Packaged as a Docker container
• Designed to run one agent per node

---

API Overview

Endpoints

• GET /health
  Health check endpoint.
  It is only for debugging/monitoring of the agent itself, not part of the specified API.

• GET /processes
  List processes with optional filters.

• GET /processes/{pid}
  Get details for a single process.

The full API specification is available in:

api/openapi.yaml

---

Example Response

{
  "processes": [
    {
      "pid": 1,
      "ppid": 0,
      "name": "systemd",
      "state": "sleeping",
      "start_time": "2026-01-15T19:07:38Z"
    }
  ],
  "count": 1
}

---

Requirements (Local Build)

• Linux
• C++20 compatible compiler (GCC / Clang)
• CMake ≥ 3.16
• Git (with submodules)

---

Clone the Repository

git clone --recurse-submodules <REPO_URL>
cd process_agent

If you already cloned without submodules:

git submodule update --init --recursive

---

Build and Run Locally

Build

mkdir -p build
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j

Run

./build/process-agent

The server listens on:

http://localhost:8080

By default, the examples below use localhost, assuming the agent is accessed from the same machine on which it is running. In practice, localhost can be replaced with the hostname or IP address of the machine where the agent is deployed, for example:

http://<node-ip>:8080
http://<hostname>:8080

This allows a central monitoring service to query multiple agents running on different nodes.

---

Interact with the Agent (Local)

Health Check

curl -i http://localhost:8080/health

List Processes

curl -i http://localhost:8080/processes

Get a Single Process

curl -i http://localhost:8080/processes/<PID>

for example:

curl -i http://localhost:8080/processes/2

Filter by State

curl -i "http://localhost:8080/processes?state=running"

Filter by Start Time (RFC3339 UTC)

curl -i "http://localhost:8080/processes?started_after=2026-01-01T00:00:00Z"

Sorting and Limiting

curl -i "http://localhost:8080/processes?sort=pid_desc&limit=5"

Supported sort values:

• pid_asc
• pid_desc
• start_time_asc
• start_time_desc

Optional: Using jq for JSON output

API responses are returned as JSON. For easier reading, you can pipe the output through jq, a lightweight command-line JSON processor.

Install jq

sudo apt install -y jq

Example usage

curl -s http://localhost:8080/processes | jq .

---

Docker

Build the Image

docker build -t process-agent:latest .

Run the Container (IMPORTANT)

To allow the agent to see host processes, the container must run in the host PID namespace:

docker run --rm -it \
  --name process-agent \
  --pid=host \
  -p 8080:8080 \
  process-agent:latest

Without --pid=host, the agent will only see container-internal processes.

---

Interact with the Agent (Docker)

curl -i http://localhost:8080/health
curl -i http://localhost:8080/processes
curl -i http://localhost:8080/processes/<PID>

see the local execution for more

---

Notes and Limitations

• started_after expects RFC3339 UTC timestamps of the form:

  YYYY-MM-DDTHH:MM:SSZ
  

• Process start times are reported with second-level precision.
  Multiple processes started shortly after boot may share the same timestamp.

• Processes may exit while being read from /proc; such processes are skipped gracefully.

---

Project Structure

.
├── Dockerfile
├── .dockerignore
├── CMakeLists.txt
├── README.md
├── api/
│   └── openapi.yaml
├── src/
│   ├── main.cpp
│   ├── procfs.hpp
│   └── procfs.cpp
└── external/
    ├── cpp-httplib/      (git submodule)
    └── nlohmann_json/    (git submodule)

---