Usage
Running the Image
The container entrypointcontainer entrypointThe executable that a container image runs when a container starts, set by the ENTRYPOINT instruction of its Dockerfile. The image's default command (CMD), or the arguments given after the image name in docker run, are passed to it as arguments, so an entrypoint can wrap any command, for example to set up the environment or record resource usage first. The docker run --entrypoint option replaces it.Dockerfile referenceGlossary runs sh under resource-trackerresource-trackerAn open-source Spare Cores tool that runs a command and samples resource usage while it runs, such as CPU, memory, disk, network, GPU, and GPU memory use. It can optionally stream the samples to the Spare Cores Sentinel platform, so that a run can be checked to see its aggregated and detailed resource utilization, e.g., whether it used all CPU or GPU cores as intended while running a Navigator benchmark workload.resource-tracker on GitHubGlossary, and has no default
command. Pass the command to run with -c:
docker run --rm ghcr.io/sparecores/stress-ng:main \
-c 'python3 /usr/local/bin/run_stressng_benchmarks.py' > stress-ng.json
The stressor suite needs no environment variables. For a quick check, the following command runs the first five stressors for 2 seconds each:
docker run --rm -e STRESSNG_QUICK=1 -e STRESSNG_LIMIT=5 \
ghcr.io/sparecores/stress-ng:main \
-c 'python3 /usr/local/bin/run_stressng_benchmarks.py'
The image includes stress-ngstress-ngAn open-source tool that loads a computer in selectable ways, with hundreds of stress tests (stressors) that exercise the CPU, memory, file systems, and kernel interfaces. With --metrics, it reports each stressor's throughput in bogo ops/s.stress-ng on GitHubGlossary itself, so -c also accepts any stress-ng
command, such as -c 'stress-ng --cpu 1 -t 10 --metrics'.
Production Setup
The Navigator's Inspector runs this image in two production tasks, each with
--privileged and --network host, and with the command under
nice -n -20niceA Unix command that runs a program with a changed scheduling priority, from -20 (highest) to 19 (lowest). Raising a process's priority above the default needs the CAP_SYS_NICE capability, which root has.man pageGlossary. The nice -n -20 command needs --privileged; a plain run,
without nice, runs at normal priority. The image itself does not set a
priority.
The stressor suite runs as follows:
docker run --rm --privileged --network host ghcr.io/sparecores/stress-ng:main \
-c 'nice -n -20 python3 /usr/local/bin/run_stressng_benchmarks.py'
The CPUCPU: Central Processing UnitThe general-purpose processor of a computer, which runs the operating system and programs. A CPU has one or more physical cores, and with SMT each core runs two or more hardware threads.WikipediaGlossary scaling loop runs the cpu stressor at each worker count that
count.awk prints for the CPU count:
docker run --rm --privileged --network host ghcr.io/sparecores/stress-ng:main \
-c 'for ncpu in $(awk -f /usr/local/bin/count.awk $(nproc)); do echo -n "$ncpu,"; nice -n -20 stress-ng --metrics --cpu $ncpu --cpu-method div16 -t 10 | egrep "metrc.*cpu" | awk "{print \$9}"; done'
Both tasks run on every server type that the Inspector benchmarks.
Run Duration
The stressor suite took the following times in production:
- about 7 minutes at the shortest, on a server with 1 vCPUvCPU: virtual CPUA CPU of a virtual machine, the unit in which cloud vendors sell compute. It is usually one hardware thread of a physical core with SMT, so two vCPUs may share one physical core.WikipediaGlossary
- about 15 minutes at the median
- about 66 minutes at the longest
The CPU scaling loop took the following times in production with
stress-ng 0.20.01:
- about 19 seconds at the shortest
- about 2.8 minutes at the median
- about 50 minutes at the longest
Output
Stressor Suite
The stressor suite prints nothing while it runs: it captures the output of
each stress-ng run and prints one JSONJSON: JavaScript Object NotationA text format for structured data, built from objects (key-value pairs), arrays, strings, numbers, booleans, and null. Most languages and tools read and write it, which makes it a common format for API responses and benchmark output.JSONGlossary document to stdoutstdoutThe standard output stream of a process, one of the three standard streams with stdin and stderr. Programs write their results to it; a shell can redirect it to a file or another program, such as > results.jsonl, while logs on stderr still reach the terminal.WikipediaGlossary at the end,
indented with two spaces. It has the following fields:
| Field | Type | Meaning |
|---|---|---|
stressors.<name>."1" | object or null | Result with one worker |
stressors.<name>."<N>" | object or null | Result with N workers, where N is meta.physical_cpus; present only when N is greater than 1 |
stressors.<name>.<workers>.bogo_ops_per_sec | float | Throughput in stress-ng bogo ops/sstress-ng bogo ops/s: bogus operations per secondThe throughput metric of stress-ng: how many times a stressor completes its own unit of work per second. Each stressor defines that unit differently, so the values compare only within one stressor and one stress-ng version.stress-ng man pageGlossary (bogus operations per second), in real time, the total across all workers |
categories.<category> | list of strings | The stressors of each category that stress-ng --stressors lists, in category order |
meta.timeout_sec_per_stressor | integer | Seconds per stressor run: 5, or 2 with STRESSNG_QUICK=1; does not reflect the 15s of stream |
meta.physical_cpus | integer | Worker count of the multi-worker runs: the number of logical CPUs available to the container |
meta.stressor_count | integer | Number of stressors run, after STRESSNG_LIMIT |
The categories field is not shortened by STRESSNG_LIMIT, so it can list
stressors that did not run.
The following is an excerpt from a production run on a server with 2 vCPUs:
"atomic": {"1": {"bogo_ops_per_sec": 869.33}, "2": {"bogo_ops_per_sec": 868.79}}
The value is the bogo ops/s (real time) column of the stress-ng metrc linestress-ng metrc lineA line in which stress-ng --metrics prints a stressor's results when the run ends, tagged metrc: the bogo ops count, the real, user, and system time, and the bogo ops/s, among other columns.stress-ng man pageGlossary
that stress-ng --metrics-brief prints for each stress-ng stressorstress-ng stressorOne stress test of stress-ng, such as cpu, memcpy, or fork, selected with a command-line option of the same name and run by one or more worker processes.stress-ng man pageGlossary. See
data/hcloud/ccx13/0/stressng_benchmarks/stdout
for a full document.
The script exits with code 0 even when some stressors fail. If stress-ng
cannot list its stressors, it prints {"error": "could not get stressor list"}
to stderrstderrThe standard error stream of a process, one of the three standard streams with stdin and stdout. Programs write logs, progress, and error messages to it, so that they stay separate from the output on stdout when the output is redirected to a file or another program.WikipediaGlossary and exits with code 1.
CPU Scaling Loop
The CPU scaling loop prints one <workers>,<bogo ops/s> line per worker count,
for example:
1,3059.78
2,3062.79
See
data/hcloud/ccx13/0/stressngfull/stdout
for a production example.
Environment Variables
| Variable | Meaning | Default |
|---|---|---|
STRESSNG_QUICK | 1 runs each stressor for 2s instead of 5s; stream still runs for 15s. Any other value keeps 5s. | unset |
STRESSNG_LIMIT | Runs only the first N stressors in alphabetical order. A value that is not an integer is ignored. | unset (all stressors) |
TRACKER_QUIET | Set in the image to quiet resource-trackerresource-trackerAn open-source Spare Cores tool that runs a command and samples resource usage while it runs, such as CPU, memory, disk, network, GPU, and GPU memory use. It can optionally stream the samples to the Spare Cores Sentinel platform, so that a run can be checked to see its aggregated and detailed resource utilization, e.g., whether it used all CPU or GPU cores as intended while running a Navigator benchmark workload.resource-tracker on GitHubGlossary. | true |