xentrace(8)

📦
version 4.20.4+39-gf1e1321c87 · 21 versions
, in debian trixie

💅 xentrace(8) — the Xen trace buffer capture girlie

okay so bestie, this is the manual page for xentrace(8) from the Xen crew, and i'm gonna walk you through it like we're texting at 2am 🫶

✨ NAME ✨

xentrace — capture Xen trace buffer data. that's it, that's the whole vibe 💖

🌸 SYNOPSIS 🌸

xentrace [ OPTIONS ] [ FILE ]

🦋 DESCRIPTION 🦋

okay so xentrace is literally the tool you use to capture trace buffer data from Xen. and the data comes out in this binary format (host endian, no cap):

CPU(uint) TSC(u64) EVENT(u32) D1 D2 D3 D4 D5 (all u32)

where:

  • CPU is the processor number
  • TSC is the record's timestamp (aka the value of the CPU cycle counter) ⏱️
  • EVENT is the event ID
  • D1...D5 are the trace data

so where does it all go? the data is dumped onto the standard output — and heads up, that must not be a TTY 🚫 — or onto a FILE you specify on the command line.

and like, the output should be parsed using the tool xenalyze, which can produce human-readable output in ASCII format. so xentrace is the raw-capture main character, xenalyze is the one who makes it make sense ✨

🎀 OPTIONS 🎀

  • -t l, --log-thresh=l — set the threshold number, l, of new records required to trigger a write of all new records to the output 📝
  • -s p, --poll-sleep=p — set the time, p, (in milliseconds) to sleep between polling the buffers for new data 😴
  • -c [c|CPU-LIST|all], --cpu-mask=[c|CPU-LIST|all] — pick which CPUs you're tracing, bestie. this can be: a hex value (of the form 0xNNNN...), or a set of cpu ranges as described below, or the string all. hex values are limited to 32 bits. if you don't specify it, the cpu-mask as set during bootup will be constructed. if you're using the CPU-LIST it expects decimal numbers, which may be specified as follows:
    • "0-3" — trace only on CPUs 0 through 3
    • "0,2,5-7" — trace only on CPUs 0, 2, and 5 through 7
    • "-3" — trace only on CPUs 0 through 3
    • "-3,7" — trace only on CPUs 0 through 3 and 7
    • "3-" — trace only on CPUs 3 up to maximum numbers of CPUs the host has

and if you use all it will use all of the CPUs the host has 💯

  • -e mask, --evt-mask=mask — set event capture mask. if you don't specify it, TRC_ALL will be used 👑
  • -?, --help — give a short usage message 🥺
  • -V, --version — print program version 🌈

💜 Event Classes (Masks) 💜

these are the event classes (masks) you can use to filter the events being gathered by xentrace, and honestly they're giving selector-menu energy:

  • 0x0001f000 — TRC_GEN
  • 0x0002f000 — TRC_SCHED
  • 0x0004f000 — TRC_DOM0OP
  • 0x0008f000 — TRC_HVM
  • 0x0010f000 — TRC_MEM
  • 0xfffff000 — TRC_ALL

🧚 Event Subclasses (More Masks) 🧚

and there's more filtering, because of course there is — these event subclasses (masks) can also be used to filter the events being gathered by xentrace:

  • 0x00081000 — TRC_HVM_ENTRYEXIT
  • 0x00082000 — TRC_HVM_HANDLER

🔥 Events 🔥

here's the full lineup of events xentrace collects from the trace buffer. literally iconic, i'm obsessed:

  • 0x0001f001 — TRC_LOST_RECORDS
  • 0x0002f001 — TRC_SCHED_DOM_ADD
  • 0x0002f002 — TRC_SCHED_DOM_REM
  • 0x0002f003 — TRC_SCHED_SLEEP
  • 0x0002f004 — TRC_SCHED_WAKE
  • 0x0002f005 — TRC_SCHED_YIELD
  • 0x0002f006 — TRC_SCHED_BLOCK
  • 0x0002f007 — TRC_SCHED_SHUTDOWN
  • 0x0002f008 — TRC_SCHED_CTL
  • 0x0002f009 — TRC_SCHED_ADJDOM
  • 0x0002f010 — TRC_SCHED_SWITCH
  • 0x0002f011 — TRC_SCHED_S_TIMER_FN
  • 0x0002f012 — TRC_SCHED_T_TIMER_FN
  • 0x0002f013 — TRC_SCHED_DOM_TIMER_FN
  • 0x0002f014 — TRC_SCHED_SWITCH_INFPREV
  • 0x0002f015 — TRC_SCHED_SWITCH_INFNEXT
  • 0x00081001 — TRC_HVM_VMENTRY
  • 0x00081002 — TRC_HVM_VMEXIT
  • 0x00082001 — TRC_HVM_PF_XEN
  • 0x00082002 — TRC_HVM_PF_INJECT
  • 0x00082003 — TRC_HVM_INJ_EXC
  • 0x00082004 — TRC_HVM_INJ_VIRQ
  • 0x00082005 — TRC_HVM_REINJ_VIRQ
  • 0x00082006 — TRC_HVM_IO_READ
  • 0x00082007 — TRC_HVM_IO_WRITE
  • 0x00082008 — TRC_HVM_CR_READ
  • 0x00082009 — TRC_HVM_CR_WRITE
  • 0x0008200A — TRC_HVM_DR_READ
  • 0x0008200B — TRC_HVM_DR_WRITE
  • 0x0008200C — TRC_HVM_MSR_READ
  • 0x0008200D — TRC_HVM_MSR_WRITE
  • 0x0008200E — TRC_HVM_CPUID
  • 0x0008200F — TRC_HVM_INTR
  • 0x00082010 — TRC_HVM_NMI
  • 0x00082011 — TRC_HVM_SMI
  • 0x00082012 — TRC_HVM_VMMCALL
  • 0x00082013 — TRC_HVM_HLT
  • 0x00082014 — TRC_HVM_INVLPG
  • 0x0010f001 — TRC_MEM_PAGE_GRANT_MAP
  • 0x0010f002 — TRC_MEM_PAGE_GRANT_UNMAP
  • 0x0010f003 — TRC_MEM_PAGE_GRANT_TRANSFER

🌺 AUTHOR 🌺

the one and only Mark A. Williamson <mark.a.williamson@intel.com> — ty for your service king 🫡💖

and that's the whole page bestie!! 💫 this version is from the Xen 4.20.5-pre era, dated 2026-10-16, and it's the xentrace(8) page through and through. now go capture some trace buffer data, you gorgeous nerd 🦋✨🎀

📦 where this page comes from