rdt

package
v0.8.0 Latest Latest
Warning

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

 Go to latest Published: Sep 19, 2024 License: Apache-2.0 Imports: 19 Imported by: 9

Documentation

Overview

Package rdt implements an API for managing Intel® RDT technologies via the resctrl pseudo-filesystem of the Linux kernel. It provides flexible configuration with a hierarchical approach for easy management of exclusive cache allocations.

Goresctrl supports all available RDT technologies, i.e. L2 and L3 Cache Allocation (CAT) with Code and Data Prioritization (CDP) and Memory Bandwidth Allocation (MBA) plus Cache Monitoring (CMT) and Memory Bandwidth Monitoring (MBM).

Basic usage example: 

rdt.SetLogger(logrus.New())

if err := rdt.Initialize(""); err != nil {
	return fmt.Errorf("RDT not supported: %v", err)
}

if err := rdt.SetConfigFromFile("/path/to/rdt.conf.yaml", false); err != nil {
	return fmt.Errorf("RDT configuration failed: %v", err)
}

if cls, ok := rdt.GetClass("my-class"); ok {
   //  Set PIDs 12345 and 12346 to class "my-class"
	if err := cls.AddPids("12345", "12346"); err != nil {
		return fmt.Errorf("failed to add PIDs to RDT class: %v", err)
	}
}

Index

Constants

View Source 
const (
	L2 cacheLevel = "L2"
	L3 cacheLevel = "L3"
)
View Source 
const (
	// RdtContainerAnnotation is the CRI level container annotation for setting
	// the RDT class (CLOS) of a container
	RdtContainerAnnotation = "io.kubernetes.cri.rdt-class"

	// RdtPodAnnotation is a Pod annotation for setting the RDT class (CLOS) of
	// all containers of the pod
	RdtPodAnnotation = "rdt.resources.beta.kubernetes.io/pod"

	// RdtPodAnnotationContainerPrefix is prefix for per-container Pod annotation
	// for setting the RDT class (CLOS) of one container of the pod
	RdtPodAnnotationContainerPrefix = "rdt.resources.beta.kubernetes.io/container."
)
View Source 
const (
	// RootClassName is the name we use in our config for the special class
	// that configures the "root" resctrl group of the system
	RootClassName = "system/default"
	// RootClassAlias is an alternative name for the root class
	RootClassAlias = ""
)
View Source 
const CacheIdAll = "all"

CacheIdAll is a special cache id used to denote a default, used as a fallback for all cache ids that are not explicitly specified.

Variables

This section is empty.

Functions

func ContainerClassFromAnnotations 

func ContainerClassFromAnnotations(containerName string, containerAnnotations, podAnnotations map[string]string) (string, error)

ContainerClassFromAnnotations determines the effective RDT class of a container from the Pod annotations and CRI level container annotations of a container. Verifies that the class exists in goresctrl configuration and that it is allowed to be used.

func DiscoverClasses 

func DiscoverClasses(resctrlGroupPrefix string) error

DiscoverClasses discovers existing classes from the resctrl filesystem. Makes it possible to discover gropus with another prefix than was set with Initialize(). The original prefix is still used for monitoring groups.

func GetMonFeatures 

func GetMonFeatures() map[MonResource][]string

GetMonFeatures returns the available monitoring stats of each available monitoring technology.

func Initialize 

func Initialize(resctrlGroupPrefix string) error

Initialize detects RDT from the system and initializes control interface of the package.

func IsQualifiedClassName 

func IsQualifiedClassName(name string) bool

IsQualifiedClassName returns true if given string qualifies as a class name

func MonSupported 

func MonSupported() bool

MonSupported returns true if RDT monitoring features are available.

func NewCollector 

func NewCollector() (prometheus.Collector, error)

NewCollector creates new Prometheus collector of RDT metrics

func RegisterCustomPrometheusLabels 

func RegisterCustomPrometheusLabels(names ...string)

RegisterCustomPrometheusLabels registers monitor group annotations to be exported as Prometheus metrics labels

func SetConfig 

func SetConfig(c *Config, force bool) error

SetConfig (re-)configures the resctrl filesystem according to the specified configuration.

func SetConfigFromData 

func SetConfigFromData(data []byte, force bool) error

SetConfigFromData takes configuration as raw data, parses it and reconfigures the resctrl filesystem.

func SetConfigFromFile 

func SetConfigFromFile(path string, force bool) error

SetConfigFromFile reads configuration from the filesystem and reconfigures the resctrl filesystem.

func SetLogger 

func SetLogger(l grclog.Logger)

SetLogger sets the logger instance to be used by the package. This function may be called even before Initialize().

Types

type CacheIdCatConfig 

type CacheIdCatConfig struct {
	Unified CacheProportion
	Code    CacheProportion
	Data    CacheProportion
}

CacheIdCatConfig is the cache allocation configuration for one cache id. Code and Data represent an optional configuration for separate code and data paths and only have effect when RDT CDP (Code and Data Prioritization) is enabled in the system. Code and Data go in tandem so that both or neither must be specified - only specifying the other is considered a configuration error.

func (*CacheIdCatConfig) UnmarshalJSON 

func (c *CacheIdCatConfig) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the Unmarshaler interface of "encoding/json"

type CacheIdMbaConfig 

type CacheIdMbaConfig []MbProportion

CacheIdMbaConfig is the memory bandwidth configuration for one cache id. It's an array of at most two values, specifying separate values to be used for percentage based and MBps based memory bandwidth allocation. For example, `{"80%", "1000MBps"}` would allocate 80% if percentage based allocation is used by the Linux kernel, or 1000 MBps in case MBps based allocation is in use.

type CacheProportion 

type CacheProportion string

CacheProportion specifies a share of the available cache lines. Supported formats:

- percentage, e.g. `50%` - percentage range, e.g. `50-60%` - bit numbers, e.g. `0-5`, `2,3`, must contain one contiguous block of bits set - hex bitmask, e.g. `0xff0`, must contain one contiguous block of bits set

type CatConfig 

type CatConfig map[string]CacheIdCatConfig

CatConfig contains the L2 or L3 cache allocation configuration for one partition or class.

func (*CatConfig) UnmarshalJSON 

func (c *CatConfig) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the Unmarshaler interface of "encoding/json"

type CatOptions 

type CatOptions struct {
	Optional bool
}

CatOptions contains the common settings for cache allocation.

type Config 

type Config struct {
	Options    Options `json:"options"`
	Partitions map[string]struct {
		L2Allocation CatConfig `json:"l2Allocation"`
		L3Allocation CatConfig `json:"l3Allocation"`
		MBAllocation MbaConfig `json:"mbAllocation"`
		Classes      map[string]struct {
			L2Allocation CatConfig         `json:"l2Allocation"`
			L3Allocation CatConfig         `json:"l3Allocation"`
			MBAllocation MbaConfig         `json:"mbAllocation"`
			Kubernetes   KubernetesOptions `json:"kubernetes"`
		} `json:"classes"`
	} `json:"partitions"`
}

Config is the user-specified RDT configuration.

type CtrlGroup 

type CtrlGroup interface {
	ResctrlGroup

	// CreateMonGroup creates a new monitoring group under this CtrlGroup.
	CreateMonGroup(name string, annotations map[string]string) (MonGroup, error)

	// DeleteMonGroup deletes a monitoring group from this CtrlGroup.
	DeleteMonGroup(name string) error

	// DeleteMonGroups deletes all monitoring groups from this CtrlGroup.
	DeleteMonGroups() error

	// GetMonGroup returns a specific monitoring group under this CtrlGroup.
	GetMonGroup(name string) (MonGroup, bool)

	// GetMonGroups returns all monitoring groups under this CtrlGroup.
	GetMonGroups() []MonGroup
}

CtrlGroup defines the interface of one goresctrl managed RDT class. It maps to one CTRL group directory in the goresctrl pseudo-filesystem.

func GetClass 

func GetClass(name string) (CtrlGroup, bool)

GetClass returns one RDT class.

func GetClasses 

func GetClasses() []CtrlGroup

GetClasses returns all available RDT classes.

type KubernetesOptions 

type KubernetesOptions struct {
	DenyPodAnnotation       bool `json:"denyPodAnnotation"`
	DenyContainerAnnotation bool `json:"denyContainerAnnotation"`
}

KubernetesOptions contains per-class settings for the Kubernetes-related functionality.

type MbOptions 

type MbOptions struct {
	Optional bool
}

MbOptions contains the common settings for memory bandwidth allocation.

type MbProportion 

type MbProportion string

MbProportion specifies a share of available memory bandwidth. It's an integer value followed by a unit. Two units are supported:

- percentage, e.g. `80%` - MBps, e.g. `1000MBps`

type MbaConfig 

type MbaConfig map[string]CacheIdMbaConfig

MbaConfig contains the memory bandwidth configuration for one partition or class.

func (*MbaConfig) UnmarshalJSON 

func (c *MbaConfig) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the Unmarshaler interface of "encoding/json"

type MonData 

type MonData struct {
	L3 MonL3Data
}

MonData contains monitoring stats of one monitoring group.

type MonGroup 

type MonGroup interface {
	ResctrlGroup

	// Parent returns the CtrlGroup under which the monitoring group exists.
	Parent() CtrlGroup

	// GetAnnotations returns the annotations stored to the monitoring group.
	GetAnnotations() map[string]string
}

MonGroup represents the interface to a RDT monitoring group. It maps to one MON group in the goresctrl filesystem.

type MonL3Data 

type MonL3Data map[uint64]MonLeafData

MonL3Data contains L3 monitoring stats of one monitoring group.

type MonLeafData 

type MonLeafData map[string]uint64

MonLeafData represents the raw numerical stats from one RDT monitor data leaf.

type MonResource 

type MonResource string

MonResource is the type of RDT monitoring resource. 

const (
	// MonResourceL3 is the RDT L3 cache monitor resource.
	MonResourceL3 MonResource = "l3"
)

type Options 

type Options struct {
	L2 CatOptions `json:"l2"`
	L3 CatOptions `json:"l3"`
	MB MbOptions  `json:"mb"`
}

Options contains common settings.

type ResctrlGroup 

type ResctrlGroup interface {
	// Name returns the name of the group.
	Name() string

	// GetPids returns the process ids assigned to the group.
	GetPids() ([]string, error)

	// AddPids assigns the given process ids to the group.
	AddPids(pids ...string) error

	// GetMonData retrieves the monitoring data of the group.
	GetMonData() MonData
}

ResctrlGroup is the generic interface for resctrl CTRL and MON groups. It maps to one CTRL or MON group directory in the goresctrl pseudo-filesystem.

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.