cgroup

package
v0.14.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 14, 2024 License: Apache-2.0 Imports: 12 Imported by: 280

Documentation

Overview

Package cgroup reads metrics and other tunable parameters associated with control groups, a Linux kernel feature for grouping tasks to track and limit resource usage.

Terminology

A cgroup is a collection of processes that are bound to a set of limits.

A subsystem is a kernel component the modifies the behavior of processes in a cgroup.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrCgroupsMissing indicates the /proc/cgroups was not found. This means
	// that cgroups were disabled at compile time (CONFIG_CGROUPS=n) or that
	// an invalid rootfs path was given.
	ErrCgroupsMissing = errors.New("cgroups not found or unsupported by OS")

	// ErrInvalidFormat indicates a malformed key/value pair on a line.
	ErrInvalidFormat = errors.New("error invalid key/value format")
)

Functions

func ProcessCgroupPaths 

func ProcessCgroupPaths(rootfsMountpoint string, pid int) (map[string]string, error)

ProcessCgroupPaths returns the cgroups to which a process belongs and the pathname of the cgroup relative to the mountpoint of the subsystem.

func SubsystemMountpoints 

func SubsystemMountpoints(rootfsMountpoint string, subsystems map[string]struct{}) (map[string]string, error)

SubsystemMountpoints returns the mountpoints for each of the given subsystems. The returned map contains the subsystem name as a key and the value is the mountpoint.

func SupportedSubsystems 

func SupportedSubsystems(rootfsMountpoint string) (map[string]struct{}, error)

SupportedSubsystems returns the subsystems that are supported by the kernel. The returned map contains a entry for each subsystem.

Types

type BlockIOSubsystem 

type BlockIOSubsystem struct {
	Metadata
	Throttle ThrottlePolicy `json:"throttle,omitempty"` // Throttle limits for upper IO rates and metrics.

}

BlockIOSubsystem contains limits and metrics from the "blkio" subsystem. The blkio subsystem controls and monitors access to I/O on block devices by tasks in a cgroup.

https://www.kernel.org/doc/Documentation/cgroup-v1/blkio-controller.txt

type CFQDevice 

type CFQDevice struct {
	DeviceID DeviceID `json:"device_id"` // ID of the device.

	// Proportional weight for the device. 0 means a per device weight is not set and
	// that the blkio.weight value is used.
	Weight uint64 `json:"weight"`

	TimeMs           uint64          `json:"time_ms"`          // Disk time allocated to cgroup per device in milliseconds.
	Sectors          uint64          `json:"sectors"`          // Number of sectors transferred to/from disk by the cgroup.
	Bytes            OperationValues `json:"io_service_bytes"` // Number of bytes transferred to/from the disk by the cgroup.
	IOs              OperationValues `json:"io_serviced"`      // Number of IO operations issued to the disk by the cgroup.
	ServiceTimeNanos OperationValues `json:"io_service_time"`  // Amount of time between request dispatch and request completion for the IOs done by this cgroup.
	WaitTimeNanos    OperationValues `json:"io_wait_time"`     // Amount of time the IOs for this cgroup spent waiting in the scheduler queues for service.
	Merges           OperationValues `json:"io_merged"`        // Total number of bios/requests merged into requests belonging to this cgroup.
}

CFQDevice contains CFQ limits and metrics associated with a single device.

type CFQScheduler 

type CFQScheduler struct {
	Weight  uint64      `json:"weight"` // Default weight for all devices unless overridden. Allowed range of weights is from 10 to 1000.
	Devices []CFQDevice `json:"devices,omitempty"`
}

CFQScheduler contains limits and metrics for the proportional weight time based division of disk policy. It is implemented in CFQ. Hence this policy takes effect only on leaf nodes when CFQ is being used.

https://www.kernel.org/doc/Documentation/block/cfq-iosched.txt

type CFS 

type CFS struct {
	// Period of time in microseconds for how regularly the cgroup's access to
	// CPU resources should be reallocated.
	PeriodMicros uint64 `json:"period_us"`
	// Total amount of time in microseconds for which all tasks in the cgroup
	// can run during one period.
	QuotaMicros uint64 `json:"quota_us"`
	// Relative share of CPU time available to tasks the cgroup. The value is
	// an integer greater than or equal to 2.
	Shares uint64 `json:"shares"`
}

CFS contains the tunable parameters for the completely fair scheduler.

type CPUAccountingStats 

type CPUAccountingStats struct {
	UserNanos   uint64 `json:"user_nanos"`
	SystemNanos uint64 `json:"system_nanos"`
}

CPUAccountingStats contains the stats reported from the cpuacct subsystem.

type CPUAccountingSubsystem 

type CPUAccountingSubsystem struct {
	Metadata
	TotalNanos  uint64   `json:"total_nanos"`
	UsagePerCPU []uint64 `json:"usage_percpu_nanos"`
	// CPU time statistics for tasks in this cgroup.
	Stats CPUAccountingStats `json:"stats,omitempty"`
}

CPUAccountingSubsystem contains metrics from the "cpuacct" subsystem.

type CPUSubsystem 

type CPUSubsystem struct {
	Metadata
	// Completely Fair Scheduler (CFS) settings.
	CFS CFS `json:"cfs,omitempty"`
	// Real-time (RT) Scheduler settings.
	RT RT `json:"rt,omitempty"`
	// CPU time statistics for tasks in this cgroup.
	Stats ThrottleStats `json:"stats,omitempty"`
}

CPUSubsystem contains metrics and limits from the "cpu" subsystem. This subsystem is used to guarantee a minimum number of cpu shares to the cgroup when the system is busy. This subsystem does not track CPU usage, for that information see the "cpuacct" subsystem.

type DeviceID 

type DeviceID struct {
	Major uint64
	Minor uint64
}

DeviceID identifies a Linux block device.

type MemoryData 

type MemoryData struct {
	Usage     uint64 `json:"usage"`         // Usage in bytes.
	MaxUsage  uint64 `json:"max_usage"`     // Max usage in bytes.
	Limit     uint64 `json:"limit"`         // Limit in bytes.
	FailCount uint64 `json:"failure_count"` // Number of times the memory limit has been reached.
}

MemoryData groups related memory usage metrics and limits.

type MemoryStat 

type MemoryStat struct {
	// Page cache, including tmpfs (shmem), in bytes.
	Cache uint64 `json:"cache"`
	// Anonymous and swap cache, not including tmpfs (shmem), in bytes.
	RSS uint64 `json:"rss"`
	// Anonymous transparent hugepages in bytes.
	RSSHuge uint64 `json:"rss_huge"`
	// Size of memory-mapped mapped files, including tmpfs (shmem), in bytes.
	MappedFile uint64 `json:"mapped_file"`
	// Number of pages paged into memory.
	PagesIn uint64 `json:"pgpgin"`
	// Number of pages paged out of memory.
	PagesOut uint64 `json:"pgpgout"`
	// Number of times a task in the cgroup triggered a page fault.
	PageFaults uint64 `json:"pgfault"`
	// Number of times a task in the cgroup triggered a major page fault.
	MajorPageFaults uint64 `json:"pgmajfault"`
	// Swap usage in bytes.
	Swap uint64 `json:"swap"`
	// Anonymous and swap cache on active least-recently-used (LRU) list, including tmpfs (shmem), in bytes.
	ActiveAnon uint64 `json:"active_anon"`
	// Anonymous and swap cache on inactive LRU list, including tmpfs (shmem), in bytes.
	InactiveAnon uint64 `json:"inactive_anon"`
	// File-backed memory on active LRU list, in bytes.
	ActiveFile uint64 `json:"active_file"`
	// File-backed memory on inactive LRU list, in bytes.
	InactiveFile uint64 `json:"inactive_file"`
	// Memory that cannot be reclaimed, in bytes.
	Unevictable uint64 `json:"unevictable"`
	// Memory limit for the hierarchy that contains the memory cgroup, in bytes.
	HierarchicalMemoryLimit uint64 `json:"hierarchical_memory_limit"`
	// Memory plus swap limit for the hierarchy that contains the memory cgroup, in bytes.
	HierarchicalMemswLimit uint64 `json:"hierarchical_memsw_limit"`
}

MemoryStat contains various memory statistics and accounting information associated with a cgroup.

type MemorySubsystem 

type MemorySubsystem struct {
	Metadata
	Mem       MemoryData `json:"mem"`      // Memory usage by tasks in this cgroup.
	MemSwap   MemoryData `json:"memsw"`    // Memory plus swap usage by tasks in this cgroup.
	Kernel    MemoryData `json:"kmem"`     // Kernel memory used by tasks in this cgroup.
	KernelTCP MemoryData `json:"kmem_tcp"` // Kernel TCP buffer memory used by tasks in this cgroup.
	Stats     MemoryStat `json:"stats"`    // A wide range of memory statistics.
}

MemorySubsystem contains the metrics and limits from the "memory" subsystem.

type Metadata 

type Metadata struct {
	ID   string `json:"id,omitempty"`   // ID of the cgroup.
	Path string `json:"path,omitempty"` // Path to the cgroup relative to the cgroup subsystem's mountpoint.
}

Metadata contains metadata associated with cgroup stats.

type OperationValues 

type OperationValues struct {
	Read  uint64 `json:"read"`
	Write uint64 `json:"write"`
	Async uint64 `json:"async"`
	Sync  uint64 `json:"sync"`
}

OperationValues contains the I/O limits or metrics associated with read, write, sync, and async operations.

type RT 

type RT struct {
	// Period of time in microseconds for how regularly the cgroup's access to
	// CPU resources should be reallocated.
	PeriodMicros uint64 `json:"period_us"`
	// Period of time in microseconds for the longest continuous period in which
	// the tasks in the cgroup have access to CPU resources.
	RuntimeMicros uint64 `json:"quota_us"`
}

RT contains the tunable parameters for the real-time scheduler.

type Reader 

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

Reader reads cgroup metrics and limits.

func NewReader 

func NewReader(rootfsMountpoint string, ignoreRootCgroups bool) (*Reader, error)

NewReader creates and returns a new Reader.

func NewReaderOptions added in v0.13.0 

func NewReaderOptions(opts ReaderOptions) (*Reader, error)

NewReaderOptions creates and returns a new Reader with the given options.

func (*Reader) GetStatsForProcess 

func (r *Reader) GetStatsForProcess(pid int) (*Stats, error)

GetStatsForProcess returns cgroup metrics and limits associated with a process.

type ReaderOptions added in v0.13.0 

type ReaderOptions struct {
	// RootfsMountpoint holds the mountpoint of the root filesystem.
	//
	// If unspecified, "/" is assumed.
	RootfsMountpoint string

	// IgnoreRootCgroups ignores cgroup subsystem with the path "/".
	IgnoreRootCgroups bool

	// CgroupsHierarchyOverride is an optional path override for cgroup
	// subsystem paths. If non-empty, this will be used instead of the
	// paths specified in /proc/<pid>/cgroup.
	//
	// This should be set to "/" when running within a Docker container,
	// where the paths in /proc/<pid>/cgroup do not correspond to any
	// paths under /sys/fs/cgroup.
	CgroupsHierarchyOverride string
}

ReaderOptions holds options for NewReaderOptions.

type Stats 

type Stats struct {
	Metadata
	CPU           *CPUSubsystem           `json:"cpu"`
	CPUAccounting *CPUAccountingSubsystem `json:"cpuacct"`
	Memory        *MemorySubsystem        `json:"memory"`
	BlockIO       *BlockIOSubsystem       `json:"blkio"`
}

Stats contains metrics and limits from each of the cgroup subsystems.

type ThrottleDevice 

type ThrottleDevice struct {
	DeviceID DeviceID `json:"device_id"` // ID of the device.

	ReadLimitBPS   uint64 `json:"read_bps_device"`   // Read limit in bytes per second (BPS). Zero means no limit.
	WriteLimitBPS  uint64 `json:"write_bps_device"`  // Write limit in bytes per second (BPS). Zero mean no limit.
	ReadLimitIOPS  uint64 `json:"read_iops_device"`  // Read limit in IOPS. Zero means no limit.
	WriteLimitIOPS uint64 `json:"write_iops_device"` // Write limit in IOPS. Zero means no limit.

	Bytes OperationValues `json:"io_service_bytes"` // Number of bytes transferred to/from the disk by the cgroup.
	IOs   OperationValues `json:"io_serviced"`      // Number of IO operations issued to the disk by the cgroup.
}

ThrottleDevice contains throttle limits and metrics associated with a single device.

type ThrottlePolicy 

type ThrottlePolicy struct {
	Devices    []ThrottleDevice `json:"devices,omitempty"`      // Device centric view of limits and metrics.
	TotalBytes uint64           `json:"total_io_service_bytes"` // Total number of bytes serviced by all devices.
	TotalIOs   uint64           `json:"total_io_serviced"`      // Total number of IO operations serviced by all devices.
}

ThrottlePolicy contains the upper IO limits and metrics for devices used by the cgroup.

type ThrottleStats 

type ThrottleStats struct {
	// Number of periods with throttling active.
	Periods uint64 `json:"periods,omitempty"`
	// Number of periods when the cgroup hit its throttling limit.
	ThrottledPeriods uint64 `json:"throttled_periods,omitempty"`
	// Aggregate time the cgroup was throttled for in nanoseconds.
	ThrottledTimeNanos uint64 `json:"throttled_nanos,omitempty"`
}

ThrottleStats contains stats that indicate the extent to which this cgroup's CPU usage was throttled.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.