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