Defining, Modifying, and Deleting Transactions

A transaction is a sequence of service operations that you want to monitor and manage as one unit. This section explains how you use Business Transaction Management to define transactions, to modify transaction definitions, and to delete transactions.

Keep in mind that the more features you turn on for your transactions, the greater the impact on Business Transaction Management performance, especially with high volume. For example, it is best to restrict message logging to narrow areas of interest rather than to enable it for all operations in a transaction. The following guidelines indicate the relative performance cost of transaction monitoring options:

  • Low: core measurements when the start and end message are the same

  • Medium: segmentation, condition evaluation

  • High: instance logging and message logging

Defining a Transaction

Defining a transaction involves specifying the following information:

  • The operations that participate in the transaction, and the start and end message for the transaction.

  • Whether the transaction should be actively monitored or temporarily quiesced.

  • Whether you want information to be segmented by ip address or consumer.

  • Whether you want to log transaction instances or message content.

  • How you want the system to correlate messages: using fingerprints or using manual keys that you define

  • How long transaction messages should be held by the system.

The following subsections explain how you specify each aspect of the transaction definition.

Selecting Operations and Enabling the Transaction

Once you have defined the operations that participate in a transaction and enabled transaction monitoring, you will be able to view transactions and related services in the Transaction view, create fixed-value and baseline Service Level Agreements (SLA), view summary of link measurements on the Summary tab and other measurements in the appropriate views. For measurements, you will be able to see the number of started and completed transactions, throughput, average response time, maximum response time, and faults.

  1. Select any operation that you want to include in transaction. You can select the operation from any view: service graph, dependency diagram, data grid, or message search tool.

  2. Select Transaction from the Create menu. Business Transaction Management brings up the Transaction tool, which allows you to define all aspects of the transaction.

  3. Select the Definition tab if it is not already selected. Note the basic elements required for a definition as shown on this tab: start message, end message, and maximum transaction duration. The Enable Transaction Monitoring checkbox is enabled by default. Disabling the box allows you to keep a transaction definition while temporarily turning off monitoring.

    In the upper pane, the tool displays all the operations that are dependent upon the operation you selected. By default, the request message of the left-most operation in the dependency chain is designated to be the start operation and the response message of the left-most operation is designated to be the end message. The tool displays the specified starting operation along with all the service operations in the consequent dependency chain. By default message fingerprints are used to correlate messages in a transaction. These are represented in the transaction map with a fingerprint icon. You can choose to have Business Transaction Management correlate messages using manual keys if you like.

  4. By default, the transaction name is based on the starting operation. To assign another name, specify it in the Transaction Name text box.

  5. If you want to change the start and end message selected by default, click on the Start message or End message drop down lists and select an alternate start and end message.

    If the start and end message are not the request/response messages of the same operation, you will need to specify keys with common content for Business Transaction Management to measure performance. You will be prompted for the required information.

  6. To further customize the transaction, use the buttons to the right of the graph to add an operation, connect it to existing operations, to indicate message flow direction, or to remove an operation. You will also need to specify manual keys to connect the operation you have added to an existing operation in your transaction.

  7. A new transaction is enabled by default. This means that Business Transaction Management is monitoring transaction performance, collecting measurements, and evaluating conditions if these have been defined for the transaction.

    To disable a transaction, click the Enable Transaction Monitoring check box. This will turn off measurement collection (segmented and non-segmented), condition evaluation, instance logging and content logging. However, SLA's applied to the transaction will continue to evaluate and potentially fire unless you explicitly disable them. Disabling a transaction is a way of quiescing transaction monitoring without losing the transaction definition.

  8. By default the scope of the transaction (how long it takes for it to complete) is set to one minute. Business Transaction Management uses this value as a guideline in locating transaction messages; it defines the time window within which unique content is expected to appear. You can change this value to a shorter or longer duration for Maximum Transaction Duration), depending on the characteristics of your transactions.

Enabling Segmentation

Business Transaction Management allows you to segment transaction measurements based on ip address and by individual consumer. You use the Segmentation tab of the Transaction tool to enable segmentation. Enabling segmentation allows you to create usage SLAs for the transaction, to see transaction usage by client IP address, and to see transaction measurements by consumer. You can see on the Profile tab which segments are enabled and which property is being used as the consumer property.

You can choose to enable either or both of the segmentation options. The image below show what the tab looks like after segmentation has been enabled and a particular property has been mapped to a consumer. Note the consumer icon.

To enable segmentation:

  1. Select the Segmentation tab of the Transaction tool

  2. To enable client address (ip) segmentation, click the check box Enable client address segmentation.

  3. To enable consumer segmentation, click the check box Enable consumer segmentation.

    Consumer segmentation depends upon defining a property for the transaction's starting message. This property refers to the message element that you want to map to the consumer business object. If you have not already defined this property before you define the transaction, you can do so as shown in steps 4 through 9. If you have defined the property, select it now.

  4. Click the New Property button. Business Transaction Management displays the Create Property tool.

  5. Specify a name for the property, and provide a description if desired.

  6. Property Source: Select the source for the property value: Message content or Header.

  7. Select the Pick from Message.... link, and select the element you want to map to the consumer business object.

  8. Consumer Mapping: Click on the check box Map to consumer through attribute Consumer Name. You can change your selection later if you wish, but you cannot have more than one property mapped to a consumer object.

  9. If you do not want the consumer name displayed exactly because it contains sensitive information, check the Treat as sensitive check box.

  10. Click OK.

Enabling Instance and Message Content Logging

Enabling instance logging allows you to see a list of transaction instances captured in a given time period. These are displayed in the Instances tab of the Transaction view. You can inspect a given instance, view any property values for that instance, and create conditions based on property values. You can also assemble any of these instances.

To enable instance logging:

  1. Select the Logging tab.

  2. Click the check box titled Enable instance and property logging.

Enabling message content logging allows you to view message content for the operations you specify. (In this case, Business Transaction Management logs all messages for the specified operations, not just those belonging to this particular transaction flow.) You can get to the message content in different ways: use the Message Log Search tool to find an operation based on free text search and then open the related transaction instance, or you can drill through to the message log from the Analysis tab and alerts.

To enable message content logging:

  1. Select the Logging tab, and click the check box titled Enable message content logging on selected operations.

  2. Select the operations (messages) whose content you want to log. Logging message content is an expensive operation. It is best to narrow the scope of messages that interest you before you start logging messages.

The example above shows that message content is enabled for the operation checkCredit of the service CreditService.

Correlating Messages in a Transaction Using Manual Keys

By default Business Transaction Management correlates messages in a transaction by computing fingerprints (hash values) based on the content of each message and by pairing incoming messages with outgoing messages all the way to the end of the call chain. Defining manual keys provides an alternate means of correlating messages. Manual correlation is used to add a secondary operation flow to a transaction, to define a transaction whose end message and start message do not belong to the same operation, and to define a missing message condition.

Transaction messages do not have to be correlated by a single method: some messages can be auto-correlated; others can be correlated using manual keys. In order to define a manual key, you must map it to a message property and that property must satisfy certain requirements as explained next.

A manual key is mapped to a message property.

The property can correspond to a single element in a message, to a combination of elements, or to a fragment of an element. You can define the property before you define the manual key

The property you define for the manual key must satisfy two requirements:

  • Its value must be the same for the messages you are correlating.

  • Its value must be unique for the scope of the transaction (the scope is defined by the value of Maximum transaction duration).

For example, in a shopping type application, the order ID is often an excellent choice for a manual key.

You will need to manually correlate operations in the following cases:

  • To add a secondary operation flow to the transaction. This might be necessary in the case of asynchronous systems like JMS or desirable if you want to connect two operation flows that share underlying data but are not causally connected. For example, you have one flow defined by an order entry, and another flow defined by the fulfillment of the order. The same order is involved in two otherwise disjoint processes.

    In this case, you will need to figure out which two operations you want to link, and to find a common element for those two operations that you can map to a message property. The process would be as follows: add the operation to the transaction; connect it to an existing operation in your transaction, and indicate the direction in which the request is going. The two operations will then be shown in the Message Keys tab, where you can connect them using a manual key.

  • To define a transaction whose end message is not the end message of the operation that starts the flow.

    In this case, you will need to find a common element in the starting message and the desired end message that you can map to a message property. When you specify the end message, the system will prompt you for the manual key that will connect the start and end message.

  • To define a missing message condition.

    In a missing message condition, an alert is generated if the target message you specify does not arrive within a given period of time after the start message occurs. In this case, you must define a key for some element that is common to the start and target message. When you define the missing message condition, the system will prompt you for the key that will connect the start and target message.

You use the Message Keys tab of the Create Transaction tool to define the means by which Business Transaction Management correlates operations when you are adding a secondary flow. Note that if a given operation correlates to more than one operation in a dependency flow, you have the option of creating manual keys for each correlation. For example, in the tab shown below, the start operation of OrderService.submit correlates to one of three possible operations. You do not have to use the same key to correlate to the three different operations nor do you have to use the same means of correlation.

To create a manual key to correlate messages:

As mentioned above, the start key and end key of a correlation must be mapped to the same property and the value of the property must be unique to the transaction. You can define the properties you need before you define the correlations or you can access the property tool from the Message Keys tab and define the property at the same time that you are defining the correlation.

  1. Select the Message Keys tab.

  2. Select the start operation for the pair of operations you want to correlate.

  3. Click the Message Fingerprint item for the Start operation of interest to see the key drop down list. Business Transaction Management displays a list of properties for the operation from which you can pick one to use as a manual key.

  4. If a property is displayed that satisfies the requirements specified in the introduction to this procedure, you can select that property to use as a key.

  5. If no property is displayed that will have a unique value on each invocation of the operation, select New Property from the drop down list to open the Property tool and use that tool to define the property you want to use as a message key.

  6. Select the End operation that corresponds to the Start operation for which you have just created the key.

  7. Repeat Steps 4 through 5 to select or define a key for the end operation. (Although the property names might be different, the value of the property must be the same.)

  8. Repeat Steps 4 through 7 for each pair of operations that you want to correlate. (The properties you have created for the manual keys are displayed in the Profile tab for the selected transaction, in the Properties pane.) When you are done defining the transaction, the graphic that represents the transaction will be changed to show key icons rather than fingerprint icons for all operations that are correlated using a manual key.

Defining Storage Settings

The final step in defining a transaction is to define archival settings and to enable the indexing of message content.

Use the Storage Settings tab to define these values. The table below shows the default settings and explains the meaning of the settings.

Item Default value Description
Retain archived condition instances 30 days The amount of time Business Transaction Management must retain archived condition instances in the transaction server's database.

An archived condition instance is a transaction instance that is assembled and retained when a condition set on one of the operations belonging to the transaction evaluates to true. (Instance logging must be turned on when you define a condition if it hasn't already been turned on.)

Retain individual messages 24 hours The minimum amount of time Business Transaction Management must retain logged messages in the transaction server's database.
Rotate message log 720 minutes If you have turned message logging on, this specifies the rotation interval for logged messages. Messages that are rotated out are held in the message log database for the amount of time defined for Retain individual messages.
Text index message content On Creates a text index in the oracle database that speeds up keyword-based searches (at the expense of storage and some initial processing time). If you disable this feature, you can still do content-based searches, but they will be slower.

Modifying a Transaction Definition

Modifying a transaction definition changes the definition of the transaction in the environment. You can modify any part of a transaction definition, but keep in mind that Business Transaction Management does not track definition versions. For this reason changing some aspects of the definition might confuse things. For example, if you add or delete operations to a transaction definition or if you change the keys used to correlate operations, and then you try to assemble a transaction instance that preceded the modified definition, you might get odd results. On the other hand, enabling or disabling the transaction, or changing storage options should not be a problem.

To modify a transaction definition:

  1. Select the transaction of interest in the Explorer > Transactions summary view.

  2. Select Edit TransactionName from the Modify menu.

  3. Use the Modify Transaction tool to modify the transaction definition. Refer to Defining a Transaction for information about definition elements.

  4. Click OK.

Business Transaction Management offers you a short cut you can use to enable or disable a transaction without having to edit its definition.

To enable or disable a transaction:

  1. Select the transaction of interest in the Explorer > Transactions summary view.

  2. Select Enable TransactionName or Disable TransactionName from the Modify menu. The appropriate action will be available, depending on the current status of the selected transaction.

Deleting a Transaction Definition

Deleting a transaction definition removes the definition from the environment. No condition alerts defined for this transaction are triggered. The system deletes all existing instances of this transaction.

To remove a transaction:

  1. Select the transaction of interest in the Explorer > Transactions summary view.

  2. Select Delete TransactionName from the Modify menu.

  3. Confirm the deletion.