dis_cpu_usage

dis_cpu_usage - Report the CPU usage of a command and the driver stack

Hint

This page describes features that were added in DIS 5.28.0. Linux only.

Synopsis

dis_cpu_usage [options] -- <command> [args...]

dis_cpu_usage --check | --notes

Description

dis_cpu_usage runs <command> and, once it exits, prints how many CPU cores were used while it ran. See Measuring CPU usage for how to read the output and how to mark phases with cpubench.

Needs root, python3, bpftrace, a loaded dis_kosif and kernel 5.17 or later with BTF, see Measuring CPU usage. Measurement probes are active on the whole node while the command runs.

Options

--label <name>

Name of the key column in the table. Default Key.

--json <file>

Also write the results to <file> as JSON.

--probe <file>

Also look for cpubench markers in <file>. Needed for programs that build the cpubench source into themselves instead of linking /opt/DIS/lib64/libcpubench.so.1. Can be given more than once.

--selftest

Exit with status 125 if the interrupts dis_cpu_usage traced don’t match /proc/interrupts.

--no-notes

Don’t print the explanation above the table.

--no-check

Skip the start-up check. Use after a successful --check.

--check

Only check that everything needed is in place, then exit.

--notes

Only print the explanation of the columns, then exit.

Environment

dis_cpu_usage sets DIS_CPU_USAGE=1 for the command. cpubench_traced() checks it.

Exit status

The exit status of <command>. 125 if dis_cpu_usage itself failed, or --selftest found a mismatch.

Stop a measurement with Ctrl-C, which also reaches the command. A SIGTERM sent to dis_cpu_usage alone stops the command too, but not processes the command started, and no results are printed.

JSON output

{
  "command": "./my_program",
  "host": "node1",
  "label": "Size",
  "hz": 1000,
  "whole_run": {"seconds": 2.56, "process": 0.14, "irq": 0.02, "deferred": 0.01, "kthread": 0.84,
                "ns": {"run": 2560000000, "process": 358400000, "irq": 51200000,
                       "deferred": 25600000, "kthread": 2150400000}},
  "rows": [
    {"key": 4, "count": 1, "seconds": 0.0051, "sync_usr": 0.0, "sync_sys": 0.72,
     "irq": 0.12, "deferred": 0.04, "kthread": 1.0,
     "scope": "process", "short": true,
     "ns": {"row": 5100000, "usr": 0, "sys": 3672000, "irq": 612000,
            "deferred": 204000, "kthread": 5100000}}
  ],
  "kthreads": {"dis_poll": 0.84},
  "kthreads_ns": {"dis_poll": 2150400000},
  "irq_check": [{"name": "dis-px-p2p0", "proc_interrupts": 18284, "traced": 18267, "ok": true}]
}

All usage values are in cores, rounded to two decimals. The ns objects and kthreads_ns hold the same times unrounded, in nanoseconds. null means the value isn’t available. hz is null when the kernel’s tick rate can’t be read.