README revision 1870:4aa2e64eff30
148187SkatoCopyright (c) 2015, Oracle and/or its affiliates. All rights reserved. 248516SkatoDO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 348516Skato 448516SkatoThis code is free software; you can redistribute it and/or modify it 548516Skatounder the terms of the GNU General Public License version 2 only, as 648516Skatopublished by the Free Software Foundation. 748516Skato 848516SkatoThis code is distributed in the hope that it will be useful, but WITHOUT 948516SkatoANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1048516SkatoFITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1148516Skatoversion 2 for more details (a copy is included in the LICENSE file that 1248516Skatoaccompanied this code). 1348516Skato 1448516SkatoYou should have received a copy of the GNU General Public License version 1548516Skato2 along with this work; if not, write to the Free Software Foundation, 1648516SkatoInc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 1748516Skato 1848516SkatoPlease contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 1948516Skatoor visit www.oracle.com if you need additional information or have any 2048516Skatoquestions. 2148516Skato 2248516Skato 2348516Skato 2448516SkatoDESCRIPTION 2548516Skato 2650477SpeterThe purpose of this library is gathering diagnostic information on test 2748187Skatofailures and timeouts. The library runs platform specific tools, which are 2848187Skatoconfigured in the way described below. The collected data will be available 2948187Skatoin HTML format next to JTR files. 3048187Skato 3148187SkatoThe library uses JTHarness Observer and jtreg TimeoutHandler extensions points. 3248187Skato 3348187SkatoDEPENDENCES 3466870Skato 3566870SkatoThe library requires jtreg 4b13+ and JDK 7+. 3648187Skato 3748187SkatoBUILDING 3848187Skato 3948187SkatoTo build a library, one should simply run make with 'JTREG_HOME' and 4048187Skato'JAVA_HOME' environment variables set. 'JAVA_HOME' should contain path to JDK, 4148187Skato'JTREG_HOME' -- path to jtreg. 4280371Snyan 4380371Snyan'image/lib/jtregFailureHandler.jar' is created on successful build. 4448187Skato 4580371SnyanCONFIGURATION 4680371Snyan 4780371SnyanProperties files are used to configure the library. They define which actions 4848187Skatoto be performed in case of individual test failure or timeout. Each platform 4948187Skatofamily uses its own property file (named '<platform>.properties'). For platform 5048187Skatoindependent actions, 'common.properties' is used. 5180371Snyan 5280371SnyanActions to be performed on each failure are listed in 'environment' property. 5380371SnyanExtra actions for timeouts are listed in 'onTimeout'. 5480371Snyan 5580371SnyanEach action is defined via the following parameters: 5680371Snyan - 'javaOnly' -- run the action only for java applications, false by default 5780371Snyan - 'app' -- an application to run, mandatory parameter 5880371Snyan - 'args' -- application command line arguments, none by default 5980371Snyan - 'params' -- a structure which defines how an application should be run, 6080371Snyan described below 6180371Snyan 6280371SnyanActions listed in 'onTimeout' are "patterned" actions. Besides the parameters 6380371Snyanlisted above, they also have 'pattern' parameter -- a string which will be 6480371Snyanreplaced by PID in 'args' parameter before action execution. 6580371Snyan 6680371Snyan'params' structure has the following parameters: 6780371Snyan - repeat -- how many times an action will be run, 1 by default 6848187Skato - pause -- delay in ms between iterations, 500 by default 6980371Snyan - timeout -- time limitation for iteration in ms, 20 000 by default 7080371Snyan - stopOnError -- if true, an action will be interrupted after the first error, 7180371Snyan false by default 7280371Snyan 7380371SnyanFrom '<platform>.properties', the library reads the following parameters 7480371Snyan - 'config.execSuffix' -- a suffix for all binary application file names 7580371Snyan - 'config.getChildren' -- a "patterned" action used to get the list of all 7680371Snyan children 7780371Snyan 7880371SnyanFor simplicity we use parameter values inheritance. This means that we are 7980371Snyanlooking for the most specified parameter value. If we do not find it, we are 8080371Snyantrying to find less specific value by reducing prefix. 8180371SnyanFor example, if properties contains 'p1=A', 'a.p1=B', 'a.b.p1=C', then 8280371Snyanparameter 'p1' will be: 8380371Snyan - 'C' for 'a.b.c' 8480371Snyan - 'B' for 'a.c' 8580371Snyan - 'A' for 'b.c' 8680371Snyan 8748187SkatoRUNNING 8848187Skato 8948187SkatoTo enable the library in jtreg, the following options should be set: 9048187Skato - '-timeoutHandlerDir' points to the built jar ('jtregFailureHandler.jar') 9148187Skato - '-observerDir' points to the built jar 9248187Skato - '-timeoutHandler' equals to jdk.test.failurehandler.jtreg.GatherProcessInfoTimeoutHandler 9348187Skato - '-observer' equals to jdk.test.failurehandler.jtreg.GatherDiagnosticInfoObserver 9448187Skato 9548187SkatoIn case of environment issues during an action execution, such as missing 96102265Snyanapplication, hung application, lack of disk space, etc, the corresponding 9748187Skatowarning appears and the library proceeds to next action. 9848187Skato 9948187SkatoEXAMPLES 10048187Skato 10148187Skato$ ${JTREG_HOME}/bin/jtreg -jdk:${JAVA_HOME} \ 10248187Skato -timeoutHandlerDir:./image/lib/jtregFailureHandler.jar \ 10348187Skato -observerDir:./image/lib/jtregFailureHandler.jar \ 10480371Snyan -timeoutHandler:jdk.test.failurehandler.jtreg.GatherProcessInfoTimeoutHandler\ 10580371Snyan -observer:jdk.test.failurehandler.jtreg.GatherDiagnosticInfoObserver \ 106111119Simp ${WS}/hotspot/test/ 107102265Snyan 10879702Snyan