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