==================
Statistics Manager
==================

Stats manager's goal is to store in database interesting data he can read on xPL network. To know which data should be stored, some XML files are used.

Adding new statistics in database
=================================

XML files
---------
In order Stats Manager to know which data from xPL network to store in database and how to store it, XML files are used.
These files are read by statmgr and define which xPL messages to listen and which data in these messages have to be store

Folder hierarchy for XML files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Here is the structure choosen to store xml files : <xml folder for statmgr>/<Technology>/<xplSchema>.xml

Example: ::

    x10/x10.basic.xml
    computer/sensor.basic.xml

Adding a new xml file
^^^^^^^^^^^^^^^^^^^^^
Xml files are provided by plugins. A plugin has to provide a file for each xpl message type. ^
So, several plugins can provide the same xml files. This problem is solved at plugin installation :

* plugin installation lists plugin's xml files provided
* plugin installation lists statmgr's xml files already installed
* if there is a conflict (xml files already exists) :

    * tell user that there is a conflict
    * display a diff of the 2 (or more) conflicted files
    * ask user to choose one file (default : the file already installed)

* plugin installation installs xml files and continue his installation

Xml file description
^^^^^^^^^^^^^^^^^^^^
A xml file for statmgr defines :

* a listener for the xpl schema
* a mapping for the listener between xpl schema elements and database 

.. code-block:: xml

    <?xml version="1.0" encoding="UTF-8"?>
    <!-- All xml definition files must be in <domogik.cfg_path>/xml directory,
        one mapping definintion per file.
    -->
    <!-- statistic : root element
    attribute technology is mandatory
    It specifies the technology for which this mapping is used.
    -->
    <statistic technology="plcbus"> 
        <schema name="control.basic">
            <xpltype type="xpl-trig">
                <listener> 
                    <filter>
                        <!-- list of 'key' nodes.
                        each node must have 2 parameters :
                            - name : the "key" of the pair 
                            - command : the "value" of the pair 
                            A message will be loggued only if schema and xpltype are corrects,
                            and only if for all "key" nodes specified, there is a name=value pair in the message.
                        -->
                        <key name="type" value="plcbus" />
                        <key name="command" value="on" />
                    </filter>
                </listener>
                <mapping> <!-- define the mapping between message keys and the database -->
                    <device field="device"/> 
                    <!-- define the field containing device name/address
                         If there is no field containing device addres, you can use 'static_name' attribute to define a name. Use with caution and only when there is no other choice :
                         <device static_name="foo"/>
                         If it is a notification message, use this : 
                         <device type="notification"/>
                    -->
                    <!-- The "value" node can have 2 attributes :
                        - field : mandatory ! define the key of the pair key=value to get in the Xpl message 
                        - new_name: optionnal, if it's define, the 'name' of this value entry will be the value defined,
                                else it will be the filed name.
                        - filter_key : define one key to read for adding a filter on renaming name in new_name
                        - filter_value : the value for the filter
                        - history_size : optionnal, indicate number of values to keep in database for a device key
                    -->
                    <value field="command"/>
                    <value field="command" history_size="5"/>
                    <value field="command" new_name="bar" />
                    <value field="command" new_name="foo" filter_key="type" filter_value="plcbus" />
                </mapping>
            </xpltype>
            <xpltype type="xpl-stat">
                <listener> 
                    <filter>
                        <key name="type" value="plcbus" />
                        <key name="command" value="off" />
                    </filter>
                </listener>
                <mapping> <!-- define the mapping between message keys and the database -->
                    <device field="device"/> <!-- define the device name -->
                    <value field="command"/>
                    <value field="command" name="bar" />
                </mapping>
            </xpltype>
        </schema>
    </statistic>

.. note::
    If xpl-trig and xpl-stat parts are identical, you can use **type="*"**

Example for x10/x10.basic: ::

    <?xml version="1.0" encoding="UTF-8"?>  
    <statistic technology="x10">
        <schema name="x10.basic">
            <xpltype type="xpl-trig">
                <listener>
                    <filter/>
                </listener>
                <mapping>
                    <device field="device"/>
                    <value field="command"/>
                    <value field="level" />
                </mapping>
            </xpltype>
        </schema>
    </statistic>
		
Flow
====
To see flow about statistics and events, see :doc:`events page </technical/rinor/rest_events>`.

Developper notes
================

Stats manager read all xml files. for each files, it create listeners. Each listener will call a callback function that put data in database with good format.