proc

Documentation

Index

• Variables
• type CollectErrors
• type Counts
  • func (c *Counts) Add(c2 Delta)
  • func (c Counts) Sub(c2 Counts) Delta
• type Delta
• type FS
  • func NewFS(mountPoint string, debug bool) (*FS, error)
  • func (fs *FS) AllProcs() Iter
• type Filedesc
• type Group
• type GroupByName
• type Grouper
  • func NewGrouper(namer common.MatchNamer, ...) *Grouper
  • func (g *Grouper) Update(iter Iter) (CollectErrors, GroupByName, error)
• type ID
• type IDInfo
  • func (p IDInfo) GetCounts() (Counts, int, error)
  • func (p IDInfo) GetMetrics() (Metrics, int, error)
  • func (p IDInfo) GetPid() int
  • func (p IDInfo) GetProcID() (ID, error)
  • func (p IDInfo) GetStates() (States, error)
  • func (p IDInfo) GetStatic() (Static, error)
  • func (p IDInfo) GetThreads() ([]Thread, error)
  • func (p IDInfo) GetWchan() (string, error)
  • func (ii IDInfo) String() string
• type Iter
• type Memory
• type Metrics
• type Proc
• type Source
• type States
  • func (s *States) Add(s2 States)
• type Static
• type Thread
• type ThreadID
• type ThreadUpdate
• type Threads
• type Tracker
  • func NewTracker(namer common.MatchNamer, ...) *Tracker
  • func (t *Tracker) Update(iter Iter) (CollectErrors, []Update, error)
• type Update

Variables

var ErrProcNotExist = fmt.Errorf("process does not exist")

ErrProcNotExist indicates a process couldn't be read because it doesn't exist, typically because it disappeared while we were reading it.

Types

type CollectErrors

type CollectErrors struct {
	// Read is incremented every time GetMetrics() returns an error.
	// This means we failed to load even the basics for the process,
	// and not just because it disappeared on us.
	Read int
	// Partial is incremented every time we're unable to collect
	// some metrics (e.g. I/O) for a tracked proc, but we're still able
	// to get the basic stuff like cmdline and core stats.
	Partial int
}

CollectErrors describes non-fatal errors found while collecting proc metrics.

type Counts

type Counts struct {
	CPUUserTime           float64
	CPUSystemTime         float64
	ReadBytes             uint64
	WriteBytes            uint64
	MajorPageFaults       uint64
	MinorPageFaults       uint64
	CtxSwitchVoluntary    uint64
	CtxSwitchNonvoluntary uint64
}

Counts are metric counters common to threads and processes and groups.

func (*Counts) Add

func (c *Counts) Add(c2 Delta)

Add adds c2 to the counts.

func (Counts) Sub

func (c Counts) Sub(c2 Counts) Delta

Sub subtracts c2 from the counts.

type Delta

type Delta Counts

Delta is an alias of Counts used to signal that its contents are not totals, but rather the result of subtracting two totals.

type FS

type FS struct {
	procfs.FS
	BootTime    uint64
	MountPoint  string
	GatherSMaps bool
	// contains filtered or unexported fields
}

FS implements Source.

func NewFS

func NewFS(mountPoint string, debug bool) (*FS, error)

NewFS returns a new FS mounted under the given mountPoint. It will error if the mount point can't be read.

func (*FS) AllProcs

func (fs *FS) AllProcs() Iter

AllProcs implements Source.

type Filedesc

type Filedesc struct {
	// Open is the count of open file descriptors, -1 if unknown.
	Open int64
	// Limit is the fd soft limit for the process.
	Limit uint64
}

Filedesc describes a proc's file descriptor usage and soft limit.

type Group

type Group struct {
	Counts
	States
	Wchans map[string]int
	Procs  int
	Memory
	OldestStartTime time.Time
	OpenFDs         uint64
	WorstFDratio    float64
	NumThreads      uint64
	Threads         []Threads
}

Group describes the metrics of a single group.

type GroupByName

type GroupByName map[string]Group

GroupByName maps group name to group metrics.

type Grouper

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

Grouper is the top-level interface to the process metrics. All tracked procs sharing the same group name are aggregated.

func NewGrouper

func NewGrouper(namer common.MatchNamer, trackChildren, trackThreads, alwaysRecheck, debug bool) *Grouper

NewGrouper creates a grouper.

func (*Grouper) Update

func (g *Grouper) Update(iter Iter) (CollectErrors, GroupByName, error)

Update asks the tracker to report on each tracked process by name. These are aggregated by groupname, augmented by accumulated counts from the past, and returned. Note that while the Tracker reports only what counts have changed since last cycle, Grouper.Update returns counts that never decrease. Even once the last process with name X disappears, name X will still appear in the results with the same counts as before; of course, all non-count metrics will be zero.

type ID

type ID struct {
	// UNIX process id
	Pid int
	// The time the process started after system boot, the value is expressed
	// in clock ticks.
	StartTimeRel uint64
}

ID uniquely identifies a process.

type IDInfo

type IDInfo struct {
	ID
	Static
	Metrics
	Threads []Thread
}

IDInfo groups all info for a single process.

func (IDInfo) GetCounts

func (p IDInfo) GetCounts() (Counts, int, error)

GetCounts implements Proc.

func (IDInfo) GetMetrics

func (p IDInfo) GetMetrics() (Metrics, int, error)

GetMetrics implements Proc.

func (IDInfo) GetPid

func (p IDInfo) GetPid() int

GetPid implements Proc.

func (IDInfo) GetProcID

func (p IDInfo) GetProcID() (ID, error)

GetProcID implements Proc.

func (IDInfo) GetStates

func (p IDInfo) GetStates() (States, error)

GetStates implements Proc.

func (IDInfo) GetStatic

func (p IDInfo) GetStatic() (Static, error)

GetStatic implements Proc.

func (IDInfo) GetThreads

func (p IDInfo) GetThreads() ([]Thread, error)

func (IDInfo) GetWchan

func (p IDInfo) GetWchan() (string, error)

func (IDInfo) String

func (ii IDInfo) String() string

type Iter

type Iter interface {
	// Next returns true if the iterator is not exhausted.
	Next() bool
	// Close releases any resources the iterator uses.
	Close() error
	// The iterator satisfies the Proc interface.
	Proc
}

Iter is an iterator over a sequence of procs.

type Memory

type Memory struct {
	ResidentBytes         uint64
	VirtualBytes          uint64
	VmSwapBytes           uint64
	ProportionalBytes     uint64
	ProportionalSwapBytes uint64
}

Memory describes a proc's memory usage.

type Metrics

type Metrics struct {
	Counts
	Memory
	Filedesc
	NumThreads uint64
	States
	Wchan string
}

Metrics contains data read from /proc/pid/*

type Proc

type Proc interface {
	// GetPid() returns the POSIX PID (process id).  They may be reused over time.
	GetPid() int
	// GetProcID() returns (pid,starttime), which can be considered a unique process id.
	GetProcID() (ID, error)
	// GetStatic() returns various details read from files under /proc/<pid>/.  Technically
	// name may not be static, but we'll pretend it is.
	GetStatic() (Static, error)
	// GetMetrics() returns various metrics read from files under /proc/<pid>/.
	// It returns an error on complete failure.  Otherwise, it returns metrics
	// and 0 on complete success, 1 if some (like I/O) couldn't be read.
	GetMetrics() (Metrics, int, error)
	GetStates() (States, error)
	GetWchan() (string, error)
	GetCounts() (Counts, int, error)
	GetThreads() ([]Thread, error)
}

Proc wraps the details of the underlying procfs-reading library. Any of these methods may fail if the process has disapeared. We try to return as much as possible rather than an error, e.g. if some /proc files are unreadable.

type Source

type Source interface {
	// AllProcs returns all the processes in this source at this moment in time.
	AllProcs() Iter
}

Source is a source of procs.

type States

type States struct {
	Running  int
	Sleeping int
	Waiting  int
	Zombie   int
	Other    int
}

States counts how many threads are in each state.

func (*States) Add

func (s *States) Add(s2 States)

type Static

type Static struct {
	Name         string
	Cmdline      []string
	ParentPid    int
	StartTime    time.Time
	EffectiveUID int
}

Static contains data read from /proc/pid/*

type Thread

type Thread struct {
	ThreadID
	ThreadName string
	Counts
	Wchan string
	States
}

Thread contains per-thread data.

type ThreadID

type ThreadID ID

type ThreadUpdate

type ThreadUpdate struct {
	// ThreadName is the name of the thread based on field of stat.
	ThreadName string
	// Latest is how much the counts increased since last cycle.
	Latest Delta
}

ThreadUpdate describes what's changed for a thread since the last cycle.

type Threads

type Threads struct {
	Name       string
	NumThreads int
	Counts
}

Threads collects metrics for threads in a group sharing a thread name.

type Tracker

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

Tracker tracks processes and records metrics.

func NewTracker

func NewTracker(namer common.MatchNamer, trackChildren, trackThreads, alwaysRecheck, debug bool) *Tracker

NewTracker creates a Tracker.

func (*Tracker) Update

func (t *Tracker) Update(iter Iter) (CollectErrors, []Update, error)

Update modifies the tracker's internal state based on what it reads from iter. Tracks any new procs the namer wants tracked, and updates its metrics for existing tracked procs. Returns nonfatal errors and the status of all tracked procs, or an error if fatal.

type Update

type Update struct {
	// GroupName is the name given by the namer to the process.
	GroupName string
	// Latest is how much the counts increased since last cycle.
	Latest Delta
	// Memory is the current memory usage.
	Memory
	// Filedesc is the current fd usage/limit.
	Filedesc
	// Start is the time the process started.
	Start time.Time
	// NumThreads is the number of threads.
	NumThreads uint64
	// States is how many processes are in which run state.
	States
	// Wchans is how many threads are in each non-zero wchan.
	Wchans map[string]int
	// Threads are the thread updates for this process, if the Tracker
	// has trackThreads==true.
	Threads []ThreadUpdate
}

Update reports on the latest stats for a process.