cgroup

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

• Variables
• func SupportedSubsystems(rootfs resolve.Resolver) (map[string]struct{}, error)
• type CGStats
• type CgroupsVersion
• type ControllerPath
• type Mountpoints
  • func SubsystemMountpoints(rootfs resolve.Resolver, subsystems map[string]struct{}) (Mountpoints, error)
• type PathList
  • func ProcessCgroupPaths(hostfs resolve.Resolver, pid int) (PathList, error)
  • func (pl PathList) Flatten() []ControllerPath
• type Reader
  • func NewReader(rootfsMountpoint resolve.Resolver, ignoreRootCgroups bool) (*Reader, error)
  • func NewReaderOptions(opts ReaderOptions) (*Reader, error)
  • func (r *Reader) CgroupsVersion(pid int) (CgroupsVersion, error)
  • func (r *Reader) GetStatsForPid(pid int) (CGStats, error)
  • func (r *Reader) GetV1StatsForProcess(pid int) (*StatsV1, error)
  • func (r *Reader) GetV2StatsForProcess(pid int) (*StatsV2, error)
  • func (r *Reader) ProcessCgroupPaths(pid int) (PathList, error)
• type ReaderOptions
• type StatsV1
  • func (stat StatsV1) CGVersion() CgroupsVersion
  • func (stat *StatsV1) FillPercentages(prev CGStats, curTime, prevTime time.Time)
  • func (stat StatsV1) Format() (mapstr.M, error)
• type StatsV2
  • func (stat StatsV2) CGVersion() CgroupsVersion
  • func (stat *StatsV2) FillPercentages(prev CGStats, curTime, prevTime time.Time)
  • func (stat StatsV2) Format() (mapstr.M, error)

Variables

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")
)

Functions

func SupportedSubsystems

func SupportedSubsystems(rootfs resolve.Resolver) (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 CGStats

type CGStats interface {
	Format() (mapstr.M, error)
	CGVersion() CgroupsVersion
	FillPercentages(prev CGStats, curTime, prevTime time.Time)
}

CGStats in an interface wrapper around the V2 and V1 cgroup stat objects

type CgroupsVersion

type CgroupsVersion int

CgroupsVersion is a version tag that defines what version of cgroups is attached to a process

const CgroupsV1 CgroupsVersion = 1

CgroupsV1 indicates that a process is cgroupsv1

const CgroupsV2 CgroupsVersion = 2

CgroupsV2 indicates that a process is cgroupsv2

type ControllerPath

type ControllerPath struct {
	ControllerPath string
	FullPath       string
	IsV2           bool
}

ControllerPath wraps the controller path

type Mountpoints

type Mountpoints struct {
	V1Mounts               map[string]string
	V2Loc                  string
	ContainerizedRootMount string
}

Mountpoints organizes info about V1 and V2 cgroup mountpoints V2 uses a "unified" hierarchy, so we have less to keep track of

func SubsystemMountpoints

func SubsystemMountpoints(rootfs resolve.Resolver, subsystems map[string]struct{}) (Mountpoints, 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.

type PathList

type PathList struct {
	V1 map[string]ControllerPath
	V2 map[string]ControllerPath
}

PathList contains the V1 and V2 controller paths in a process Separate the V1 and V2 cgroups so we don't have hybrid cgroups fighting for one namespace

func ProcessCgroupPaths

func ProcessCgroupPaths(hostfs resolve.Resolver, pid int) (PathList, error)

ProcessCgroupPaths is a wrapper around Reader.ProcessCgroupPaths for libraries that only need the slimmer functionality from the gosigar cgroups code. This does not have the same function signature, and consumers still need to distinguish between v1 and v2 cgroups.

func (PathList) Flatten

func (pl PathList) Flatten() []ControllerPath

Flatten combines the V1 and V2 cgroups in cases where we don't need a map with keys

type Reader

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

Reader reads cgroup metrics and limits.

func NewReader

func NewReader(rootfsMountpoint resolve.Resolver, ignoreRootCgroups bool) (*Reader, error)

NewReader creates and returns a new Reader.

func NewReaderOptions

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

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

func (*Reader) CgroupsVersion

func (r *Reader) CgroupsVersion(pid int) (CgroupsVersion, error)

CgroupsVersion reports if the given PID is attached to a V1 or V2 controller

func (*Reader) GetStatsForPid

func (r *Reader) GetStatsForPid(pid int) (CGStats, error)

GetStatsForPid is a generic method that returns a CGStats interface for V1 and V2 cgroup statistics. For applications that require raw metrics, use GetV*StatsForProcess()

func (*Reader) GetV1StatsForProcess

func (r *Reader) GetV1StatsForProcess(pid int) (*StatsV1, error)

GetV1StatsForProcess returns cgroup metrics and limits associated with a process.

func (*Reader) GetV2StatsForProcess

func (r *Reader) GetV2StatsForProcess(pid int) (*StatsV2, error)

GetV2StatsForProcess returns cgroup metrics and limits associated with a process.

func (*Reader) ProcessCgroupPaths

func (r *Reader) ProcessCgroupPaths(pid int) (PathList, error)

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

type ReaderOptions

type ReaderOptions struct {
	// RootfsMountpoint holds the mountpoint of the root filesystem.
	//
	// pass
	RootfsMountpoint resolve.Resolver

	// 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 StatsV1

type StatsV1 struct {
	ID            string                       `json:"id,omitempty" struct:"id,omitempty"`     // ID of the cgroup.
	Path          string                       `json:"path,omitempty" struct:"path,omitempty"` // Path to the cgroup relative to the cgroup subsystem's mountpoint.
	CPU           *cgv1.CPUSubsystem           `json:"cpu,omitempty" struct:"cpu,omitempty"`
	CPUAccounting *cgv1.CPUAccountingSubsystem `json:"cpuacct,omitempty" struct:"cpuacct,omitempty"`
	Memory        *cgv1.MemorySubsystem        `json:"memory,omitempty" struct:"memory,omitempty"`
	BlockIO       *cgv1.BlockIOSubsystem       `json:"blkio,omitempty" struct:"blkio,omitempty"`
	Version       CgroupsVersion               `json:"cgroups_version,omitempty" struct:"cgroups_version,omitempty"`
}

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

func (StatsV1) CGVersion

func (stat StatsV1) CGVersion() CgroupsVersion

CGVersion returns the version of the underlying cgroups stats

func (*StatsV1) FillPercentages

func (stat *StatsV1) FillPercentages(prev CGStats, curTime, prevTime time.Time)

FillPercentages uses a previous CGStats object to fill out the percentage values in the cgroup metrics. The `prev` object must be from the same process. curTime and Prev time should be time.Time objects that correspond to the "scrape time" of when the metrics were gathered.

func (StatsV1) Format

func (stat StatsV1) Format() (mapstr.M, error)

Format converts the stats object to a MapStr that can be sent to Report()

type StatsV2

type StatsV2 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.
	CPU     *cgv2.CPUSubsystem    `json:"cpu,omitempty" struct:"cpu,omitempty"`
	Memory  *cgv2.MemorySubsystem `json:"memory,omitempty" struct:"memory,omitempty"`
	IO      *cgv2.IOSubsystem     `json:"io,omitempty" struct:"io,omitempty"`
	Version CgroupsVersion        `json:"cgroups_version,omitempty" struct:"cgroups_version,omitempty"`
}

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

func (StatsV2) CGVersion

func (stat StatsV2) CGVersion() CgroupsVersion

CGVersion returns the version of the underlying cgroups stats

func (*StatsV2) FillPercentages

func (stat *StatsV2) FillPercentages(prev CGStats, curTime, prevTime time.Time)

FillPercentages uses a previous CGStats object to fill out the percentage values in the cgroup metrics. The `prev` object must be from the same process. curTime and Prev time should be time.Time objects that correspond to the "scrape time" of when the metrics were gathered.

func (StatsV2) Format

func (stat StatsV2) Format() (mapstr.M, error)

Format converts the stats object to a MapStr that can be sent to Report()