process

Documentation

Index

• func Descriptors(ctx context.Context, pids ...int) (map[int][]Descriptor, error)
• func Environment(ctx context.Context, pid int, options EnvironmentOptions) (map[string]string, error)
• func IntervalCPUPercent(previous *CPUSample, current CPUSample) (*float64, error)
• type CPUSample
• type Descriptor
  • func (d Descriptor) IsConnected() bool
  • func (d Descriptor) IsListening() bool
  • func (d Descriptor) IsSocket() bool
• type EnvironmentOptions
• type Process
• type ProcessIO
• type ResourceUsage
• type Snapshot
  • func Discover(ctx context.Context, opts SnapshotOptions) (*Snapshot, error)
  • func NewSnapshot(processes []Process) *Snapshot
  • func (s *Snapshot) AggregateSubtree(pid int) ResourceUsage
  • func (s *Snapshot) All() []Process
  • func (s *Snapshot) Ancestors(pid int) []Process
  • func (s *Snapshot) Get(pid int) (Process, bool)
  • func (s *Snapshot) PopulateIO(ctx context.Context, pids []int) error
  • func (s *Snapshot) PopulateWorkingDirectories(ctx context.Context, pids []int)
  • func (s *Snapshot) Subtree(pid int) []Process
• type SnapshotOptions

Functions

func Descriptors

func Descriptors(ctx context.Context, pids ...int) (map[int][]Descriptor, error)

Descriptors lists the files and sockets each of pids holds open, by pid, read with one lsof call. A pid lsof lists nothing for, one that is not running or not readable by this user, is left out.

func Environment

func Environment(ctx context.Context, pid int, options EnvironmentOptions) (map[string]string, error)

Environment is pid's environment as the kernel reports it, limited to the keys and prefixes options name; no keys and no prefixes is all of it.

func IntervalCPUPercent

func IntervalCPUPercent(previous *CPUSample, current CPUSample) (*float64, error)

IntervalCPUPercent returns the CPU% a process used between two samples: CPU time consumed divided by wall time elapsed, ×100, per core like top (a process saturating two cores reads 200).

The result is nil, meaning unknown, when there is no previous sample or the pid was reused by a different process (start times differ): a rate needs two observations of the same process, and a fake 0 would read as idle. Samples that cannot be compared (different pids, missing start time, a clock that did not advance, CPU time going backwards) are errors.

Types

type CPUSample

type CPUSample struct {
	Process Process
	At      time.Time
}

CPUSample is one observation of a process: the listing entry and the wall clock time the listing was taken.

type Descriptor

type Descriptor struct {
	FD         string `json:"fd"`
	Type       string `json:"type"`
	Name       string `json:"name"`
	Protocol   string `json:"protocol,omitempty"`
	State      string `json:"state,omitempty"`
	LocalAddr  string `json:"localAddr,omitempty"`
	RemoteAddr string `json:"remoteAddr,omitempty"`
	Port       int    `json:"port,omitempty"`
}

Descriptor is one file a process holds open, as lsof reports it: a regular file, directory, device, pipe or socket. Internet sockets carry their protocol, TCP state and endpoints.

func (Descriptor) IsConnected

func (d Descriptor) IsConnected() bool

IsConnected reports whether d is a TCP or UDP socket with a peer.

func (Descriptor) IsListening

func (d Descriptor) IsListening() bool

IsListening reports whether d accepts traffic on its port: a listening TCP socket, or a UDP socket bound without a peer.

func (Descriptor) IsSocket

func (d Descriptor) IsSocket() bool

IsSocket reports whether d is an internet or unix-domain socket.

type EnvironmentOptions

type EnvironmentOptions struct {
	Keys     []string
	Prefixes []string
}

type Process

type Process struct {
	PID    int    `json:"pid"`
	PPID   int    `json:"ppid,omitempty"`
	Status string `json:"status,omitempty"`
	Active bool   `json:"active"`
	// CPUPercent is the OS-reported figure, not current load: a lifetime
	// average (cpu time ÷ elapsed) on linux and windows, a decaying ~1 minute
	// average on darwin. A hung busy loop can read as idle; use CPUTime with
	// IntervalCPUPercent for the CPU% over a sampling interval.
	CPUPercent float64 `json:"cpuPercent,omitempty"`
	// CPUTime is the cumulative user+system CPU time the process has used
	// (JSON: nanoseconds). Resolution is 1s on linux ps, 10ms on darwin ps.
	CPUTime          time.Duration     `json:"cpuTime,omitempty"`
	MemoryPercent    float64           `json:"memoryPercent,omitempty"`
	RSSBytes         uint64            `json:"rssBytes,omitempty"`
	IO               *ProcessIO        `json:"io,omitempty"`
	StartedAt        *time.Time        `json:"startedAt,omitempty"`
	Command          string            `json:"command,omitempty"`
	CWD              string            `json:"cwd,omitempty"`
	CWDError         string            `json:"cwdError,omitempty"`
	Environment      map[string]string `json:"environment,omitempty"`
	EnvironmentError string            `json:"environmentError,omitempty"`
}

type ProcessIO

type ProcessIO struct {
	DiskReadBytes  uint64 `json:"diskReadBytes"`
	DiskWriteBytes uint64 `json:"diskWriteBytes"`
}

type ResourceUsage

type ResourceUsage struct {
	CPUPercent    float64   `json:"cpuPercent"`
	MemoryPercent float64   `json:"memoryPercent"`
	RSSBytes      uint64    `json:"rssBytes"`
	Processes     []Process `json:"processes,omitempty"`
}

type Snapshot

type Snapshot struct {
	// contains filtered or unexported fields
}

func Discover

func Discover(ctx context.Context, opts SnapshotOptions) (*Snapshot, error)

Discover lists the host's processes, leaving out the ps it runs to list them: a caller sampling its own process tree would otherwise see a new child of its own at every sample. ps runs under LC_ALL=C so lstart and decimal columns parse regardless of the caller's locale.

func NewSnapshot

func NewSnapshot(processes []Process) *Snapshot

func (*Snapshot) AggregateSubtree

func (s *Snapshot) AggregateSubtree(pid int) ResourceUsage

func (*Snapshot) All

func (s *Snapshot) All() []Process

func (*Snapshot) Ancestors

func (s *Snapshot) Ancestors(pid int) []Process

func (*Snapshot) Get

func (s *Snapshot) Get(pid int) (Process, bool)

func (*Snapshot) PopulateIO

func (s *Snapshot) PopulateIO(ctx context.Context, pids []int) error

func (*Snapshot) PopulateWorkingDirectories

func (s *Snapshot) PopulateWorkingDirectories(ctx context.Context, pids []int)

func (*Snapshot) Subtree

func (s *Snapshot) Subtree(pid int) []Process

type SnapshotOptions

type SnapshotOptions struct {
	Environment *EnvironmentOptions
}