xrefcode.com / docs / cli / live-profile

$ xref live profile

On this page

Usage
Arguments and options
Examples
Record two seconds
Limits
Provenance

Sample where a running process spends its CPU time and save a bounded recording (.xprof) that the profile commands read: hot functions, blocks and instructions, with call chains unwound from .eh_frame (--callers dwarf, the default). Recording can be limited to a function (--within) or to windows opened by a uprobe trigger.

Usage

xref live profile [OPTIONS] --pid <PID>

Arguments and options

Options

--pid <PID>

Target process ID.

--duration <DURATION>

Capture duration, e.g. 10s or 200ms.

default 10s

--duration-ms <DURATION_MS>

Capture duration in milliseconds.

--freq <FREQ>

Requested samples per second per thread; defaults to 4000 [alias: --hz].

--period <PERIOD>

Hardware events per sample instead of a frequency.

--event <EVENT>

Hardware event that drives sampling [possible values: cycles, instructions, cache-misses, branch-misses].

default cycles

--tid <TIDS>

Sample only this thread ID (repeatable); all threads by default.

--callers <CALLERS>

How call chains are recorded: DWARF stack copies unwound with .eh_frame, LBR, frame pointers, or none [alias: --callgraph] [possible values: dwarf, lbr, fp, none].

default dwarf

--within <WITHIN>

Report only samples whose call chain includes this function or address (repeatable).

--trigger-probe <TRIGGER_PROBE>

Code address whose uprobe hits open recording windows; without it the whole duration is recorded.

--window <WINDOW>

Length of each trigger window, e.g. 200ms (the default).

--window-ms <WINDOW_MS>

Length of each trigger window in milliseconds.

--max-windows <MAX_WINDOWS>

Record up to this many separate post-trigger windows.

--trigger-fetch <TRIGGER_FETCH>

Named tracefs fetch, e.g. op=+40(%sp):u64, for trigger filtering.

--trigger-filter <TRIGGER_FILTER>

Numeric predicate over a named trigger fetch.

--json

Print the capture statistics and the report as JSON.

--folded <FOLDED>

Also write folded stacks (flame-graph input) to this new file.

--out <OUT>

Keep the .xprof recording at this new path; without it a temporary recording is deleted after the report.

--max-samples <MAX_SAMPLES>

Stop recording after this many samples.

default 10000000

--stack-bytes <STACK_BYTES>

User stack bytes copied with each sample for DWARF unwinding.

default 2048

--include-kernel

Include kernel-mode samples; requires suitable perf permissions.

Examples

The target is ripgrep 14.1.1 (rg) filtering an endless input stream, as on live maps. PIDs and runtime addresses belong to that run.

Record two seconds

Command

$ xref -b rg live profile --pid 4084848 --duration 2s --out rg.xprof

Output

capture: 2001 ms, observer thread CPU: 15 ms (excludes target and interrupt-context overhead)
7999 samples, 0 lost, 0 dropped; partial=true
target mapping: /srv/xref-docs/rg
  50.89% self   50.89% total       4071 [kernel]:unknown
  19.71% self   27.73% total       1577 target:fn_430060
  11.56% self   11.61% total        925 target:fn_10b0c0
   8.98% self    8.98% total        718 target:unknown
   3.55% self    3.55% total        284 target:fn_4752a0
   3.49% self    7.79% total        279 target:fn_4302b0
   0.75% self    0.75% total         60 target:fn_42f380
   0.31% self    0.31% total         25 target:fn_4307b0
   0.25% self    0.25% total         20 target:fn_406150
   0.10% self   27.80% total          8 target:fn_de140
   0.08% self   39.54% total          6 target:fn_fc020
   0.08% self    0.08% total          6 target:fn_4062e0
   0.05% self    0.05% total          4 target:fn_13af50
   0.04% self   27.84% total          3 target:fn_fb4b0
   0.04% self    0.04% total          3 target:fn_408bf0
   0.03% self   27.70% total          2 target:fn_138ef0
   0.01% self    0.28% total          1 target:fn_406fd0

Output cut here: lines 1–20 of 39 shown.

The summary printed after the capture is the same report as profile report. Samples are never attributed to the target when they fall outside it. A shared library whose file on disk is verified to be the one mapped in the process is symbolized as its own module; a library that cannot be verified (changed or missing file) or has no symbols, and kernel samples, stay unknown frames of their module, as [kernel]:unknown does here.

Limits

Needs perf access to the process: with kernel.perf_event_paranoid 1 (the setting of the recording host) a user may profile their own processes; kernel samples need --include-kernel and a setting that allows them.
--out does not overwrite an existing file.
Chains whose unwinding stops (missing CFI, code outside the binary) are counted in the warning: lines rather than guessed.

Provenance

Recorded with a development build of xref after 0.4.0 on Linux x86-64, on rg = ripgrep 14.1.1 (official stripped release). Live examples ran against one ripgrep process filtering an endless input stream; commands shown with sudo ran as root. Output is unchanged except that whitespace at the end of each line and empty lines at the end of the output are removed; long outputs are cut where marked.

Source: docs/cli/live-profile.md · generated for the site; edit the Markdown, not this page.