BEA Home | Events | Solutions | Partners | Products | Services | Download | Developer Center | WebSUPPORT
| WebLogic Server Doc Home | Programming WebLogic JTA | Previous Topic | Next Topic | Contents | Index | View as PDF

Troubleshooting Transactions

The following sections describe troubleshooting tools and tasks for use in determining why transactions fail and deciding what actions to take to correct the problem.

- Overview of Troubleshooting Transactions

- Troubleshooting Tools

- Debugging Tips

- Handling Heuristic Completions

- Transaction System Recovery

Overview of Troubleshooting Transactions

WebLogic Server includes the ability to monitor currently running transactions and ensure that adequate information is captured in the case of heuristic completion. It also provides the ability to monitor performance of database queries, transactional requests, and bean methods.

Troubleshooting Tools

WebLogic Server provides the following aids to transaction troubleshooting:

- Exceptions

- Transaction identifier

- Transaction naming and properties

- Transaction status

- Transaction statistics

- Transaction monitoring

- Transaction logging

Exceptions

WebLogic JTA supports all standard JTA exceptions. For more information about standard JTA exceptions, see the Javadoc for the javax.transaction and javax.transaction.xa package APIs

In addition to the standard JTA exceptions, WebLogic Server provides the class weblogic.transaction.RollbackException. This class extends javax.transaction.RollbackException and preserves the original reason for a rollback. Before rolling a transaction back, or before setting it to rollbackonly, an application can supply a reason for the rollback. All rollbacks triggered inside the transaction service set the reason (for example, timeouts, XA errors, unchecked exceptions in beforeCompletion, or inability to contact the transaction manager). Once set, the reason cannot be overwritten.

Transaction Identifier

The Transaction Service assigns a transaction identifier (Xid) to each transaction. This ID can be used to isolate information about a specific transaction in a log file. You can retrieve the transaction identifier using the getXID method in the weblogic.transaction.Transaction interface. For detailed information on methods for getting the transaction identifier, see the weblogic.transaction.Transaction Javadoc.

Transaction Name and Properties

WebLogic JTA provides extensions to javax.transaction.Transaction that support transaction naming and user-defined properties. These extensions are included in the weblogic.transaction.Transaction interface.

The transaction name indicates a type of transaction (for example, funds transfer or ticket purchase) and should not be confused with the transaction ID, which identifies a unique transaction on a server. The transaction name makes it easier to identify a transaction type in the context of an exception or a log file.

User-defined properties are key/value pairs, where the key is a string identifying the property and the value is the current value assigned to the property. Transaction property values must be objects that implement the Serializable interface. You manage properties in your application using the set and get methods defined in the weblogic.transaction.Transaction interface. Once set, properties stay with a transaction during its entire lifetime and are passed between machines as the transaction travels through the system. Properties are saved in the transaction log, and are restored during crash recovery processing. If a transaction property is set more than once, the latest value is retained.

For detailed information on methods for setting and getting the transaction name and transaction properties, see the weblogic.transaction.Transaction Javadoc.

Transaction Status

The Java Transaction API provides transaction status codes using the javax.transaction.Status class. Use the getStatusAsString method in weblogic.transaction.Transaction to return the status of the transaction as a string. The string contains the major state as specified in javax.transaction.Status with an additional minor state (such as logging or pre-preparing).

Transaction Statistics

Transaction statistics are provided for all transactions handled by the transaction manager on a server. These statistics include the number of total transactions, transactions with a specific outcome (such as committed, rolled back, or heuristic completion), rolled back transactions by reason, and the total time that transactions were active. For detailed information on transaction statistics, see the Administration Console Online Help.

Transaction Monitoring

You can monitor transactions in progress using the WebLogic Console. In addition to displaying statistics, as described in Transaction Statistics, you can display the following:

- transactions by name, including rollback and time active information

- transactions by resource, including statistics on total, committed, and rolled back transactions

- all active transactions, including information on status, servers, resources, properties, and the transaction identifier

Transaction Log

Each server has a transaction log which records information about the propagation of a transaction through the system. The transaction log is written to persistent storage and assists the server in recovering from system crashes and network failures. You cannot directly access the transaction log; the file is in a binary format.

The transaction log consists of multiple files. Each file is subject to garbage collection; when none of the records in a transaction log file are needed, the system deletes the file and returns the disk space to the file system. In addition, the system creates a new transaction log file if the previous log file becomes too large.

Transaction log files are uniquely named using a pathname prefix, the server name, a four-digit numeric suffix, and a file extension. Specify a value for the TransactionLogFilePrefix server attribute using the WebLogic Console to set the pathname prefix. The TransactionLogFilePrefix attribute should be set so that transaction log files are created on a highly available file system, for example, on a RAID device.

On a UNIX system with a server name of websvr, you might see the following log files:

>     /usr7/applog1/websvr0000.tlog
>     /usr7/applog1/websvr0001.tlog
>     /usr7/applog1/websvr0002.tlog

Similarly, on a Windows NT system, you might see the following log files:

>     C:/weblogic/logA/websvr0000.tlog
>     C:/weblogic/logA/websvr0001.tlog
>     C:/weblogic/logA/websvr0002.tlog

If you notice a large number of transaction log files on your system, this may be an indication of one or more long-running transactions that have not completed. This can be caused by resource manager failures or transactions with especially large timeout values.

If the file system containing the transaction log runs out of space, commit() throws SystemException, and the transaction manager places a message in the system error log. No transactions are committed until more space is available.

When migrating a server to another machine, move the transaction log files as well, keeping all the log files for a server together.

Heuristic Log Files

When importing transactions from a foreign transaction manager into WebLogic Server, the WebLogic Server transaction manager acts as an XA resource coordinated by the foreign transaction manager. In rare catastrophic situations, such as after the transaction abandon timeout expires or if the XA resources participating in the WebLogic Server imported transaction throw heuristic exceptions, the WebLogic Server transaction manager will make a heuristic decision. That is, the WebLogic Server transaction manager will decide to commit or roll back the transaction without input from the foreign transaction manager. If the WebLogic Server transaction manager makes a heuristic decision, it stores the information of the heuristic decision in the heuristic log files until the foreign transaction manager tells it to forget the transaction.

Heuristic log files are stored with transaction log files and look similar to transaction log files with .heur before the .tlog extension. They use the following format:

>     <TLOG_file_prefix>\<server_name><4-digit number>.heur.tlog

On a UNIX system with a server name of websvr, you might see the following heuristic log files:

>     /usr7/applog1/websvr0000.heur.tlog
>     /usr7/applog1/websvr0001.heur.tlog
>     /usr7/applog1/websvr0002.heur.tlog

Similarly, on a Windows system, you might see the following heuristic log files:

>     C:\weblogic\logA\websvr0000.heur.tlog
>     C:\weblogic\logA\websvr0001.heur.tlog
>     C:\weblogic\logA\websvr0002.heur.tlog

Debugging Tips

Use the naming properties of transactions to isolate and identify problem transactions.

Debugging transactions may require fault isolation to be performed between WebLogic JTA and the participating resources.

Handling Heuristic Completions

An heuristic completion (or heuristic decision) occurs when a resource makes a unilateral decision during the completion stage of a distributed transaction to commit or rollback updates. This can leave distributed data in an indeterminate state. Network failures or transaction timeouts are possible causes for heuristic completion. In the event of an heuristic completion, one of the following heuristic outcome exceptions may be thrown:

- HeuristicRollback - one resource participating in a transaction decided to autonomously rollback its work, even though it agreed to prepare itself and wait for a commit decision. If the Transaction Manager decided to commit the transaction, the resource's heuristic rollback decision was incorrect, and might lead to an inconsistent outcome since other branches of the transaction were committed.

- HeuristicCommit - one resource participating in a transaction decided to autonomously commit its work, even though it agreed to prepare itself and wait for a commit decision. If the Transaction Manager decided to rollback the transaction, the resource's heuristic commit decision was incorrect, and might lead to an inconsistent outcome since other branches of the transaction were rolled back.

- HeuristicMixed - the Transaction Manager is aware that a transaction resulted in a mixed outcome, where some participating resources committed and some rolled back. The underlying cause was most likely heuristic rollback or heuristic commit decisions made by one or more of the participating resources.

- HeuristicHazard - the Transaction Manager is aware that a transaction might have resulted in a mixed outcome, where some participating resources committed and some rolled back. But system or resource failures make it impossible to know for sure whether a Heuristic Mixed outcome definitely occurred. The underlying cause was most likely heuristic rollback or heuristic commit decisions made by one or more of the participating resources.

When an heuristic completion occurs, a message is written to the server log. Refer to your database vendor documentation for instructions on resolving heuristic completions.

Some resource managers save context information for heuristic completions. This information can be helpful in resolving resource manager data inconsistencies. If the ForgetHeuristics attribute is selected (set to true) on the JTA panel of the WebLogic Console, this information is removed after an heuristic completion. When using a resource manager that saves context information, you may want to set the ForgetHeuristics attribute to false.

Transaction System Recovery

The WebLogic Server transaction manager is designed to recover from system crashes with minimal user intervention. A prepared transaction is not left unresolved in the resource manager without either a commit or rollback action from the transaction manager, even after multiple crashes.

You can choose to abandon transactions after a specified amount of time. Using the AbandonTimeoutSeconds attribute, you can set the maximum time, in seconds, that a transaction coordinator will persist in attempting to complete a transaction. The default value is 86400 seconds, or 24 hours. After the abandon transaction timer expires, no further attempt is made to resolve the transaction with any resources that are unavailable or unable to acknowledge the transaction outcome.

The transaction manager has the following responsibilities after a system crash:

- Maintain consistency across resources

  If a transaction is committed before a crash, and XAResource.recover() returns the transaction ID, the transaction manager consistently calls XAResource.commit(). If a transaction is not committed before a crash, and XAResource.recover() returns its transaction ID, the transaction manager consistently calls XAResource.rollback(). In other words, a transaction manager crash by itself cannot cause a mixed heuristic completion where some branches are committed and some are rolled back.

- Resolve prepared transactions

  Once the transaction manager has prepared any transaction with a resource manager, it must call XAResource.recover() during crash recovery for that resource manager and eventually resolve (by calling the commit(), rollback(), or forget() method) all transaction IDs returned by recover().

- Persist in achieving transaction resolution

  If a resource manager crashes, the transaction manager must eventually call commit() or rollback() for each prepared transaction until it gets a successful return from commit() or rollback(). The attempts to resolve the transaction and can be limited by setting the AbandonTimeoutSeconds configuration attribute.

- Report heuristic completions

  If the resource manager reports a heuristic commit or heuristic rollback, this is recorded in the server log by the transaction manager, and forget() called if the Forget Heuristics configuration attribute is enabled. If the Forget Heuristics configuration attribute is not enabled, refer to your database vendor's documentation for information in resolving heuristic completions.

Copyright © 2001 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.