cgroups

Documentation

Index

• Constants
• func ContainerFilter(path, name string) (string, error)
• func DefaultFilter(path, name string) (string, error)
• func SetReporter(r Reporter)
• type CPUStats
• type Cgroup
• type ControllerNotFoundError
  • func (e *ControllerNotFoundError) Error() string
  • func (e *ControllerNotFoundError) Is(target error) bool
• type DeviceIOStats
• type FileSystemError
  • func (e *FileSystemError) Error() string
  • func (e *FileSystemError) Unwrap() error
• type IOStats
• type InvalidInputError
  • func (e *InvalidInputError) Error() string
• type MemoryStats
• type PIDStats
• type PSIStats
• type Reader
  • func NewReader(opts ...ReaderOption) (*Reader, error)
  • func (r *Reader) GetCgroup(id string) Cgroup
  • func (r *Reader) ListCgroups() []Cgroup
  • func (r *Reader) RefreshCgroups(cacheValidity time.Duration) error
• type ReaderFilter
• type ReaderOption
  • func WithCgroupV1BaseController(controller string) ReaderOption
  • func WithHostPrefix(hostPrefix string) ReaderOption
  • func WithProcPath(fullPath string) ReaderOption
  • func WithReaderFilter(rf ReaderFilter) ReaderOption
• type Reporter
• type Stats
• type ValueError
  • func (e *ValueError) Error() string
  • func (e *ValueError) Unwrap() error

Constants

const (
	UserHZToNano uint64 = uint64(time.Second) / 100
)

UserHZToNano holds the divisor to convert HZ to Nanoseconds It's safe to consider it being 100Hz in userspace mode

Functions

func ContainerFilter

func ContainerFilter(path, name string) (string, error)

ContainerFilter returns a filter that will match cgroup folders containing a container id

func DefaultFilter

func DefaultFilter(path, name string) (string, error)

DefaultFilter matches all cgroup folders and use folder name as identifier

func SetReporter

func SetReporter(r Reporter)

SetReporter allows to set a Reporter (set to nil to disable)

Types

type CPUStats

type CPUStats struct {
	User   *uint64
	System *uint64
	Total  *uint64

	Shares           *uint64 // Raw share value (no unit)
	ElapsedPeriods   *uint64 // Number (no unit)
	ThrottledPeriods *uint64 // Number (no unit)
	ThrottledTime    *uint64
	CPUCount         *uint64 // Number of accessible logical CPU (from cpuset.cpus)

	SchedulerPeriod *uint64
	SchedulerQuota  *uint64

	PSISome PSIStats
}

CPUStats - all metrics are in nanoseconds execept if otherwise specified cgroupv1: cpu/cpuacct/cpuset cgroupv2: cpu/cpuset

type Cgroup

type Cgroup interface {
	// Identifier returns the cgroup identifier that was generated by the selected `Filter` (default: folder name)
	Identifier() string
	// GetParent returns parent Cgroup (will fail if used on root cgroup)
	GetParent() (Cgroup, error)
	// GetStats returns all cgroup statistics at once. Each call triggers a read from filesystem (no cache)
	// The given Stats object is filled with new values. If re-using object, old values are not cleared on read failure.
	GetStats(*Stats) error
	// GetCPUStats returns all cgroup statistics at once. Each call triggers a read from filesystem (no cache)
	// The given CPUStats object is filled with new values. If re-using object, old values are not cleared on read failure.
	GetCPUStats(*CPUStats) error
	// GetMemoryStats returns all cgroup statistics at once. Each call triggers a read from filesystem (no cache)
	// The given MemoryStats object is filled with new values. If re-using object, old values are not cleared on read failure.
	GetMemoryStats(*MemoryStats) error
	// GetIOStats returns all cgroup statistics at once. Each call triggers a read from filesystem (no cache)
	// The given IOStats object is filled with new values. If re-using object, old values are not cleared on read failure.
	GetIOStats(*IOStats) error
	// GetPIDStats returns all cgroup statistics at once. Each call triggers a read from filesystem (no cache)
	// The given PIDStats object is filled with new values. If re-using object, old values are not cleared on read failure.
	GetPIDStats(*PIDStats) error
}

Cgroup interface abstracts actual Cgroup implementation (v1/v2)

type ControllerNotFoundError

type ControllerNotFoundError struct {
	Controller string
}

ControllerNotFoundError is returned when trying to access a cgroup controller that's not visible in /proc/mount (cgroup v1 only)

func (*ControllerNotFoundError) Error

func (e *ControllerNotFoundError) Error() string

func (*ControllerNotFoundError) Is

func (e *ControllerNotFoundError) Is(target error) bool

Is returns whether two ControllerNotFoundError targets the same controller

type DeviceIOStats

type DeviceIOStats struct {
	ReadBytes       *uint64
	WriteBytes      *uint64
	ReadOperations  *uint64
	WriteOperations *uint64

	ReadBytesLimit       *uint64 // cgroupv2 only (bytes/s)
	WriteBytesLimit      *uint64 // cgroupv2 only (bytes/s)
	ReadOperationsLimit  *uint64 // cgroupv2 only (ops/s)
	WriteOperationsLimit *uint64 // cgroupv2 only (ops/s)
}

DeviceIOStats is a sub-structure to store stats per device

type FileSystemError

type FileSystemError struct {
	FilePath string
	Err      error
}

FileSystemError is returned when an error occurs when reading cgroup filesystem

func (*FileSystemError) Error

func (e *FileSystemError) Error() string

func (*FileSystemError) Unwrap

func (e *FileSystemError) Unwrap() error

type IOStats

type IOStats struct {
	ReadBytes       *uint64
	WriteBytes      *uint64
	ReadOperations  *uint64
	WriteOperations *uint64
	Devices         map[string]DeviceIOStats

	PSISome PSIStats
	PSIFull PSIStats
}

IOStats store I/O statistics about a cgroup. Devices identifier in map is MAJOR:MINOR cgroupv1: blkio cgroupv2: io

type InvalidInputError

type InvalidInputError struct {
	Desc string
}

InvalidInputError is returned when an input parameter has an invalid value (typically, passing a nil pointer)

func (*InvalidInputError) Error

func (e *InvalidInputError) Error() string

type MemoryStats

type MemoryStats struct {
	UsageTotal   *uint64
	Cache        *uint64
	Swap         *uint64
	RSS          *uint64
	RSSHuge      *uint64
	MappedFile   *uint64
	Pgpgin       *uint64 // Number (no unit), cgroupv1 only
	Pgpgout      *uint64 // Number (no unit), cgroupv1 only
	Pgfault      *uint64 // Number (no unit)
	Pgmajfault   *uint64 // Number (no unit)
	InactiveAnon *uint64
	ActiveAnon   *uint64
	InactiveFile *uint64
	ActiveFile   *uint64
	Unevictable  *uint64

	KernelMemory *uint64

	// This field is mapped to `memory.failcnt` for cgroupv1 and to "oom" in `memory.event`, it does not mean an OOMKill event happened.
	OOMEvents     *uint64 // Number (no unit).
	OOMKiilEvents *uint64 // cgroupv2 only

	Limit             *uint64
	MinThreshold      *uint64 // cgroupv2 only
	LowThreshold      *uint64 // cgroupv1: mapped to soft_limit
	HighThreshold     *uint64 // cgroupv2 only
	SwapLimit         *uint64
	SwapHighThreshold *uint64 // cgroupv2 only

	PSISome PSIStats
	PSIFull PSIStats
}

MemoryStats - all metrics in bytes except if otherwise specified All statistics are hierarchical (i.e. includes all descendants) Meaning for each value can be checked at: https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt or https://www.kernel.org/doc/Documentation/cgroup-v2.txt Source: cgroupv1: memory controller cgroupv2: memory controller

type PIDStats

type PIDStats struct {
	PIDs                    []int
	HierarchicalThreadCount *uint64 // Number of threads in cgroups + all children
	HierarchicalThreadLimit *uint64 // Maximum number of threads in cgroups + all children
}

PIDStats store stats about running threads and processes cgroupv1: pid cgroupv2: pid

type PSIStats

type PSIStats struct {
	Avg10  *float64 // Percentage (0-100)
	Avg60  *float64 // Percentage (0-100)
	Avg300 *float64 // Percentage (0-100)
	Total  *uint64  // Nanoseconds
}

PSIStats represent the Pressure Stall Information data Source: cgroupv1: not present cgroupv2: *.pressure

type Reader

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

Reader is the main interface to scrape data from cgroups Calling RefreshCgroups() with your cache toleration is mandatory to retrieve accurate data All Reader methods support concurrent calls

func NewReader

func NewReader(opts ...ReaderOption) (*Reader, error)

NewReader returns a new cgroup reader with given options

func (*Reader) GetCgroup

func (r *Reader) GetCgroup(id string) Cgroup

GetCgroup returns cgroup for a given id, or nil if not found.

func (*Reader) ListCgroups

func (r *Reader) ListCgroups() []Cgroup

ListCgroups returns list of known cgroups

func (*Reader) RefreshCgroups

func (r *Reader) RefreshCgroups(cacheValidity time.Duration) error

RefreshCgroups triggers a refresh if data are older than cacheValidity. 0 to always refesh.

type ReaderFilter

type ReaderFilter func(path, name string) (string, error)

ReaderFilter allows to filter cgroups based on their path + folder name

type ReaderOption

type ReaderOption func(*Reader)

ReaderOption allows to customize reader behavior (Builder-style)

func WithCgroupV1BaseController

func WithCgroupV1BaseController(controller string) ReaderOption

WithCgroupV1BaseController sets which controller is used to select cgroups it then assumes that, if being, used other controllers uses the same relative path. Default to "memory" if not set.

func WithHostPrefix

func WithHostPrefix(hostPrefix string) ReaderOption

WithHostPrefix sets where hosts path are mounted (if not running on-host)

func WithProcPath

func WithProcPath(fullPath string) ReaderOption

WithProcPath sets where /proc is currently mounted. If set, hostPrefix is not added to this path. Default to `$hostPrefix/proc` if empty.

func WithReaderFilter

func WithReaderFilter(rf ReaderFilter) ReaderOption

WithReaderFilter sets the filter used to select interesting cgroup folders and provides an identifier for them.

type Reporter

type Reporter interface {
	// HandleError is called when a non-blocking error has been encountered.
	// e is the encountered error
	HandleError(e error)

	// FileAccessed is called everytime time a file is opened
	FileAccessed(path string)
}

Reporter defines some hooks that can be used to track and report on cgroup parsing. It's typically useful for logging and debugging.

type Stats

type Stats struct {
	CPU    *CPUStats
	Memory *MemoryStats
	IO     *IOStats
	PID    *PIDStats
}

Stats wraps all container metrics

type ValueError

type ValueError struct {
	Data string
	Err  error
}

ValueError is reported when the parser encounters an unexpected content in a cgroup file. This error is not blocking and will only be retported through the reporter. Seeing this error means that there's either in bug in the parsing code (most likely), unsupported new cgroup feature, Kernel bug (less likely)

func (*ValueError) Error

func (e *ValueError) Error() string

func (*ValueError) Unwrap

func (e *ValueError) Unwrap() error