ProcLens — Universal Process Intelligence & Workload Classifier

Production-grade, zero-ML-dependency process intelligence in a single statically-linked Go binary.

Quick Start · Commands · Architecture · Terminology Guide · Maths Explained · Contributing & Setup

What ProcLens does in one sentence:
It reads live /proc telemetry, classifies every running process into one of 37 semantic workload archetypes, generates validated kernel tuning recommendations, detects architectural shifts on the node, and optionally sends a structured payload to a frontier LLM for SRE narrative analysis — all in a single binary with no root required.

Quick Start
Why ProcLens? — Unique Selling Points
37 Workload Archetypes
System Architecture
What Inputs It Takes
How It Works
The Maths Behind It
Command Reference
Colourful Terminal Output
LLM Enrichment (enrich)
Build & Deploy
Security Model
Prometheus Metrics
Production Readiness Checklist
Testing & Quality
Comparison Matrix
Roadmap
Related Docs

Quick Start

# Build on any platform
go build -o proc-lens ./cmd/proc-lens

# Scan all running processes (with colourful output)
./proc-lens scan

# Deep-dive a specific PID (professional 256-colour terminal report)
./proc-lens analyze --pid 1234

# AI-enriched SRE report using default LLM provider (gemini)
export GEMINI_API_KEY="your-key"
./proc-lens enrich --allow-remote-llm

# Understand what a process is and why
./proc-lens explain --pid 1234

# Detect node workload drift from a scan log
./proc-lens drift --file scan.jsonl

📖 New to the project? Read CONTRIBUTING.md for a step-by-step development setup and execution guide, and terminologies.md for plain-English explanations of every technical concept used here.

Why ProcLens? — Unique Selling Points

ProcLens is built with 10 core Unique Selling Points (USPs) that distinguish it from traditional system tools. These include:

Semantic HLD Workload Classification (37 archetypes, zero ML, sub-10µs)
Node Workload Fingerprinting (Stable SHA-256 fleet signature)
Real-Time Workload Drift Detection (Structured JSONL alerts)
Validated, Safe Kernel Optimisation (Live comparison with /proc/sys)
Structured Recommendations (GitOps-friendly JSON)
Ultra-Low-Privilege Security Model (CAP_SYS_PTRACE only, no root)
Platform Capability Transparency (capabilities subcommand)
True Dual-Use Binary (Laptop CLI + production DaemonSet)
LLM Enrichment with Security Gates (Pre-redacted, explicit flags)
Professional 256-Colour Terminal Output (Material-inspired console UI)

📖 Want to see how ProcLens compares to standard tools? Read COMPETITIVE-LANDSCAPE.md for a detailed breakdown of each USP, comparisons against traditional exporters/profilers, and our deployment positioning.

Colourful Terminal Output

ProcLens features a sophisticated terminal interface designed for high-density information display, utilising 256-colour palettes to highlight system health and workload classification:

   InteractiveShell        [██████████████████████░░░░░░░░]  72.0%
   MessageBroker           [████████████████████░░░░░░░░░░]  68.0%
   LegacySOAService        [███████████████░░░░░░░░░░░░░░░]  54.0%

Bar fill colour scales by score: 🟢 ≥70% · 🟡 40–69% · 🟠 20–39% · ⬜ <20%
Archetype tier colours follow a Material Design-inspired palette (Blue=Network, Green=Database, Red=AI, etc.)
Telemetry rows colour-coded by threshold (green→yellow→red)

37 Workload Archetypes

The classifier now covers 37 archetypes organised into 9 tiers, reflecting the modern reality of cloud-native, serverless, legacy SOA, and ML-ops workloads:

📐 Curious exactly how a process becomes one of these 37 categories? See the full mathematical breakdown and examples in maths-behind-repo.md.

Tier	Categories
1 — Network Ingress	`LoadBalancer` · `APIGateway` · `ServiceMesh` · `CDNEdgeNode`
2 — Application	`WebServer` · `Microservice` · `ServerlessWorker` · `JobWorker` · `SchedulerDaemon`
3 — Data Stores	`CacheStore` · `RelationalDB` · `NoSQLDB` · `ColumnarDB` · `VectorDB` · `TimeSeriesDB` · `GraphDB` · `ObjectStore`
4 — Messaging	`MessageBroker` · `EventStreaming` · `StreamProcessor`
5 — Search/Analytics	`SearchEngine` · `OLAPEngine`
6 — AI/ML	`AITraining` · `AIInference` · `MLPipeline` · `FeatureStore`
7 — Infrastructure	`OrchestratorAgent` · `OrchestratorPod` · `ServiceDiscovery` · `ConfigManager`
8 — Observability	`MonitoringAgent` · `LogAggregator` · `TracingAgent`
9 — Developer/Legacy	`InteractiveShell` · `UtilityBatch` · `LegacySOAService` · `CIRunner` · `Unknown`

Examples per category (selected):

Category Real-world processes

APIGateway Kong, APISIX, KrakenD and similar

ServiceMesh Istio, Linkerd, Consul components

TimeSeriesDB InfluxDB, VictoriaMetrics, Prometheus TSDB

GraphDB Neo4j, JanusGraph, Dgraph

ObjectStore MinIO, SeaweedFS, Ceph RGW

StreamProcessor Apache Flink, Spark Streaming

OLAPEngine Trino/Presto, Apache Druid, Spark SQL

MLPipeline MLflow, Kubeflow, DVC, Prefect

LogAggregator Fluent Bit, Fluentd, Logstash, Vector

TracingAgent Jaeger, Zipkin, OTel trace components

LegacySOAService Traditional enterprise app servers (JBoss-style, WebLogic-style)

CIRunner Jenkins, GitLab CI, GitHub Actions runners

System Architecture

graph TD
    A[Cross-Platform gopsutil Telemetry] -->|Raw Stats Snapshot| B[Rate Computation Engine]
    B -->|Physical Metrics| C[Feature Extractor: simple scale]
    C -->|8-dim Feature Vector| D[Absolute Difference — 37 Centroids]
    D -->|Match Scores| E[Heuristics & Rule Boosters]
    E -->|Final Archetype| F[Node Fingerprint Engine SHA-256]
    F -->|Compare Cycles| G[Drift Detection Engine]
    E -->|Category| H[Autonomous Optimisation Engine]
    H -->|Verify /proc/sys live| I[Tuning Validation — PENDING/APPLIED]
    I -->|Structured JSON Recs| J[Cobra CLI · Prometheus · JSONL]
    G -->|DriftReport Events| J
    F -->|Fingerprint Events| J
    J -->|--allow-remote-llm| K[LLM Enrichment — default provider]

What Inputs It Takes

ProcLens gathers the following vital signs for every running process (primarily reading from the /proc filesystem on Linux):

CPU Usage: How much CPU power the process consumes.
Memory RSS: The physical RAM memory size occupied by the process.
Thread Count: The number of threads the process has spawned.
Socket Count: The number of active network connections (sockets).
File Descriptors: The count of open files and system resources.
I/O Read Speed: Disk read rates in kilobytes per second.
I/O Write Speed: Disk write rates in kilobytes per second.
Context Switches: The rate at which the CPU switches between different execution threads.
Cgroup Paths: Used to identify container boundaries and map processes to Kubernetes Namespace, Pod, and Container names.
System Configurations: Reads live host parameters (like vm.swappiness or net.core.somaxconn from /proc/sys/) to check if optimisations are already applied.

How It Works (Processing Pipeline)

ProcLens processes telemetry using simple, easy-to-understand arithmetic steps:

Step 1: Metric Scaling and Bounding

Telemetry metrics span completely different scales (e.g., Memory RSS can be thousands of megabytes, while Thread Count might be a single digit). If we compared raw numbers directly, the memory values would completely drown out the thread counts.

To keep comparisons fair, ProcLens scales every metric to a range between 0.0 and 10.0 by dividing the raw value by a standard scaling factor and capping the result at 10.0:

Telemetry Metric	Division Factor	Cap Limit
CPU Usage (%)	10.0	10.0
Memory (RSS) (MB)	100.0	10.0
Thread Count	10.0	10.0
Socket Count	50.0	10.0
File Descriptors (FDs)	50.0	10.0
Disk Read Speed (KB/s)	1000.0	10.0
Disk Write Speed (KB/s)	1000.0	10.0
Context Switch Rate	1000.0	10.0

Example: If a process uses 200MB of Memory, we divide by 100 to get 2.0. If a process uses 2048MB, dividing by 100 gives 20.48, which we cap at 10.0.

Step 2: Absolute Difference Profile Matching

For each category, ProcLens stores a "typical profile" (called a centroid) of what a process in that category looks like (e.g., the typical database profile has high memory and high disk write speed).

ProcLens compares a process's scaled metrics to each of the 37 category profiles using a simple absolute difference formula:

Find the difference for each of the 8 metrics.
Sum those differences and find the average difference.
Convert the average difference into a similarity score: $$\text{Similarity Score} = 1.0 - \left( \frac{\text{Average Difference}}{10.0} \right)$$
- If the average difference is 0.0, the similarity score is 1.0 ($100%$ match).
- If the average difference is 10.0, the similarity score is 0.0 ($0%$ match).

Step 3: Heuristic Rules and Boosters

Because some processes can look alike numerically (e.g., a web server and a microservice have similar resource profiles), ProcLens uses string-matching rules to boost scores:

Name & Arguments: If the process name contains "postgres" or "mysql", the RelationalDB score receives a significant boost.
Special Thresholds: If a process has more than 500 sockets, its LoadBalancer score is boosted.

Step 4: Workload Fingerprinting & Diversity Score

Every scan cycle, ProcLens compiles a stable SHA-256 fingerprint hash based on the percentage distribution of HLD categories (bucketed to the nearest 5% to avoid background noise).

It also computes a Shannon entropy diversity score scaled between 0.0 and 1.0:

0.0 means a single workload archetype dominates the host node completely.
1.0 represents a perfectly uniform mix of different workload types.

📖 See terminologies.md → Mathematics & Algorithms for beginner-friendly explanations of all these concepts.

📐 Want the full mathematical details with worked examples? Read maths-behind-repo.md — it explains the scaling, L1 distance, rule boosters, Shannon entropy, and includes concrete classification walkthroughs (bash, postgres, nginx, etc.).

Command Reference

`scan` — Fleet Node Intelligence

# Single-shot colourised table with node fingerprint header
./proc-lens scan -c 0.1 -m 5.0 -d 1s

# Loop mode with drift detection, PSI, and hardware profiling
./proc-lens scan --loop --interval 10s --enable-psi --enable-hardware-profile

# JSONL streaming for DaemonSet / log shipping
./proc-lens scan --loop --format json

# With Prometheus metrics endpoint
./proc-lens scan --loop --http-addr 0.0.0.0:8091

Key flags:

Flag	Default	Description
`--duration / -d`	`1s`	Profiling window for rate calculations
`--min-cpu / -c`	`0.05`	Minimum CPU% to display
`--min-mem / -m`	`2.0`	Minimum RSS MB to display
`--loop / -l`	`false`	Continuous refresh mode
`--interval / -i`	`10s`	Refresh interval in loop mode
`--enable-psi`	`false`	Collect Linux Pressure Stall Information
`--enable-hardware-profile`	`false`	Collect NUMA / storage / SIMD topology
`--http-addr`	`127.0.0.1:8091`	Prometheus + healthz endpoint
`--http-bearer-token`	`""`	Optional auth token for metrics endpoint

`analyze` — Deep Process Profile (Colourised)

# Rich 256-colour report with score bars and structured recommendations
./proc-lens analyze --pid 1234 --duration 2s

# Machine-readable JSON with full StructuredRecommendations array
./proc-lens analyze --pid 1234 --format json

The analyze output now renders:

Primary blue banner header
Per-metric threshold colouring (green → yellow → red)
Reversed-video badge for the primary archetype
30-cell coloured score bars per archetype (lime-green / amber / orange / grey by score tier)
⚡ Heuristics section (amber)
→ Recommendations in Bright Green

`run` — Shift-Left Workload Profiling

# Profile a command before production deployment
./proc-lens run --cmd "gunicorn app:main --workers 4" --duration 5s

# CI/CD pipeline check
./proc-lens run --cmd "tar -czf backup.tar.gz /var/log" --format json | jq '.primary_category'

`enrich` — LLM-Powered SRE Reports

# Profile live system → default LLM provider → SRE analysis
export GEMINI_API_KEY="your-gemini-key"
./proc-lens enrich --allow-remote-llm

# Override model (e.g. experimental or another provider)
./proc-lens enrich --allow-remote-llm --model gemini-2.0-flash

# Analyse a specific PID only
./proc-lens enrich --allow-remote-llm --pid 1234

# Local Ollama (no --allow-remote-llm required)
./proc-lens enrich --endpoint "http://localhost:11434/v1/chat/completions" --model "llama3"

# Use claude provider
export ANTHROPIC_API_KEY="your-key"
./proc-lens enrich --provider claude --allow-remote-llm

# Use openai provider
export OPENAI_API_KEY="your-key"
./proc-lens enrich --provider openai --allow-remote-llm

# Load telemetry from a previously exported JSON file
./proc-lens enrich --file scan-export.json --allow-remote-llm

Default models per provider:

Provider	Default Model	Notes
`gemini`	`gemini-flash-latest`	Alias for latest stable Gemini Flash model
`openai`	`gpt-4o-mini`	Cost-efficient GPT-4 class model
`grok`	`grok-2`	Grok model (via compatible endpoint)
`claude`	`claude-3-5-sonnet-20241022`	Claude Sonnet model

⚠️ Important: The API key is passed via X-goog-api-key header (not URL query param) to avoid key leakage in proxy/server logs. The LLM HTTP call uses a dedicated 120-second context, fully isolated from the signal-cancellation context — eliminating the context canceled error that affected prior versions.

`explain` — Classifier Reasoning

# Human-readable "why was this process classified X?" report
./proc-lens explain --pid 1234

# JSON output for automation
./proc-lens explain --pid 1234 --format json

`psi` — Node Resource Pressure

# View CPU, memory, and I/O pressure stall information
./proc-lens psi

# Note: requires Linux kernel ≥ 4.20 with PSI enabled

📖 See terminologies.md → PSI.

`hardware` — Hardware Topology & ISA Discovery

# NUMA layout, block storage type, SIMD instruction sets
./proc-lens hardware

# JSON output
./proc-lens hardware --format json

📖 See terminologies.md → NUMA.

`drift` — Workload Composition Shift Detection

# Analyse a scan log file for drift events
./proc-lens drift --file scan.jsonl

# JSON output
./proc-lens drift --file scan.jsonl --format json

`capabilities` — Platform Transparency

# See which features are FULL / PARTIAL / UNAVAILABLE on this platform
./proc-lens capabilities

# Machine-readable JSON
./proc-lens capabilities --format json

Colourful Terminal Output

ProcLens uses a Material Design-inspired 256-colour ANSI palette across all text-mode commands. Colours are mapped by semantic meaning:

Colour	Code	Used for
Primary Blue `38;5;33`	`#4285F4`	Headers, network/ingress archetypes
Green `38;5;40`	`#34A853`	Data stores, recommendations ✓
Yellow `38;5;220`	`#FBBC05`	Search/analytics, mid-score bars
Red `38;5;196`	`#EA4335`	AI Training, critical CPU
Orange `38;5;208`	`#FF6D00`	Messaging/streaming, disk write
Teal `38;5;37`	`#00897B`	Context switches, service mesh
Indigo `38;5;63`	`#3949AB`	Orchestration / infrastructure
Pink `38;5;205`	`#E91E63`	AI inference / ML pipelines
Amber `38;5;214`	`#FF8F00`	Heuristics ⚡, observability
Gray `38;5;245`	`#9E9E9E`	Shell / utility / legacy

Score bars fill with:

🟢 Lime-green 38;5;46 — score ≥ 70%
🟡 Amber 38;5;220 — score 40–69%
🟠 Deep orange 38;5;202 — score 20–39%
⬜ Dark grey 38;5;240 — score < 20%

LLM Enrichment (enrich)

What the LLM receives

A structured JSON payload containing:

Node context: hostname, OS/arch, kernel version, CPU cores, total RAM
Top-N process predictions with: PID, name, archetype, confidence, full telemetry (CPU user/system splits, RSS, swap, threads, FDs, sockets, I/O speeds, voluntary/involuntary context switches, OOM score, cgroup/container ID, pod UID)
Local optimiser recommendations already computed

What the LLM produces

A structured SRE report covering:

Executive Summary — one-paragraph node workload health assessment
Workload Origin & Intent — interprets process purpose from cmdlines + resource footprints
System Risk Analysis — identifies bottlenecks (CPU scheduler contention, OOM risk, I/O queues)
Prioritised Optimisation Plan — actionable sysctl/ulimit commands with rationale, verification commands, and risk classification (Low / Medium / High)

Security design

Signal ctx (Ctrl+C aware)     ──► profiling phase only
LLM ctx (120s, Background)   ──► callGemini() only
                                   │
                                   └─► X-goog-api-key header (never in URL)

Build & Deploy

Prerequisites

Go 1.24+ installed
For Linux cross-compile from Windows/macOS: set CGO_ENABLED=0

Build Commands

# Linux (static binary — for Docker/K8s)
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w -extldflags -static" -o proc-lens ./cmd/proc-lens

# macOS Apple Silicon
GOOS=darwin GOARCH=arm64 go build -o proc-lens-mac-silicon ./cmd/proc-lens

# macOS Intel
GOOS=darwin GOARCH=amd64 go build -o proc-lens-mac-intel ./cmd/proc-lens

# Windows
GOOS=windows GOARCH=amd64 go build -o proc-lens.exe ./cmd/proc-lens

📖 For a full walkthrough including environment setup and troubleshooting, see CONTRIBUTING.md.

Docker

# Build
docker build -t proc-lens:latest .

# Run (requires hostPID + CAP_SYS_PTRACE for host metrics)
docker run -d --name proc-lens \
  --pid=host --cap-add=SYS_PTRACE \
  -v /proc:/host/proc:ro -v /sys:/host/sys:ro \
  -e HOST_PROC=/host/proc -e HOST_SYS=/host/sys \
  proc-lens:latest

📖 See terminologies.md → DaemonSet for Kubernetes concepts.

Kubernetes / Helm

# Validate templates
helm lint deploy/proc-lens

# Deploy as DaemonSet to kube-system
helm upgrade --install proc-lens deploy/proc-lens --namespace kube-system

The Helm chart ships with:

UID 65534 (nobody), privileged: false, readOnlyRootFilesystem: true
Only CAP_SYS_PTRACE added
/healthz liveness/readiness probe on port 8091
NetworkPolicy restricting metrics scraping to authorised namespaces
PodDisruptionBudget for safe rolling updates

GoReleaser (CI/CD)

The release pipeline uses GoReleaser v2 (fully migrated — no deprecated fields):

Old (deprecated)	New (v2)
`archives.format`	`archives.formats`
`dockers:`	`dockers_v2:`
`docker_manifests:`	`docker_manifests_v2:`

# Local snapshot build (no tag required)
goreleaser release --snapshot --clean

📖 See terminologies.md → GoReleaser and terminologies.md → GHCR.

Security Model

ProcLens is designed with robust security controls:

Least-Privilege Container: Runs as nobody (UID 65534), allowPrivilegeEscalation: false, read-only root filesystem, only CAP_SYS_PTRACE.
Command-Line Redaction: Default-on — shows only the binary path + [REDACTED]. Use --expose-cmdline deliberately.
Subprocess Execution Guard: run subcommand requires explicit --allow-run. Blocked entirely in host-privileged container context (UID 0 + HOST_PROC).
Outbound Exfiltration Gate: enrich requires --allow-remote-llm for non-local LLM endpoints. Blocked in host-privileged container context.
Secure Metrics Server: Optional Bearer token auth (--http-bearer-token), ReadTimeout/WriteTimeout/MaxHeaderBytes hardening, NetworkPolicy in Helm chart.
API Key Safety: For the gemini provider, the API key is sent via the required X-goog-api-key header — never in URL query params.

For a detailed competitive landscape comparison, see COMPETITIVE-LANDSCAPE.md.

Prometheus Metrics

ProcLens exports low-cardinality Prometheus metrics on /metrics (port 8091 by default). Labels use category strings only — no per-PID labels that would cause cardinality explosion.

Metric	Type	Description
`proc_lens_scans_total`	Counter	Scan cycles completed
`proc_lens_collection_errors_total`	Counter	Errors by reason label
`proc_lens_processes_classified_total`	Counter	Cumulative classifications by category
`proc_lens_processes_scanned`	Gauge	PIDs discovered in last cycle
`proc_lens_predictions`	Gauge	Current counts by category
`proc_lens_agent_cpu_usage_percent`	Gauge	Agent's own CPU usage
`proc_lens_agent_memory_rss_bytes`	Gauge	Agent's own RSS
`proc_lens_k8s_metadata_success_rate`	Gauge	Pod metadata resolution rate
`proc_lens_collection_duration_seconds`	Histogram	Full cycle duration
`proc_lens_per_process_collection_seconds`	Histogram	Per-PID collection cost
`proc_lens_http_requests_total`	Counter	HTTP requests to metrics/healthz server

FinOps use case: Feed proc_lens_predictions{category="RelationalDB"} into OpenCost or Kubecost to explain why certain nodes have high IOPS costs.

📖 See terminologies.md → Low-Cardinality Metrics and JSONL Output.

Production Readiness Checklist

Before deploying ProcLens in production:

Least Privilege — container runs with readOnlyRootFilesystem: true, only CAP_SYS_PTRACE, allowPrivilegeEscalation: false
HTTP Server Hardening — if exposing /metrics, configure --http-bearer-token
Network Segmentation — enable the default NetworkPolicy to restrict port 8091 to Prometheus pods only
Resource Limits — set CPU limit (e.g. 200m) and memory limit (e.g. 256Mi) on the DaemonSet
Host Namespace Mapping — HOST_PROC=/host/proc and HOST_SYS=/host/sys correctly set and read-only mounted
Cmdline Redaction — confirm --expose-cmdline is NOT set unless explicitly required
LLM Gate — if using enrich, confirm --allow-remote-llm intent and firewall rules
GoReleaser v2 — .goreleaser.yml uses dockers_v2 / docker_manifests_v2 (no deprecated fields)

Testing & Quality

# Run the full test suite
go test ./... -v -count=1

# Run only classifier tests (includes all 37 archetype table tests)
go test ./pkg/classifier/... -v

# Benchmarks
go test ./pkg/classifier -bench=. -run=^$

# Fuzz testing (requires Go 1.21+)
go test ./pkg/classifier -fuzz=FuzzPredict -fuzztime=30s

# Verify build for all platforms
go build ./...

The test suite includes:

Table-driven tests for all 37 archetypes (including Kafka, Kong, Istio, InfluxDB, MinIO, Fluent Bit, etcd, Celery, Neo4j, Triton and others)
Zero-value safety — Predict(collector.ProcessStats{}) must never panic
Confidence bounds — all outputs guaranteed in [0.0, 1.0]
Centroid completeness — every category constant must have a matching centroid entry
Fuzz harness — property-based testing with arbitrary name/cmdline inputs

Comparison Matrix

Feature	ProcLens	Raw Host Exporter	Code Profiler	Syscall Security	In-Kernel Monitor	APM Platform	SQL Introspector	Plugin Agent
HLD Semantic Classification	✅ 37 archetypes	❌	❌	❌	❌	⚠️ Partial	❌	❌
Node Workload Fingerprint	✅ SHA-256	❌	❌	❌	❌	❌	❌	❌
Workload Drift Detection	✅ Structured events	❌	❌	⚠️ Rule-based	⚠️ Rule-based	❌	❌	❌
Validated Kernel Tuning	✅ Live /proc/sys	❌	❌	❌	❌	❌	❌	❌
Machine-Readable Recommendations	✅ JSON + Risk	❌	❌	❌	❌	❌	❌	❌
Cmdline Redaction (Default)	✅	❌	❌	❌	❌	❌	❌	❌
Air-Gap Capable	✅	✅	✅	⚠️	⚠️	❌	✅	✅
Capabilities Required	`PTRACE` only	None	`BPF` etc	`BPF`/module	`BPF`/module	`BPF` etc	None	None
LLM Enrichment (Gated)	✅ Supported LLM backends	❌	❌	❌	❌	⚠️ Backend	❌	❌
256-Colour CLI Output	✅ Material-inspired palette	❌	❌	❌	❌	❌	❌	❌
Platform Capability Report	✅	❌	❌	❌	❌	❌	❌	❌
Self-Observing Metrics	✅ 11 metrics	✅	❌	❌	❌	✅	❌	✅
Static Single Binary	✅	✅	❌	❌	❌	❌	⚠️	✅
Windows Support	✅ Graceful	✅	❌	❌	❌	❌	✅	✅

Roadmap

Centralized Intellect Service — decouple LLM calling from the edge collector for tighter security
Kubernetes Downward API — correlate processes with Deployment/StatefulSet owners and QoS classes
Temporal Trend Buffers — rolling 5-minute history for memory leak / CPU ramp detection
Fingerprint-keyed LLM Cache — cache enrichment results by fingerprint hash to reduce API costs
GitOps Recommendation Export — --dry-run-json flag outputting Ansible/Terraform-compatible format
eBPF Classifier Accelerator — optional eBPF probe for sub-microsecond feature extraction
WASM Plugin System — user-defined archetype rules without recompiling

Related Docs

Document	Description
terminologies.md	Plain-English glossary of every technical concept — ideal for junior engineers and newcomers
maths-behind-repo.md	Detailed, beginner-friendly explanation of the classification maths (scaling, L1 distance, centroids, Shannon entropy, and worked examples for all 37 archetypes)
CONTRIBUTING.md	How to contribute, development setup, build, and deployment execution guides
COMPETITIVE-LANDSCAPE.md	Detailed comparison against traditional host introspection, security, and APM tools
CHANGELOG.md	Release history and version notes
CODE_OF_CONDUCT.md	Community standards and reporting guidelines

ProcLens — See what your processes really are.

Built with ❤️ in Go · Apache 2.0 · Contribute · Report an Issue

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.github		.github
cmd/proc-lens		cmd/proc-lens
deploy		deploy
dist		dist
pkg		pkg
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.goreleaser.yml		.goreleaser.yml
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
COMPETITIVE-LANDSCAPE.md		COMPETITIVE-LANDSCAPE.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum
maths-behind-repo.md		maths-behind-repo.md
terminologies.md		terminologies.md

Category	Real-world processes
`APIGateway`	Kong, APISIX, KrakenD and similar
`ServiceMesh`	Istio, Linkerd, Consul components
`TimeSeriesDB`	InfluxDB, VictoriaMetrics, Prometheus TSDB
`GraphDB`	Neo4j, JanusGraph, Dgraph
`ObjectStore`	MinIO, SeaweedFS, Ceph RGW
`StreamProcessor`	Apache Flink, Spark Streaming
`OLAPEngine`	Trino/Presto, Apache Druid, Spark SQL
`MLPipeline`	MLflow, Kubeflow, DVC, Prefect
`LogAggregator`	Fluent Bit, Fluentd, Logstash, Vector
`TracingAgent`	Jaeger, Zipkin, OTel trace components
`LegacySOAService`	Traditional enterprise app servers (JBoss-style, WebLogic-style)
`CIRunner`	Jenkins, GitLab CI, GitHub Actions runners

Folders and files

Latest commit

History

Repository files navigation

ProcLens — Universal Process Intelligence & Workload Classifier

Table of Contents

Quick Start

Why ProcLens? — Unique Selling Points

Colourful Terminal Output

37 Workload Archetypes

System Architecture

What Inputs It Takes

How It Works (Processing Pipeline)

Step 1: Metric Scaling and Bounding

Step 2: Absolute Difference Profile Matching

Step 3: Heuristic Rules and Boosters

Step 4: Workload Fingerprinting & Diversity Score

Command Reference

scan — Fleet Node Intelligence

analyze — Deep Process Profile (Colourised)

run — Shift-Left Workload Profiling

enrich — LLM-Powered SRE Reports

explain — Classifier Reasoning

psi — Node Resource Pressure

hardware — Hardware Topology & ISA Discovery

drift — Workload Composition Shift Detection

capabilities — Platform Transparency

Colourful Terminal Output

LLM Enrichment (enrich)

What the LLM receives

What the LLM produces

Security design

Build & Deploy

Prerequisites

Build Commands

Docker

Kubernetes / Helm

GoReleaser (CI/CD)

Security Model

Prometheus Metrics

Production Readiness Checklist

Testing & Quality

Comparison Matrix

Roadmap

Related Docs

About

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`scan` — Fleet Node Intelligence

`analyze` — Deep Process Profile (Colourised)

`run` — Shift-Left Workload Profiling

`enrich` — LLM-Powered SRE Reports

`explain` — Classifier Reasoning

`psi` — Node Resource Pressure

`hardware` — Hardware Topology & ISA Discovery

`drift` — Workload Composition Shift Detection

`capabilities` — Platform Transparency

Packages