1 Configuring Signaling |
|
2 ===================== |
|
3 |
|
4 Helium signaling framework offers you a simplest way to control |
|
5 failures on build flow, and provides you an easy way to get reporting on |
|
6 some crucial steps of your build. |
|
7 |
|
8 |
|
9 The configuration |
|
10 ----------------- |
|
11 |
|
12 The signaling configuration is divided on three parts: |
|
13 |
|
14 * the signalConfig: defines the signal (Depreciated - please use signalListenerConfig) |
|
15 * the signalListenerConfig: defines the signal |
|
16 * the signalInput: defines what to do when a signal is raised |
|
17 * the notifierList: defines a set of notifiers |
|
18 |
|
19 signalListenerConfig |
|
20 .................... |
|
21 |
|
22 This part of the configuration is not targeted to be overridden by the build manager. |
|
23 |
|
24 The following example defines a custom signal named as **customSignal**. |
|
25 The default configuration must reference a default signalInput configuration using a nested inputRef element, |
|
26 so the signaling framework knows how to behave when a signal is raised. |
|
27 |
|
28 .. code-block:: xml |
|
29 |
|
30 <hlm:signalListenerConfig id="customSignal" target="target-name" message="target-name triggered a signal"> |
|
31 <signalNotifierInput> |
|
32 <signalInput refid="signalInputId" /> |
|
33 <notifierInput file="some/file/to/notify.html" /> |
|
34 </signalNotifierInput> |
|
35 <hlm:targetCondition> |
|
36 </available file="some-file.txt" /> |
|
37 </hlm:targetCondition> |
|
38 </hlm:signalConfig> |
|
39 |
|
40 A signal will then be triggered each time the **target-name** completed. The signalInput will then defined how it should be handled. |
|
41 |
|
42 Other way to trigger a signal is by using the signal task: |
|
43 |
|
44 .. code-block:: xml |
|
45 |
|
46 <hlm:signal name="customSignal" result="1"> |
|
47 <signalNotifierInput> |
|
48 <signalInput refid="signalInputId" /> |
|
49 <notifierInput file="some/file/to/notify.html" /> |
|
50 </signalNotifierInput> |
|
51 </hlm:signal> |
|
52 |
|
53 |
|
54 signalInput |
|
55 ........... |
|
56 |
|
57 This Ant type defines what a signal should do when it is raised. The failbuild attribute defines |
|
58 if a build failure should be: |
|
59 |
|
60 * failing the build now (value: now) |
|
61 * deferred at the end of the build (value: defer) |
|
62 * ignored (value: never) |
|
63 |
|
64 Then the configuration will accept a reference to a notifierList using the notifierListRef element. |
|
65 |
|
66 Example of configurations |
|
67 |
|
68 .. code-block:: xml |
|
69 |
|
70 <hlm:signalInput id="customSignalInput" failbuild="now"> |
|
71 <hlm:notifierListRef refid="customNotifier" /> |
|
72 </hlm:signalInput> |
|
73 |
|
74 This will run all notifier from the customNotifier configuration then fail the build. |
|
75 |
|
76 .. code-block:: xml |
|
77 |
|
78 <hlm:signalInput id="customSignalInput" failbuild="defer"/> |
|
79 |
|
80 This will defer the failure at the end of the build, no notifier will be run. |
|
81 |
|
82 notifierList |
|
83 ............ |
|
84 |
|
85 The notifierList Ant type allows the user to configure a set of Notifier (e.g Email, execute task): |
|
86 |
|
87 The following example configures a notifier list that will send an email and run few echo task to print |
|
88 some information. |
|
89 |
|
90 .. code-block:: xml |
|
91 |
|
92 <hlm:notifierList id="customNotifier"> |
|
93 <hlm:emailNotifier templateSrc="${helium.dir}/tools/common/templates/log/email_new.html.ftl" |
|
94 title="[signal] ${signal.name}" smtp="smtp.server.address" |
|
95 ldap="ldap://ldap.server.address:389" |
|
96 notifyWhen="always"/> |
|
97 <hlm:executeTaskNotifier> |
|
98 <echo>defaultSignalAlwaysNotifier: Signal: ${signal.name}</echo> |
|
99 <echo>defaultSignalAlwaysNotifier: Status: ${signal.status}</echo> |
|
100 </hlm:executeTaskNotifier> |
|
101 </hlm:notifierList> |
|
102 |
|
103 Detailed documentation of the notifier interface could be found `here <../../helium-antlib/index.html>`_. |
|
104 |
|
105 |
|
106 Example: configuring compileSignal |
|
107 ---------------------------------- |
|
108 |
|
109 In this example we will configure the compileSignal to behave this way: |
|
110 |
|
111 * send an email to additional users e.g: user@foo.com, user@bar.com |
|
112 * defer the build failure. |
|
113 |
|
114 You configuration should contains (e.g build.xml) |
|
115 |
|
116 .. code-block:: xml |
|
117 |
|
118 <?xml version="1.0"?> |
|
119 <project name="mybuild"> |
|
120 ... |
|
121 <import file="${helium.dir}/helium.ant.xml"/> |
|
122 ... |
|
123 |
|
124 <hlm:notifierList id="myCustomNotifierList"> |
|
125 <hlm:emailNotifier templateSrc="${helium.dir}/tools/common/templates/log/email_new.html.ftl" |
|
126 title="[signal] My build goes wrong: ${signal.name}" |
|
127 smtp="${email.smtp.server}" |
|
128 ldap="${email.ldap.server}" |
|
129 notifyWhen="fail" |
|
130 additionalrecipients="user@foo.com,user@bar.com"/> |
|
131 </hlm:notifierList> |
|
132 |
|
133 <hlm:signalInput id="compileSignalInput" failbuild="defer"> |
|
134 <hlm:notifierListRef refid="myCustomNotifierList" /> |
|
135 </hlm:signalInput> |
|
136 |
|
137 </project> |
|
138 |
|
139 |
|
140 A custom notifierList has been created with **myCustomNotifierList** as reference ID. It defines |
|
141 a emailNotifier which uses the default email template under Helium (${helium.dir}/tools/common/templates/log/email_new.html.ftl). |
|
142 It also set the title of you email to be "[signal] My build goes wrong: ${signal.name}" (signal.name property will be replace by the signal name raised). |
|
143 **notifyWhen** attribute will make the notifier to send a notification only on build failure. |
|
144 Finally the two additional email addresses will be set using the **additionalrecipients** attribute. |
|
145 |
|
146 We then need to link the signal configuration and our custom the notifier list. The signalInput element is use to achieve that. |
|
147 It must be defined using the same reference ID (see reference overriding howto) as the one in the Helium configuration, the naming convention for this is: **<signal_name>Input**. |
|
148 Its **failbuild** attribute is set to **defer** which will configure the build to keepgoing, and fail at the end of the build flow. |
|
149 Finally an embedded notifierListRef element will reference our custom notifier list: **myCustomNotifierList**. |
|
150 |
|
151 While failing the signaling framework will execute all notifier defined and then store internally the build failure so it can raise it again at the end of the execution. |
|
152 |
|
153 |
|
154 Example: Report specific errors not included by default |
|
155 ------------------------------------------------------- |
|
156 |
|
157 Target prep-work-area has extra log extraction added and output xml is read by a new signal. |
|
158 |
|
159 .. code-block:: xml |
|
160 |
|
161 <hlm:signalInput id="prepWorkAreaSignalInputWarn" failbuild="defer"> |
|
162 <hlm:notifierListRef refid="defaultSignalFailNotifier" /> |
|
163 </hlm:signalInput> |
|
164 |
|
165 <hlm:signalListenerConfig id="prepWorkAreaSignalWarn"> |
|
166 <signalNotifierInput> |
|
167 <signalInput refid="prepWorkAreaSignalInputWarn" /> |
|
168 <notifierInput file="${build.log.dir}/${build.id}_ccm_get_input.log2.xml" /> |
|
169 </signalNotifierInput> |
|
170 <hlm:targetCondition name="prep-work-area" message="Warnings happened during Preparing Work Area"> |
|
171 <hlm:hasSeverity severity="error" file="${build.log.dir}/${build.id}_ccm_get_input.log2.xml"/> |
|
172 </hlm:targetCondition> |
|
173 </hlm:signalListenerConfig> |
|
174 |
|
175 <target name="prep-work-area" depends="ccmgetinput.prep-work-area"> |
|
176 <hlm:logextract file="${build.log.dir}/${build.id}_ccm_get_input.log" outputfile="${build.log.dir}/${build.id}_ccm_get_input.log2.xml"> |
|
177 <logfilterset> |
|
178 <logfilter category="error" regex=".*Explicitly specified but not included" /> |
|
179 </logfilterset> |
|
180 </hlm:logextract> |
|
181 </target> |
|