README revision 1870:4aa2e64eff30 
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
39To build a library, one should simply run make with 'JTREG_HOME' and
40'JAVA_HOME' environment variables set. 'JAVA_HOME' should contain path to JDK,
41'JTREG_HOME' -- path to jtreg.
42
43'image/lib/jtregFailureHandler.jar' is created on successful build.
44
45CONFIGURATION
46
47Properties files are used to configure the library. They define which actions
48to be performed in case of individual test failure or timeout. Each platform
49family uses its own property file (named '<platform>.properties'). For platform
50independent actions, 'common.properties' is used.
51
52Actions to be performed on each failure are listed in 'environment' property.
53Extra actions for timeouts are listed in 'onTimeout'.
54
55Each action is defined via the following parameters:
56 - 'javaOnly' -- run the action only for java applications, false by default
57 - 'app' -- an application to run, mandatory parameter
58 - 'args' -- application command line arguments, none by default
59 - 'params' -- a structure which defines how an application should be run,
60 described below
61
62Actions listed in 'onTimeout' are "patterned" actions. Besides the parameters
63listed above, they also have 'pattern' parameter -- a string which will be
64replaced by PID in 'args' parameter before action execution.
65
66'params' structure has the following parameters:
67 - repeat -- how many times an action will be run, 1 by default
68 - pause -- delay in ms between iterations, 500 by default
69 - timeout -- time limitation for iteration in ms, 20 000 by default
70 - stopOnError -- if true, an action will be interrupted after the first error,
71 false by default
72
73From '<platform>.properties', the library reads the following parameters
74 - 'config.execSuffix' -- a suffix for all binary application file names
75 - 'config.getChildren' -- a "patterned" action used to get the list of all
76 children
77
78For simplicity we use parameter values inheritance. This means that we are
79looking for the most specified parameter value. If we do not find it, we are
80trying to find less specific value by reducing prefix.
81For example, if properties contains 'p1=A', 'a.p1=B', 'a.b.p1=C', then
82parameter 'p1' will be:
83 - 'C' for 'a.b.c'
84 - 'B' for 'a.c'
85 - 'A' for 'b.c'
86
87RUNNING
88
89To enable the library in jtreg, the following options should be set:
90 - '-timeoutHandlerDir' points to the built jar ('jtregFailureHandler.jar')
91 - '-observerDir' points to the built jar
92 - '-timeoutHandler' equals to jdk.test.failurehandler.jtreg.GatherProcessInfoTimeoutHandler
93 - '-observer' equals to jdk.test.failurehandler.jtreg.GatherDiagnosticInfoObserver
94
95In case of environment issues during an action execution, such as missing
96application, hung application, lack of disk space, etc, the corresponding
97warning appears and the library proceeds to next action.
98
99EXAMPLES
100
101$ ${JTREG_HOME}/bin/jtreg -jdk:${JAVA_HOME}                                   \
102 -timeoutHandlerDir:./image/lib/jtregFailureHandler.jar                       \
103 -observerDir:./image/lib/jtregFailureHandler.jar                             \
104 -timeoutHandler:jdk.test.failurehandler.jtreg.GatherProcessInfoTimeoutHandler\
105 -observer:jdk.test.failurehandler.jtreg.GatherDiagnosticInfoObserver         \
106 ${WS}/hotspot/test/
107
108