User Guide
|
Enterprise
RTView®
User Guide |
|
Defining Transactions Transactions for the Transaction Monitor, Transaction Display Generator and Transaction Simulator must be defined in the TRANSACTIONS.ini file, which can be modified with any text editor (such as Windows Notepad). If no directory has been specified for initialization files and this file is not found in the directory where you started the current application, then the Transaction Monitor will search under lib in your installation directory. The Transaction Display Generator and the Transaction Simulator will only search for TRANSACTIONS.ini in the directory where they are started. The Transaction Monitor, Transaction Display Generator and Transaction Simulator must access this initialization file to function properly. NOTE: When you start an Enterprise RTView application from the Windows Start menu, it runs from the demos directory. NOTE: The TRANSACTIONS.ini file can contain any number of transaction definitions. A transaction definition is a list of two or more JMS or TIBCO Rendezvous messages that describe a business event. These messages are listed in the order they are expected to execute. Each pair of messages makes up an interface. Each transaction definition may contain any number of interfaces, but each interface must be defined by exactly two JMS or TIBCO Rendezvous messages. Each definition must begin with a startBusTransaction keyword and the transaction name, which must be followed by the msg lines containing the two JMS destinations or TIBCO Rendezvous subjects that define the first interface. The interface keyword is used to associate the previous two msg lines with the interface name. Subsequent interfaces must contain only one new msg line because the ending message of the previous interface serves as the beginning message of the next interface. Each message must be followed by the field in that message which contains the unique ID that will be used to track each transaction. The endBusTransaction keyword must be used to end each transaction definition. Any parameters in TRANSACTIONS.ini which contain spaces must be enclosed in single quotes. The following transaction definition describes a business transaction that is made up of 3 messages, messageA, messageB, and messageC:
The following options are available in your transaction definition:
A table of supported keywords for transaction definitions is provided at the bottom of this page for reference. The same TRANSACTIONS.ini can be used for the Transaction Monitor, Transaction Display Generator and Transaction Simulator. Additional keywords are supported for the Transaction Display Generator and some options are ignored for both the Transaction Display Generator and Transaction Simulator. See the Defining Transactions For the Transaction Display Generator and Defining Transactions for the Transaction Simulator sections below for more information. The Transaction Monitor supports both JMS and TIBCO Rendezvous messages. By default, the Transaction Monitor listens for all transaction messages using JMS. To use TIBCO Rendezvous as the default, set the defaultds option to be rv in TMOPTIONS.ini or on the command line. In addition to setting the default data source, you can also specify a data source to use per transaction or per message in a transaction. This allows you to monitor transactions that are made up of a combination of JMS and TIBCO Rendezvous messages. To use a different data source than the default for a single message or transaction, use the keyword ds followed by jms for JMS or rv for TIBCO Rendezvous on the startBusTransaction or msg lines in your transaction definition. For example:
Specifying
a Connection
In addition to specifying a default connection, you can also specify a different JMS connection or TIBCO Rendezvous transport per transaction definition or per message definition. This allows you to monitor transactions made up of messages on multiple JMS connections and on multiple TIBCO Rendezvous transports. To specify a connection to use for a single transaction, use the keyword transConnection followed by the information for your data source on the line below startBusTransaction in the transaction definition.To specify a different connection to use for a single message within a transaction, use the keyword msgConnection followed by information for your data source on the line below the msg line. For both transConnection and msgConnection, the following must be used after the keyword:
For example, a JMS connection:
For example, a TIBCO Rendezvous connection:
In both examples above, the msgConnection applies to messageA only. Specifying
an Active Transaction Limit or Expiration
Specifying
Messages and Message IDs
The fields containing the tracking ID maybe different for each message. For example, in the definition above, the following message fields are used to get the tracking ID from each message in the transaction: idA = tracking_id1Since all these messages belong to the same transaction, the concatenation of all fields (per message) must result in the same tracking ID: tracking_id1 = tracking_id2 = tracking_id3If the tracking ID is contained in a JMS TextMessage, use <TEXT> for the message field name: If a tracking ID within your message is contained in XML data, then you must add the $xml: prefix to the name of the message field that contains the XML data. This field should be followed by the list of XML tags in hierarchical order ending in the tag that contains the tracking ID. For example, the invoice_data message field contains the following XML: <InvoiceData>To use the value of InvoiceID as your tracking ID, you would specify this message in TRANSACTIONS.ini as follows: If the tracking ID within your message is contained in an XML attribute, add :$attrib=attribute_name to the end of the XML field containing the attribute. For example, the invoice_data message field contains the following XML: <InvoiceData>To use the value of the id attribute in the InvoiceID field as your tracking ID, you would specify this message in TRANSACTIONS.ini as follows: msg msgA $xml:invoice_data::InvoiceData::InvoiceID:$attrib=id To use the value of a JMS message header field as your tracking ID, add the $header prefix to the name of the header field: msg msgA $header:JMSCorrelationID To use the value of a JMS message property field as your tracking ID, add the $prop prefix to the name of the property field: msg msgA $prop:senderID Using
Queue Messages (supported for TIBCO EMS only) msg QUEUE:status.process.queue $prop:ID For queues, the TIBCO system monitor messages are used to get the message, so in order to use these in your transactions, you must use a connection that has permission to receive system monitor messages. The connection must be to the EMS server that sends the message (ie the home server for the queue). NOTE: It is not possible to parse the message body content of the original message from the system monitor message, so the id fields for queues must be JMS property or header fields. For each queue in a transaction definition, a subscription to the corresponding system monitor message is made. For example, if status.process.queue is specified for the queue, a subscription will be made to $sys.monitor.Q.r.status.process.queue. The system monitor messages generate additional overhead on your EMS server, see your TIBCO documentation for more information. Note that TIBCO does not guarantee system monitor messages, so we may not receive system monitor messages for some queue messages. This means that the Transaction Monitor may report that a transaction is stalled, when it actually completed. The system monitor messages may also not be sent at the same time as the original message, so the latency values my not be accurate. There is no workaround for this. However, in most cases, they will be sent at about the same time the original message was sent. NOTE: Queues are only supported on TIBCO EMS connections. Using
Temporary Destinations (supported for TIBCO EMS only) msg TEMP_DEST $prop:ID NOTE: You cannot use a temporary destination for the first message in a transaction. For temporary destinations, the TIBCO system monitor messages are used to get the message, so in order to use these in your transactions, you must use a connection that has permission to receive system monitor messages. The connection must be to the EMS server that sends the message (ie the home server for the queue or temporary destination). NOTE: It is not possible to parse the message body content of the original message from the system monitor message, so the id fields for temporary destinations must be JMS property or header fields. Since the Transaction Monitor does not know in advance which destination a temporary destination will resolve to, it will subscribe to the system monitor messages for all temporary destinations on the each connection in your transaction definition that contains a temporary destination. When the message previous to the temporary destination message in the transaction definition is received, the Transaction Monitor will get the destination from the JMSReplyTo property to determine which temporary destination will be used for the next message in the transaction. This destination is always on the same server that sent the message, so the connection for temporary destination, as well as the previous message containing the JMSReplyTo value, must be to the server that sent the message (ie the home server for the topic or queue). By default, if a transaction definition contains a temporary destination the Transaction Monitor will subscribe to these system monitor messages
$sys.monitor.Q.r.$TMP$.> The system monitor messages generate additional overhead on your EMS server, see your TIBCO documentation for more information. Note that TIBCO does not guarantee system monitor messages, so we may not receive system monitor messages for some queue or temporary destination messages. This means that the Transaction Monitor may report that a transaction is stalled, when it actually completed. The system monitor messages may also not be sent at the same time as the original message, so the latency values my not be accurate. There is no workaround for this. However, in most cases, they will be sent at about the same time the original message was sent. You can narrow down the number of system monitor messages that will be sent to the Transaction Monitor by specifying that you only want to listen for temporary topics or temporary queues instead of both. You can also narrow down the number of system monitor messages that will be sent by specifying a more specific destination. See the tempdest and tempdestmode options in TMOPTIONS.ini or from the command line for more information. Since TIBCO does not guarantee that the system monitor temporary destination message will arrive after the previous message in the transaction, the Transaction Monitor will store all temporary destination messages that it receives that do not already have a listener. In order to prevent a memory problem, temporary destination messages that have been stored for 5 minutes without any listeners registering for them are removed. This time limit can be changed by using the tempdestexpire option in TMOPTIONS.ini or from the command line line The Transaction Monitor assumes that it will not have multiple transaction instances using the same temporary destination at the same time. For example, the JMSReplyTo value for the message before the temporary destination resolves to a destination $TMP$.12345. If the Transaction Monitor has received a message from that destination that has not expired, it is assumed to be the correct message for the transaction. If the Transaction Monitor has not yet received a message from $TMP$.12345, it will assume that the next message that comes in from that destination is the correct message for the transaction. NOTE: Temporary destinations are only supported on TIBCO EMS connections. Re-using
Messages in Transactions In order to use the same message as the first message in multiple transaction definitions, you will need to specify a transDefField and transDefValue. The Transaction Monitor will use this to determine which transaction definition a message belongs to. The transDefField must go at the beginning of the TRANSACTIONS.ini before the first transaction definition. It must contain the name of the message and the field in the message that the Transaction Monitor can use to determine which transaction that message belongs to. The transDefField can be a top level, nested, xml, jms header or jms property field. The syntax for specifying nested, xml, jms header and jms property fields is the same as the message ID described above. The transFieldValue must go before the first msg definition in the transaction definition and must be followed by the value that it will contain if it is to be used for that transaction. For example:
In the example above, messageA is used as the first message in both MyTransaction1 and MyTransacton2. When the Transaction Monitor receives messageA, it will use the value in the transType field to determine which transaction to start. In order to use the same message multiple times within a single transaction, you will need to specify a msgOrderField and msgOrderValue. The Transaction Monitor will use this to determine which interface to start or update and whether or not the messages are coming in the correct order. The msgOrderField definition must go at the beginning of the TRANSACTIONS.ini before the first transaction definition. It must contain the name of the message and the field in the message that the Transaction Monitor can use to determine which position in the transaction that instance represents. The msgOrderField can be a top level, nested, xml, jms header or jms property field. The syntax for specifying nested, xml, jms header and jms property fields is the same as the message ID described above. The msgOrderValue must go in the msg definition within the transaction definition and must be followed by the value that it will contain. For example:
In the example above, the messageA message is used 3 times within the same transaction. When the Transaction Monitor receives messageA, it will use the value in the orderField to determine which interface to start or update. Defining
Transactions For the Transaction Display Generator
This transaction definition causes the Transaction Display Generator to create a new display named ti_upo.rtv, using the last field in the startBusTransaction line. This display contains four components. The start component is named Siebel (the third field in the startBusTransaction line) and the end component is named RR (the fourth field in the startBusTransaction line). There are two intermediate components named Oracle and Siebel (the third argument in the interface line). The color of the header on objects representing the Oracle and Siebel components will be black due to the 1 at the end of the interface lines. The 1 is optional and if it is not specified, the color of the header on objects will be gray. For more information on creating generated displays, see Transaction Display Generator. Defining
Transactions for the Transaction Simulator Table
of Supported Keywords for Transaction Definitions
|
|
|
|
|