PCP-COLLECTL(1)            General Commands Manual           PCP-COLLECTL(1)

NAME         top

       pmcollectl,  pcp-collectl  -  collect data that describes the current
       system status

SYNOPSIS         top

       pcp collectl [-f file | -p file ...]  [options ...]

DESCRIPTION         top

       pcp-collectl is a system-level performance monitoring utility that
       records or displays specific operating system data for one or more
       sets of subsystems.  Any of the subsystems (such as CPU, Disks,
       Memory or Sockets) can be included or excluded from data collection.
       Data can either be displayed immediately to a terminal, or stored in
       files for retrospective analysis.

       pcp-collectl is a python(1) script providing much of the
       functionality available from the collectl(1) Linux utility (which
       happens to be written in perl(1)).

       It makes use of the Performance Co-Pilot (PCP) toolkit to simplify
       its implementation, as well as provide more of the collectl
       functionality on platforms other than Linux.

       pcp-collectl has two primary modes of operation:

       1. Record Mode (-f or --filename option) which reads data from a live
          system and writes output to a file or displays it on a terminal.

       2. Playback Mode (-p or -a option) which reads data from one or more
          PCP archive files and displays output on a terminal.  Note that
          these files are not raw collectl format data, rather they are
          archives created by the pmlogger(1) utility (possibly indirectly,
          through use of the -f option to pcp-collectl).


       In this mode data is taken from a live system and either displayed on
       the terminal or written to a PCP archive.

       -h host
              Display metrics from host instead of displaying metrics from
              the local host.

       -c, --count samples
              The number of samples to record.

       -f, --filename filename
              This is the name of a PCP archive to write the output to.

       -i, --interval interval
              This is the sampling interval in seconds.  The default is 1
       -R, --runtime duration
              Specify the duration of data collection where the duration is
              a number followed by one of wdhms, indicating how many weeks,
              days, hours, minutes or seconds the collection is to be taken


       In this mode, data is read from one or more PCP data files that were
       generated with the recording option, or indirectly via the pmlogger

       -f, --filename filename
              If specified, this is the name of a PCP archive to write the
              output to (rather than the terminal).

       -p, --playback filename
              Read data from the specified PCP archive folio files(s) -
              refer to pmafm(1) for archive folio details.

       -a, --archive filename
              Read data from the specified PCP raw archive files(s). The
              argument is a comma-separated list of names, each of which may
              be the base name of an archive or the name of a directory
              containing one or more archives.

COMMON OPTIONS         top

       The following options are supported in both record and playback

              Display standard help message.

       -s, --subsys subsystem
              This field controls which subsystem data is to be collected or
              played back for. The rules for displaying results vary
              depending on the type of data to be displayed.  If you write
              data for CPUs and DISKs to a raw file and play it back with
              -sc, you will only see CPU data.  If you play it back with
              -scm you will still only see CPU data since memory data was
              not collected.  To see the current set of default subsystems,
              which are a subset of this full list, use -h.

              The default is "cdn", which stands for CPU, Disk and Network
              summary data.


              c - CPU
              d - Disk
              f - NFS V3 Data
              j - Interrupts
              m - Memory
              n - Networks


              This is the set of detail data from which in most cases the
              corresponding summary data is derived.  So, if one has 3 disks
              and chooses -sd, one will only see a single total taken across
              all 3 disks.  If one chooses -sD, individual disk totals will
              be reported but no totals.

              C - CPU
              D - Disk
              F - NFS Data
              J - Interrupts
              M - Memory node data, which is also known as NUMA data
              N - Networks

              Display output in verbose mode.  This often displays more data
              than in the default mode.  When displaying detail data,
              verbose mode is forced.  Furthermore, if summary data for a
              single subsystem is to be displayed in verbose mode, the
              headers are only repeated occasionally whereas if multiple
              subsystems are involved each needs their own header.

SEE ALSO         top

       PCPIntro(1), collectl(1), collectl2pcp(1), perl(1), python(1),
       pmlogger(1), pmcd(1), pmafm(1), pmprobe(1), pmrep(1), PMAPI(3), and

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at ⟨⟩.
       If you have a bug report for this manual page, send it to  This page was obtained from the project's upstream
       Git repository ⟨⟩ on
       2019-07-28.  (At that time, the date of the most recent commit that
       was found in the repository was 2019-07-26.)  If you discover any
       rendering problems in this HTML version of the page, or you believe
       there is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to

Performance Co-Pilot                 PCP                     PCP-COLLECTL(1)

Pages that refer to this page: collectl2pcp(1)pmrep(1)