powermetrics(1)             General Commands Manual            powermetrics(1)

NAME
     powermetrics

SYNOPSIS
     powermetrics [-i sample__interval__ms] [-r order] [-t wakeup__cost]
                  [-o output__file] [-n sample__count]

DESCRIPTION
     powermetrics gathers and display CPU usage statistics (divided into time
     spent in user mode and supervisor mode), timer and interrupt wakeup
     frequency (total and, for near-idle workloads, those that resulted in
     package idle exits), and on supported platforms, interrupt frequencies
     (categorized by CPU number), package C-state statistics (an indication of
     the time the core complex + integrated graphics, if any, were in low-
     power idle states), CPU frequency distribution during the sample. The
     tool may also display estimated power consumed by various SoC subsystems,
     such as CPU, GPU, ANE (Apple Neural Engine).  Note: Average power values
     reported by powermetrics are estimated and may be inaccurate - hence they
     should not be used for any comparison between devices, but can be used to
     help optimize apps for energy efficiency.

     -h, --help
             Print help message.

     -s samplers, --samplers samplers
             Comma separated list of samplers and sampler groups. Run with -h
             to see a list of samplers and sampler groups. Specifying
             "default" will display the default set, and specifying "all" will
             display all supported samplers.

     -o file, --output-file file
             Output to file instead of stdout.

     -b size, --buffer-size size
             Set output buffer size (0=none, 1=line)

     -i _N, --sample-rate _N
             sample every _N ms (0=disabled) [default: 5000ms]

     -n _N, --sample-count _N
             Obtain _N periodic samples (0=infinite) [default: 0]

     -t _N, --wakeup-cost _N
             Assume package idle wakeups have a CPU time cost of _N us when
             using hybrid sort orders using idle wakeups with time-based
             metrics

     -r method, --order method
             Order process list using specified method [default: composite]

             [pid]
                   process identifier
             [wakeups]
                   total package idle wakeups (alias: -W)
             [cputime]
                   total CPU time used (alias: -C)
             [composite]
                   energy number, see --show-process-energy (alias: -O)

     -f format, --format format
             Display data in specified format [default: text]

             [text]
                   human-readable text output
             [plist]
                   machine-readable property list, NUL-separated

     -a _N, --poweravg _N
             Display poweravg every _N samples (0=disabled) [default: 10]

     --hide-cpu-duty-cycle
             Hide CPU duty cycle data

     --show-initial-usage
             Print initial sample for entire uptime

     --show-usage-summary
             Print final usage summary when exiting

     --show-pstates
             Show pstate distribution. Only available on certain hardware.

     --show-plimits
             Show plimits, forced idle and RMBS. Only available on certain
             hardware.

     --show-cpu-qos
             Show per cpu QOS breakdowns.

     --show-process-coalition
             Group processes by coalitions and show per coalition information.
             Processes that have exited during the sample will still have
             their time billed to the coalition, making this useful for
             disambiguating DEAD_TASK time.

     --show-responsible-pid
             Show responsible pid for xpc services and parent pid

     --show-process-wait-times
             Show per-process sfi wait time info

     --show-process-qos-tiers
             Show per-process qos latency and throughput tier

     --show-process-io
             Show per-process io information

     --show-process-gpu
             Show per-process gpu time. This is only available on certain
             hardware.

     --show-process-netstats
             Show per-process network information

     --show-process-qos
             Show QOS times aggregated by process. Per thread information is
             not available.

     --show-process-energy
             Show per-process energy impact number. This number is a rough
             proxy for the total energy the process uses, including CPU, GPU,
             disk io and networking. The weighting of each is platform
             specific. Enabling this implicitly enables sampling of all the
             above per-process statistics.

     --show-process-samp-norm
             Show CPU time normailzed by the sample window, rather than the
             process start time. For example a process that launched 1 second
             before the end of a 5 second sample window and ran continuously
             until the end of the window will show up as 200 ms/s here and
             1000 ms/s in the regular column.

     --show-process-ipc
             Show per-process Instructions and cycles on ARM machines. Use
             with --show-process-amp to show cluster stats.

     --show-all
             Enables all samplers and displays all the available information
             for each sampler.

     This tool also implements special behavior upon receipt of certain
     signals to aid with the automated collection of data:

     SIGINFO
           take an immediate sample
     SIGIO
           flush any buffered output
     SIGINT/SIGTERM/SIGHUP
           stop sampling and exit

OUTPUT
     Guidelines for energy reduction

     CPU time, deadlines and interrupt wakeups: Lower is better

     Interrupt counts: Lower is better

     C-state residency: Higher is better

     Running Tasks

     1. CPU time consumed by threads assigned to that process, broken down
     into time spent in user space and kernel mode.

     2. Counts of "short" timers (where the time-to-deadline was < 5
     milliseconds in the future at the point of timer creation) which woke up
     threads from that process. High frequency timers, which typically have
     short time-to-deadlines, can result in significant energy consumption.

     3. A count of total interrupt level wakeups which resulted in dispatching
     a thread from the process in question. For example, if a thread were
     blocked in a usleep() system call, a timer interrupt would cause that
     thread to be dispatched, and would increment this counter. For workloads
     with a significant idle component, this metric is useful to study in
     conjunction with the package idle exit metric reported below.

     4. A count of "package idle exits" induced by timers/device interrupts
     which awakened threads from the process in question. This is a subset of
     the interrupt wakeup count. Timers and other interrupts that trigger
     "package idle exits" have a greater impact on energy consumption relative
     to other interrupts. With the exception of some Mac Pro systems, Mac and
     iOS systems are typically single package systems, wherein all CPUs are
     part of a single processor complex (typically a single IC die) with
     shared logic that can include (depending on system specifics) shared last
     level caches, an integrated memory controller etc. When all CPUs in the
     package are idle, the hardware can power-gate significant portions of the
     shared logic in addition to each individual processor's logic, as well as
     take measures such as placing DRAM in to self-refresh (also referred to
     as auto-refresh), place interconnects into lower-power states etc. Hence
     a timer or interrupt that triggers an exit from this package idle state
     results in a a greater increase in power than a timer that occurred when
     the CPU in question was already executing. The process initiating a
     package idle wakeup may also be the "prime mover", i.e. it may be the
     trigger for further activity in its own or other processes. This metric
     is most useful when the system is relatively idle, as with typical light
     workloads such as web browsing and movie playback; with heavier
     workloads, the CPU activity can be high enough such that package idle
     entry is relatively rare, thus masking package idle exits due to the
     process/thread in question.

     5. If any processes arrived and vanished during the inter-sample
     interval, or a previously sampled process vanished, their statistics are
     reflected in the row labeled "DEAD_TASKS". This can identify issues
     involving transient processes which may be spawned too frequently. dtrace
     ("execsnoop") or other tools can then be used to identify the transient
     processes in question. Running powermetrics in coalition mode, (see
     below), will also help track down transient process issues, by billing
     the coalition to which the process belongs.

     Interrupt Distribution

     The interrupts sampler reports interrupt frequencies, classified by
     interrupt vector and associated device, on a per-CPU basis. Mac OS
     currently assigns all device interrupts to CPU0, but timers and
     interprocessor interrupts can occur on other CPUs. Interrupt frequencies
     can be useful in identifying misconfigured devices or areas of
     improvement in interrupt load, and can serve as a proxy for identifying
     device activity across the sample interval. For example, during a
     network-heavy workload, an increase in interrupts associated with Airport
     wireless ("ARPT"), or wired ethernet ("ETH0" "ETH1" etc.) is not
     unexpected. However, if the interrupt frequency for a given device is
     non-zero when the device is not active (e.g. if "HDAU" interrupts, for
     High Definition Audio, occur even when no audio is playing), that may be
     a driver error. The int_sources sampler attributes interrupts to the
     responsible InterruptEventSources, which helps disambiguate the cause of
     an interrupt if the vector serves more than one source.

     Battery Statistics

     The battery sampler reports battery discharge rates, current and maximum
     charge levels, cycle counts and degradation from design capacity across
     the interval in question, if a delta was reported by the battery
     management unit. Note that the battery controller data may arrive out-of-
     phase with respect to powermetrics samples, which can cause aliasing
     issues across short sample intervals. Discharge rates across
     discontinuities such as sleep/wake may also be inaccurate on some
     systems; however, the rate of change of the total charge level across
     longer intervals is a useful indicator of total system load. Powermetrics
     does not filter discharge rates for A/C connect/disconnect events, system
     sleep residency etc. Battery discharge rates are typically not comparable
     across machine models.

     Processor Energy Usage

     The cpu_power sampler reports data derived from the Intel energy models;
     as of the Sandy Bridge intel microarchitecture, the Intel power control
     unit internally maintains an energy consumption model whose details are
     proprietary, but are likely based on duty cycles for individual execution
     units, current voltage/frequency etc. These numbers are not strictly
     accurate but are correlated with actual energy consumption. This section
     lists: power dissipated by the processor package which includes the CPU
     cores, the integrated GPU and the system agent (integrated memory
     controller, last level cache), and separately, CPU core power and GT
     (integrated GPU) power (the latter two in a forthcoming version). The
     energy model data is generally not comparable across machine models.

     The cpu_power sampler next reports, on processors with Nehalem and newer
     microarchitectures, hardware derived processor frequency and idle
     residency information, labeled "P-states" and "C-states" respectively in
     Intel terminology.

     C-states are further classified in to "package c-states" and per-core C-
     states. The processor enters a "c-state" in the scheduler's idle loop,
     which results in clock-gating or power-gating CPU core and, potentially,
     package logic, considerably reducing power dissipation. High package c-
     state residency is a goal to strive for, as energy consumption of the CPU
     complex, integrated memory controller if any and DRAM is significantly
     reduced when in a package c-state. Package c-states occur when all CPU
     cores within the package are idle, and the on-die integrated GPU if any
     (SandyBridge mobile and beyond), on the system is also idle. Powermetrics
     reports package c-state residency as a fraction of the time sampled. This
     is available on Nehalem microarchitecture and newer processors. Note that
     some systems, such as Mac Pros, do not enable "package" c-states.

     Powermetrics also reports per-core c-state residencies, signifying when
     the core in question (which can include multiple SMTs or "hyperthreads")
     is idle, as well as active/inactive duty cycle histograms for each
     logical processor within the core. This is available on Nehalem
     microarchitecture and newer processors.

     This section also lists the average clock frequency at which the given
     logical processor executed when not idle within the sampled interval,
     expressed as both an absolute frequency in MHz and as a percentage of the
     nominal rated frequency. These average frequencies can vary due to the
     operating system's demand based dynamic voltage and frequency scaling.
     Some systems can execute at frequencies greater than the nominal or "P1"
     frequency, which is termed "turbo mode" on Intel systems. Such operation
     will manifest as > 100% of nominal frequency. Lengthy execution in turbo
     mode is typically energy inefficient, as those frequencies have high
     voltage requirements, resulting in a correspondingly quadratic increase
     in power insufficient to outweigh the reduction in execution time.
     Current systems typically have a single voltage/frequency domain per-
     package, but as the processors can execute out-of-phase, they may display
     different average execution frequencies.

     Disk Usage and Network Activity

     The network and disk samplers reports deltas in disk and network activity
     that occured during the sample. Also specifying --show-process-netstats
     and --show-process-io will give you this information on a per process
     basis in the tasks sampler.

     Backlight level

     The battery sampler also reports the instantaneous value of the backlight
     luminosity level. This value is likely not comparable across systems and
     machine models, but can be useful when comparing scenarios on a given
     system.

     Devices

     The devices sampler, for each device, reports the time spent in each of
     the device's states over the course of the sample. The meaning of the
     different states is specific to each device. Powermetrics denotes low
     power states with an "L", device usable states with a "U" and power on
     states with an "O".

     SMC

     The smc sampler displays information supplied by the System Management
     Controller. On supported platforms, this includes fan speed and
     information from various temperature sensors. These are instantaneous
     values taken at the end of the sample window, and do not necessarily
     reflect the values at other times in the window.

     Thermal

     The thermal sampler displays the current thermal pressure the system is
     under. This is an instantaneous value taken at the end of the sample
     window, and does not necessarily reflect the value at other times in the
     window.

     SFI

     The sfi sampler shows system wide selective forced idle statistics.
     Selective forced idle is a mechanism the operating system uses to limit
     system power while minimizing user impact, by throttling certain threads
     on the system. Each thread belongs to an SFI class, and this sampler
     displays how much each SFI class is currently being throttled or empty if
     none of them is throttled. These are instantaneous values taken at the
     end of the sample window, and do not necessarily reflect the values at
     other times in the window. To get SFI wait time statistics on a per
     process basis use --show-process-wait-times.

KNOWN ISSUES
     Changes in system time and sleep/wake can cause minor inaccuracies in
     reported cpu time.

Darwin                              5/1/12                              Darwin
