manpagez: man pages & more
man powermetrics(1)
Home | html | info | man
powermetrics(1)           BSD General Commands Manual          powermetrics(1)




     powermetrics [-i sample_interval_ms] [-o order] [-t wakeup_cost]
                  [-u output_file] [-n sample_count]


     powermetrics gathers and display CPU usage statistics (divided into time
     spent in user mode and supervisor mode), timer and interrupt wakeup fre-
     quency (total and, for near-idle workloads, those that resulted in pack-
     age idle exits), and on supported platforms, interrupt frequencies (cate-
     gorized 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), as well as the average execution frequency for each CPU
     when not idle.

     -h, --help
             Print help message.

     -u 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-interval 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 met-

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

                   process identifier
                   total package idle wakeups (alias: -W)
                   total CPU time used (alias: -C)
                   weighted hybrid of package idle wakeups and CPU time used
                   (alias: -O)

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

                   human-readable text output
                   machine-readable property list, NUL-separated

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

             Hide platform power data

             Hide CPU duty cycle data

             Hide GPU duty cycle data

             Print initial sample for entire uptime

             Print final usage summary when exiting

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

           take an immediate sample
           flush any buffered output
           stop sampling and exit


     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 millisec-
     onds 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 con-
     junction 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 pack-
     age 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 work-
     loads such as web browsing and movie playback; with heavier workloads,
     the CPU activity can be high enough such that package idle entry is rela-
     tively rare, thus masking package idle exits due to the process/thread in

     5. If any processes arrived and vanished during the inter-sample inter-
     val, 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.

     Interrupt Distribution

     Powermetrics also 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 identify-
     ing 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 fre-
     quency 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.

     Battery Statistics

     Powermetrics 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. Bat-
     tery discharge rates are typically not comparable across machine models.

     Processor Energy Usage

     Powermetrics next 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 pro-
     prietary, 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 con-
     troller, last level cache), and separately, CPU core power and GT (inte-
     grated GPU) power (the latter two in a forthcoming version). The energy
     model data is generally not comparable across machine models.

     Powermetrics next reports, on processors with Nehalem and newer microar-
     chitectures, hardware derived processor frequency and idle residency
     information, labeled "P-states" and "C-states" respectively in Intel ter-

     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 logi-
     cal processor within the core. This is available on Nehalem microarchi-
     tecture 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. Cur-
     rent systems typically have a single voltage/frequency domain per-pack-
     age, but as the processors can execute out-of-phase, they may display
     different average execution frequencies.

     Disk Usage and Network Activity

     Powermetrics reports deltas in disk and network activity that occured
     during the sample.

     Backlight level

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


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

Darwin                         October 15, 2013                         Darwin

Mac OS X 10.9 - Generated Tue Oct 15 07:56:15 CDT 2013
© 2000-2021
Individual documents may contain additional copyright information.