302cbb9054
takes a host:port specification. - Update the manual page and add an example showing how log over the network using pmcstat(8) and nc(1). Document the current inability to process logs in cross-platform manner. - Have pmcstat_open_log() call err(3) directly in case of an error; this simplifies error handling in its caller. MFC after: 1 week
310 lines
8.6 KiB
Groff
310 lines
8.6 KiB
Groff
.\" Copyright (c) 2003-2006 Joseph Koshy. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" This software is provided by Joseph Koshy ``as is'' and
|
|
.\" any express or implied warranties, including, but not limited to, the
|
|
.\" implied warranties of merchantability and fitness for a particular purpose
|
|
.\" are disclaimed. in no event shall Joseph Koshy be liable
|
|
.\" for any direct, indirect, incidental, special, exemplary, or consequential
|
|
.\" damages (including, but not limited to, procurement of substitute goods
|
|
.\" or services; loss of use, data, or profits; or business interruption)
|
|
.\" however caused and on any theory of liability, whether in contract, strict
|
|
.\" liability, or tort (including negligence or otherwise) arising in any way
|
|
.\" out of the use of this software, even if advised of the possibility of
|
|
.\" such damage.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd April 2, 2006
|
|
.Os
|
|
.Dt PMCSTAT 8
|
|
.Sh NAME
|
|
.Nm pmcstat
|
|
.Nd "performance measurement with performance monitoring hardware"
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl C
|
|
.Op Fl D Ar pathname
|
|
.Op Fl E
|
|
.Op Fl M Ar mapfilename
|
|
.Op Fl O Ar logfilename
|
|
.Op Fl P Ar event-spec
|
|
.Op Fl R Ar logfilename
|
|
.Op Fl S Ar event-spec
|
|
.Op Fl W
|
|
.Op Fl c Ar cpu
|
|
.Op Fl d
|
|
.Op Fl g
|
|
.Op Fl k Ar kerneldir
|
|
.Op Fl n Ar rate
|
|
.Op Fl o Ar outputfile
|
|
.Op Fl p Ar event-spec
|
|
.Op Fl q
|
|
.Op Fl r Ar fsroot
|
|
.Op Fl s Ar event-spec
|
|
.Op Fl t Ar pid
|
|
.Op Fl v
|
|
.Op Fl w Ar secs
|
|
.Op Ar command Op Ar args
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility measures system performance using the facilities provided by
|
|
.Xr hwpmc 4 .
|
|
.Pp
|
|
The
|
|
.Nm
|
|
utility can measure both hardware events seen by the system as a
|
|
whole, and those seen when a specified process is executing on the
|
|
system's CPUs.
|
|
If a specific process is being targeted (for example,
|
|
if the
|
|
.Fl t Ar pid
|
|
option is specified, or if a command line is specified using
|
|
.Ar command ) ,
|
|
then measurement occurs till the target process exits or
|
|
the
|
|
.Nm
|
|
utility is interrupted by the user.
|
|
If a specific process is not targeted for measurement, then
|
|
.Nm
|
|
will perform system-wide measurements till interrupted by the
|
|
user.
|
|
.Pp
|
|
A given invocation of
|
|
.Nm
|
|
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
|
|
.Nm .
|
|
The output of sampling PMCs may be configured to go to a log file for
|
|
subsequent offline analysis, or, at the expense of greater
|
|
overhead, may be configured to be printed in text form on the fly.
|
|
.Pp
|
|
Hardware events to measure are specified to
|
|
.Nm
|
|
using event specifier strings
|
|
.Ar event-spec .
|
|
The syntax of these event specifiers is machine dependent and is
|
|
documented in
|
|
.Xr pmc 3 .
|
|
.Pp
|
|
A process-mode PMC may be configured to be inheritable by the target
|
|
process' current and future children.
|
|
.Sh OPTIONS
|
|
The following options are available:
|
|
.Bl -tag -width indent
|
|
.It Fl C
|
|
Toggle between showing cumulative or incremental counts for
|
|
subsequent counting mode PMCs specified on the command line.
|
|
The default is to show incremental counts.
|
|
.It Fl D Ar pathname
|
|
Create files with per-program samples in the directory named
|
|
by
|
|
.Ar pathname .
|
|
The default is to create these files in the current directory.
|
|
.It Fl 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 characteristics of a
|
|
complex pipeline of processes when used in conjunction with the
|
|
.Fl d
|
|
option.
|
|
The default is to not to enable per-process tracking.
|
|
.It Fl M Ar mapfilename
|
|
Write the mapping between executable objects encountered in the event
|
|
log and the abbreviated pathnames used for
|
|
.Xr gprof 1
|
|
profiles to file
|
|
.Ar mapfilename .
|
|
If this option is not specified, mapping information is not written.
|
|
Argument
|
|
.Ar mapfilename
|
|
may be a
|
|
.Dq Li -
|
|
in which case this mapping information is sent to the output
|
|
file configured by the
|
|
.Fl o
|
|
option.
|
|
.It Fl O Ar logfilename
|
|
Send logging output to file
|
|
.Ar logfilename .
|
|
If
|
|
.Ar logfilename
|
|
is of the form
|
|
.Ar hostname Ns : Ns Ar port ,
|
|
where
|
|
.Ar hostname
|
|
does not start with a
|
|
.Sq \&.
|
|
or a
|
|
.Sq / ,
|
|
then
|
|
.Nm
|
|
will open a network socket to host
|
|
.Ar hostname
|
|
on port
|
|
.Ar port .
|
|
.Pp
|
|
If the
|
|
.Fl O
|
|
option is not specified and one of the logging options is requested,
|
|
then
|
|
.Nm
|
|
will print a textual form of the logged events to the configured
|
|
output file.
|
|
.It Fl P Ar event-spec
|
|
Allocate a process mode sampling PMC measuring hardware events
|
|
specified in
|
|
.Ar event-spec .
|
|
.It Fl R Ar logfilename
|
|
Perform offline analysis using sampling data in file
|
|
.Ar logfilename .
|
|
.It Fl S Ar event-spec
|
|
Allocate a system mode sampling PMC measuring hardware events
|
|
specified in
|
|
.Ar event-spec .
|
|
.It Fl 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 behaviour of processes in the system.
|
|
It may incur substantial overhead if enabled.
|
|
The default is for this feature to be disabled.
|
|
.It Fl c Ar cpu
|
|
Set the cpu for subsequent system mode PMCs specified on the
|
|
command line to
|
|
.Ar cpu .
|
|
The default is to allocate system mode PMCs on CPU zero.
|
|
.It Fl 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.
|
|
.It Fl g
|
|
Produce flat execution profiles in a format compatible with
|
|
.Xr gprof 1 .
|
|
A separate profile file is generated for each executable object
|
|
encountered.
|
|
Profile files are placed in sub-directories named by their PMC
|
|
event name.
|
|
.It Fl k Ar kerneldir
|
|
Set the pathname of the kernel directory to argument
|
|
.Ar kerneldir .
|
|
This directory specifies where
|
|
.Nm
|
|
should look for the kernel and its modules.
|
|
The default is
|
|
.Pa /boot/kernel .
|
|
.It Fl n Ar 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.
|
|
.It Fl o Ar outputfile
|
|
Send counter readings and textual representations of logged data
|
|
to file
|
|
.Ar outputfile .
|
|
The default is to send output to
|
|
.Pa stderr .
|
|
.It Fl p Ar event-spec
|
|
Allocate a process mode counting PMC measuring hardware events
|
|
specified in
|
|
.Ar event-spec .
|
|
.It Fl q
|
|
Decrease verbosity.
|
|
.It Fl r Ar fsroot
|
|
Set the top of the filesystem hierarchy under which executables
|
|
are located to argument
|
|
.Ar fsroot .
|
|
The default is
|
|
.Pa / .
|
|
.It Fl s Ar event-spec
|
|
Allocate a system mode counting PMC measuring hardware events
|
|
specified in
|
|
.Ar event-spec .
|
|
.It Fl t Ar pid
|
|
Attach all process mode PMCs allocated to the process with PID
|
|
.Ar pid .
|
|
The option is not allowed in conjunction with specifying a
|
|
command using
|
|
.Ar command .
|
|
.It Fl v
|
|
Increase verbosity.
|
|
.It Fl w Ar secs
|
|
Print the values of all counting mode PMCs every
|
|
.Ar secs
|
|
seconds.
|
|
The argument
|
|
.Ar secs
|
|
may be a fractional value.
|
|
The default interval is 5 seconds.
|
|
.El
|
|
.Pp
|
|
If
|
|
.Ar command
|
|
is specified, it is executed using
|
|
.Xr execvp 3 .
|
|
.Sh EXAMPLES
|
|
To perform system-wide statistical sampling on an AMD Athlon CPU with
|
|
samples taken every 32768 instruction retirals and data being sampled
|
|
to file
|
|
.Pa sample.stat ,
|
|
use:
|
|
.Dl "pmcstat -O sample.stat -n 32768 -S k7-retired-instructions"
|
|
.Pp
|
|
To execute
|
|
.Nm mozilla
|
|
and measure the number of data cache misses suffered
|
|
by it and its children every 12 seconds on an AMD Athlon, use:
|
|
.Dl "pmcstat -d -w 12 -p k7-dc-misses mozilla"
|
|
.Pp
|
|
To perform system-wide sampling based on processor instructions
|
|
retired use:
|
|
.Dl "pmcstat -S instructions -O /tmp/sample.out"
|
|
.Pp
|
|
To send the generated event log to a remote machine use:
|
|
.Dl "pmcstat -S instructions -O remotehost:port"
|
|
On the remote machine, the sample log can be collected using
|
|
.Xr nc 1 :
|
|
.Dl "nc -l remotehost port > /tmp/sample.out"
|
|
.Pp
|
|
To generate
|
|
.Xr gprof 1
|
|
compatible flat profiles from a sample file use:
|
|
.Dl "pmcstat -R /tmp/sample.out -g"
|
|
.Sh DIAGNOSTICS
|
|
.Ex -std
|
|
.Sh SEE ALSO
|
|
.Xr gprof 1 ,
|
|
.Xr nc 1 ,
|
|
.Xr execvp 3 ,
|
|
.Xr pmc 3 ,
|
|
.Xr pmclog 3 ,
|
|
.Xr hwpmc 4 ,
|
|
.Xr pmccontrol 8 ,
|
|
.Xr sysctl 8
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
utility first appeared in
|
|
.Fx 6.0 .
|
|
It is
|
|
.Ud
|
|
.Sh AUTHORS
|
|
.An Joseph Koshy Aq jkoshy@FreeBSD.org
|
|
.Sh BUGS
|
|
.Nm
|
|
cannot yet analyse
|
|
.Xr hwpmc 4
|
|
logs generated by non-native architectures.
|