PCP-ATOPSAR(1)

📦
version 7.1.5 · 6 versions
, in centos-stream 10, fedora 43, fedora 44, ubuntu resolute

💅 pcp-atopsar — the manual page, but make it make sense

okay bestie, so this is PCP-ATOPSAR(1) from the General Commands Manual section, and it's literally the Advanced System Activity Report for the pcp-atop family. grab a beverage, we're getting into it 🍓

✨ NAME ✨

pcp-atopsar — Advanced System Activity Report (the pcp-atop related one, iykyk)

🦋 SYNOPSIS 🦋

pcp [pcp options] atopsar [atop options] [-r file|date] [-h host] [-R
cnt] [-b [YYYMMDD]hh:mm[ss]] [-e [YYYMMDD]hh:mm[ss]]
pcp [pcp options] atopsar [atop options] interval [samples]

two whole vibes, two whole synopsis lines. pick your fighter 💅

🌸 DESCRIPTION 🌸

The pcp-atopsar program? It reports statistics at the system level. That's the whole point. Periodt.

🎀 first synopsis line — the logfile era 🎀

no sampling interval specified, so we're going shopping in an archive file 💖

In the first synopsis line (no sampling interval specified), pcp-atopsar extracts data from a raw logfile that has been recorded previously by pmlogger(1) (or via the -w option of the pcp-atop program).

You can specify the name of the logfile with the -r option of the pcp-atopsar program. When a pmlogger daily logfile is used, named $PCP_LOG_DIR/pmlogger/[host]/YYYYMMDD (where YYYYMMDD reflects the date), the required date of the form YYYYMMDD can be specified with the -r option instead of the filename, or the symbolic name 'y' can be used for yesterday's daily logfile (this can be repeated so 'yyyy' indicates the logfile of four days ago). If the -r option is not specified at all, today's daily logfile is used by default.

By default, the hostname of the localhost will be used when resolving pmlogger archives, however an alternative host can be specified using the -h option.

The starting and ending times of the report can be defined using the options -b and -e followed by a time argument of the form [YYYYMMDD]hh:mm[ss].

🦋 second synopsis line — live from the kernel 🦋

sampling mode, main character energy ✨

In the second synopsis line, pcp-atopsar reads actual activity counters from the kernel with the specified interval (in seconds) and the specified number of samples (optionally).

When pcp-atopsar is activated in this way it immediately sends the output for every requested report to standard output. If only one type of report is requested, the header is printed once and after every interval seconds the statistical counters are shown for that period. If several reports are requested, a header is printed per sample followed by the statistical counters for that period.

💜 the pcp(1) pipeline glow-up 💜

When invoked via the pcp(1) command, the PCPIntro(1) options -h/--host, -a/--archive, -O/--origin, -s/--samples, -t/--interval, -Z/--timezone and several other pcp options become indirectly available, see PCPIntro(1) for their descriptions.

🎀 the generic flags — behaviour modifiers 🎀

Some generic flags can be specified to influence the behaviour of the pcp-atopsar program:

  • -S — By default the timestamp at the beginning of a line is suppressed if more lines are shown for one interval. With this flag a timestamp is given for every output-line (easier for post-processing).
  • -a — By default certain resources as disks and network interfaces are only shown when they were active during the interval. With this flag all resources of a given type are shown, even if they were inactive during the interval.
  • -x — By default pcp-atopsar only uses colors if output is directed to a terminal (window). These colors might indicate that a critical occupation percentage has been reached (red) or has been almost reached (cyan) for a particular resource. See the man-page of atop for a detailed description of this feature (section COLORS). With the flag -x the use of colors is suppressed unconditionally.
  • -C — By default pcp-atopsar only uses colors if output is directed to a terminal (window). These colors might indicate that a critical occupation percentage has been reached (red) or has been almost reached (cyan) for a particular resource. See the man-page of atop for a detailed description of this feature (section COLORS). With the flag -C colors will always be used, even if output is not directed to a terminal.
  • -M — Use markers at the end of a line to indicate that a critical occupation percentage has been reached ('*') or has been almost reached ('+') for particular resources. The marker '*' is similar to the color red and the marker '+' to the color cyan. See the man-page of atop for a detailed description of these colors (section COLORS).
  • -H — Repeat the header line within a report for every N detail lines. The value of N is determined dynamically in case of output to a tty/window (depending on the number of lines); for output to a file or pipe this value is 23.
  • -R — Summarize cnt samples into one sample. When the logfile contains e.g. samples of 10 minutes, the use of the flag '-R 6' shows a report with one sample for every hour.

👑 the report-picker flags 👑

Other flags are used to define which reports are required:

  • -A — Show all possible reports.
  • -c — Report about CPU utilization (in total and per cpu).
  • -g — Report about GPU utilization (per GPU).
  • -p — Report about processor-related matters, like load-averages and hardware interrupts.
  • -P — Report about processes.
  • -m — Current memory- and swap-occupation.
  • -s — Report about paging- and swapping-activity, and overcommitment.
  • -B — Report about Pressure Stall Information (PSI).
  • -l — Report about utilization of logical volumes.
  • -f — Report about utilization of multiple devices.
  • -d — Report about utilization of disks.
  • -n — Report about NFS mounted filesystems on NFS client.
  • -j — Report about NFS client activity.
  • -J — Report about NFS server activity.
  • -i — Report about the network interfaces.
  • -I — Report about errors for network-interfaces.
  • -w — Report about IP version 4 network traffic.
  • -W — Report about errors for IP version 4 traffic.
  • -y — General report about ICMP version 4 layer activity.
  • -Y — Per-type report about ICMP version 4 layer activity.
  • -u — Report about UDP version 4 network traffic.
  • -z — Report about IP version 6 network traffic.
  • -Z — Report about errors for IP version 6 traffic.
  • -k — General report about ICMP version 6 layer activity.
  • -K — Per-type report about ICMP version 6 layer activity.
  • -U — Report about UDP version 6 network traffic.
  • -t — Report about TCP network traffic.
  • -T — Report about errors for TCP-traffic.
  • -h — Report about Infiniband utilization.
  • -O — Report about top-3 processes consuming most processor capacity. This report is only available when using a log file (not when specifying an interval).
  • -G — Report about top-3 processes consuming most resident memory. This report is only available when using a log file (not when specifying an interval).
  • -D — Report about top-3 processes issuing most disk transfers. This report is only available when using a log file (not when specifying an interval).
  • -N — Report about top-3 processes issuing most IPv4/IPv6 socket transfers. This report is only available when using a log file (not when specifying an interval).
heads up bestie: those last four — -O, -G, -D, -N — are log-file only. they literally do not work with an interval. no cap. 🙈

🧚 PCP ATOPSAR OPTIONS 🧚

The following additional PCP command line long options are also available:

  • --align=align — Force the initial sample to be aligned on the boundary of a natural time unit align. Refer to PCPIntro(1) for a complete description of the syntax for align.
  • --archive=archive — Performance metric values are retrieved from the set of Performance Co-Pilot (PCP) archive files identified by the argument archive, which 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.
  • --finish=endtime — When reporting archived metrics, the report will be restricted to those records logged before or at endtime. Refer to PCPIntro(1) for a complete description of the syntax for endtime.
  • --host=host — Fetch performance metrics from pmcd(1) on host, rather than from the default localhost.
  • --hostzone — Use the local timezone of the host that is the source of the performance metrics, as identified by either the --host or the --archive options. The default is to use the timezone of the local host.
  • --hotproc — Use the pmdaproc(1) hotproc metrics.
  • --interval=interval — Set the reporting interval to something other than the default 1 second. The interval argument follows the syntax described in PCPIntro(1), and in the simplest form may be an unsigned integer (the implied units in this case are seconds).
  • --samples=samples — The samples option defines the number of samples to be retrieved and reported.
  • --start=starttime — When reporting archived metrics, the report will be restricted to those records logged at or after starttime. Refer to PCPIntro(1) for a complete description of the syntax for starttime.
  • --timezone=timezone — Use timezone for the date and time. Timezone is in the format of the environment variable TZ as described in environ(7).
  • --version — Display version number and exit.

🌈 OUTPUT DESCRIPTION 🌈

Depending on the requested report, a number of columns with output values are produced. The values are mostly presented as a number of events per second.

⭐ the -c report — CPU utilization, per cpu ⭐

The output for the flag -c contains the following columns per cpu:

  • usr% — Percentage of cpu-time consumed in user mode (program text) for all active processes running with a nice value of zero (default) or a negative nice value (which means a higher priority than usual). The cpu consumption in user mode of processes with a nice value larger than zero (lower priority) is indicated in the nice%-column.
  • nice% — Percentage of cpu time consumed in user mode (i.e. program text) for all processes running with a nice value larger than zero (which means with a lower priority than average).
  • sys% — Percentage of cpu time consumed in system mode (kernel text) for all active processes. A high percentage usually indicates a lot of system calls being issued.
  • irq% — Percentage of cpu time consumed for handling of device interrupts.
  • softirq% — Percentage of cpu time consumed for soft interrupt handling.
  • steal% — Percentage of cpu time stolen by other virtual machines running on the same hardware.
  • guest% — Percentage of cpu time used by other virtual machines running on the same hardware (overlaps with usr%/nice%).
  • wait% — Percentage of unused cpu time while at least one of the processes in wait-state awaits completion of disk I/O.
  • idle% — Percentage of unused cpu time because all processes are in a wait-state but not waiting for disk-I/O.

⭐ the -g report — GPU utilization, per GPU ⭐

The output for the flag -g contains the following columns per GPU:

  • busaddr — GPU number and bus-ID (separated by '/').
  • gpubusy — GPU busy percentage during interval.
  • membusy — how busy the GPU memory was during the interval, as a percentage 🧠✨ like, the chunk of time it spent actually issuing reads and writes to memory.
  • memocc — what percentage of memory is occupied right now at this exact moment.
  • memtot — total memory available, the whole bag 💖
  • memuse — GPU memory in use at this moment.
  • gputype — what kind of GPU it is 👑

🎀 the -p output 🎀

  • pswch/s — process switches (aka context switches, iykyk) per second on this cpu. A process switch happens the moment an active thread (the one using a cpu, bestie) enters a wait state or has fully used up its time slice — and then another thread gets picked to use the cpu. Slay, rotation.
  • devintr/s — hardware interrupts handled per second on this cpu.
  • clones/s — new threads started per second 🌱
  • loadavg1 — load average showing the average number of threads sitting in the runqueue or in a non-interruptible wait state (usually waiting on disk or tape I/O) over the last minute.
  • loadavg5 — same vibe but over the last 5 minutes.
  • loadavg15 — and same again over the last 15 minutes ⏳

🦋 the -P output — processes & threads 🦋

  • clones/s — new threads started per second.
  • pexit/s
  • curproc — total number of processes hanging out in the system.
  • curzomb — number of zombie processes in the system 🧟 (they're literally undead, no cap).
  • trun — total threads in the system in state 'running'.
  • tslpi — total threads in state 'interruptible sleeping' 😴
  • tslpu — total threads in state 'uninterruptible sleeping'.
  • tidle — total threads in state 'idle' — that's uninterruptible sleeping but not counted in the load average.

🌸 the -m output — memory & swap utilization 🌸

  • memtotal — total usable main memory size.
  • memfree — available main memory size at this moment (a snapshot 📸).
  • buffers — main memory used at this moment to cache metadata-blocks (snapshot).
  • cached — main memory used at this moment to cache data-blocks (snapshot).
  • dirty — how much memory in the page cache still has to be flushed to disk at this moment (snapshot) 🧼
  • slabmem — main memory used at this moment for dynamically allocated memory by the kernel (snapshot).
  • swptotal — total swap space size at this moment (snapshot).
  • swpfree — available swap space at this moment (snapshot).

💜 the -s output — how much swapping is going on 💜

  • pagescan/s — scanned pages per second, triggered by free memory dropping below a particular threshold 📉
  • swapin/s — memory-pages the system read from the swap-device per second.
  • swapout/s — memory-pages the system wrote to the swap-device per second.
  • oomkill — number of processes killed during the last interval because there wasn't enough memory/swap 😭 The value -1 means this counter just isn't supported by your current kernel version, no biggie.
  • commitspc — the committed virtual memory space, i.e. the reserved virtual space for all allocations of private memory space for processes.
  • commitlim — the maximum limit for the committed space, which is by default swap size plus 50% of memory size. Heads up though: the kernel only checks whether the committed space exceeds the limit if strict overcommit handling is configured (vm.overcommit_memory is 2).

🌈 the -B output — Pressure Stall Information (PSI) 🌈

  • cpusome — average pressure percentage during the interval for the category 'CPU some'.
  • memsome — average pressure percentage during the interval for 'memory some'.
  • memfull — average pressure percentage during the interval for 'memory full'.
  • iosome — average pressure percentage during the interval for 'I/O some'.
  • iofull — average pressure percentage during the interval for 'I/O full' 🔥

💅 the -l (LVM), -f (MD) and -d (hard disk) outputs — one set of columns per active unit 💅

  • disk — the name.
  • busy — busy-percentage of the unit, meaning the portion of time the device was busy handling requests.
  • read/s — read-requests issued per second on this unit.
  • KB/read — average Kbytes transferred per read-request for this unit.
  • writ/s — write-requests (discard requests included, bestie) issued per second on this unit.
  • KB/writ — average Kbytes transferred per write-request for this unit.
  • avque — average number of requests outstanding in the queue while the unit is busy.
  • avserv — average milliseconds a request needs on this unit (seek, latency and data-transfer) ⏱️

🧚 the -n output — NFS mounted filesystems (client side) 🧚

  • mounted_device — the mounted device, containing the server name and the server directory being mounted.
  • physread/s — Kilobytes of data physically read from the NFS server by processes running on the NFS client.
  • KBwrite/s — Kilobytes of data physically written to the NFS server by processes running on the NFS client. And if the NFS filesystem got mounted during the interval, the state 'M' is shown 👀

🍓 the -j output — NFS client activity 🍓

  • rpc/s — RPC calls per second issued to NFS server(s).
  • rpcread/s — read RPC calls per second issued to NFS server(s).
  • rpcwrite/s — write RPC calls per second issued to NFS server(s).
  • retrans/s — retransmitted RPC calls per second.
  • autrefresh/s — authorization refreshes per second.

👑 the -J output — NFS server activity 👑

  • rpc/s — RPC calls per second received from NFS client(s).
  • rpcread/s — read RPC calls per second received from NFS client(s).
  • rpcwrite/s — write RPC calls per second received from NFS client(s).
  • MBcr/s — Megabytes per second returned to read requests by clients.
  • MBcw/s — Megabytes per second passed in write requests by clients.
  • nettcp/s — requests per second handled via TCP.
  • netudp/s — requests per second handled via UDP.

⭐ the -i output — network interface utilization ⭐

  • interf — name of the interface.
  • busy — busy percentage for this interface. If the linespeed of the interface couldn't be determined (say, for virtual interfaces), a question mark is shown ❓
  • ipack/s — packets received from this interface per second.
  • opack/s — packets transmitted to this interface per second.
  • iKbyte/s — Kbytes received from this interface per second.
  • oKbyte/s — Kbytes transmitted via this interface per second.
  • imbps/s — effective number of megabits received per second.
  • ombps/s — effective number of megabits transmitted per second.
  • maxmbps/s — linespeed as number of megabits per second. If the linespeed couldn't be determined (e.g. virtual interfaces), the value 0 is shown. And the linespeed gets followed by the indication 'f' (full duplex) or 'h' (half duplex) 🫶

💀 the -I output — network interface failures 💀

  • interf — name of the interface.
  • ierr/s — bad packets received from this interface per second.
  • oerr/s — times packet transmission to this interface failed per second.
  • coll/s — collisions encountered per second while transmitting packets.
  • idrop/s — received packets dropped per second because the local system ran out of buffer-space.
  • odrop/s — transmitted packets dropped per second because the local system ran out of buffer-space.
  • iframe/s — frame alignment-errors encountered per second on received packets.
  • ocarrier/s — carrier-errors encountered per second on transmitted packets.

🌸 the -w output — IPv4-layer utilization (with the formal SNMP-names in brackets, iykyk) 🌸

  • inrecv/s — IP datagrams received from interfaces per second, including the ones received in error (ipInReceives).
  • outreq/s — IP datagrams that local higher-layer protocols handed to IP in requests for transmission per second (ipOutRequests).
  • indeliver/s — received IP datagrams successfully delivered to higher protocol-layers per second (ipInDelivers).
  • forward/s — received IP datagrams per second where this entity was not their final IP destination, so an attempt was made to forward them (ipForwDatagrams).
  • reasmok/s — IP datagrams successfully reassembled per second (ipReasmOKs).
  • fragcreat/s — IP datagram fragments generated per second at this entity (ipFragCreates).

🙈 the -W output — IPv4-layer failures (SNMP-names in brackets again) 🙈

  • in: dsc/s — input IP datagrams per second where nothing blocked their continued processing but they got discarded anyway, e.g. for lack of buffer space (ipInDiscards).
  • in: hder/s — input IP datagrams per second discarded because the IP header had errors (ipInHdrErrors).
  • in: ader/s — how many input IP datagrams per second got yeeted because the IP address in the destination field wasn't valid for this entity to receive (ipInAddrErrors). 💅
  • in: unkp/s — inbound packets per second dropped because the protocol was unknown or unsupported, no cap (ipInUnknownProtos).
  • in: ratim/s — the number of timeout-situations per second that happen while we're still waiting on other fragments so reassembly can actually succeed (ipReasmTimeout). the way fragmentation tests your patience 😭
  • in: rfail/s — failures per second caught by the IP reassembly algorithm (ipReasmFails).
  • out: dsc/s — output IP datagrams per second that had no problems blocking their continued processing but still got discarded anyway, like when there's no buffer space (ipOutDiscards). it's giving "so close but no" 💀
  • out: nrt/s — IP datagrams per second discarded because literally no route could be found (ipOutNoRoutes). lost in the void fr fr

✨ the -y flag: ICMPv4 general utilization ✨

The output for the flag -y gives you the general utilization of the ICMPv4-layer plus some per-type ICMP-message info (formal SNMP-names between brackets):

  • intot/s — ICMP messages of any type received per second at this entity (icmpInMsgs).
  • outtot/s — ICMP messages of any type transmitted per second from this entity (icmpOutMsgs).
  • inecho/s — ICMP Echo (request) messages received per second (icmpInEchos).
  • inerep/s — ICMP Echo-Reply messages received per second (icmpInEchoReps).
  • otecho/s — ICMP Echo (request) messages transmitted per second (icmpOutEchos).
  • oterep/s — ICMP Echo-Reply messages transmitted per second (icmpOutEchoReps).

🌸 the -Y flag: the other ICMPv4 message types 🌸

The output for the flag -Y covers the other types of ICMPv4-messages (formal SNMP-names between brackets):

  • ierr/s — ICMP messages received per second that were determined to have ICMP-specific errors (icmpInErrors).
  • isq/s — ICMP Source Quench messages received per second (icmpInSrcQuenchs).
  • ird/s — ICMP Redirect messages received per second (icmpInRedirects).
  • idu/s — ICMP Destination Unreachable messages received per second (icmpInDestUnreachs).
  • ite/s — ICMP Time Exceeded messages received per second (icmpOutTimeExcds). yes bestie, that's the SNMP name the page gives it, we don't ask questions 🫶
  • oerr/s — ICMP messages transmitted per second that were determined to have ICMP-specific errors (icmpOutErrors).
  • osq/s — ICMP Source Quench messages transmitted per second (icmpOutSrcQuenchs).
  • ord/s — ICMP Redirect messages transmitted per second (icmpOutRedirects).
  • odu/s — ICMP Destination Unreachable messages transmitted per second (icmpOutDestUnreachs).
  • ote/s — ICMP Time Exceeded messages transmitted per second (icmpOutTimeExcds).

🦋 the -u flag: UDPv4-layer utilization 🦋

The output for the flag -u spills the tea on the utilization of the UDPv4-layer (formal SNMP-names between brackets):

  • indgram/s — UDP datagrams per second delivered to UDP users (udpInDatagrams).
  • outdgram/s — UDP datagrams transmitted per second from this entity (udpOutDatagrams).
  • inerr/s — received UDP datagrams per second that couldn't be delivered for reasons other than there being no application at the destination port (udpInErrors).
  • noport/s — received UDP datagrams per second where there was genuinely no application listening at the destination port (udpNoPorts). nobody home, iconic abandonment 😭

🎀 the -z flag: IPv6-layer utilization 🎀

The output for the flag -z is all about the utilization of the IPv6-layer (formal SNMP-names between brackets):

  • inrecv/s — input IPv6-datagrams received from interfaces per second, error ones included (ipv6IfStatsInReceives).
  • outreq/s — IPv6-datagrams per second that local higher-layer protocols handed to IP in requests for transmission (ipv6IfStatsOutRequests). heads up: this counter does not include any forwarded datagrams.
  • inmc/s — multicast packets per second received by the interface (ipv6IfStatsInMcastPkts).
  • outmc/s — multicast packets per second transmitted to the interface (ipv6IfStatsOutMcastPkts).
  • indeliv/s — IP datagrams successfully delivered per second to IPv6 user-protocols, ICMP included (ipv6IfStatsInDelivers).
  • reasmok/s — IPv6 datagrams successfully reassembled per second (ipv6IfStatsReasmOKs). slay, the fragments came home 💖
  • fragcre/s — IPv6 datagram fragments generated per second at this entity (ipv6IfStatsOutFragCreates).

💀 the -Z flag: IPv6-layer failures 💀

The output for the flag -Z is the failures-detected-in-the-IPv6-layer report (formal SNMP-names between brackets):

  • in: dsc/s — input IPv6 datagrams per second that hit no problems blocking continued processing but were discarded anyway, like for lack of buffer space (ipv6IfStatsInDiscards).
  • in: hder/s — input datagrams per second discarded because of errors in the IPv6 header (ipv6IfStatsInHdrErrors).
  • in: ader/s — input datagrams per second discarded because the IPv6 address in the destination field wasn't valid for this entity to receive (ipv6IfStatsInAddrErrors).
  • in: unkp/s — locally-addressed datagrams per second discarded because of an unknown or unsupported protocol (ipv6IfStatsInUnknownProtos).
  • in: ratim/s — timeout-situations per second while other IPv6 fragments were still expected for successful reassembly (ipv6ReasmTimeout).
  • in: rfail/s — failures per second detected by the IPv6 reassembly-algorithm (ipv6IfStatsReasmFails).
  • out: dsc/s — output IPv6 datagrams per second that had nothing blocking their continued processing but got discarded anyway, e.g. for lack of buffer space (ipv6IfStatsOutDiscards).
  • out: nrt/s — IPv6 datagrams per second discarded because no route could be found (ipv6IfStatsInNoRoutes).

🧚 the -k flag: ICMPv6 general utilization 🧚

The output for the flag -k gives you the general utilization of the ICMPv6-layer plus per-type ICMP-message info (formal SNMP-names between brackets):

  • intot/s — ICMPv6 messages of any type received per second at the interface (ipv6IfIcmpInMsgs).
  • outtot/s — ICMPv6 messages of any type transmitted per second from this entity (ipv6IfIcmpOutMsgs).
  • inerr/s — ICMPv6 messages received per second that had ICMP-specific errors, such as bad ICMP checksums, bad length, etc (ipv6IfIcmpInErrors). the audacity of a bad checksum 🙈
  • innsol/s — ICMP Neighbor Solicit messages received per second (ipv6IfIcmpInNeighborSolicits).
  • innadv/s — ICMP Neighbor Advertisement messages received per second (ipv6IfIcmpInNeighborAdvertisements).
  • otnsol/s — ICMP Neighbor Solicit messages transmitted per second (ipv6IfIcmpOutNeighborSolicits).
  • otnadv/s — ICMP Neighbor Advertisement messages transmitted per second (ipv6IfIcmpOutNeighborAdvertisements).

⭐ the -K flag: the other ICMPv6 message types ⭐

The output for the flag -K handles the other types of ICMPv6-messages (formal SNMP-names between brackets):

  • iecho/s — ICMP Echo (request) messages received per second (ipv6IfIcmpInEchos).
  • ierep/s — ICMP Echo-Reply messages received per second (ipv6IfIcmpInEchoReplies).
  • oerep/s — ICMP Echo-Reply messages transmitted per second (ipv6IfIcmpOutEchoReplies).
  • idu/s — ICMP Destination Unreachable messages received per second (ipv6IfIcmpInDestUnreachs).
  • odu/s — ICMP Destination Unreachable messages transmitted per second (ipv6IfIcmpOutDestUnreachs).
  • ird/s — ICMP Redirect messages received per second (ipv6IfIcmpInRedirects).
  • ord/s — ICMP Redirect messages transmitted per second (ipv6IfIcmpOutRedirect).
  • ite/s — ICMP Time Exceeded messages received per second (ipv6IfIcmpInTimeExcds).
  • ote/s — ICMP Time Exceeded messages transmitted per second (ipv6IfIcmpOutTimeExcds).

🍓 the -U flag: UDPv6-layer utilization 🍓

The output for the flag -U is the utilization report for the UDPv6-layer (formal SNMP-names between brackets):

  • indgram/s — UDPv6 datagrams per second delivered to UDP users (udpInDatagrams),
  • outdgram/s — UDPv6 datagrams transmitted per second from this entity (udpOutDatagrams),
  • inerr/s — received UDPv6 datagrams per second that couldn't be delivered for reasons other than no application sitting at the destination port (udpInErrors).
  • noport/s — received UDPv6 datagrams per second where there was no application at the destination port (udpNoPorts).

🔥 the -t flag: TCP-layer utilization 🔥

The output for the flag -t covers the utilization of the TCP-layer (formal SNMP-names between brackets):

  • insegs/s — received segments per second, the in-error ones included (tcpInSegs).
  • outsegs/s — transmitted segments per second, excluding any that contain only retransmitted octets (tcpOutSegs).
  • actopen/s — active opens per second that this entity has supported (tcpActiveOpens).
  • pasopen/s — passive opens per second that this entity has supported (tcpPassiveOpens).
  • nowopen — the number of connections currently open (snapshot) whose state is either ESTABLISHED or CLOSE-WAIT (tcpCurrEstab). note bestie: this one's a snapshot, not a per-second rate 👑

🌈 the -T flag: TCP-layer failures 🌈

The output for the flag -T reports the failures detected in the TCP-layer (formal SNMP-names between brackets):

  • inerr/s — received segments per second that came in with errors (tcpInErrs).
  • retrans/s — retransmitted segments per second (tcpRetransSegs).
  • attfail/s — failed connection attempts per second that have happened at this entity (tcpAttemptFails). we don't talk about those 😭
  • estabreset/s — number of resets per second that have occurred at this entity (tcpEstabResets). Connection chaos, but make it per-second 💅
  • outreset/s — number of transmitted segments per second containing the RST flag (tcpOutRsts). Bye-bye connections, tracked statistically 🫶

The output for the flag -h provides information about utilization of Infiniband ports:

  • controller — name of controller.
  • port — controller port.
  • busy — busy percentage for this port.
  • ipack/s — number of packets received from this port per second.
  • opack/s — number of packets transmitted to this port per second.
  • igbps/s — effective number of gigabits received per second.
  • ogbps/s — effective number of gigabits transmitted per second.
  • maxgbps/s — maximum rate as number of gigabits per second.
  • lanes — number of lanes.

The output for the flag -O provides information about the top-3 of processes with the highest processor consumption:

  • pid — process-id (if zero, the process has exited while the pid could not be determined).
  • command — the name of the process.
  • cpu% — the percentage of cpu-capacity being consumed. This value can exceed 100% for a multithreaded process running on a multiprocessor machine. Yes, bestie, over 100% is a whole vibe 🔥

The output for the flag -G provides information about the top-3 of processes with the highest memory consumption:

  • pid — process-id (if zero, the process has exited while the pid could not be determined).
  • command — the name of the process.
  • mem% — the percentage of resident memory-utilization by this process.

The output for the flag -D provides information about the top-3 of processes that issue the most read and write accesses to disk:

  • pid — process-id (if zero, the process has exited while the pid could not be determined).
  • command — the name of the process.
  • dsk% — the percentage of read and write accesses related to the total number of read and write accesses issued on disk by all processes, so a high percentage does not imply a high disk load on system level. Important caveat, no cap 🧚

The output for the flag -N provides information about the top-3 of processes that issue the most socket transfers for IPv4/IPv6:

  • pid — process-id (if zero, the process has exited while the pid could not be determined).
  • command — the name of the process.
  • net% — the percentage of socket transfers related to the total number of transfers issued by all processes, so a high percentage does not imply a high network load on system level. Same energy, different resource 🌈

✨ EXAMPLES ✨

To see today's cpu-activity so far (supposed that atop is logging in the background):

pcp-atopsar

To see the memory occupation for June 5, 2018 between 10:00 and 12:30 (supposed that pmlogger has been logging daily in the background on host acme.com):

pcp-atopsar -m -r $PCP_LOG_DIR/pmlogger/acme.com/20180605 -b 10:00 -e 12:30

or

pcp-atopsar -m -r 20180605 -b 10:00 -e 12:30

or, suppose it is June 8, 2018 at this moment:

pcp-atopsar -m -r yyy -b 10:00 -e 12:30

Write a logfile with atop to record the system behaviour for 30 minutes (30 samples of one minute) and produce all available reports afterwards:

pcp-atop -w /tmp/atoplog 60 30

pcp-atopsar -A -r /tmp/atoplog

To watch TCP activity evolve for ten minutes (10 samples with sixty seconds interval):

pcp-atopsar -t 60 10

To watch the header-lines ('_' as last character) of all reports with only the detail-lines showing critical resource consumption (marker '*' or '+' as last character):

pcp-atopsar -AM | grep '[_*+]$'

📁 FILES 📁

  • /etc/atoprc — configuration file containing system-wide default values (mainly flags). See related man-page.
  • ~/.atoprc — configuration file containing personal default values (mainly flags). See related man-page.
  • $PCP_LOG_DIR/pmlogger/HOST/YYYYMMDD — daily data file, where YYYYMMDD are digits representing the date, and HOST is the hostname of the machine being logged.

🌱 PCP ENVIRONMENT 🌱

Environment variables with the prefix PCP_ are used to parameterize the file and directory names used by PCP. On each installation, the file /etc/pcp.conf contains the local values for these variables. The $PCP_CONF variable may be used to specify an alternative configuration file, as described in pcp.conf(5).

For environment variables affecting PCP tools, see pmGetOptions(3).

🐞 DEBUGGING OPTIONS 🐞

The -D or --debug pcp option enables the output of additional diagnostics on stderr to help triage problems, although the information is sometimes cryptic and primarily intended to provide guidance for developers rather than end-users. debug is a comma separated list of debugging options; use pmdbg(1) with the -l option to obtain a list of the available debugging options and their meaning.

👀 SEE ALSO 👀

Go peek at PCPIntro(1), pcp(1), pcp-atop(1), mkaf(1), pmlogger(1), pmlogger_daily(1) and pcp-atoprc(5). The whole PCP bestie cinematic universe is right there 💖

Source/version: Performance Co-Pilot / PCP — PCP-ATOPSAR(1) — and the date is the one doing its little footer cameo, not retyping the whole line, periodt. 💅🎀

📦 where this page comes from