.. index::
  module: Configuring Diamonds

====================
Configuring Diamonds
====================

.. contents::

Introduction
------------
Diamonds is web application that can collect all build related information and categorize
builds. It can represent build information in different metrics. This document describes how
to configure diamonds in helium and minimum set of properties required.

Diamonds Server setup
---------------------
These are the minimum set of properties required in order to start the diamonds. All the properties are
defined automatically with already defined set of properties. The end user would not be required to change
any thing. As these are configured once for different vendors (symbian foundation, nokia, others.)

    <!-- Diamonds server details -->
    
    <property name="diamonds.host" value="diamonds.xxx.com"/>
    <property name="diamonds.port" value="9900"/>


Initialize diamonds
-------------------
`diamonds` target is the initialize target for diamonds logging. Call diamonds target in build target sequence
and this will log the already available data to diamonds and continue to log data onward as soon as they are available.
This is done already in helium build target sequence. So user can ignore this section. Earlier the diamonds
target needs to be called once the build area is initialized, but now this could be called even
before, as the output for diamonds files are generated in the cache location.


Disable diamonds reporting
--------------------------
Diamonds reporting can be skipped by defining the property ``diamonds.enabled`` to false.
e.g.::

    hlm -Ddiamonds.enabled=false 


Diamonds Configuration details
------------------------------
Diamonds configurations are extendable now. The default diamonds configuration is there under
${helium.dir}/config/diamonds_config_default.ant.xml. The configuration is based on ant properties
and references. So if the user wants to add process and report for new information, they can add
the details in their configurations. There are three types of information being provided using the 
configurations and are below.

Properties Required:
====================
Below are the properties requried for processing diamonds. But these are mapped to predifined properties
in helium and no action required for the user. The end user would not be required to change
any thing. As these are configured once for different vendors (symbian foundation, nokia, others.)

    <property name="diamonds.smtp.server" value="${email.smtp.server}" />
    <property name="diamonds.ldap.server" value="${email.ldap.server}" />
    <property name="diamonds.initializer.targetname" value="diamonds" />
    <property name="diamonds.tstamp.format" value="yyyy-MM-dd'T'HH:mm:ss" />
    <property name="diamonds.category" value="${build.family}" />

Stage Configurations:
=====================
Stages are to record information specific to stages. Stage information is used for both logging and
diamonds reporting. The build process needs to define stages clearly and map it with the configurations
as below.

.. code-block:: xml

      <hlm:stage id="get-baseline" startTarget="check-free-space" endTarget="enable-abiv2" />
      <hlm:stage id="get-source" startTarget="do-prep-work-area" endTarget="create-bom" />
      <hlm:stage id="clean-and-prep" startTarget="ido-prep-clean-dfs" endTarget="ido-pre-compile" />
      <hlm:stage id="build" startTarget="ido-build-parallel-dfs" endTarget="compile-ctc" />
      <hlm:stage id="rombuild" startTarget="image-creation" endTarget="image-creation" />
      <hlm:stage id="create-ATS-drop" startTarget="ats-test" endTarget="ats-aste" />        
      <hlm:stage id="post-build" startTarget="image-creation" endTarget="archive" />

The stage configuration provides the information about the stage starting and ending target sequence.
There should be a corresponding stagerecord for each stage, which is to store the log information
for that specific stages, please refer to logging module for more information.

Both the stages / target reporting using messaging type to provide details to be sent to diamonds
reporting. See details in messaging sections for further details.

Currently the diamonds reporting just records the start / end time using the following configuration.

.. code-block:: xml

    <hlm:fmppMessage id="stage.time.message" sourceFile="${diamonds.template-dir}/diamonds_stage.xml.ftl">
        <data expandProperties="yes">
            ant: antProperties()
        </data>
    </hlm:fmppMessage>

The config takes a template to be used to convert, the template is converted using fmpp and all 
the output files are processed and sent to diamonds. All the input to fmpp task could be used here.
The template diamonds_stage.xml.ftl just reports the start / end time. In addition to duration, if 
the user wants to send more information for the stages it could be done by overriding the 
configuration as below and controlling using the user defined template.

.. code-block:: xml

    <hlm:fmppMessage id="stage.time.message" ${diamonds.custom.template.dir}/diamonds_stage_custom.xml.ftl>
        <data expandProperties="yes">
            ant: antProperties()
        </data>
    </hlm:fmppMessage>


Reporting based on target execution:
====================================
If some data needs to be sent at the end of target execution, this can be defined with below configuration.

    <hlm:targetMessage id="diamonds.id" target="diamonds">
        <hlm:fmppMessage sourceFile="${helium.dir}/tools/common/templates/diamonds/tool.xml.ftl" >
            <data expandProperties="yes">
                ant: antProperties()
            </data>
        </hlm:fmppMessage>
    </hlm:targetMessage>