tools/perf/Documentation/perf-record.txt

perf-record(1)
==============

NAME
----
perf-record - Run a command and record its profile into perf.data

SYNOPSIS
--------
[verse]
'perf record' [-e <EVENT> | --event=EVENT] [-l] [-a] <command>
'perf record' [-e <EVENT> | --event=EVENT] [-l] [-a] -- <command> [<options>]

DESCRIPTION
-----------
This command runs a command and gathers a performance counter profile
from it, into perf.data - without displaying anything.

This file can then be inspected later on, using 'perf report'.


OPTIONS
-------
<command>...::
	Any command you can specify in a shell.

-e::
--event=::
	Select the PMU event. Selection can be:

        - a symbolic event name	(use 'perf list' to list all events)

        - a raw PMU event (eventsel+umask) in the form of rNNN where NNN is a
	  hexadecimal event descriptor.

        - a hardware breakpoint event in the form of '\mem:addr[:access]'
          where addr is the address in memory you want to break in.
          Access is the memory access type (read, write, execute) it can
          be passed as follows: '\mem:addr[:[r][w][x]]'.
          If you want to profile read-write accesses in 0x1000, just set
          'mem:0x1000:rw'.

--filter=<filter>::
        Event filter.

-a::
--all-cpus::
        System-wide collection from all CPUs.

-l::
        Scale counter values.

-p::
--pid=::
	Record events on existing process ID.

-t::
--tid=::
        Record events on existing thread ID.

-r::
--realtime=::
	Collect data with this RT SCHED_FIFO priority.
-A::
--append::
	Append to the output file to do incremental profiling.

-f::
--force::
	Overwrite existing data file. (deprecated)

-c::
--count=::
	Event period to sample.

-o::
--output=::
	Output file name.

-i::
--no-inherit::
	Child tasks do not inherit counters.
-F::
--freq=::
	Profile at this frequency.

-m::
--mmap-pages=::
	Number of mmap data pages.

-g::
--call-graph::
	Do call-graph (stack chain/backtrace) recording.

-q::
--quiet::
	Don't print any message, useful for scripting.

-v::
--verbose::
	Be more verbose (show counter open errors, etc).

-s::
--stat::
	Per thread counts.

-d::
--data::
	Sample addresses.

-T::
--timestamp::
	Sample timestamps. Use it with 'perf report -D' to see the timestamps,
	for instance.

-n::
--no-samples::
	Don't sample.

-R::
--raw-samples::
Collect raw sample records from all opened counters (default for tracepoint counters).

-C::
--cpu::
Collect samples only on the list of CPUs provided. Multiple CPUs can be provided as a
comma-separated list with no space: 0,1. Ranges of CPUs are specified with -: 0-2.
In per-thread mode with inheritance mode on (default), samples are captured only when
the thread executes on the designated CPUs. Default is to monitor all CPUs.

-N::
--no-buildid-cache::
Do not update the builid cache. This saves some overhead in situations
where the information in the perf.data file (which includes buildids)
is sufficient.

SEE ALSO
--------
linkperf:perf-stat[1], linkperf:perf-list[1]