--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/buildframework/helium/doc/src/manual/metrics.rst Tue Apr 27 08:33:08 2010 +0300
@@ -0,0 +1,233 @@
+.. ============================================================================
+ Name : metrics.rst
+ Part of : Helium
+
+ Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
+ All rights reserved.
+ This component and the accompanying materials are made available
+ under the terms of the License "Eclipse Public License v1.0"
+ which accompanies this distribution, and is available
+ at the URL "http://www.eclipse.org/legal/epl-v10.html".
+
+ Initial Contributors:
+ Nokia Corporation - initial contribution.
+
+ Contributors:
+
+ Description:
+
+ ============================================================================
+
+####################
+Helium Build Metrics
+####################
+
+.. index::
+ module: Helium Build Metrics
+
+
+.. contents::
+
+Introduction
+============
+
+This describes the types of build and release metrics that can be collected using Helium and a Diamonds installation and how they can be collected.
+
+.. index::
+ single: Diamonds
+
+Diamonds Link for builds:
+=========================
+ Diamonds homepage: <http://diamonds.nmp.nokia.com/diamonds>
+
+
+Helium configuration
+====================
+To enable logging to diamonds from Helium one needs to ensure that:
+
+* The properties :hlm-p:`diamonds.host` and :hlm-p:`diamonds.port` are set correctly.
+* By default they are taken from ``helium/tools/common/companyproperties.ant.xml``, but can be overridden by using:
+
+ * **Command line**
+
+ For example, if the Diamonds server IP address changed to ``new.diamonds.server:newport`` then you would use:
+
+ * *hlm.bat -Ddiamonds.host=new.diamonds.server -Ddiamonds.port=newport*
+
+ * **ANT team file**
+
+ For example, if the Diamonds server IP address changed to ``new.diamonds.server:newport`` then you would put the following lines in your ``<team>.ant.xml``::
+
+ <property name="diamonds.host" value="new.diamonds.server"/>*
+ <property name="diamonds.port" value="newport"/>*
+
+* If you define the property :hlm-p:`skip.diamonds` to ``true`` Diamonds is disabled.
+
+
+.. index::
+ single: Diamonds server configuration
+
+Diamonds server configuration
+=============================
+
+Config file: ``helium/config/diamonds_config.xml.ftl``.
+
+
+Properties need to be defined for successful logging:
+-----------------------------------------------------
+
+
+.. csv-table:: Diamonds logging related properties
+ :header: "Property name", "Description"
+
+ "``diamonds.host``", "Diamonds server address"
+ "``diamonds.port``", "Server port number"
+ "``diamonds.path``", "Builds path in Diamonds server"
+ ":hlm-p:`build.family`", "Category of product"
+ ":hlm-p:`stages`", "Start and end target of a stages with logical stage name"
+ ":hlm-p:`sysdef.configurations.list`", "System definition name list to log component faults"
+ ":hlm-p:`build.name`", "Name of product"
+ ":hlm-p:`release.label`", "Name of release"
+ ":hlm-p:`publish`", "Set this property to publish to network"
+ ":hlm-p:`publish.dir`", "Published build environment location"
+ ":hlm-p:`diamonds.build.tags`", "Set this property to send custom build tag(s) to Diamonds"
+
+
+.. index::
+ single: Metrics
+
+Metrics
+=======
+
+
+Metrics name: Build duration
+----------------------------
+
+Description
+~~~~~~~~~~~~
+ Build duration in hours as a function of time.
+
+Collection method
+~~~~~~~~~~~~~~~~~~~
+ The started time and finished time are uploaded to diamonds automatically from Helium.
+
+Location in Diamonds
+~~~~~~~~~~~~~~~~~~~~~~
+ In Diamonds, Builds->Summary.
+
+ For categorization by product programs, Build->Click "category" hyperlink. For
+ categorization by build accelerators, Build->Other->Click "Build system" hyperlink.
+
+
+RVCT compiler warnings
+----------------------
+
+Description
+~~~~~~~~~~~
+ Number of build warnings in SW build - RVCT compiler warnings to tell about the quality of the software.
+
+Collection Method
+~~~~~~~~~~~~~~~~~
+ Number of RVCT bad warnings, warnings and errors are send to diamond aumatically from Helium after each build.
+
+Location in Diamonds
+~~~~~~~~~~~~~~~~~~~~~~
+ In Diamonds, Builds->Summary->Compilation error summary.
+
+
+Metrics name: "number of object files" and "number of generated files"
+----------------------------------------------------------------------
+
+Description
+~~~~~~~~~~~~
+ Number of object files and generated files for a build
+
+Collection method
+~~~~~~~~~~~~~~~~~~~
+ Necessary data are collected from build information automatically
+
+ Based on helium/config/diamonds_config.xml.ftl cofiguration, Helium automatically sends the start and end time of a stage to diamonds.
+
+
+Location in Diamonds
+~~~~~~~~~~~~~~~~~~~~~~
+ In Diamonds, Builds->Others->Object files & Generated files.
+
+
+Metrics name: Build stage duration
+----------------------------------
+
+Description
+~~~~~~~~~~~~
+ Date and time of start and finish. A=Date and time of start B= Date and time of finish.
+ Metric = B-A calculated for each build stages. In the graph only the 4 main stages are shown.\
+
+ * *1. pre-build (Synergy check outs and snapshots, build area preparation)*
+ * *2. build (main build)*
+ * *3. post build (Post build, China, Japan, EE images, EE zip, Localization, Localized roms)*
+ * *4. release to channels (db, ftp, network disk)*
+
+Collection method
+~~~~~~~~~~~~~~~~~~~
+ The started time and finished time are uploaded to diamonds automatically from Helium.
+
+Location in Diamonds
+~~~~~~~~~~~~~~~~~~~~~~
+ In Diamonds, Builds->Summary. Click "Stages>>"
+
+
+Metrics name: API Usage
+----------------------------------
+
+Description
+~~~~~~~~~~~~
+ Types of api are private, internal, domain and sdk. Illegal API is (internal+private), if any illegal api exists it will show the Illegal API's name with path.
+
+Collection method
+~~~~~~~~~~~~~~~~~~~
+ If disable.analysis.tool is not set, data will be uploaded to diamonds automatically from Helium.
+
+Location in Diamonds
+~~~~~~~~~~~~~~~~~~~~~~
+ In Diamonds, Builds->Other->API usage
+
+
+Metrics name: Build tags
+------------------------
+
+Description
+~~~~~~~~~~~~
+ Build tags are used to group builds for metric collection purposes.
+
+Collection method
+~~~~~~~~~~~~~~~~~~~
+ To send custom build tags to Diamonds the property diamonds.build.tags should be set as follows:
+ * For a single build tag (e.g. "build_tag1") -> hlm -Ddiamonds.build.tags="build_tag1"
+ * For multiple build tags (e.g. "build_tag1" and "build_tagN") -> hlm -Ddiamonds.build.tags="build_tag1,build_tagN"
+
+ Note:
+ * Build tags should not exceed 50 characters.
+ * Duplicate build tags will be ignored.
+ * If an "Available Tag" is set, then in Diamonds it gets removed from that list and transferred to "Build's Tags" list.
+
+Location in Diamonds
+~~~~~~~~~~~~~~~~~~~~~~
+ In Diamonds, Builds->Tags->Build's Tags.
+
+ For categorization by tags, Click Builds->"Navigation" pane->"Build Archives"->by tags
+
+
+Metrics name: Information about "base environment"
+--------------------------------------------------
+
+Description
+~~~~~~~~~~~~
+ Information about what "base environment" is unzipped.
+
+Collection method
+~~~~~~~~~~~~~~~~~~~
+ Necessary data are collected from build information automatically if currentRelease.xml exists in the environment.
+
+Location in Diamonds
+~~~~~~~~~~~~~~~~~~~~~~
+ In Diamonds, Builds->Content. See "Input" for s60.