usage

Documentation

Overview

Package usage provides representations of resource usage.

Index

• Variables
• func Init() error
• func TotalMemory(memSize, used uint64) uint64
• type CPUStats
  • func (s *CPUStats) Accumulate(s2 CPUStats)
  • func (s *CPUStats) DifferenceSince(earlierSample CPUStats) CPUStats
• type IO
  • func (i *IO) AccountReadIO(bytes int64)
  • func (i *IO) AccountReadSyscall(bytes int64)
  • func (i *IO) AccountWriteIO(bytes int64)
  • func (i *IO) AccountWriteSyscall(bytes int64)
  • func (i *IO) Accumulate(io *IO)
  • func (i *IO) Clone(other *IO)
• type MemoryKind
• type MemoryLocked
  • func (m *MemoryLocked) Copy() (MemoryStats, uint64)
  • func (m *MemoryLocked) CopyPerCg(memCgID uint32) (MemoryStats, uint64)
  • func (m *MemoryLocked) Dec(val uint64, kind MemoryKind, memCgID uint32)
  • func (m *MemoryLocked) Inc(val uint64, kind MemoryKind, memCgID uint32)
  • func (m *MemoryLocked) Move(val uint64, to MemoryKind, from MemoryKind, memCgID uint32)
  • func (m *MemoryLocked) Total() uint64
  • func (m *MemoryLocked) TotalPerCg(memCgID uint32) uint64
• type MemoryStats
• type RTMemoryStats
  • func RTMemoryStatsPointer(addr uintptr) *RTMemoryStats

Variables

var (
	// MinimumTotalMemoryBytes is the minimum reported total system memory.
	MinimumTotalMemoryBytes uint64 = 2 << 30 // 2 GB

	// MaximumTotalMemoryBytes is the maximum reported total system memory.
	// The 0 value indicates no maximum.
	MaximumTotalMemoryBytes uint64
)

These options control how much total memory the is reported to the application. They may only be set before the application starts executing, and must not be modified.

var RTMemoryStatsSize = unsafe.Sizeof(RTMemoryStats{})

RTMemoryStatsSize is the size of the RTMemoryStats struct.

Functions

func Init

func Init() error

Init initializes global 'MemoryAccounting'.

func TotalMemory

func TotalMemory(memSize, used uint64) uint64

TotalMemory returns the "total usable memory" available.

This number doesn't really have a true value so it's based on the following inputs and further bounded to be above the MinumumTotalMemoryBytes and below MaximumTotalMemoryBytes.

memSize should be the platform.Memory size reported by platform.Memory.TotalSize() used is the total memory reported by MemoryLocked.Total()

Types

type CPUStats

type CPUStats struct {
	// UserTime is the amount of time spent executing application code.
	UserTime time.Duration

	// SysTime is the amount of time spent executing sentry code.
	SysTime time.Duration

	// VoluntarySwitches is the number of times control has been voluntarily
	// ceded due to blocking, etc.
	VoluntarySwitches uint64
}

CPUStats contains the subset of struct rusage fields that relate to CPU scheduling.

+stateify savable

func (*CPUStats) Accumulate

func (s *CPUStats) Accumulate(s2 CPUStats)

Accumulate adds s2 to s.

func (*CPUStats) DifferenceSince

func (s *CPUStats) DifferenceSince(earlierSample CPUStats) CPUStats

DifferenceSince computes s - earlierSample.

Precondition: s >= earlierSample.

type IO

type IO struct {
	// CharsRead is the number of bytes read by read syscalls.
	CharsRead atomicbitops.Uint64

	// CharsWritten is the number of bytes written by write syscalls.
	CharsWritten atomicbitops.Uint64

	// ReadSyscalls is the number of read syscalls.
	ReadSyscalls atomicbitops.Uint64

	// WriteSyscalls is the number of write syscalls.
	WriteSyscalls atomicbitops.Uint64

	// BytesRead is the number of bytes actually read into pagecache.
	BytesRead atomicbitops.Uint64

	// BytesWritten is the number of bytes actually written from pagecache.
	BytesWritten atomicbitops.Uint64

	// BytesWriteCancelled is the number of bytes not written out due to
	// truncation.
	BytesWriteCancelled atomicbitops.Uint64
}

IO contains I/O-related statistics.

+stateify savable

func (*IO) AccountReadIO

func (i *IO) AccountReadIO(bytes int64)

AccountReadIO does the accounting for a read IO into the file system.

func (*IO) AccountReadSyscall

func (i *IO) AccountReadSyscall(bytes int64)

AccountReadSyscall does the accounting for a read syscall.

func (*IO) AccountWriteIO

func (i *IO) AccountWriteIO(bytes int64)

AccountWriteIO does the accounting for a write IO into the file system.

func (*IO) AccountWriteSyscall

func (i *IO) AccountWriteSyscall(bytes int64)

AccountWriteSyscall does the accounting for a write syscall.

func (*IO) Accumulate

func (i *IO) Accumulate(io *IO)

Accumulate adds up io usages.

func (*IO) Clone

func (i *IO) Clone(other *IO)

Clone turns other into a clone of i.

type MemoryKind

type MemoryKind int

MemoryKind represents a type of memory used by the application.

For efficiency reasons, it is assumed that the Memory implementation is responsible for specific stats (documented below), and those may be reported in aggregate independently. See the platform.Memory interface as well as the control.Usage.Collect method for more information.

const (
	// System represents miscellaneous system memory. This may include
	// memory that is in the process of being reclaimed, system caches,
	// page tables, swap, etc.
	//
	// This memory kind is backed by platform memory.
	System MemoryKind = iota

	// Anonymous represents anonymous application memory.
	//
	// This memory kind is backed by platform memory.
	Anonymous

	// PageCache represents memory allocated to back sandbox-visible files that
	// do not have a local fd. The contents of these files are buffered in
	// memory to support application mmaps.
	//
	// This memory kind is backed by platform memory.
	PageCache

	// Tmpfs represents memory used by the sandbox-visible tmpfs.
	//
	// This memory kind is backed by platform memory.
	Tmpfs

	// Ramdiskfs represents memory used by the ramdiskfs.
	//
	// This memory kind is backed by platform memory.
	Ramdiskfs

	// Mapped represents memory related to files which have a local fd on the
	// host, and thus can be directly mapped. Typically these are files backed
	// by gofers with donated-fd support. Note that this value may not track the
	// exact amount of memory used by mapping on the host, because we don't have
	// any visibility into the host kernel memory management. In particular,
	// once we map some part of a host file, the host kernel is free to
	// arbitrarily populate/decommit the pages, which it may do for various
	// reasons (ex. host memory reclaim, NUMA balancing).
	//
	// This memory kind is backed by the host pagecache, via host mmaps.
	Mapped
)

type MemoryLocked

type MemoryLocked struct {

	// RTMemoryStats records the memory stats that need to be exposed through
	// shared page.
	*RTMemoryStats
	// File is the backing file storing the memory stats.
	File *os.File
	// MemCgIDToMemStats is the map of cgroup ids to memory stats.
	MemCgIDToMemStats map[uint32]*memoryStats
	// contains filtered or unexported fields
}

MemoryLocked is Memory with access methods.

var MemoryAccounting *MemoryLocked

MemoryAccounting is the global memory stats.

There is no need to save or restore the global memory accounting object, because individual frame kinds are saved and charged only when they become resident.

func (*MemoryLocked) Copy

func (m *MemoryLocked) Copy() (MemoryStats, uint64)

Copy returns a copy of the structure with a total.

This method is thread-safe.

func (*MemoryLocked) CopyPerCg

func (m *MemoryLocked) CopyPerCg(memCgID uint32) (MemoryStats, uint64)

CopyPerCg returns a copy of the structure with a total for a cgroup.

This method is thread-safe.

func (*MemoryLocked) Dec

func (m *MemoryLocked) Dec(val uint64, kind MemoryKind, memCgID uint32)

Dec removes a usage of 'val' bytes from memory category 'kind' for a cgroup with id 'memCgID'. If 'memCgID' is zero, the memory is removed only from the total usage.

This method is thread-safe.

func (*MemoryLocked) Inc

func (m *MemoryLocked) Inc(val uint64, kind MemoryKind, memCgID uint32)

Inc adds an additional usage of 'val' bytes to memory category 'kind' for a cgroup with id 'memCgID'. If 'memCgID' is zero, the memory is accounted only for the total memory usage.

This method is thread-safe.

func (*MemoryLocked) Move

func (m *MemoryLocked) Move(val uint64, to MemoryKind, from MemoryKind, memCgID uint32)

Move moves a usage of 'val' bytes from 'from' to 'to' for a cgroup with id 'memCgID'.

This method is thread-safe.

func (*MemoryLocked) Total

func (m *MemoryLocked) Total() uint64

Total returns a total memory usage.

This method is thread-safe.

func (*MemoryLocked) TotalPerCg

func (m *MemoryLocked) TotalPerCg(memCgID uint32) uint64

TotalPerCg returns a total memory usage for a cgroup.

This method is thread-safe.

type MemoryStats

type MemoryStats struct {
	System    uint64
	Anonymous uint64
	PageCache uint64
	Tmpfs     uint64
	Mapped    uint64
	Ramdiskfs uint64
}

MemoryStats tracks application memory usage in bytes. All fields correspond to the memory category with the same name.

type RTMemoryStats

type RTMemoryStats struct {
	RTMapped atomicbitops.Uint64
}

RTMemoryStats contains the memory usage values that need to be directly exposed through a shared memory file for real-time access. These are categories not backed by platform memory. For details about how this works, see the memory accounting docs.

N.B. Please keep the struct in sync with the API. Notably, changes to this struct requires a version bump and addition of compatibility logic in the control server. As a special-case, adding fields without re-ordering existing ones do not require a version bump because the mapped page we use is initially zeroed. Any added field will be ignored by an older API and will be zero if read by a newer API.

func RTMemoryStatsPointer

func RTMemoryStatsPointer(addr uintptr) *RTMemoryStats

RTMemoryStatsPointer casts addr to a RTMemoryStats pointer.