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

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

At the moment, metrics from 3 sources are available:

- RAPL (available on newer Intel CPUs), values read via /sys file system
- RAPL (available on newer Intel CPUs), values read via cpu MSR registers
- 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.sysfs:

    If RAPL via /sys is available, denki.rapl.sysfs 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, i.e.

	denki.rapl.sysfs
   	 	inst [0 or "0-package-0"] value 169013
   	 	inst [1 or "0-dram"] value 12294
   	 	inst [2 or "1-package-1"] value 135669
   		inst [3 or "1-dram"] value 9600

 -  denki.rapl.msr:

    If RAPL via MSR cpu registers is available, denki.rapl.msr can 
	give an estimation of the current power consumption.  On 
	laptops, typically 5 RAPL MSR domains are available:

	denki.raplmsr
   		inst [0 or "package_energy"] value 17222
    	inst [1 or "cores_energy"] value 6110
    	inst [2 or "uncore_energy"] value 143
    	inst [3 or "dram_energy"] value 3167
    	inst [4 or "psys_energy"] value 53005

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

Links
=====

More details are available in the pmda-denki handbook:
* https://github.com/christianhorn/smallhelpers/tree/main/pmda-denki-handbook
* Rendered as html:
  https://htmlpreview.github.io/?https://github.com/christianhorn/smallhelpers/blob/main/pmda-denki-handbook/denki.html
* As pdf:
  https://github.com/christianhorn/smallhelpers/blob/main/pmda-denki-handbook/denki.pdf