9 |
9 |
10 Introduction |
10 Introduction |
11 ------------ |
11 ------------ |
12 Diamonds is web application that can collect all build related information and categorize |
12 Diamonds is web application that can collect all build related information and categorize |
13 builds. It can represent build information in different metrics. This document describes how |
13 builds. It can represent build information in different metrics. This document describes how |
14 to configure diamonds in helium. |
14 to configure diamonds in helium and minimum set of properties required. |
15 |
15 |
16 Diamonds Server setup |
16 Diamonds Server setup |
17 --------------------- |
17 --------------------- |
18 Please define ``diamonds.host`` property with server address and ``diamonds.port`` with server port number. |
18 These are the minimum set of properties required in order to start the diamonds. All the properties are |
19 e. g. :: |
19 defined automatically with already defined set of properties. The end user would not be required to change |
|
20 any thing. As these are configured once for different vendors (symbian foundation, nokia, others.) |
20 |
21 |
21 <!-- Diamonds server details --> |
22 <!-- Diamonds server details --> |
|
23 |
22 <property name="diamonds.host" value="diamonds.xxx.com"/> |
24 <property name="diamonds.host" value="diamonds.xxx.com"/> |
23 <property name="diamonds.port" value="9900"/> |
25 <property name="diamonds.port" value="9900"/> |
24 |
26 |
25 |
27 |
26 Initialize diamonds |
28 Initialize diamonds |
27 ------------------- |
29 ------------------- |
28 `diamonds` target is the initialize target for diamonds logging. Call diamonds target in build target sequence |
30 `diamonds` target is the initialize target for diamonds logging. Call diamonds target in build target sequence |
29 and this will log the already available data to diamonds and continue to log data onward as soon as they are available. |
31 and this will log the already available data to diamonds and continue to log data onward as soon as they are available. |
30 This is done already in helium build target sequence. So user can ignore this section. |
32 This is done already in helium build target sequence. So user can ignore this section. Earlier the diamonds |
|
33 target needs to be called once the build area is initialized, but now this could be called even |
|
34 before, as the output for diamonds files are generated in the cache location. |
31 |
35 |
32 Disable diamonds logging |
36 |
33 ------------------------------- |
37 Disable diamonds reporting |
34 Diamonds logging can be skipped by defining the property ``skip.diamonds`` to true. |
38 -------------------------- |
|
39 Diamonds reporting can be skipped by defining the property ``diamonds.enabled`` to false. |
35 e.g.:: |
40 e.g.:: |
36 |
41 |
37 hlm -Dskip.diamonds=true |
42 hlm -Ddiamonds.enabled=false |
38 |
43 |
39 |
44 |
40 Add targets into diamonds configuration ftl file |
45 Diamonds Configuration details |
41 ------------------------------------------------ |
46 ------------------------------ |
42 Diamonds detail configurations are in helium/config/diamonds_config.xml.ftl file. |
47 Diamonds configurations are extendable now. The default diamonds configuration is there under |
43 User have to add target here(this target must be already defined in configuration) |
48 ${helium.dir}/config/diamonds_config_default.ant.xml. The configuration is based on ant properties |
44 if they want to log some additional data to diamonds after the target execution. |
49 and references. So if the user wants to add process and report for new information, they can add |
|
50 the details in their configurations. There are three types of information being provided using the |
|
51 configurations and are below. |
45 |
52 |
46 Define the target with the following attributes inside ``<targets>`` node: |
53 Properties Required: |
|
54 ==================== |
|
55 Below are the properties requried for processing diamonds. But these are mapped to predifined properties |
|
56 in helium and no action required for the user. The end user would not be required to change |
|
57 any thing. As these are configured once for different vendors (symbian foundation, nokia, others.) |
47 |
58 |
48 .. csv-table:: Target |
59 <property name="diamonds.smtp.server" value="${email.smtp.server}" /> |
49 :header: "Attribute", "Description", "Required" |
60 <property name="diamonds.ldap.server" value="${email.ldap.server}" /> |
50 |
61 <property name="diamonds.initializer.targetname" value="diamonds" /> |
51 "name", "Name of the target","Yes" |
62 <property name="diamonds.tstamp.format" value="yyyy-MM-dd'T'HH:mm:ss" /> |
52 "template-file", "template file to process the data","No, if not defined, consider template file name same as target name" |
63 <property name="diamonds.category" value="${build.family}" /> |
53 "logfile", "log file which will be processed","No" |
|
54 "ant-properties","set true if you need values from ant properties, default is false","No" |
|
55 "defer", "logging will be deferred and will be logged at the build finish time. Default is false","No" |
|
56 |
64 |
57 e.g |
65 Stage Configurations: |
|
66 ===================== |
|
67 Stages are to record information specific to stages. Stage information is used for both logging and |
|
68 diamonds reporting. The build process needs to define stages clearly and map it with the configurations |
|
69 as below. |
58 |
70 |
59 .. code-block:: xml |
71 .. code-block:: xml |
60 |
72 |
61 <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"/> |
73 <hlm:stage id="get-baseline" startTarget="check-free-space" endTarget="enable-abiv2" /> |
|
74 <hlm:stage id="get-source" startTarget="do-prep-work-area" endTarget="create-bom" /> |
|
75 <hlm:stage id="clean-and-prep" startTarget="ido-prep-clean-dfs" endTarget="ido-pre-compile" /> |
|
76 <hlm:stage id="build" startTarget="ido-build-parallel-dfs" endTarget="compile-ctc" /> |
|
77 <hlm:stage id="rombuild" startTarget="image-creation" endTarget="image-creation" /> |
|
78 <hlm:stage id="create-ATS-drop" startTarget="ats-test" endTarget="ats-aste" /> |
|
79 <hlm:stage id="post-build" startTarget="image-creation" endTarget="archive" /> |
|
80 |
|
81 The stage configuration provides the information about the stage starting and ending target sequence. |
|
82 There should be a corresponding stagerecord for each stage, which is to store the log information |
|
83 for that specific stages, please refer to logging module for more information. |
|
84 |
|
85 Both the stages / target reporting using messaging type to provide details to be sent to diamonds |
|
86 reporting. See details in messaging sections for further details. |
|
87 |
|
88 Currently the diamonds reporting just records the start / end time using the following configuration. |
|
89 |
|
90 .. code-block:: xml |
|
91 |
|
92 <hlm:fmppMessage id="stage.time.message" sourceFile="${diamonds.template-dir}/diamonds_stage.xml.ftl"> |
|
93 <data expandProperties="yes"> |
|
94 ant: antProperties() |
|
95 </data> |
|
96 </hlm:fmppMessage> |
|
97 |
|
98 The config takes a template to be used to convert, the template is converted using fmpp and all |
|
99 the output files are processed and sent to diamonds. All the input to fmpp task could be used here. |
|
100 The template diamonds_stage.xml.ftl just reports the start / end time. In addition to duration, if |
|
101 the user wants to send more information for the stages it could be done by overriding the |
|
102 configuration as below and controlling using the user defined template. |
|
103 |
|
104 .. code-block:: xml |
|
105 |
|
106 <hlm:fmppMessage id="stage.time.message" ${diamonds.custom.template.dir}/diamonds_stage_custom.xml.ftl> |
|
107 <data expandProperties="yes"> |
|
108 ant: antProperties() |
|
109 </data> |
|
110 </hlm:fmppMessage> |
62 |
111 |
63 |
112 |
64 If no logfile provided, looks for xml file to send using <build.id_target_name.xml> file or <target_name.xml> file, |
113 Reporting based on target execution: |
65 if both doesn't exists does nothing. tries to pass ant properties and sends it. For below example, it looks for |
114 ==================================== |
66 <build.id_create-bom.xml> or create_bom.xml and if any one exists then it will send that data. |
115 If some data needs to be sent at the end of target execution, this can be defined with below configuration. |
67 |
116 |
68 :: |
117 <hlm:targetMessage id="diamonds.id" target="diamonds"> |
69 |
118 <hlm:fmppMessage sourceFile="${helium.dir}/tools/common/templates/diamonds/tool.xml.ftl" > |
70 <target name="create-bom"/> |
119 <data expandProperties="yes"> |
71 |
120 ant: antProperties() |
72 |
121 </data> |
73 Using only ant properties for a specific target to send data |
122 </hlm:fmppMessage> |
74 |
123 </hlm:targetMessage> |
75 :: |
|
76 |
|
77 <target name="ant-prop-target" template-file="ant-prop.xml.ftl" ant-properties="true"/> |
|
78 |
|