What lens-top shows
lens-top displays CPU, memory, load, process state and I/O rates. It keeps a small amount of in-memory session history to calculate rates and trends.
This keeps history attached to the correct process if the operating system reuses a PID.
Host summary
- CPU, memory, swap, load and uptime
- Process, running, zombie and warning counts
- Recent trends for the live terminal
Process detail
- Command, user, parent, state, threads and start time
- CPU, memory and read/write rates
- Service and cgroup context where Linux exposes it
- Fields that could not be collected are marked unavailable
Reading the process screen
The default sort is descending CPU. The selected process is pinned by PID and start time across refreshes and sort-order changes, so the detail screen does not jump to a different process.
Common investigations
The machine feels slow
Compare host CPU, memory and load first. Sort by CPU, then memory. A high load with modest CPU may point to blocked I/O rather than pure computation. Open the leading process to compare its current value with the short history and command context.
Memory is under pressure
Sort by memory and inspect RSS, virtual size and process history. A large virtual allocation is not the same as resident memory. Use the Health view to check swap pressure and growing-memory findings before deciding that the largest process is the cause.
A process is constantly replaced
Group by service/cgroup or filter by name. Changing PIDs with short runtimes can indicate a supervisor restart loop. Continue in lens-services and lens-logs rather than signalling an arbitrary current instance.
A zombie appears
Open the process detail and note its parent. A zombie has already exited; sending it another signal cannot reap it. The parent must collect its exit status, so investigate the parent process or supervising service.
You need to watch a command's effect
Press ! to open a diagnostic shell beside the live process view. Run the deliberate diagnostic command there and observe CPU, memory, process count or state change without switching terminals.
Install
On Raspberry Pi OS, Debian or Ubuntu, install the release package matching dpkg --print-architecture. See the installation guide for the complete package matrix and macOS instructions.
dpkg --print-architecture
sudo apt install ./dataplicity-lens_<version>_<architecture>.deb
lens-topRelease automation builds Linux and macOS archives, Debian and RPM packages, checksums and SBOMs.
Use
Run with no flags on a terminal to open the TUI. Resize the window at any time: wider and taller terminals show more process detail, while compact terminals keep the main values and controls. --once prints one snapshot and defaults to plain text; --plain, --json and --jsonl select a one-shot format directly. Redirected output is plain automatically. An explicit --interval is also used as the one-shot CPU measurement window.
lens-top
lens-top --plain --sort memory --limit 10
lens-top --json --filter-user postgres
lens-top --jsonl --min-cpu 5
lens-top --onceInteraction
Stable output
Plain, JSON and JSON Lines render the same snapshot model. JSON documents include an explicit schema version and RFC 3339 UTC generation time. Byte fields remain bytes; rates are bytes per second; unavailable data is nullable or listed explicitly.
{
"schema_version": "2",
"generated_at": "2026-08-03T00:00:00Z",
"host": { "hostname": "production-gateway-04" },
"processes": [ ... ],
"findings": [ ... ]
}Configuration
No configuration is required. Command-line options override environment variables, which override the config file and built-in defaults.
lens-top --print-default-config
# ~/.config/dataplicity-lens/config.toml
# LENS_TOP_* environment variablesSignal a process deliberately
Press a on a selected process. Choose a signal, then review the exact process name, PID and pinned start identity on a separate confirmation screen. Press y to execute or Esc to go back.
| Signal | Typical intent | Operational note |
|---|---|---|
| TERM | Ask the process to exit | Preferred first termination signal; the process can handle it and clean up. |
| HUP | Request reload or reopened files | Meaning is application-specific; confirm the service documents it. |
| INT | Interrupt as if from an interactive terminal | The process may handle or ignore it. |
| STOP | Suspend execution | Cannot be caught; the process remains present but does no work. |
| CONT | Resume a stopped process | Useful only for a process currently suspended. |
| KILL | Force immediate exit | Cannot be handled; no application cleanup runs. Use only when warranted. |
Lens rejects PID 0, PID 1 and its own PID. Immediately before sending the signal it recollects the target and rejects the operation if that PID now belongs to another process or has exited. It reports whether the same process remains afterward and refreshes the process list.
# Plan only
lens-top --signal term --pid 4242 --dry-run
# Explicit non-interactive confirmation and structured result
lens-top --signal term --pid 4242 --yes --jsonWhen process fields are missing
Lens keeps a process row when one field cannot be collected. Permission-limited command lines, file-descriptor counts, I/O counters or service context are shown as unavailable and listed in the process's unavailable_fields array in JSON.
Processes can start and exit during collection. Normal races are tolerated. A process that disappears before an action is confirmed is treated as a stale target and is never replaced by whichever process later receives the same PID.