Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
PMCSTAT(8)		  BSD System Manager's Manual		    PMCSTAT(8)

     pmcstat --	performance measurement	with performance monitoring hardware

     pmcstat [-C] [-D pathname]	[-E] [-M mapfilename] [-O logfilename]
	     [-P event-spec] [-R logfilename] [-S event-spec] [-W]
	     [-c cpu-spec] [-d]	[-g] [-k kerneldir] [-n	rate] [-o outputfile]
	     [-p event-spec] [-q] [-r fsroot] [-s event-spec]
	     [-t process-spec] [-v] [-w	secs] [command [args]]

     The pmcstat utility measures system performance using the facilities pro-
     vided by hwpmc(4).

     The pmcstat utility can measure both hardware events seen by the system
     as	a whole, and those seen	when a specified set of	processes are execut-
     ing on the	system's CPUs.	If a specific set of processes is being	tar-
     geted (for	example, if the	-t process-spec	option is specified, or	if a
     command line is specified using command), then measurement	occurs till
     command exits, or till all	target processes specified by the -t
     process-spec options exit,	or till	the pmcstat utility is interrupted by
     the user.	If a specific set of processes is not targeted for measure-
     ment, then	pmcstat	will perform system-wide measurements till interrupted
     by	the user.

     A given invocation	of pmcstat can mix allocations of system-mode and
     process-mode PMCs,	of both	counting and sampling flavors.	The values of
     all counting PMCs are printed in human readable form at regular intervals
     by	pmcstat.  The output of	sampling PMCs may be configured	to go to a log
     file for subsequent offline analysis, or, at the expense of greater over-
     head, may be configured to	be printed in text form	on the fly.

     Hardware events to	measure	are specified to pmcstat using event specifier
     strings event-spec.  The syntax of	these event specifiers is machine de-
     pendent and is documented in pmc(3).

     A process-mode PMC	may be configured to be	inheritable by the target
     process' current and future children.

     The following options are available:

     -C	     Toggle between showing cumulative or incremental counts for sub-
	     sequent counting mode PMCs	specified on the command line.	The
	     default is	to show	incremental counts.

     -D	pathname
	     Create files with per-program samples in the directory named by
	     pathname.	The default is to create these files in	the current

     -E	     Toggle showing per-process	counts at the time a tracked process
	     exits for subsequent process-mode PMCs specified on the command
	     line.  This option	is useful for mapping the performance charac-
	     teristics of a complex pipeline of	processes when used in con-
	     junction with the -d option.  The default is to not to enable
	     per-process tracking.

     -M	mapfilename
	     Write the mapping between executable objects encountered in the
	     event log and the abbreviated pathnames used for gprof(1) pro-
	     files to file mapfilename.	 If this option	is not specified, map-
	     ping information is not written.  Argument	mapfilename may	be a
	     "-" in which case this mapping information	is sent	to the output
	     file configured by	the -o option.

     -O	logfilename
	     Send logging output to file logfilename.  If logfilename is of
	     the form hostname:port, where hostname does not start with	a `.'
	     or	a `/', then pmcstat will open a	network	socket to host
	     hostname on port port.

	     If	the -O option is not specified and one of the logging options
	     is	requested, then	pmcstat	will print a textual form of the
	     logged events to the configured output file.

     -P	event-spec
	     Allocate a	process	mode sampling PMC measuring hardware events
	     specified in event-spec.

     -R	logfilename
	     Perform offline analysis using sampling data in file logfilename.

     -S	event-spec
	     Allocate a	system mode sampling PMC measuring hardware events
	     specified in event-spec.

     -W	     Toggle logging the	incremental counts seen	by the threads of a
	     tracked process each time they are	scheduled on a CPU.  This is
	     an	experimental feature intended to help analyse the dynamic be-
	     haviour of	processes in the system.  It may incur substantial
	     overhead if enabled.  The default is for this feature to be dis-

     -c	cpu-spec
	     Set the cpus for subsequent system	mode PMCs specified on the
	     command line to cpu-spec.	Argument cpu-spec is a comma separated
	     list of CPU numbers, or the literal `*' denoting all CPUs.	 The
	     default is	to allocate system mode	PMCs on	all CPUs.

     -d	     Toggle between process mode PMCs measuring	events for the target
	     process' current and future children or only measuring events for
	     the target	process.  The default is to measure events for the
	     target process alone.

     -g	     Produce flat execution profiles in	a format compatible with
	     gprof(1).	A separate profile file	is generated for each exe-
	     cutable object encountered.  Profile files	are placed in sub-di-
	     rectories named by	their PMC event	name.

     -k	kerneldir
	     Set the pathname of the kernel directory to argument kerneldir.
	     This directory specifies where pmcstat should look	for the	kernel
	     and its modules.  The default is /boot/kernel.

     -n	rate
	     Set the default sampling rate for subsequent sampling mode	PMCs
	     specified on the command line.  The default is to configure PMCs
	     to	sample the CPU's instruction pointer every 65536 events.

     -o	outputfile
	     Send counter readings and textual representations of logged data
	     to	file outputfile.  The default is to send output	to stderr.

     -p	event-spec
	     Allocate a	process	mode counting PMC measuring hardware events
	     specified in event-spec.

     -q	     Decrease verbosity.

     -r	fsroot
	     Set the top of the	filesystem hierarchy under which executables
	     are located to argument fsroot.  The default is /.

     -s	event-spec
	     Allocate a	system mode counting PMC measuring hardware events
	     specified in event-spec.

     -t	process-spec
	     Attach process mode PMCs to the processes named by	argument
	     process-spec.  Argument process-spec may be a non-negative	inte-
	     ger denoting a specific process id, or a regular expression for
	     selecting processes based on their	command	names.

     -v	     Increase verbosity.

     -w	secs
	     Print the values of all counting mode PMCs	every secs seconds.
	     The argument secs may be a	fractional value.  The default inter-
	     val is 5 seconds.

     If	command	is specified, it is executed using execvp(3).

     To	perform	system-wide statistical	sampling on an AMD Athlon CPU with
     samples taken every 32768 instruction retirals and	data being sampled to
     file sample.stat, use:
	   pmcstat -O sample.stat -n 32768 -S k7-retired-instructions

     To	execute	mozilla	and measure the	number of data cache misses suffered
     by	it and its children every 12 seconds on	an AMD Athlon, use:
	   pmcstat -d -w 12 -p k7-dc-misses mozilla

     To	measure	processor instructions retired for all processes named "emacs"
	   pmcstat -t '^emacs$'	-p instructions

     To	count instruction tlb-misses on	CPUs 0 and 2 on	a Intel	Pentium
     Pro/Pentium III SMP system	use:
	   pmcstat -c 0,2 -s p6-itlb-miss

     To	perform	system-wide sampling on	all configured processors based	on
     processor instructions retired use:
	   pmcstat -S instructions -O /tmp/sample.out

     To	send the generated event log to	a remote machine use:
	   pmcstat -S instructions -O remotehost:port
     On	the remote machine, the	sample log can be collected using nc(1):
	   nc -l remotehost port > /tmp/sample.out

     To	generate gprof(1) compatible flat profiles from	a sample file use:
	   pmcstat -R /tmp/sample.out -g

     The pmcstat utility exits 0 on success, and >0 if an error	occurs.

     gprof(1), nc(1), execvp(3), pmc(3), pmclog(3), hwpmc(4), pmccontrol(8),

     The pmcstat utility first appeared	in FreeBSD 6.0.	 It is currently under

     Joseph Koshy <>

     The pmcstat utility cannot	yet analyse hwpmc(4) logs generated by non-na-
     tive architectures.

BSD				April 23, 2007				   BSD


Want to link to this manual page? Use this URL:

home | help