Skip to content

Latest commit

 

History

History
91 lines (66 loc) · 4.8 KB

CONFIGURE_BYTEMAN.adoc

File metadata and controls

91 lines (66 loc) · 4.8 KB
Raw

Configure Byteman for Use with the Quickstarts

Summary

Byteman is a tool that simplifies tracing and testing of Java programs. It allows you to insert extra Java code into your application, either as it is loaded during JVM startup or after it has already started running. This code can be used to trace what the application is doing and to monitor and debug deployments to be sure it is operating correctly. You can also use Byteman to inject faults or synchronization code when testing your application.

A few of the quickstarts use Byteman to demonstrate distributed transaction processing and crash recovery, for example, to halt an application server in the middle of a distributed transaction to demonstrate crash recovery.

The following sections describe the steps necessary to install, configure, and use Byteman with these quickstarts.

Note
 See Use of EAP_HOME and JBOSS_HOME Variables for information about the Red Hat JBoss Enterprise Application Platform installation path.

Download and Configure Byteman

  1. Download Byteman from http://www.jboss.org/byteman/downloads/.

  2. Extract the ZIP file to a directory of your choice. In the instructions below, we refer to this directory as BYTEMAN_HOME.

  3. By default, the Byteman download provides unrestricted permissions to others which can cause a problem when running Ruby commands for the OpenShift quickstarts. To restrict the permissions to others, open a terminal and type the following:

    $ chmod -R o-rwx BYTEMAN_HOME/

Clear the Transaction ObjectStore

Transaction objectstore data remaining from previous tests can prevent Byteman from working properly. You must remove any remaining data before running new Byteman tests. If you are using the default file based transaction logging store:

  1. Open a terminal and type the following:

    $ ls EAP_HOME/standalone/data/tx-object-store/ShadowNoFileLockStore/defaultStore/StateManager/BasicAction/TwoPhaseCoordinator/AtomicAction/

  2. If this directory exists and contains any files, delete them before starting the server:

    $ rm -rf EAP_HOME/standalone/data/tx-object-store/ShadowNoFileLockStore/defaultStore/StateManager/BasicAction/TwoPhaseCoordinator/AtomicAction/*

  3. On Windows, use the file manager to accomplish the same result.

Use Byteman to Halt the Application

Note
 The Byteman scripts only work in JTA mode. They do not work in JTS mode. If you have configured the server for a quickstart that uses JTS, you must follow the quickstart instructions to remove the JTS configuration from the JBoss EAP server before making the following changes. Otherwise Byteman will not halt the server.

When instructed to use Byteman to halt the application, perform the following steps:

  1. Find the appropriate configuration file for your operating system in the list below.

    • For Linux: EAP_HOME/bin/standalone.conf

    • For Windows: EAP_HOME\bin\standalone.conf.bat

  1. Important: Make a backup copy of this configuration file before making any modifications!

  2. Open the configuration file and append the text specified in the quickstart README file instructions to the end of the configuration file. Be sure to replace the BYTEMAN_HOME with the path to the Byteman download and the QUICKSTART_HOME with the path to the quickstarts.

    The following is an example of of the configuration changes needed for the jta-crash-rec quickstart.

    • For Linux:

      JAVA_OPTS="-javaagent:/BYTEMAN_HOME/lib/byteman.jar=script:/QUICKSTART_HOME/jta-crash-rec/src/main/scripts/xa.btm ${JAVA_OPTS}"

    • For Windows:

      SET "JAVA_OPTS=%JAVA_OPTS% -javaagent:C:__BYTEMAN_HOME__\lib\byteman.jar=script:C:__QUICKSTART_HOME__\jta-crash-rec\src\main\scripts\xa.btm %JAVA_OPTS%"

Disable the Byteman Script

When you have completed testing the quickstart, replace the server configuration file with the backup copy you created above to disable Byteman.