|
|
|
|
|
|
| | | |
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
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.
WebLogic Server provides the following aids to transaction troubleshooting:
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.
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.
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 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.
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:
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.
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
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:
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.
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:
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.
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().
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.
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.
|