CLI Sensor Language

The cms_perf executable supports configuring each load sensor via the CLI. This allows to parse mathematical expressions including the actual system sensors to calculate the final reading.

# allow 10x load per core than usual
cms_perf --runq=100.0*loadq/10/ncores

Load Sensors

The cms_perf provides five sensor readings as percentages, which can be customized individually. By default, they express the canonical cms.perf readings:

--prunq

Expression to compute system load percentage [default: prunq]

--pcpu

Expression to compute cpu utilization percentage [default: pcpu]

--pmem

Expression to compute memory utilization percentage [default: pmem]

--ppag

Expression to compute paging load percentage [default: 0]

--pio

Expression to compute network utilization percentage [default: pio]

Each canonical sensor reading is available in sensor expressions with its canonical name. For example, prunq always refers to the default definition of --prunq.

Sensor Expressions

Each sensor can be reconfigured by supplying an expression to compute it. Expressions use a simple language, which consists of

  • float operators *, /, +, - and parentheses,

  • function calls with and without arguments, and

  • constants such as numbers and enums.

Constant Literals

Number literals are decimals, with optional sign and fractional part. For example, this includes 12, -1.2, and 12..

Enum literals are plain names, and only allowed in functions that expect them. For example, ncores allows ncores(all) and ncores(physical), but not ncores(inet6) nor ncores("all").

Functions Calls

Various functions are built-in for use in sensor expressions. Some of these are actual system sensors, collecting data from the system, others are helpers to transform data, such as taking the maximum of several data points. There are two ways to use functions in expressions: using just the bare name to invoke default arguments, or using the name followed by parenthesised arguments.

# allow 10x load per all cores than usual
cms_perf --runq=100.0*loadq/10/ncores

Available Functions

A range of functions are provided by cms_perf. Note that some functions provide or operate on percentages (e.g. pmem, prelu) while others provide or operate on absolute values (e.g. nsockets). These are indicated by the name prefix p or n, respectively.

System Sensors

These functions query information of the overall sytem. They are suitable for efficiently getting information on the overall load of the system on which XRootD runs.

loadq

Deprecated alias of nloadq

ncores or ncores(kind)

Number of CPU cores, by default including logical cores as well

kind selects which cores to count, and may be one of all or physical. It defaults to all.

nloadq

Absolute system load, the number of active processes

nsockets or nsockets(kind)

Number of open sockets across all processes

kind selects which sockets to count, and may be one of inet, inet4, inet6, tcp, tcp4, tcp6, udp, udp4, udp6, unix or all. It defaults to tcp.

pcpu

Percentage of cpu utilisation

pio

Percentage of network I/O utilisation

pmem

Percentage of memory utilisation

prunq

Percentage of system load per core, equivalent to 100*nloadq/ncores

pswap

Percentage of swap utilisation

XRootD Sensors

These functions inspect local XRootD processes. They are less efficient than the system-wide sensors but provide a view on the actual work performed by XRootD.

xrd.nfds

Number of file descriptors by all XRootD processes

xrd.nthreads

Number of threads by all XRootD processes

xrd.piowait

Percentage of time waiting for IO by all XRootD processes

Transformations

These functions transform absolute and percentage values. Transformations can be combined and stacked, but they fundamentally require sensors or constants as input.

erf(value)

The error function mapping -inf..inf to -1..1. See math.erf()

This maps 0 to 0 and increases with diminishing return as value increases. Useful to map an unbounded counter (such as nsockets) to the bounded range 0..1.

max(a, b, others...)

The maximum value of all arguments

min(a, b, others...)

The minimum value of all arguments

prelu(pct, bias)

Truncate pct below bias to 0 and normalize the result

This effectively remaps the percentages range bias..100 to 0..100. Useful to ignore low load situations in which differences are incosequential.

psigmoid(value)

A sigmoid boosting changes around 50 but compressing low/high values

Applying sigmoid to the range 0..100 compresses the low and high ranges (0..25 and 75..100) but expands the medium range (25..75). For load balancing, this means load around 50 is preferred and the most sensitive to differences.

relu(value, bias)

Reduce value by bias and truncate below 0, as max(value-bias, 0)