JBoss XA-Datasources Test

An XA Datasource is needed to execute a distributed transaction. Generally, a distributed transaction spans 2 or more different datasources. An XA datasource is used instead of the datasource if the target Jboss application:

• Uses the Java Transaction API (JTA)

• Includes multiple database updates within a single transaction

• Accesses multiple resources, such as a database and the Java Messaging Service (JMS), during a transaction

• Uses the same connection pool on multiple servers

Though the XA datasource can use all transaction features of the application server and need fewer physical connections, the XA datasource involves performance overhead along with the risk of a higher deadlock. There may also be a necessity of more physical connections when an emulated XA datasource is used in the target environment. When an XA datasource is used in the target environment, administrators would be required to carefully monitor the XA datasource as the slightest variation in the connections or a higher waiting time for a connection may cause a severe performance overhead on the XA datasource. To overcome such abnormalities, administrators may use the JBoss XA-Datasources test. This test helps the administrators figure out the following:

• The number of connections that are currently available and the number of active connections;

• The number of connections that were created and destroyed using this datasource;

• The time taken to create a connection on this datasource and the maximum time taken for creating a connection;

• How many connections are available in a connection pool and how well the connections of a connection pool are utilized?

• The prepared statement cache size and the number of prepared statements added

• How many times prepared statements are accessed and how well the prepared statement cache caters to the requests for accessing the prepared statements?

Target of the test : A WildFly JBoss server

Agent deploying the test : An internal agent

Outputs of the test : One set of results for each XA datasource of the target WildFly JBoss that is to be monitored

Configurable parameters for the test

Parameters	Description
Test period	How often should the test be executed
Host	The host for which the test is to be configured.
Port	The port at which the specified HOST listens. By default, this is 9990.
SSL	If the WildFly JBoss server being monitored is an SSL-enabled server, then set the SSL flag to Yes. If not, then set the SSL flag to No.
Is JBoss Running In Domain Mode?	Specify whether the server to be monitored is currently running in Domain Mode or not. By default, this flag is set to No which implies that the server is currently running in Standalone Mode. If you have started the target JBoss server using the default web profile configuration in domain mode i.e, if you have executed the ./domain.sh command from the <JBoss_INSTALL_DIR>/bin directory, then specify Yes against this flag.
JBoss Host Name	Specify whether the target server to be monitored is a master or a slave in a JBoss cluster. By default, none will be specified here which implies that the target JBoss server is a standalone server. Refer to Identifying the host name and server instance name of the WildFly JBoss server running in Domain mode to know how to identify whether the target server is a master or slave in your environment.
JBoss Server Instance Name	Specify the name of the server instance that is to be monitored. By default, none will be specified here. Refer to Identifying the host name and server instance name of the WildFly JBoss server running in Domain mode to identify the name of the server instance that is to be monitored.
Management User and Management Password	Specify the credentials of the user who is authorized to access the management console of the target JBoss server. To create a new user, refer to Creating a new management user in the WildFly JBoss server of this document.
Confirm Password	Confirm the Management Password by retyping it here.

Measures made by the test:

Measurement	Description	Measurement Unit	Interpretation
Active count	Indicates the number of active connections in this XA datasource.	Number	A high value is desired for this measure.
Available count	Indicates the number of connections that are currently available for use in this XA datasource.	Number	A low value for this measure indicates that adequate connections are not available in the datasource.
Average blocking time	Indicates the average time spent for blocking a connection during the last measurement period.	Secs
Average creation time	Indicates the average time spent for creating a physical connection during the last measurement period.	Secs	Comparing the value of this measure across the XA datasources will reveal the XA datasource that is the slowest when creating a physical connection.
Created count	Indicates the number of connections that were created in this XA datasource.	Number
Destroyed count	Indicates the number of connections that were destroyed in this XA datasource since the start of the server.	Number
Max creation time	Indicates the maximum time taken to create a connection in this XA datasource.	Secs	Compare the value across the XA datasources to identify the XA datasource that is taking too long to create a connection i.e., you can identify the XA datasource that is the slowest.
Max used count	Indicates the maximum number of connections that were used in this XA datasource.	Number
Max wait time	Indicates the maximum time a user has to wait for a connection in this XA datasource.	Secs	A low value is desired for this measure. An abnormally high value or a sudden increase in the value of this measure is a cause of concern which requires further investigation.
Timed out	Indicates the time taken for a connection to time out.	Mins	Normally, a connection would time out if it has been waiting in the queue for a longer time.
Total blocking time	Indicates the total time taken for a connection to fail or time out.	Secs
Total creation time	Indicates the time taken to create a connection in this XA datasource.	Secs	A low value is desired for this measure.
Maximum pool size	Indicates the maximum number of connections allowed in the connection pool of this XA datasource.	Number	The max-pool-size parameter defines the maximum size of the connection pool. This parameter is more important because it limits the number of active connections to the datasource and thus the concurrent activity on the data source. If this value is set too low it's likely that the platform's hardware resources will be underutilized.
Minimum pool size	Indicates the minimum number of connections that the connection pool of this XA datasource can contain.	Number	The min-pool-size data source parameter defines the minimum size of the connection pool. The default minimum is zero connections, so if a minimum pool size is not specified, no connections will be created in the connection pool when the platform starts. As data source transactions occur, connections will be requested but because the pool defaults to zero on start up, none will be available. The connection pool examines the minimum and maximum parameters, creates connections and places them in the pool. Users of any affected application will experience a delay while this occurs. During periods of inactivity the connection pool will shrink, possibly to the minimum value, and later when transactions occur application performance will again suffer.
PreparedStatement cache size	Indicates the number of prepared statements per connection to be kept open and reused in subsequent requests.	Number	When using the JPA annotations for queries, the result is prepared statements that will be executed against the database. Prepared statements have two phases for execution: preparation of the statement, and execution of the statement. Statement preparation involves significant CPU load so to improve throughput prepared statements can be cached. Statements can be cached either via the JDBC driver or configuration of the data source. To enable caching of prepared statement, add the following two lines to the data source configuration file, a file with the pattern *-ds.xml (where the * is usually your database, such as oracle, mysql, db2, etc.) in the directory: JBOSS_EAP_DIST/jboss-as/server/PROFILE/deploy. Note that the minimal configuration does not support data sources. <prepared-statement-cache-size>100</prepared-statement-cache-size> <shared-prepared-statements>true</shared-prepared-statements> The first line enables the prepared statement cache and sets the size of the cache. This should be large enough to hold all the prepared statements across any and all deployed applications using this particular data source (multiple data sources can be configured). The second line states that if two requests are executed in the same transaction the prepared statement cache should return the same statement. This will avoid the use of CPU cycles in preparing the same statements over and over again, increasing throughput and decreasing response times. The actual improvement will vary according to specific circumstances but is well worth the effort.
PreparedStatement cache access count	Indicates the number of times the prepared statement cache was accessed.	Number
PreparedStatement cache add count	Indicates the number of new prepared statements that were added i.e., cached in the prepared statement cache.	Number
PreparedStatement cache current size	Indicates the number of prepared statements that are currently available in the cache.	Number	If the value of this measure is close to the PreparedStatement cache size measure, then it indicates that the prepared statement cache is almost running out of space.
vPreparedStatement cache delete count	Indicates the number of prepared statements that are deleted from the prepared statement cache.	Number
PreparedStatement cache hit count	Indicates the number of times the statement was accessed from the prepared statement cache.	Number	A high value is desired for this measure.
PreparedStatement cache miss count	Indicates the number of times a request for a statement was not serviced from the prepared statement cache.	Number	A high value for this measure is a cause of concern.