---
name: "pmcollectl"
section: "1"
platform: "linux"
package: "pcp"
version: "4.3.2+really4.3.1-0.1"
release: "Debian 10 (Buster)"
platforms: ["linux"]
url: "https://new.carta.tech/pcp-collectl"
---

# pmcollectl(1)

collect data that describes the current system status

Part of [pcp-collectl(1)](/pcp-collectl/1.md).

## NAME

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

## SYNOPSIS

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

## DESCRIPTION

**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)](/python/1.md) script providing much of the functionality available from the [**collectl**(1)](/collectl/1.md) Linux utility (which happens to be written in [**perl**(1)](/perl/1.md)).

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)](/pmlogger/1.md) utility (possibly indirectly, through use of the **-f** option to **pcp-collectl**).

## RECORD MODE OPTIONS

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 second.

- **-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 for.

## PLAYBACK MODE OPTIONS

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** utility.

- **-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)](/pmafm/1.md) 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

The following options are supported in both record and playback modes.

- **--help**

  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.

  - **SUMMARY SUBSYSTEMS**

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

  - **DETAIL SUBSYSTEMS**

    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

- **--verbose**

  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

[**PCPIntro**(1)](/PCPIntro/1.md), [**collectl**(1)](/collectl/1.md), [**collectl2pcp**(1)](/collectl2pcp/1.md), [**perl**(1)](/perl/1.md), [**python**(1)](/python/1.md), [**pmlogger**(1)](/pmlogger/1.md), [**pmcd**(1)](/pmcd/1.md), [**pmafm**(1)](/pmafm/1.md), [**pmprobe**(1)](/pmprobe/1.md), [**pmrep**(1)](/pmrep/1.md), [**PMAPI**(3)](/PMAPI/3.md), and [**pcp.conf**(5)](/pcp.conf/5.md).