Red Hat SummitCe contenu n'est pas disponible dans la langue sélectionnée.
Chapter 13. Configuring Transactions
13.1. Transactions Subsystem Configuration
13.1.1. Configuring the Transaction Manager
You can configure the transaction manager using the web-based management console or the command line management CLI.
Configuring the Transaction Manager Using the Management Console
The following steps explain how to configure the transaction manager using the web-based management console:
- Select the Configuration tab from the top of the screen.
- If you are running JBoss EAP as a managed domain, choose the desired profile to modify.
- From the Subsystem list, select Transactions and click View.
- Click Edit on the appropriate tab for the settings that you want to edit, such as Recovery for recovery options.
- Make the necessary changes and click Save to save the changes.
- Click Need Help? to display help text.
Configuring the Transaction Manager Using the Management CLI
Using the management CLI, you can configure the transaction manager using a series of commands. The commands all begin with /subsystem=transactions for a standalone server or /profile=default/subsystem=transactions/ for the default profile in a managed domain.
For a detailed listing of all the transaction manager configuration options, see the Transaction Manager Configuration Options for JBoss EAP.
13.1.2. Configuring the Transaction Manager Using System Properties
In addition to configuring the transaction manager options using the management console or management CLI, many transaction manager options are also configurable using system properties.
However, the following options are configurable only using system properties. They are not configurable using the management CLI or management console.
| Property Name | Description |
|---|---|
| RecoveryEnvironmentBean.periodicRecoveryPeriod | Interval between recovery attempts, in seconds.
|
| RecoveryEnvironmentBean.recoveryBackoffPeriod | Interval between the first and second recovery passes, in seconds.
|
| RecoveryEnvironmentBean.periodicRecoveryInitializationOffset | Interval before first recovery pass, in seconds.
|
| RecoveryEnvironmentBean.expiryScanInterval | Interval between expiry scans, in hours.
|
The following is an example of these system properties configured in the standalone.xml server configuration file.
<system-properties>
<property name="RecoveryEnvironmentBean.periodicRecoveryPeriod" value="180"/>
<property name="RecoveryEnvironmentBean.recoveryBackoffPeriod" value="20"/>
<property name="RecoveryEnvironmentBean.periodicRecoveryInitializationOffset" value="5"/>
<property name="RecoveryEnvironmentBean.expiryScanInterval" value="24"/>
</system-properties>For more information on how to configure system properties, see System Properties.
13.1.3. Configuring Your Datasource to Use JTA
This task shows you how to enable Java Transaction API (JTA) on your datasource.
Prerequisites
- Your database must support Java Transaction API. If in doubt, consult the documentation for your database.
Create a non-XA datasource.
NoteXA datasources are already JTA capable by default.
Configuring the Datasource to use Java Transaction API
Use the following management CLI command to set the
jtaattribute totrue./subsystem=datasources/data-source=DATASOURCE_NAME:write-attribute(name=jta,value=true)NoteIn a managed domain, precede this command with
/profile=PROFILE_NAME.Reload the server for the changes to take effect.
reload
Your datasource is now configured to use JTA.
13.1.4. About Transaction Log Messages
You can track the transaction status while keeping the log files readable by using the DEBUG log level for the transaction logger. For detailed debugging, use the TRACE log level. Refer to Configuring Logging for the Transactions Subsystem for information on configuring the transaction logger.
Transaction Manager (TM) can generate a lot of logging information when configured to log in the TRACE log level. Following are some of the most commonly-seen messages. This list is not comprehensive, so you may see messages other than these.
| Transaction Begin |
When a transaction begins, a method |
| Transaction Commit |
When a transaction commits, a method |
| Transaction Rollback |
When a transaction rolls back, a method |
| Transaction Timeout |
When a transaction times out, a method |
13.1.5. Configuring Logging for the Transactions Subsystem
You can control the amount of information logged about transactions, independent of other logging settings in JBoss EAP. You can configure the logging settings using the management console or the management CLI.
Configuring the Transaction Logger Using the Management Console
Navigate to the Logging subsystem configuration.
- In the management console, click the Configuration tab. If you use a managed domain, you must first choose the appropriate server profile.
- Select the Logging subsystem and click View.
Edit the
com.arjunaattributes.Select the Log Categories tab. The
com.arjunaentry is already present. Selectcom.arjunaand click Edit in the Attributes section. You can change the log level and choose whether to use parent handlers or not.Log Level:
As transactions can produce a lot of logging output, the default logging level is set to
WARNso that the server log is not overwhelmed by transaction output. If you need to check transaction processing details, use theTRACElog level so that transaction IDs are shown.Use Parent Handlers:
Parent handler indicates whether the logger should send its output to its parent logger. The default behavior is
true.
- Click Save to save the changes.
Configuring the Transaction Logger Using the Management CLI
Use the following command to set the logging level from the management CLI. For a standalone server, remove the /profile=default from the command.
/profile=default/subsystem=logging/logger=com.arjuna:write-attribute(name=level,value=VALUE)13.1.6. Tuning the Transactions Subsystem
For tips on optimizing performance for the transactions subsystem, see the Transactions Subsystem Tuning section of the Performance Tuning Guide.
13.2. Transaction Administration
13.2.1. Browse and Manage Transactions
The management CLI supports the ability to browse and manipulate transaction records. This functionality is provided by the interaction between the TM and the management API of JBoss EAP.
The TM stores information about each pending transaction and the participants involved the transaction, in a persistent storage called the object store. The management API exposes the object store as a resource called the log-store. The probe operation reads the transaction logs and creates a node path for each record. You can call the probe operation manually, whenever you need to refresh the log-store. It is normal for transaction logs to appear and disappear quickly.
Refresh the Log Store
The following command refreshes the log store for server groups which use the profile default in a managed domain. For a standalone server, remove the profile=default from the command.
/profile=default/subsystem=transactions/log-store=log-store:probe
View All Prepared Transactions
To view all prepared transactions, first refresh the log store, then run the following command, which functions similarly to a file system ls command.
ls /profile=default/subsystem=transactions/log-store=log-store/transactions
Or
/host=master/server=server-one/subsystem=transactions/log-store=log-store:read-children-names(child-type=transactions)
Each transaction is shown, along with its unique identifier. Individual operations can be run against an individual transaction. For more information, see Manage a Transaction.
13.2.1.1. Manage a Transaction
View the Attributes of a Transaction
To view information about a transaction, such as its JNDI name, EIS product name and version, or its status, use the read-resource operation.
/profile=default/subsystem=transactions/log-store=log-store/transactions=0\:ffff7f000001\:-b66efc2\:4f9e6f8f\:9:read-resource
View the Details of a Transaction Participant
Each transaction log contains a child element called participants. Use the read-resource operation on this element to see the details of a participant of the transaction. Participants are identified by their JNDI names.
/profile=default/subsystem=transactions/log-store=log-store/transactions=0\:ffff7f000001\:-b66efc2\:4f9e6f8f\:9/participants=java\:\/JmsXA:read-resource
The result may look similar to this:
{
"outcome" => "success",
"result" => {
"eis-product-name" => "ActiveMQ",
"eis-product-version" => "2.0",
"jndi-name" => "java:/JmsXA",
"status" => "HEURISTIC",
"type" => "/StateManager/AbstractRecord/XAResourceRecord"
}
}
The outcome status shown here is in a HEURISTIC state and is eligible for recovery. See Recover a Transaction Participant for more details.
In special cases it is possible to create orphan records in the object store, that is XAResourceRecords, which do not have any corresponding transaction record in the log. For example, XA resource prepared but crashed before the TM recorded and is inaccessible for the domain management API. To access such records you need to set management option expose-all-logs to true. This option is not saved in management model and is restored to false when the server is restarted.
/profile=default/subsystem=transactions/log-store=log-store:write-attribute(name=expose-all-logs, value=true)
You can use this alternate command, which shows participant IDs of transaction in an aggregated form.
/host=master/server=server-one/subsystem=transactions/log-store=log-store/transactions=0\:ffff7f000001\:-b66efc2\:4f9e6f8f\:9:read-children-names(child-type=participants)
Delete a Transaction
Each transaction log supports a delete operation, to delete the transaction log representing the transaction.
/profile=default/subsystem=transactions/log-store=log-store/transactions=0\:ffff7f000001\:-b66efc2\:4f9e6f8f\:9:delete
This deletes all participants in the transaction as well.
Typically, you would leave participant log management to the recovery system or to the transaction log that owns it, but the delete operation is available for cases when you know it is safe to do so. In the case of heuristically completed XA resources, a forget call is triggered so that XA resource vendor logs are cleaned correctly. If this forget call fails, by default the delete operation will still succeed. You can override this behavior by setting the ObjectStoreEnvironmentBean.ignoreMBeanHeuristics system property to false.
Recover a Transaction Participant
Each transaction participant supports recovery by using the recover operation.
/profile=default/subsystem=transactions/log-store=log-store/transactions=0\:ffff7f000001\:-b66efc2\:4f9e6f8f\:9/participants=2:recover
If the transaction participant’s status is HEURISTIC, the recover operation switches the status to PREPARE and asks the periodic recovery process to replay the commit.
If the commit is successful, the participant is removed from the transaction log. You can verify this by running the probe operation on the log-store and checking that the participant is no longer listed. If this is the last participant, the transaction is also deleted.
Refresh the Status of a Transaction Participant
If a transaction needs recovery, you can use the refresh operation to be sure it still requires recovery, before attempting the recovery.
/profile=default/subsystem=transactions/log-store=log-store/transactions=0\:ffff7f000001\:-b66efc2\:4f9e6f8f\:9/participants=2:refresh
In JBoss EAP 7.0, transaction failure exceptions are simply serialized and passed over the wire to the client. The client gets a ClassNotFoundException exception if they do not have the exception class on their class path.
JBoss EAP 7.1 introduces the org.wildfly.common.rpc.RemoteExceptionCause exception, which is known to the client as it is from the wildfly library. The server clones the original exception to this new one, puts all field of the original exception to a string form and adds them to the exception’s message. The server then passes only exceptions of type RemoteExceptionCause to the client.
13.2.2. View Transaction Statistics
If transaction manager statistics are enabled, you can view statistics on processed transactions by the transaction manager. See Configuring the Transaction Manager for information about how to enable transaction manager statistics.
You can view statistics using either the management console or the management CLI. In the management console, transaction statistics are available by navigating to the Transactions subsystem from the Runtime tab. From the management CLI, you can view statistics by using include-runtime=true to the read-resource operation. For example:
/subsystem=transactions:read-resource(include-runtime=true)
The following table shows the management console display name, management CLI attribute, and description for each transaction statistic.
| Display Name | Attribute | Description |
|---|---|---|
| Aborted | number-of-aborted-transactions | The number of aborted transactions. |
| Application Failures | number-of-application-rollbacks | The number of failed transactions, including timeouts, whose failure origin was an application. |
| Average Commit Time | average-commit-time | The average time of transaction commit, in nanoseconds, measured from when the client calls commit until the transaction manager determines that it was successful. |
| Committed | number-of-committed-transactions | The number of committed transactions. |
| Heuristics | number-of-heuristics | The number of transactions in a heuristic state. |
| Inflight Transactions | number-of-inflight-transactions | The number of transactions which have begun but not yet terminated. |
| Nested Transactions | number-of-nested-transactions | The total number of nested transactions created. |
| Number of Transactions | number-of-transactions | The total number of transactions created, including nested. |
| Resource Failures | number-of-resource-rollbacks | The number of failed transactions whose failure origin was a resource. |
| System Failures | number-of-system-rollbacks | The number of transactions that have been rolled back due to internal system errors. |
| Timed Out | number-of-timed-out-transactions | The number of transactions that have rolled back due to timeout. |
13.2.3. Transactions Object Store
Transactions need a place to store objects. One of the options for object storage is a JDBC datasource. If performance is a particular concern, the JDBC object store can be slower than a file system or ActiveMQ journal object store.
If the transactions subsystem is configured to use Apache ActiveMQ Artemis journal as storage type for transaction logs, then two instances of JBoss EAP are not permitted to use the same directory for storing the journal. Application server instances can not share the same location and each has to configure a unique location for it.
Losing a transaction object store can lead to losing data consistency. Thus, the object store needs to be placed on a safe drive.
Use a JDBC Datasource as a Transactions Object Store
Follow the below steps to use a JDBC datasource as a transactions object store.
-
Create a datasource, for example,
TransDS. For instructions, see Create a Non-XA datasource. Note that the datasource’s JDBC driver must be installed as a core module, not as a JAR deployment, for the object store to work properly. Set the datasource’s
jtaattribute tofalse./subsystem=datasources/data-source=TransDS:write-attribute(name=jta, value=false)
Set the
jdbc-store-datasourceattribute to the JNDI name for the datasource to use, for example,java:jboss/datasources/TransDS./subsystem=transactions:write-attribute(name=jdbc-store-datasource, value=java:jboss/datasources/TransDS)
Set the
use-jdbc-storeattribute totrue./subsystem=transactions:write-attribute(name=use-jdbc-store, value=true)
- Restart the JBoss EAP server for the changes to take effect.
Transactions JDBC Store Attributes
The following table identifies all of the available attributes related to JDBC object storage.
Attribute names in this table are listed as they appear in the management model, for example, when using the management CLI. See the schema definition file located at EAP_HOME/docs/schema/wildfly-txn_4_0.xsd to view the elements as they appear in the XML, as there may be differences from the management model.
| Property | Description |
|---|---|
| use-jdbc-store |
Set this to |
| jdbc-store-datasource | The JNDI name of the JDBC datasource used for storage. |
| jdbc-action-store-drop-table |
Whether to drop and recreate the action store tables at launch. The default is |
| jdbc-action-store-table-prefix | The prefix for the action store table names. |
| jdbc-communication-store-drop-table |
Whether to drop and recreate the communication store tables at launch. The default is |
| jdbc-communication-store-table-prefix | The prefix for the communication store table names. |
| jdbc-state-store-drop-table |
Whether to drop and recreate the state store tables at launch. The default is |
| jdbc-state-store-table-prefix | The prefix for the state store table names. |
Use the ActiveMQ Journal Object Store
Follow the below steps to use an ActiveMQ journal object store.
Set the
use-journal-storeattribute totrue./subsystem=transactions:write-attribute(name=use-journal-store,value=true)
- Restart the JBoss EAP server for the changes to take effect.
