Chapter 3. Managing Transactions

3.1. Browsing 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 Transaction Manager 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.

Refreshing 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

Viewing 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 Administering a Transaction.

3.2. Administering a Transaction

Viewing the Attributes of a Transaction

To view information about a transaction, such as its Java Naming and Directory Interface 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

Viewing 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 Java Naming and Directory Interface 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)

Deleting a Transaction Participant

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.

Warning

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.

Recovering 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.

Refreshing 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

3.3. Viewing Transaction Statistics

If transaction manager statistics are enabled, you can view statistics on processed transactions by the transaction manager. See the Configuring the Transaction Manager section of the JBoss EAP Configuration Guide 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 Transaction 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.

Table 3.1. Transactions Subsystem Statistics

Display NameAttributeDescription

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.

3.4. Configuring the 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.

Important

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.

Note

Losing a transaction object store can lead to losing data consistency. Thus, the object store needs to be placed on a safe drive.

Using a JDBC Datasource as a Transactions Object Store

Follow the below steps to use a JDBC datasource as a transactions object store.

  1. Create a datasource, for example, TransDS. For instructions on a non-XA datasource, see the Create a Non-XA datasource section of the JBoss EAP Configuration Guide. Note that the datasource’s JDBC driver must be installed as a core module, as described in the JBoss EAP Configuration Guide, not as a JAR deployment, for the object store to work properly.
  1. Set the datasource’s jta attribute to false.

    /subsystem=datasources/data-source=TransDS:write-attribute(name=jta, value=false)
  2. Set the jdbc-store-datasource attribute to the Java Naming and Directory Interface 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)
  3. Set the use-jdbc-store attribute to true.

    /subsystem=transactions:write-attribute(name=use-jdbc-store, value=true)
  4. 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.

Note

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.

Table 3.2. JDBC Store Attributes for Transactions

PropertyDescription

use-jdbc-store

Set this to true to enable the JDBC store for transactions.

jdbc-store-datasource

The Java Naming and Directory Interface 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 false.

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 false.

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 false.

jdbc-state-store-table-prefix

The prefix for the state store table names.

Using the ActiveMQ Journal Object Store

Follow the below steps to use an ActiveMQ journal object store.

  1. Set the use-journal-store attribute to true.

    /subsystem=transactions:write-attribute(name=use-journal-store,value=true)
  2. Restart the JBoss EAP server for the changes to take effect.