proc

Documentation

Overview

Package proc reads the Linux process table from /proc once and answers the questions beekeeper asks of it: who is whose parent, which session a process belongs to, how long it has run. Reading /proc directly instead of grepping `ps` output means a pattern never matches the command that looks for it.

Index

• Constants
• func Alive(pid int) bool
• func AnonKiB(pid int) int
• func Background(ctx context.Context) context.Context
• func Cgroup(pid int) string
• func Command(ctx context.Context, name string, arg ...string) *exec.Cmd
• func Cwd(pid int) string
• func Environ(pid int) (map[string]string, error)
• func Held(pid int) []string
• func IsBackground(ctx context.Context) bool
• func Kubeconfig(c *exec.Cmd, files []string)
• func LookPath(name string) (string, error)
• func Named(name string, uid int) []int
• func Started(pid int) (time.Time, error)
• func Terminate(pids []int, grace time.Duration)
• func UID(pid int) int
• func WriteBytes(pid int) (int64, error)
• type Process
  • func (p *Process) Cmdline() string
  • func (p *Process) Elapsed(now time.Time) time.Duration
• type Table
  • func NewTable(ps ...*Process) *Table
  • func Read() (*Table, error)
  • func ReadAt(root string) (*Table, error)
  • func (t *Table) Ancestors(pid int) []*Process
  • func (t *Table) AnonKiB(pid int) int
  • func (t *Table) Children(pid int) []*Process
  • func (t *Table) Cwd(pid int) string
  • func (t *Table) Descendants(pid int) []*Process
  • func (t *Table) Environ(pid int) (map[string]string, error)
  • func (t *Table) Orphaned(p *Process) bool
  • func (t *Table) Process(pid int) *Process

Constants

const Niceness = "10"

Niceness is the nice level of a command started under a Background context: behind every interactive process on a starved machine.

Functions

func Alive

func Alive(pid int) bool

Alive reports whether a process with that PID exists.

func AnonKiB

func AnonKiB(pid int) int

AnonKiB returns the anonymous resident memory of pid in KiB: what killing it would give back.

func Background

func Background(ctx context.Context) context.Context

Background marks ctx: the commands Command starts under it run at nice Niceness.

func Cgroup

func Cgroup(pid int) string

Cgroup returns the cgroup v2 path of pid ("/user.slice/…"), or "".

func Command

func Command(ctx context.Context, name string, arg ...string) *exec.Cmd

Command is exec.CommandContext for a read the caller can do without: under a Background context it runs through nice (when the machine has it), and a command killed by ctx gives up its pipes after waitDelay.

func Cwd

func Cwd(pid int) string

Cwd returns the working directory of pid.

func Environ

func Environ(pid int) (map[string]string, error)

Environ returns the environment of pid (readable for the caller's own processes).

func Held

func Held(pid int) []string

Held returns the paths pid holds: its working directory, its executable and every file it has open, a deleted one by the path it had (readable for the caller's own processes).

func IsBackground

func IsBackground(ctx context.Context) bool

IsBackground reports whether ctx is marked by Background.

func Kubeconfig

func Kubeconfig(c *exec.Cmd, files []string)

Kubeconfig makes c read the kubeconfig files as kubectl merges a KUBECONFIG list; none, c keeps the environment's.

func LookPath

func LookPath(name string) (string, error)

LookPath is exec.LookPath, then the Go tool directories for a bare name PATH lacks: beside the running binary, $GOBIN, every $GOPATH/bin, ~/go/bin and ~/.go/bin, in that order. A systemd user unit, the sandbox broker for one, runs with the service manager's PATH, the distribution's default without the directory go install writes to, where kind and the other Go CLIs live beside beekeeper. A tool found nowhere fails naming the directories looked in; a name with a path separator is exec's alone.

func Named

func Named(name string, uid int) []int

Named returns the PIDs of the live processes whose command name (comm) is name and which run as uid.

func Started

func Started(pid int) (time.Time, error)

Started is when the live process pid started.

func Terminate

func Terminate(pids []int, grace time.Duration)

Terminate sends the processes pids SIGTERM, and SIGKILL to those still alive after grace.

func UID

func UID(pid int) int

UID returns the real user id pid runs as, or -1 when it cannot be read.

func WriteBytes

func WriteBytes(pid int) (int64, error)

WriteBytes is what the live process pid caused to be written to storage (write_bytes of /proc/<pid>/io); another user's process is unreadable.

Types

type Process

type Process struct {
	PID   int
	PPID  int
	Comm  string
	Args  []string
	Start time.Time
	// StartTicks is Start as the kernel counts it: clock ticks since boot.
	StartTicks int64
	// CPU is the processor time it has burned (user and system).
	CPU time.Duration
	// RSSKiB is its resident memory, file-backed pages included.
	RSSKiB int
}

Process is one entry of the table.

func (*Process) Cmdline

func (p *Process) Cmdline() string

Cmdline is the argument vector joined by spaces.

func (*Process) Elapsed

func (p *Process) Elapsed(now time.Time) time.Duration

Elapsed is how long the process has run at now.

type Table

type Table struct {
	ByPID map[int]*Process
	// contains filtered or unexported fields
}

Table is a snapshot of the process table.

func NewTable

func NewTable(ps ...*Process) *Table

NewTable is the table of the processes ps, linked by their parents: a process tree built in memory rather than read.

func Read

func Read() (*Table, error)

Read scans /proc.

func ReadAt

func ReadAt(root string) (*Table, error)

ReadAt scans the process tree under root: /proc, or a copy of it (each process's stat, cmdline and environ, and the btime line of stat) captured into testdata.

func (*Table) Ancestors

func (t *Table) Ancestors(pid int) []*Process

Ancestors returns the parent chain of pid, nearest first.

func (*Table) AnonKiB

func (t *Table) AnonKiB(pid int) int

AnonKiB returns the anonymous resident memory of pid in the table's process tree.

func (*Table) Children

func (t *Table) Children(pid int) []*Process

Children returns the direct children of pid.

func (*Table) Cwd

func (t *Table) Cwd(pid int) string

Cwd returns the working directory of pid in the table's process tree.

func (*Table) Descendants

func (t *Table) Descendants(pid int) []*Process

Descendants returns every process below pid, depth first.

func (*Table) Environ

func (t *Table) Environ(pid int) (map[string]string, error)

Environ returns the environment of pid in the table's process tree.

func (*Table) Orphaned

func (t *Table) Orphaned(p *Process) bool

Orphaned reports whether p's parent is gone: the kernel reparented it to PID 1 or to the user's service manager, the subreaper of its units.

func (*Table) Process

func (t *Table) Process(pid int) *Process

Process is the process pid of the table, nil when the table has none or is nil.