--- a/buildframework/helium/sf/java/diamonds/diamonds.rst Wed Jun 16 16:51:40 2010 +0300
+++ b/buildframework/helium/sf/java/diamonds/diamonds.rst Fri Aug 13 14:59:05 2010 +0300
@@ -11,14 +11,16 @@
------------
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.
+to configure diamonds in helium and minimum set of properties required.
Diamonds Server setup
---------------------
-Please define ``diamonds.host`` property with server address and ``diamonds.port`` with server port number.
-e. g. ::
+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"/>
@@ -27,52 +29,95 @@
-------------------
`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.
+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 logging
--------------------------------
-Diamonds logging can be skipped by defining the property ``skip.diamonds`` to true.
+
+Disable diamonds reporting
+--------------------------
+Diamonds reporting can be skipped by defining the property ``diamonds.enabled`` to false.
e.g.::
- hlm -Dskip.diamonds=true
+ hlm -Ddiamonds.enabled=false
-Add targets into diamonds configuration ftl file
-------------------------------------------------
-Diamonds detail configurations are in helium/config/diamonds_config.xml.ftl file.
-User have to add target here(this target must be already defined in configuration)
-if they want to log some additional data to diamonds after the target execution.
-
-Define the target with the following attributes inside ``<targets>`` node:
+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.
-.. csv-table:: Target
- :header: "Attribute", "Description", "Required"
-
- "name", "Name of the target","Yes"
- "template-file", "template file to process the data","No, if not defined, consider template file name same as target name"
- "logfile", "log file which will be processed","No"
- "ant-properties","set true if you need values from ant properties, default is false","No"
- "defer", "logging will be deferred and will be logged at the build finish time. Default is false","No"
+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.)
-e.g
+ <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
- <target name="check-tool-dependencies" template-file="tool.xml.ftl" logfile="${ant['temp.build.dir']}/build/doc/ivy/tool-dependencies-${ant['build.type']}.xml" ant-properties="true" defer="true"/>
+ <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>
-If no logfile provided, looks for xml file to send using <build.id_target_name.xml> file or <target_name.xml> file,
-if both doesn't exists does nothing. tries to pass ant properties and sends it. For below example, it looks for
-<build.id_create-bom.xml> or create_bom.xml and if any one exists then it will send that data.
-
-::
-
- <target name="create-bom"/>
+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.
-
-Using only ant properties for a specific target to send data
-
-::
-
- <target name="ant-prop-target" template-file="ant-prop.xml.ftl" ant-properties="true"/>
-
+ <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>
\ No newline at end of file