README revision 2013:55cf2b46a77a 
1Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
2DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
3
4This code is free software; you can redistribute it and/or modify it
5under the terms of the GNU General Public License version 2 only, as
6published by the Free Software Foundation.
7
8This code is distributed in the hope that it will be useful, but WITHOUT
9ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
10FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
11version 2 for more details (a copy is included in the LICENSE file that
12accompanied this code).
13
14You should have received a copy of the GNU General Public License version
152 along with this work; if not, write to the Free Software Foundation,
16Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
17
18Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
19or visit www.oracle.com if you need additional information or have any
20questions.
21
22
23
24DESCRIPTION
25
26The purpose of this library is gathering diagnostic information on test
27failures and timeouts. The library runs platform specific tools, which are
28configured in the way described below. The collected data will be available
29in HTML format next to JTR files.
30
31The library uses JTHarness Observer and jtreg TimeoutHandler extensions points.
32
33DEPENDENCES
34
35The library requires jtreg 4b13+ and JDK 7+.
36
37BUILDING
38
39The library is built using the top level build-test-failure-handler target and
40is automatically included in the test image and picked up by hotspot and jdk
41test makefiles.
42
43CONFIGURATION
44
45Properties files are used to configure the library. They define which actions
46to be performed in case of individual test failure or timeout. Each platform
47family uses its own property file (named '<platform>.properties'). For platform
48independent actions, 'common.properties' is used.
49
50Actions to be performed on each failure are listed in 'environment' property.
51Extra actions for timeouts are listed in 'onTimeout'.
52
53Each action is defined via the following parameters:
54 - 'javaOnly' -- run the action only for java applications, false by default
55 - 'app' -- an application to run, mandatory parameter
56 - 'args' -- application command line arguments, none by default
57 - 'params' -- a structure which defines how an application should be run,
58 described below
59
60Actions listed in 'onTimeout' are "patterned" actions. Besides the parameters
61listed above, they also have 'pattern' parameter -- a string which will be
62replaced by PID in 'args' parameter before action execution.
63
64'params' structure has the following parameters:
65 - repeat -- how many times an action will be run, 1 by default
66 - pause -- delay in ms between iterations, 500 by default
67 - timeout -- time limitation for iteration in ms, 20 000 by default
68 - stopOnError -- if true, an action will be interrupted after the first error,
69 false by default
70
71From '<platform>.properties', the library reads the following parameters
72 - 'config.execSuffix' -- a suffix for all binary application file names
73 - 'config.getChildren' -- a "patterned" action used to get the list of all
74 children
75
76For simplicity we use parameter values inheritance. This means that we are
77looking for the most specified parameter value. If we do not find it, we are
78trying to find less specific value by reducing prefix.
79For example, if properties contains 'p1=A', 'a.p1=B', 'a.b.p1=C', then
80parameter 'p1' will be:
81 - 'C' for 'a.b.c'
82 - 'B' for 'a.c'
83 - 'A' for 'b.c'
84
85RUNNING
86
87To enable the library in jtreg, the following options should be set:
88 - '-timeoutHandlerDir' points to the built jar ('jtregFailureHandler.jar')
89 - '-observerDir' points to the built jar
90 - '-timeoutHandler' equals to jdk.test.failurehandler.jtreg.GatherProcessInfoTimeoutHandler
91 - '-observer' equals to jdk.test.failurehandler.jtreg.GatherDiagnosticInfoObserver
92
93In case of environment issues during an action execution, such as missing
94application, hung application, lack of disk space, etc, the corresponding
95warning appears and the library proceeds to next action.
96
97EXAMPLES
98
99$ ${JTREG_HOME}/bin/jtreg -jdk:${JAVA_HOME}                                   \
100 -timeoutHandlerDir:./image/lib/jtregFailureHandler.jar                       \
101 -observerDir:./image/lib/jtregFailureHandler.jar                             \
102 -timeoutHandler:jdk.test.failurehandler.jtreg.GatherProcessInfoTimeoutHandler\
103 -observer:jdk.test.failurehandler.jtreg.GatherDiagnosticInfoObserver         \
104 ${WS}/hotspot/test/
105
106