STATS-COLLECT-START(1)

📦 version 1.0.59, in fedora 43

✨ NAME ✨

start — the stats-collect command that runs your command while collecting statistics 💅

🌸 SYNOPSIS 🌸

usage: stats-collect start [-h] [-q] [-d] [-H HOSTNAME] [-U USERNAME]
       [-K PRIVKEY] [-T TIMEOUT] [--time-limit LIMIT] [-o OUTDIR] [--reportid
       REPORTID] [--stats STATS] [--stats-intervals STATS_INTERVALS]
       [--list-stats] [--report] COMMAND

💖 DESCRIPTION 💖

Okay so bestie, here's the tea ☕ — start runs a command and collects statistics while it does it. Two things, one command, we love a multitasking icon 👑

The COMMAND string can have placeholders in {} braces, and those get swapped out for the actual values. It's giving mad-libs but make it sysadmin 🔥

Here's every placeholder she supports:

  • {HOSTNAME}: the name of the host to run the command on.
  • {USERNAME}: the name of the user to use for logging into the remote host over SSH.
  • {PRIVKEY}: path to the private SSH key that should be used for logging into the remote host. Defaults to none.
  • {TIMEOUT}: SSH connect timeout in seconds.
  • {CPUS}: the list of CPUs to measure. Defaults to none.
  • {OUTDIR}: the output directory where the result will be stored.
  • {REPORTID}: the Report ID of the result.
  • {STATS}: comma-separated list of statistics names that will be collected.

🎀 GENERAL OPTIONS 🎀

💫 the basics

  • -h — show this help message and dip. Bye 👋
  • -q — be quiet. Shhh 🤫
  • -d — print debugging information. For when you need the whole lore 🕵️

🌈 host & connection stuff

  • -H HOSTNAME, --host HOSTNAME — name of the host to run the command on.
  • -U USERNAME, --username USERNAME — name of the user to use for logging into the remote host over SSH. The default user name is root.
  • -K PRIVKEY, --priv-key PRIVKEY — path to the private SSH key that should be used for logging into the remote host. By default the key is automatically found from standard paths like ~/.ssh.
  • -T TIMEOUT, --timeout TIMEOUT — SSH connect timeout in seconds, default is 8.

⏳ timing & output

  • --time-limit LIMIT — the time limit for statistics collection, after which the collection will stop if the command cmd (given as a positional argument) has not finished executing. Like a little countdown bestie, no cap ⏰
  • -o OUTDIR, --outdir OUTDIR — okay so the manpage literally says nothing else here 🙈 that's the whole entry. Take it up with the authors 💀
  • --reportid REPORTID — any string which may serve as an identifier of this run. By default report ID is the current date, prefixed with the remote host name in case the -H option was used: [hostname-]YYYYMMDD. For example, "20150323" is a report ID for a run made on March 23, 2015. The allowed characters are: ACSII alphanumeric, -, ., ,, _, and ~. (Yes, "ACSII" — that's how it's written in the source, I'm just the messenger 🫶)

📊 stats stuff (the main character section)

  • --stats STATS — comma-separated list of statistics to collect. They are stored in the the stats sub-directory of the output directory. By default, only turbostat, sysinfo statistics are collected. Use all to collect all possible statistics. Use --stats="" or --stats="none" to disable statistics collection. If you know exactly what statistics you need, specify the comma-separated list of statistics to collect. For example, use turbostat,acpower if you need only turbostat and AC power meter statistics. You can also specify the statistics you do not want to be collected by pre-pending the ! symbol. For example, all,!turbostat would mean: collect all the statistics supported by the SUT, except for
and that's literally where the original sentence stops 💀 it just says "except for" and ends. Iconic, honestly. I'm not gonna finish a sentence the source didn't finish ✋
  • --stats-intervals STATS_INTERVALS — the intervals for statistics. Statistics collection is based on doing periodic snapshots of data. For example, by default the acpower statistics collector reads SUT power consumption for the last second every second, and turbostat default interval is 5 seconds. Use acpower:5,turbostat:10 to increase the intervals to 5 and 10 seconds correspondingly. Use the --list-stats to get the default interval values.
  • --list-stats — print information about the statistics stats-collect can collect and exit. A little menu of everything she's got 💅
  • --report — generate an HTML report for collected results (same as calling report command with default arguments). Slay, you get a whole report card 🎀

🦋 local runs & pipes

  • --cmd-local — run the command on the local host instead of the SUT (HOSTNAME). This is useful for client/server workloads where the SUT runs the server and the local host runs the client. Main character energy, but on your own machine 💅
  • -P PIPE_PATH, --pipe-path PIPE_PATH* — path to the named pipe where the executed command is going to write the lables to. The named pipe is created on the SUT (HOSTNAME). The labels are used for the X-axix in the HTML reports. Use the special keyword "auto" to instruct stats-collect to automatically create a named pipe in the temporary directory (use the {PIPE_PATH} placeholder in workload's command line to get the path in this case). No named pipe is created by default.
  • --pipe-timeout PIPE_TIMEOUT — the longest allowed time interval between named pipe input lines. The stats-collect tool exits with an error if the interval exceeds PIPE_TIMEOUT. The default timeout is 5 minutes. Specify time value in minutes, or use one of the following specifiers: d - days, h - hours, m - minutes, s - seconds. For example, --pipe-timeout=1m 20s would mean mean 1 minute and 20 seconds. (Two "mean"s, bestie — I don't make the rules, I just keep every detail fr fr 😭)
⚠️ heads up: PIPE_TIMEOUT getting blown means stats-collect bails with an error. Not a vibe. Keep those pipe lines flowing ✨

and that's the whole page, bestie 💖 go collect those stats and be iconic 👑

🌸 this one's straight from the START() manual, dated 25-03-2024 — mwah, sending it to you with love 🫶🎀
📦 where this page comes from