STRUCT ITRACE_SYNTH_OPTS(9)

💅 struct itrace_synth_opts(9) 💅

okay so bestie, welcome to the Kernel API Manual entry for struct itrace_synth_opts — literally the vibe-check config blob for AUX area tracing synthesis options. yes that's a mouthful, no i will not be shortening it, we respect the full name in this house 🫶

---

✨ NAME ✨

struct itrace_synth_opts — AUX area tracing synthesis options. that's it. that's the whole name section. iconic brevity 💅

---

🌈 SYNOPSIS 🌈

struct itrace_synth_opts {
    bool set;
    bool default_no_sample;
    bool inject;
    bool instructions;
    bool cycles;
    bool branches;
    bool transactions;
    bool ptwrites;
    bool pwr_events;
    bool other_events;
    bool intr_events;
    bool errors;
    bool dont_decode;
    bool log;
    bool calls;
    bool returns;
    bool callchain;
    bool add_callchain;
    bool thread_stack;
    bool last_branch;
    bool add_last_branch;
    bool approx_ipc;
    bool flc;
    bool llc;
    bool tlb;
    bool remote_access;
    bool mem;
    bool timeless_decoding;
    bool use_timestamp;
    bool vm_time_correlation;
    bool vm_tm_corr_dry_run;
    char *vm_tm_corr_args;
    unsigned int            callchain_sz;
    unsigned int            last_branch_sz;
    unsigned long long      period;
    enum itrace_period_type period_type;
    unsigned long           initial_skip;
    unsigned long           *cpu_bitmap;
    struct perf_time_interval *ptime_range;
    int range_num;
    unsigned int            error_plus_flags;
    unsigned int            error_minus_flags;
    unsigned int            log_plus_flags;
    unsigned int            log_minus_flags;
    unsigned int            quick;
    unsigned int            log_on_error_size;
 };

look at all those bools. it's giving "i contain multitudes" energy fr fr 🌸

---

🎀 Members 🎀

okay so here's the whole roster, in order, no skipping, we don't do that here:

• set — tells you whether or not the options have actually been set. the "did anyone actually flip a switch" flag, lowkey important.
• default_no_sample — default to no sampling. that's the whole thing. no sampling by default.
• inject — says the event (not just the sample!) has to be fully synthesized, because 'perf inject' is gonna write it out. full send, not partial ✨
• instructions — whether to synthesize 'instructions' events.
• cycles — whether to synthesize 'cycles' events. heads up bestie: these are not fully accurate, because CYC packets only get emitted together with other events, like branches. so like… approximation era 💀
• branches — whether to synthesize 'branches' events.
• transactions — whether to synthesize events for transactions.
• ptwrites — whether to synthesize events for ptwrites.
• pwr_events — whether to synthesize power events. ⚡
• other_events — whether to synthesize other events recorded due to the use of aux_output.
• intr_events — whether to synthesize interrupt events.
• errors — whether to synthesize decoder error events. yes we want to know about the errors, that's the point 🙈
• dont_decode — whether to skip decoding entirely. just… nope, not doing it.
• log — write a decoding log.
• calls — limit branch samples to calls (can be combined with returns 👀).
• callchain — add callchain to 'instructions' events.
• add_callchain — add callchain to existing event records.
• thread_stack — feed branches to the thread_stack.
• last_branch — add branch context to 'instruction' events.
• add_last_branch — add branch context to existing event records.
• approx_ipc — approximate IPC.
• flc — whether to synthesize first level cache events.
• llc — whether to synthesize last level cache events.
• tlb — whether to synthesize TLB events.
• remote_access — whether to synthesize remote access events.
• mem — whether to synthesize memory events.
• timeless_decoding — prefer "timeless" decoding, i.e. ignore timestamps. time is a construct anyway ⭐
• use_timestamp — use the timestamp trace as kernel time.
• vm_time_correlation — perform VM Time Correlation.
• vm_tm_corr_dry_run — VM Time Correlation dry-run. practice round, no commitment 💅
• vm_tm_corr_args — VM Time Correlation implementation-specific arguments.
• callchain_sz — maximum callchain size.
• last_branch_sz — branch context size.
• period — (the original page gives this one no description at all, so neither will i. mysterious. main character energy honestly 🕵️)
• period_type — (same deal, no description given. we love an unexplained field 👑)
• initial_skip — skip N events at the beginning.
• cpu_bitmap — CPUs for which to synthesize events, or NULL for all.
• ptime_range — time intervals to trace or NULL.
• range_num — number of time intervals to trace.
• error_plus_flags — flags to affect what errors are reported.
• error_minus_flags — flags to affect what errors are reported. (yes, same description as the one above — they're a plus/minus pair, it's a whole thing 🫶)
• log_plus_flags — flags to affect what is logged.
• log_minus_flags — flags to affect what is logged. (again, matching pair, we stan symmetry ✨)
• quick — quicker (less detailed) decoding. fast mode. zoom zoom 🔥
• log_on_error_size — size of log to keep for outputting log only on errors.

---

🦋 Return 🦋

this section is literally just one line and it's describing the returns member that's chillin' up in the struct but whose description lives down here instead, and honestly? quirky of it:

limit branch samples to returns (can be combined with calls).

---

💖 SEE ALSO 💖

Kernel file ./tools/perf/util/auxtrace.h — plus the whole friend group:

• struct auxtrace_index_entry(9)
• struct auxtrace_index(9)
• struct auxtrace(9)
• struct auxtrace_buffer(9)
• struct auxtrace_queue(9)
• struct auxtrace_queues(9)
• struct auxtrace_heap_item(9)
• struct auxtrace_heap(9)
• struct auxtrace_mmap(9)
• struct auxtrace_mmap_params(9)
• struct auxtrace_record(9)
• struct addr_filter(9)
• struct addr_filters(9)

---

ngl bestie, the flags that say "not fully accurate" and the ones describing what errors get reported are the ones to actually pay attention to — the rest is vibes and bools 💀

---

and that's the page!! sourced straight from ./tools/perf/util, dated October 2026, and it's struct itrace_synth_opts(9) signing off 🎀✨💜 periodt.