Persistent Data

This section provides information to help you administer Business Transaction Management persistent data and includes the following subsections:

Configuring the Business Transaction Management Database Credentials

When you installed Business Transaction Management, you configured it to use an Oracle database. If the credentials used for accessing the database change, you must modify the associated setting in Business Transaction Management accordingly.

To modify the database credentials setting:

  1. Choose Admin > Edit Database Settings.

    The Edit Database Settings tool opens. This tool lets you set the user name and password used by the Business Transaction Management central services to access the Business Transaction Management databases.

    Note:

    Do not select the Embedded Database option. All three databases should have the External Database option selected.
  2. Edit the user name and password as appropriate for each database.

  3. Click Apply.

Setting up the Message Log Database

If you enable message logging on a transaction, then you must ensure that a database is set up for the monitors to log messages to. During installation and initial configuration of Business Transaction Management, you should have created a message log database (messageLogDB) and provided connection settings for this database. These connection settings were automatically stored in the Default Message Log Database policy and applied to all monitors.

However, you are not restricted to using a single database for message logging. You can create additional databases and configure some monitors to use one database and other monitors another database. You do this by first editing the Criteria section of the default policy so that the policy no longer applies to the monitors that will log to a different database. You then create a new policy for each new database, and use each policy's Criteria section to apply the policy to the appropriate monitors. You must take care that each monitor has only one policy applied to it. For information about creating a message log database, refer to the Business Transaction Management Installation Guide.

If you change the location or the logon credentials of any of your message log databases, then you must reconfigure the settings your monitors use to connect to it. You do this by editing the appropriate message log database policy.

To view the monitors to which an existing message log policy is applied:

  1. Select Administration > System Policies in the Navigator.

  2. Select the policy in the main area.

  3. Click the Targets tab.

To edit or apply a new message log database:

  1. Create or identify the Oracle database instance that you want to use for your message log database.

  2. Open the message log database policy you will use for configuring the database connection:

    If you want to edit the default message log database policy:

    1. Select Administration > System Policies in the Navigator.

    2. Select the Default Message Logging Database Policy in the main area.

    3. Choose Modify > Edit Definition for Default Message Logging Database Policy.

    If you want to apply a new message log database policy, choose Admin > Create System Policy > Message Log Database.

    The Create Message Log Database policy opens.

  3. Ensure that the Database Type is set to Use External Oracle Database.

    Note:

    The embedded database is not supported for production systems.
  4. If you want to allow Business Transaction Management central services to directly access the message log database, ensure that the Allow Central Access option is enabled.

    If this option is disabled, the central services can access the message log database only by way of the monitor.

    Some central services (such as the transaction monitoring component) require access to message content stored in the message log database. These central services can access the database either by way of the monitor or by a direct connection. Using a direct connection improves the performance of message log queries. You should enable this communication channel whenever possible.

    In some deployment scenarios, you might not want the central services querying the database directly and would prefer that the monitor do so on their behalf. One such case is when the monitor and database are firewalled off from the central services. In such a scenario, the central services could communicate with the monitor, but presumably not with the database.

  5. Provide a connection string and user credentials for accessing the database.

    The user whose credentials you provide must have privileges to create and drop tables and indexes.

  6. Adjust the Maximum Transaction Metrics Rows, if necessary.

    In the beginning, you should probably leave this at the default setting.

    This field specifies the maximum number of rows recorded in the temporary tables used for tracking individual transaction start and end messages prior to the computation of aggregated transaction measurements. Increasing the value allows the performance server to process transaction measurements more efficiently at the expense of more disk usage by the message log database.

  7. You can edit advanced options by enabling the Show Advanced Options checkbox.

    The following table describes the advanced options:

    Advanced Options UI Default Setting Description
    Indexer Tuning Parameters - -
    Use Auto Statistics enabled Boolean

    If this parameter is enabled, the monitor gathers database statistics from the database on a regular basis. It is essential that up-to-date database statistics are maintained to allow message log queries to run efficiently. The statistics are gathered based on the number of inserts to the database that have occurred.

    Log Bundle Read Batch Size 300 Integer

    Determines how many messages are processed by the indexer in a single database transaction.

    Indexer Wakeup Interval 10 Integer - time (in seconds)

    Determines how often the indexer should wake up to check for any impending work.

    Clean Database Check Interval 120 Integer - time (in seconds)

    Determines the interval at which the indexer performs various maintenance tasks. When performing maintenance, the indexer:

    1. Deletes expired information from the database.

    2. Cleans the summary statistics table.

    3. Removes database tables which hold the result from expired cursors.

    Clean Cursors Check Interval 3600 Integer - time (in seconds)

    Determines the interval at which the indexer will remove expired query results from the database.

    Although this task is part of the indexer's normal maintenance, this may need to be done more often than other tasks.

    Stop Indexing disabled Boolean

    If set to true, this option tells the indexer to suspend all activity. Content to be indexed will still be captured by active logging policies, but will not be transferred from on-disk storage into the database until indexing is resumed.

    This option is especially useful during times of heavy message traffic, when optimization of resources and a steady flow of traffic is more important than being able to inspect indexed messages. You can later set the Stop Indexing value to false to allow Business Transaction Management to index the messages and enter them into your database.

    Note: Be aware that during the time the indexer is suspended, Business Transaction Management does nothing to manage the disk space being used. It is up to you to make sure that there is enough empty disk space to capture messages being logged by logging policies.

    Database Error Min Delay 10 Integer - time (in seconds)

    Specifies the minimum amount of time the indexer will wait before retrying logging-related database operations when a database error occurs. On each successive failure, the delay will be adjusted upward by multiplying the current delay by the value of the Database Error Delay Expansion Factor parameter. The maximum wait time between retries is bounded by Database Error Max Delay.

    An example of a database error that this parameter applies to would be the monitor being unable to contact the database. For example, at the default settings, if the monitor loses its connection to the database, it will attempt to reconnect after 10 seconds. If it cannot reconnect, it will wait 20 seconds and try again, and so on. The longest it will wait between attempts is 3600 seconds (1 hour).

    Database Error Max Delay 3600 Integer - time (in seconds)

    See description for Database Error Min Delay.

    Database Error Delay Expansion Factor 2.0 See description for Database Error Min Delay.
    Max Messages Indexed per Bundle Run 5000 Integer

    Limits the maximum number of messages indexed for a particular endpoint on each indexer run. All endpoints in a single monitor are indexed by a single worker.

    Maximum Indexer Query Execution Time 300 Long - time (in seconds)

    Specifies an upper-bound time limit on the run time of any indexer-initiated query.

    Maximum Query Execution Time 30 Long - time (in seconds)

    Specifies an upper-bound time limit on the run time of any user-initiated query. Users may initiate long-running queries against the message log. Once submitted, users do not have a way to cancel the query and must wait for it to complete.

    The default value for this parameter is 30 seconds. Setting this value to 0 allows all queries to run to their completion regardless of their complexity. For this reason, this setting (0) is not recommended.

    Num Indexer Worker Threads 3 Long

    Specifies the number of worker threads used by the log policy indexer. The indexer cycles through the endpoints with applied logging policies and indexes each endpoint in turn. Adding threads allows for more endpoints to be indexed concurrently.

    Metadata Insert Batch Size 300 Long

    Controls metadata insert statements. This parameter specifies the number of rows of a particular type to batch together before running a SQL statement. The actual batch size is also influenced by the Log Bundle Read Batch Size parameter because it sets the maximum transaction size.

    Message Insert Batch Size 30 Long

    Controls message insert statements. This parameter specifies the number of rows of a particular type to batch together before running a SQL statement. The actual batch size is also influenced by the Log Bundle Read Batch Size parameter because it sets the maximum transaction size.

    Num User Query Connections 5 Long

    Specifies the number of connections to the message log database that should be created for the purpose of user queries. The pool is a shared pool and consists of connections created for system processing (controlled by Num Indexer Worker Threads) and connections for user queries (controlled by Num User Query Connections).

    Reuse Tables disabled Boolean

    The Rotation Interval setting in the Message History policy controls how long messages are retained in the database. By default, messages are deleted by deleting tables and added by adding tables. Enable this setting if you want to reuse tables rather than delete and create new tables. The tables are cleared before being reused. In most scenarios, it is more efficient to leave this setting disabled.

    Min Entries per Fragment 0 Long

    Messages are stored in sets of tables, called fragments. This setting specifies a minimum number of messages a fragment must have before being rotated. This constraint is in addition to that of the Rotation Interval setting in the Message History policy. Note: a request/response pair is considered to be two messages.

    Indexer Setup Data Version - -
    label.IndexerSetupData.generateEndpointStatistics disabled In general, you should enable this field only if requested to do so by the Oracle support team.

    If a monitor is managing an endpoint that participates in a transaction, then the monitor will be running the message indexer (the out-of-band indexer) for the purpose logging. When the message indexer is running in a monitor, the monitor's Status tab includes information about the performance of the message indexer. By default, the tab displays summary indexer statistics for all the endpoints for which message indexing is active. If you enable this setting, the tab's indexer statistics include detailed performance information for each endpoint participating in message indexing.


  8. In the Criteria section, choose the monitors that will log to the database.

    Note:

    Take care that you do not apply more than one message log database policy to any single monitor. This means that if you are applying a new message log database policy, you must first edit the Criteria section of your existing policies so that they don't apply to the same monitors as your new policy. If you apply more than one message log database policy to a single monitor, Business Transaction Management generates a system alert.

    All monitors in a monitor group must log to the same message log database.

  9. Click Apply.

About Persistent Storage Directories

At initial startup, Business Transaction Management creates a set of persistent storage directories to collect system output log entries and store user preferences for the system deployments. By default, the persistent storage directories are created within the application server's installation directory at WL_install_dir/user_projects/domains/domain_name/servers/server_name/btmstorage/*.

Your company's in-house procedures and rules for persistent storage might require you to place the persistent storage directories in a different location. In such a case, you can reconfigure the location of the persistent storage directories.

An installed Business Transaction Management system is composed of a set of deployments (EAR files), which are themselves composed of subdeployments (WAR files). Each subdeployment has an associated persistent storage directory of the same name, minus the “.war”. The following table lists the names of the deployments, subdeployments, and persistent storage directories.

Table 11-2 Business Transaction Management deployments, subdeployments, and persistent storage directories

Deployments (EARs) Subdeployments (WARs) Persistent storage directories

btmMain

btmui

btmcentral

btmcontainer

btmui

btmcentral

btmcontainer

btmPerformanceServer

btmcontainer

btmperformance

btmcontainer

btmperformance

btmTransactionServer

btmcontainer

btmtransaction

btmcontainer

btmtransaction

btmMonitor

btmmonitor

btmmonitor


Relocating Business Transaction Management Persistent Storage Directories

This topic explains how to change the default location of the persistent storage directories for Business Transaction Management deployments to a location outside of the container that hosts these deployments.

This topic contains the following subsections to guide you through the steps required to relocate persistent storage directories:

Backup Before Relocating Persistent Storage Directories

Before following the procedure for relocating persistent storage directory locations, it is very important that you backup any persistent storage directories that already exist in the default location in your container. These default persistent storage directories are created the first time you start up your Business Transaction Management deployments, and are listed in the sections below for each container. You will later need to copy the contents of these directories to the new location you have defined for each deployment's persistent storage directory.

If you do not backup and remove the existing persistent storage directories, the settings in your new persistent storage directories might not be loaded and used the next time you restart Business Transaction Management. By default, Business Transaction Management references the default locations for the deployments' persistent storage directories. If the default directories still exist after you have set their new location, the new location might not be recognized. User preferences are also contained within these storage directories. Business Transaction Management reads these user preference files on each restart.

The default location of the persistent storage directories is WAS_install_dir/profiles/profile_name_name/btmstorage/node_name/server_name/*.

You should document where you relocate your persistent storage directories because you will have to define their location again if you redeploy Business Transaction Management applications (for example, during an upgrade). It is also important to document your new persistent storage directory locations if you want to use the LogMerger tool to collect and merge output of system log messages from these locations. It is easiest to create a configuration file for the LogMerger tool, as that will also act as a documentation source for your new persistent storage directory locations. For more about the LogMerger tool and creating a configuration file for the tool, see logMerger utility.

General Instructions for Relocating Persistent Storage Directories

The following steps outline the general instructions to relocate the persistent storage directories.

  1. Shutdown your Business Transaction Management deployments.

  2. Backup your persistent storage directories and place them in a safe location.

  3. Modify persistent storage directory locations in each deployment's web.xml file.

  4. Move backup copies of the persistent storage directories to the new persistent storage directory locations.

    Note:

    If you do not plan to use the information already collected in the persistent storage directory in the new location, you must create an empty persistent storage directory in the new location using the same name as the original storage directory.
  5. Package and redeploy, if required, each deployment whose persistent storage directories you want to relocate.

  6. Restart your deployments.

  7. Confirm new system output log (logdir) entries in the new locations.

Detailed Instructions for Relocating Persistent Storage Directories

The Business Transaction Management deployments can be found in the following directory locations. You will need to locate these deployments in order to edit the location of the persistent storage directory in each deployment's web.xml file:

WL_install_dir/user_projects/domains/domain_name/server_name/ .wlnotdelete/extract/server_name_n_n/public/btmstorage/*

For example, the btmcentral deployment is located in this directory:

WL_install_dir/user_projects/domains/domain_name/server_name/ .wlnotdelete/extract/server_name_btmcentral_btmcentral/public/btmstorage/btmcentral

To relocate persistent storage directories:

  1. Shut down your Business Transaction Management deployments.

  2. Backup the contents of the current default persistent storage directories and place them in a safe place.

  3. Modify persistent storage directory locations in each deployment's web.xmlfile:

    1. Locate the exploded war file for the deployment whose storage directory you want to change.

    2. From the exploded war file, open the deployment's WEB-INF/web.xml file in a text or XML editor.

    3. Set the new location for the persistent storage directory by setting the storageDirectory parameter value for that deployment as follows:

      Edit the AmberPointDefault value in the following lines and set it to the location of the new storage directory:

      <!-- PERSISTENT STORAGE DIRECTORY To set the persistent storage area to some value, change the value of param-value to some EXISTING directory where you want things stored. -->
      <context-param>
      <param-name>com.amberpoint.storageDirectory</param-name>
      <param-value>AmberPointDefault</param-value> </context-param>
      

      Note:

      You must not change the names of the persistent storage directories. You may change only the path to the directories.

    Examples:

    • On Windows systems – if you want the persistent storage directory for btmcentral to be in C:\btm_data\btmcentral, change the default entry within your btmcentral web.xml file to the following:

      <context-param>
      <param-name>com.amberpoint.storageDirectory</param-name>
      <param-value>C:\btm_data\btmcentral</param-value> </context-param>
      
    • On Unix-like systems – if you want the persistent storage directory for btmcentral to be in opt/webserviceapplogs/btm_data/btmcentral, change the default entry within your btmcentral web.xml file to the following:

      <context-param>
      <param-name>com.amberpoint.storageDirectory</param-name>
      <param-value>/opt/webserviceapplogs/btm_data/btmcentral</param-value>
      </context-param>
      
  4. Create the new empty persistent storage directory in the new location (if you want to start from scratch), or move the backup copy of the original persistent storage directory to the new directory location.

  5. If required, undeploy and redeploy each deployment whose persistent storage directories you want to relocate as follows:

    Note:

    When repackaging system deployments, make sure to include the manifest file associated with the deployment, as this file contains important information required for deployment.
    1. Package the new deployment that includes the edited web.xmlfile into a new application war file.

    2. Undeploy the existing deployment using the WebLogic Console.

    3. Shut down the WebLogic server and delete the original persistent storage directory.

      Note:

      You must delete the persistent storage directories from their default locations. If the deployments find persistent storage directories in their default locations, they will ignore the new directory locations.
    4. Restart WebLogic and redeploy the new system deployment using the WebLogic Console.

  6. Restart your deployments.

  7. Confirm new system output log (logdir) entries in the new locations.

    Data should now be written to the persistent storage directory locations you defined in each deployment's web.xml file. Check to make sure new system service log files (logdir) and other directories have been created in the new location upon container startup.

    If you use the logMerger tool to merge system service logs, make sure that you refer to the new persistent storage directory locations when merging log files.