JITTERDEBUGGER(1)

JITTERDEBUGGER(1) 💅

okay bestie, buckle up, we're doing section 1 of the General Commands Manual today and it's jitterdebugger — the tool that measures wake up latencies. yes it's giving "why is my box stuttering" energy, and yes we're obsessed. 🦋

✨ NAME ✨

jitterdebugger — measures wake up latencies. that's it, that's the whole name section, she's concise. 💖

✨ SYNOPSIS ✨

jitterdebugger [OPTIONS]

✨ DESCRIPTION ✨

so here's the vibe: jitterdebugger measures wake up latencies. what it actually does is start a thread on every single CPU, and each one programs a timer and then measures the time it takes from the timer expiring until the thread that set the timer runs again. it's literally a stopwatch but for the scheduler. ⏱️✨

and like, good news: jitterdebugger's default settings will produce a correct measurement. no cap. you can just run it and trust the numbers. 🫶

the program runs until it gets a CTRL-C or a SIGTERM. then the results get printed to STDOUT as a JSON encoded string. slay. 💅

✨ OPTIONS ✨

• -h, --help — shows the help text and dips. classic. 👋
• -v, --verbose — shows live updates of the measurements. main character mode, you get to watch the numbers move. 👀
• -f, --file=FILE — writes the results into the FILE. take it to go. 🎀
• -c, --command=CMD — starts a workload CMD in the background, e.g. -c "while true; do; hackbench; done". and because CMD is executed in a full shell, VARIABLE expansion works as well — so yes, your env vars will pop off. and when jitterdebugger terminates itself (because of a break value or loops), the background workload gets terminated too. no orphan processes left hanging, we love a clean exit. ✨
• -N SERVER:PORT — sends samples to SERVER:PORT as UDP packets. see also jittersamples --listen. it's giving long distance relationship but make it telemetry. 📡
• -t, --timeout=N — runs measurements for N seconds. and N is allowed to be postfixed with d (days), h (hours), m (minutes) or s (seconds). so -t 2h is a whole vibe. 🌸
• -l, --loops=N — runs measurements N times and then terminates jitterdebugger. a fixed number of rounds, then bedtime. 😴
• -b, --break=N — runs jitterdebugger until the N or greater latency has been observed. and bestie it does more than just stop: it will also stop a running tracer by writing 0 to tracing/tracing_on. furthermore, the value observed will be written to the trace buffers tracing/trace_marker, e.g. "Hit latency 249". iconic forensic behaviour. 🔥
• -i, --interval=N — sets the sleep time between each measuring. the default value is 1000us. 💤
• -o, --output=DIR — writes all samples measured into directory DIR. the file is called samples.raw, it's binary encoded, and it can be decoded using jittersamples. additional meta data is stored into DIR too. ✨
• -a, --affinity=CPUSET — sets the CPU affinity mask. jitterdebugger starts measuring threads only on CPUSET, e.g. 0,2,5-7 starts a thread on the first, third and 5, 6 and 7 CPU. may also be set in hexadecimal with a 0x prefix. pick your faves. 🎯
• -p, --priority=PRI — sets the priority of the measuring threads. the default value is 98. > ⚠️ note: priority 99 is not available because 99 should only be used for kernel housekeeping tasks. don't touch it, it's not yours. 💀

✨ EXAMPLES ✨

here's the moment you've been waiting for, the demo. 🍓

# jitterdebugger  -v
affinity: 0,1 = 2 [0x3]
T: 0 (  614) A: 0 C:     13476 Min:         3 Avg:    3.08 Max:        10
T: 1 (  615) A: 1 C:     13513 Min:         3 Avg:    3.10 Max:        20
^C
{
  "cpu": {
    "0": {
      "histogram": {
        "3": 4070,
        "4": 269,
        "5": 26,
        "6": 5,
        "7": 1,
        "8": 1,
        "9": 2,
        "10": 1
      },
      "count": 4375,
      "min": 3,
      "max": 10,
      "avg": 3.08
    },
    "1": {
      "histogram": {
        "3": 4002,
        "4": 320,
        "5": 22,
        "6": 4,
        "7": 2,
        "8": 1,
        "10": 2,
        "11": 1,
        "16": 2,
        "20": 1
      },
      "count": 4357,
      "min": 3,
      "max": 20,
      "avg": 3.10
    }
  }
}

see how it prints live with -v, you hit ^C, and then it dumps the whole JSON at you? that's the whole arc. beautiful. 😭👑

✨ SEE ALSO ✨

jittersamples(1) jitterplot(1) — the rest of the friend group. go say hi. 🫶

okay and for the lil sign-off: this page lives in the General Commands Manual (that's section 1, iykyk), and the footer just says JITTERDEBUGGER(1) right back at you — so there's no date or version to spill, just the name, twice, because she's consistent. periodt. 💖✨🌈