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:

    If RAPL is available, denki.rapl 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

    These values can be used to compare for example power consumption of 
    various web browsers 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.bat.energy_now:

    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 the system runs on battery, this metric shows the 
    current battery discharge rate.  If the system is charging
    the battery, this value reports how much power is currently
    consumed - so consumption for battery charging plus running
    system itself.  This is computed by firmware/driver, and 
    much more frequently updated than denki.bat.energy_now_rate.

 -  denki.bat.capacity:

	This metric reports the fillstate of the battery in percent.
