Denki PMDA
===========

This is the PMDA providing metrics which are related to the systems
electricity.

At the moment, metrics from 2 sources are available:

- RAPL values, available on newer Intel CPUs.
- battery values


Metrics
=======

The file ./help contains descriptions for all of the metrics exported
by this PMDA.

Once the PMDA has been installed, the following command will list all
the available metrics and their explanatory "help" text:

	$ pminfo -fT denki

Installation
============

 +  # cd $PCP_PMDAS_DIR/denki

 +  Then simply use

	# ./Install

 +  Watch the logfile:

        # less /var/log/pcp/pmcd/denki.log

 +  Verify if the metrics which are available on the system appear:

        # pminfo -fF denki
        # pmrep denki

De-installation
===============

 +  Simply use

	# cd $PCP_PMDAS_DIR/denki
	# ./Remove

Troubleshooting
===============

 +  After installing or restarting the agent, the PMCD log file
    ($PCP_LOG_DIR/pmcd/pmcd.log) and the PMDA log file
    ($PCP_LOG_DIR/pmcd/denki.log) should be checked for any warnings
    or errors.

Usage scenarios/examples
========================

 -  denki.rapl.rate:

    If RAPL is available, denki.rapl.rate can give an estimation of
    the current power consumption.  On laptops, typically 4 RAPL
    domains are available:

      inst [0 or "package-0"] - consumption of the other 3 domains
      inst [1 or "core"]      - cpus consumption
      inst [2 or "uncore"]    - typically GPU, if on motherboard
      inst [3 or "dram"]      - memory

    When accessed with 'pmrep denki.rapl.rate', these values can
    be used to compare for example power consumption of various
    webbrowsers while playing a video or webgl sites.  One can
    also verify if offloading to the GPU is working.

    On systems with multiple numa zones, also multiple RAPL 
    packages can be available, pmda-denki should properly deal
    with these.  For these, i.e. domains 0-package-0 and
    1-package-0 will become available as instances.

 -  denki.rapl.raw:

    If RAPL is available, this provides the raw values from the
    kernel.  These can be utilized for more accurate power con-
    sumption comparisons.  Example workflow:

    1) query the values, i.e. using 'pminfo denki.rapl.raw'
    2) run your workload
    3) query the current values again, use the values from 1)
       and the time between 1) and 3) to compute the overall
       consumption.
    4) Perform 1) to 3) again, with a different software or
       a different software version.

 -  denki.bat.energy_now_raw:

    If battery readings are available, this metric has the
    current reading, so the charge level of the battery.
    Battery readings are great for measuring overall system
    consumption - RAPL is just covering some components.
    The raw reading can like denki.rapl.raw be used to read
    the current charge level at 2 points in time, do a work-
    load in between, and compute the consumption.

 -  denki.bat.energy_now_rate:

    If battery readings are available, this shows the rate
    of discharging (positive value) or charging (negative
    value) of the overall system.  pmda-denki computes this
    every 60 seconds, from the denki.bat.energy_now_raw 
    readings.

 -  denki.bat.power_now:

    If battery readings are available, then this value
    shows the current battery discharge rate, so also overall
    system consumption.  This is computed by firmware/driver,
    and much more frequently updated than 
    denki.bat.energy_now_rate.
