README
¶
proctree
proctree is a simple package for working with a tree of processes.
Features
- Easy to use with sensible defaults and golang option pattern
- Thread safe refresh mechanism
- Identity of Process objects preserved across refreshes
- Filters out kernel threads by default
- Can work with a subset of processes with provided root pids
- A command-line wrapper is included in cmd/proctree that allows you to display a process tree
Install
Binaries
$ go install github.com/sammck-go/proctree/...
Source
$ go get -v github.com/sammck-go/proctree/...
Commandline Usage
$ proctree --help
Usage: proctree [<option>...]
Print process tree details.
Options:
-a, --include-ancestors Include ancestors of roots. No effect if roots not provided.
Disabled by default.
-k, --include-kernel-threads Include kernel threads. Disabled by default.
-r, --root strings Provides a pid to use as a root of the tree. May be repeated.
By default, all orphaned processes are roots.
pflag: help requested
Package Usage
import "github.com/sammck-go/proctree"
Package proctree provides tools for inspecting, monitoring, and manipulating the system process tree.
Usage
type Config
type Config struct {
}
Config provides configuration options for contruction of a ProcTree. The constructed object is immutable after it is constructed by NewConfig.
func NewConfig
func NewConfig(opts ...ConfigOption) *Config
NewConfig creates a proctree Config object from provided options. The resulting object can be passed to New using WithConfig.
func (*Config) Refine
func (cfg *Config) Refine(opts ...ConfigOption) *Config
Refine creates a new Config object by applying ConfigOptions to an existing config.
type ConfigOption
type ConfigOption func(*Config)
ConfigOption is an opaque configuration option setter created by one of the With functions. It follows the Golang "options" pattern.
func WithConfig
func WithConfig(other *Config) ConfigOption
WithConfig allows initialization of a new configuration object starting with an existing one, and incremental initialization of configuration separately from initialization of the PidFile. If provided, this option should be appear first in the option list, since it replaces all configuration values.
func WithKernelThreads
func WithKernelThreads() ConfigOption
WithKernelThreads enables inclusion of kernel threads (children of pid 2). By default, kernel threads are excluded.
func WithRootAncestors
func WithRootAncestors() ConfigOption
WithRootAncestors enables inclusion of all Processes that are ancestors of the pids configured with WithRootPid. Has no effect if WithRootPid is not specified. By default, root ancestors are excluded and the root Processes appear at the first level of the tree.
func WithRootPid
func WithRootPid(pid int) ConfigOption
WithRootPid adds a pid to the set of pids to be included as roots of the tree. By default, all orphaned processes are included as roots.
func WithoutKernelThreads
func WithoutKernelThreads() ConfigOption
WithoutKernelThreads disables inclusion of kernel threads (children of pid 2). This is the default option.
func WithoutRootAncestors
func WithoutRootAncestors() ConfigOption
WithoutRootAncestors disables inclusion of Processes that are ancestors of the pids configured with WithRootPid. Has no effect if WithRootPid is not specified. Root ancestors are excluded and the root Processes appear at the first level of the tree. This is the default setting.
func WithoutRootPid
func WithoutRootPid() ConfigOption
WithoutRootPid removes all pids added with WithRootPid, restoring config the default, which is to include all orphaned processses.
type ProcTree
type ProcTree struct {
}
ProcTree represents a session that inspects, monitors, and manipulates the system process tree
func New
func New(opts ...ConfigOption) (*ProcTree, error)
New creates a new process tree management object and populates it with an initial snapshot
func (*ProcTree) Close
func (pt *ProcTree) Close() error
Close implements io.Closer. Shuts down the ProcTree and releases resources
func (*ProcTree) PidProcess
func (pt *ProcTree) PidProcess(pid int) (proc *Process, ok bool)
PidProcess looks up a Process in the current snapshot by PID. If there is no process with the provided PID, (nil, false) is returned.
func (*ProcTree) Processes
func (pt *ProcTree) Processes() []*Process
Processes returns a snapshot of the list of Process objects the tree, sorted in ascending PID order. If root pids were provided at configuration time, only processes descended from the provided root Processes will be returned.
func (*ProcTree) Roots
func (pt *ProcTree) Roots() []*Process
Roots returns a snapshot of the list of all included Process objects that are toplevel roots, sorted in ascending PID order.
func (*ProcTree) SortProcessesByPid
func (pt *ProcTree) SortProcessesByPid(procs []*Process)
SortProcessesByPid sorts a slice of Processes in increasing pid order.
func (*ProcTree) Update
func (pt *ProcTree) Update(pruneTombstones bool) error
Update refreshes the ProcTree session with a new snapshot view of current processes. Process objects from the previous snapshot are preserved, but may become tombstoned.
func (*ProcTree) Walk
func (pt *ProcTree) Walk(h ProcessHandler) error
Walk walks all subtrees starting at the configured root Process objects, invoking a handler for each. Roots are walked in pid order; within each root Processes are walked in depth-first order with children sorted in pid order.
func (*ProcTree) WalkFromRoots
func (pt *ProcTree) WalkFromRoots(roots []*Process, h ProcessHandler) error
WalkFromRoots walks all subtrees starting at this provided root Process objects, invoking a handler for each. Roots are walked in provided order; within each root Processes are walked in depth-first order with children sorted in pid order. It is the caller's responsibility to ensure that no root is a descendant of another; otherwise the handler will be called multiple times for the same Process.
type Process
type Process struct {
}
Process repressents an abstraction of a single process within a ProcTree session. It maintains its identity within a single session.
func (*Process) Children
func (p *Process) Children() []*Process
Children returns an immutable snapshot slice of Processes known to be a child of the Process. Only children that meet configured filter conditions (e.g., are in configured root subtrees or ancestor paths) are included. This will include tombstoned children that have been added since the last time tombstones were pruned.
func (*Process) Depth
func (p *Process) Depth() int
Depth computes the depth of this process in the process tree. 0 is returned for root processes; 1 for their children; etc.
func (*Process) Executable
func (p *Process) Executable() string
Executable returns the executable name associated with a process, without the directory path
func (*Process) IsAncestorOf
func (p *Process) IsAncestorOf(descendant *Process) bool
IsAncestorOf returns true if the Process is a known ancestor of a provided descendant Process
func (*Process) IsDescendantOf
func (p *Process) IsDescendantOf(ancestor *Process) bool
IsDescendantOf returns true if the Process is a known descendant of a provided ancestor Process
func (*Process) OrigParent
func (p *Process) OrigParent() *Process
OrigParent returns the Process that was the parent before this process became detached (reattached to pid 1), if it is known. Otherwise, returns the parent at the time the session was initialized, which may be null or pid 1.
func (*Process) Parent
func (p *Process) Parent() *Process
Parent returns the Process that is the parent of this Process, or nil if the Process does not have a parent that is configured for inclusion.
func (*Process) Pid
func (p *Process) Pid() int
Pid returns the pid of a Process
func (*Process) WalkAncestry
func (p *Process) WalkAncestry(h ProcessHandler) error
WalkAncestry walks the ancestry list starting at this process, up to the root, invoking a handler for each. Only Processes enabled by configuration are included
func (*Process) WalkSubtree
func (p *Process) WalkSubtree(h ProcessHandler) error
WalkSubtree walks an entire subtree starting at this process as the root, invoking a handler for each. Processes are walked in depth-first order with children sorted in pid order. Only subtrees enabled by configuration are included
type ProcessHandler
type ProcessHandler func(*Process) error
ProcessHandler represents a function that is called back to act on a process. Used for process tree walking operations.
Caveats
- Has not been tested on Windows. In particular, WithoutKernelThreads may cause real processes to be hidden.
Contributing
- http://golang.org/doc/code.html
- http://golang.org/doc/effective_go.html
github.com/sammck-go/proctree/proctree.gocontains the importable packagegithub.com/sammck-go/proctree/cmd/proctree.gocontains the command-line wrapper tool
Changelog
1.0- Initial release
Documentation
¶
Overview ¶
Package proctree provides tools for inspecting, monitoring, and manipulating the system process tree.
Index ¶
- type Config
- type ConfigOption
- type ProcTree
- func (pt *ProcTree) Close() error
- func (pt *ProcTree) PidProcess(pid int) *Process
- func (pt *ProcTree) Processes() []*Process
- func (pt *ProcTree) Roots() []*Process
- func (pt *ProcTree) SortProcessesByPid(procs []*Process)
- func (pt *ProcTree) Update(pruneTombstones bool) error
- func (pt *ProcTree) Walk(h ProcessHandler) error
- func (pt *ProcTree) WalkFromRoots(roots []*Process, h ProcessHandler) error
- type Process
- func (p *Process) Children() []*Process
- func (p *Process) Depth() int
- func (p *Process) Executable() string
- func (p *Process) IsAncestorOf(descendant *Process) bool
- func (p *Process) IsDescendantOf(ancestor *Process) bool
- func (p *Process) OrigParent() *Process
- func (p *Process) Parent() *Process
- func (p *Process) Pid() int
- func (p *Process) WalkAncestry(h ProcessHandler) error
- func (p *Process) WalkSubtree(h ProcessHandler) error
- type ProcessHandler
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// contains filtered or unexported fields
}
Config provides configuration options for contruction of a ProcTree. The constructed object is immutable after it is constructed by NewConfig.
func NewConfig ¶
func NewConfig(opts ...ConfigOption) *Config
NewConfig creates a proctree Config object from provided options. The resulting object can be passed to New using WithConfig.
func (*Config) Refine ¶
func (cfg *Config) Refine(opts ...ConfigOption) *Config
Refine creates a new Config object by applying ConfigOptions to an existing config.
type ConfigOption ¶
type ConfigOption func(*Config)
ConfigOption is an opaque configuration option setter created by one of the With functions. It follows the Golang "options" pattern.
func WithConfig ¶
func WithConfig(other *Config) ConfigOption
WithConfig allows initialization of a new configuration object starting with an existing one, and incremental initialization of configuration separately from initialization of the PidFile. If provided, this option should be appear first in the option list, since it replaces all configuration values.
func WithKernelThreads ¶
func WithKernelThreads() ConfigOption
WithKernelThreads enables inclusion of kernel threads (children of pid 2). By default, kernel threads are excluded.
func WithRootAncestors ¶
func WithRootAncestors() ConfigOption
WithRootAncestors enables inclusion of all Processes that are ancestors of the pids configured with WithRootPid. Has no effect if WithRootPid is not specified. By default, root ancestors are excluded and the root Processes appear at the first level of the tree.
func WithRootPid ¶
func WithRootPid(pid int) ConfigOption
WithRootPid adds a pid to the set of pids to be included as roots of the tree. By default, all orphaned processes are included as roots.
func WithoutKernelThreads ¶
func WithoutKernelThreads() ConfigOption
WithoutKernelThreads disables inclusion of kernel threads (children of pid 2). This is the default option.
func WithoutRootAncestors ¶
func WithoutRootAncestors() ConfigOption
WithoutRootAncestors disables inclusion of Processes that are ancestors of the pids configured with WithRootPid. Has no effect if WithRootPid is not specified. Root ancestors are excluded and the root Processes appear at the first level of the tree. This is the default setting.
func WithoutRootPid ¶
func WithoutRootPid() ConfigOption
WithoutRootPid removes all pids added with WithRootPid, restoring config the default, which is to include all orphaned processses.
type ProcTree ¶
type ProcTree struct {
// contains filtered or unexported fields
}
ProcTree represents a session that inspects, monitors, and manipulates the system process tree
func New ¶
func New(opts ...ConfigOption) (*ProcTree, error)
New creates a new process tree management object and populates it with an initial snapshot
func (*ProcTree) PidProcess ¶
PidProcess looks up a Process in the current snapshot by PID. If there is no process with the provided PID, of if the process is excluded by config, nil is returned.
func (*ProcTree) Processes ¶
Processes returns a snapshot of the list of Process objects the tree, sorted in ascending PID order. If root pids were provided at configuration time, only processes descended from the provided root Processes will be returned.
func (*ProcTree) Roots ¶
Roots returns a snapshot of the list of all included Process objects that are toplevel roots, sorted in ascending PID order.
func (*ProcTree) SortProcessesByPid ¶
SortProcessesByPid sorts a slice of Processes in increasing pid order.
func (*ProcTree) Update ¶
Update refreshes the ProcTree session with a new snapshot view of current processes. Process objects from the previous snapshot are preserved, but may become tombstoned.
func (*ProcTree) Walk ¶
func (pt *ProcTree) Walk(h ProcessHandler) error
Walk walks all subtrees starting at the configured root Process objects, invoking a handler for each. Roots are walked in pid order; within each root Processes are walked in depth-first order with children sorted in pid order.
func (*ProcTree) WalkFromRoots ¶
func (pt *ProcTree) WalkFromRoots(roots []*Process, h ProcessHandler) error
WalkFromRoots walks all subtrees starting at this provided root Process objects, invoking a handler for each. Roots are walked in provided order; within each root Processes are walked in depth-first order with children sorted in pid order. It is the caller's responsibility to ensure that no root is a descendant of another; otherwise the handler will be called multiple times for the same Process.
type Process ¶
type Process struct {
// contains filtered or unexported fields
}
Process repressents an abstraction of a single process within a ProcTree session. It maintains its identity within a single session.
func (*Process) Children ¶
Children returns an immutable snapshot slice of Processes known to be a child of the Process. Only children that meet configured filter conditions (e.g., are in configured root subtrees or ancestor paths) are included. This will include tombstoned children that have been added since the last time tombstones were pruned.
func (*Process) Depth ¶
Depth computes the depth of this process in the process tree. 0 is returned for root processes; 1 for their children; etc.
func (*Process) Executable ¶
Executable returns the executable name associated with a process, without the directory path
func (*Process) IsAncestorOf ¶
IsAncestorOf returns true if the Process is a known ancestor of a provided descendant Process
func (*Process) IsDescendantOf ¶
IsDescendantOf returns true if the Process is a known descendant of a provided ancestor Process
func (*Process) OrigParent ¶
OrigParent returns the Process that was the parent before this process became detached (reattached to pid 1), if it is known. Otherwise, returns the parent at the time the session was initialized, which may be null or pid 1.
func (*Process) Parent ¶
Parent returns the Process that is the parent of this Process, or nil if the Process does not have a parent that is configured for inclusion.
func (*Process) WalkAncestry ¶
func (p *Process) WalkAncestry(h ProcessHandler) error
WalkAncestry walks the ancestry list starting at this process, up to the root, invoking a handler for each. Only Processes enabled by configuration are included
func (*Process) WalkSubtree ¶
func (p *Process) WalkSubtree(h ProcessHandler) error
WalkSubtree walks an entire subtree starting at this process as the root, invoking a handler for each. Processes are walked in depth-first order with children sorted in pid order. Only subtrees enabled by configuration are included
type ProcessHandler ¶
ProcessHandler represents a function that is called back to act on a process. Used for process tree walking operations.
Source Files
Directories