Oracle recommends taking the ILT course: D56080GC10: Tuxedo 10gR3: Application Administration. The course details the concepts that provide the foundation for this hands-on tutorial.

Oracle recommends taking the online course: D65997GC10: Tuxedo 11gR1: Monitor Tuxedo with TSAM. The online course provides the concepts for this hands-on tutorial.

Installed Oracle XE 10g Universal Database. The Oracle XE database was chosen for its smaller footprint and the likelihood that most people would have this database installed on their machine.

Make sure to run these steps to increase Oracle XE's processing capabilities for use with this lab:

Open a command window and run the following commands after the database is installed:

• sqlplus "/as sysdba"
• alter system set processes = 200 scope = spfile;
• alter system set sessions = 400 scope = spfile;
• alter system set transactions = 360 scope = spfile;
• shutdown immediate
• startup
  

To verify your new settings, run the following commands:

• select name, value
  

Run the following command to exit sqlplus:

• quit

Installed Oracle Database Client

Installed Oracle Tuxedo 11gR1 (instructions)

Installed Oracle SALT 11gR1 (instructions)

Installed Oracle TSAM 11gR1 (instructions)

Install TSAMLabs.zip:

Note: It is important that you unzip to the location specified below, else aspects of the demo Web application will not work.

Unzip TSAMLabs.zip to your C:\ folder. This should create a folder called C:\TSAMLabs.

Set Up Initial Environment:

In a text editor, open C:\TSAMLabs\bin\labenv.cmd and change the following environment variables to match your environment . Do not change the INCLUDE= variable, because this is to ensure that no specific INCLUDE settings are in place. Ensure that the line that calls the Microsoft Visual Studio environment variable script points to the correct location.

Note: Although there is an OBEDIR variable, it does not work for everything so you must install to the C:\ folder.

When you are done, your file should look similar to the following:

Save your changes.

Change TomCat Port:

The default listening port for TomCat is 8080. Unfortunately, this also happens to be the default listening port for the Oracle XE database Web server. Open the %ORACLE_HOME%\tsam11gR1\%TOMCATDIR%\conf\server.xml file, and locate the server's port configuration that is set to 8080. Change the number to 8001, and save your changes.

Start TuxDemo Environment :

First, ensure that the Tuxedo tlisten process is not running. Open Control Panel>Administrative Tools>Services and find the entry called TListen 11gR1. Select the entry and stop the service. Also configure the service to start manually. You need to turn this service off because it will not run with the correct environment variables set for the BROKER domain, and the servers on the second machine will fail to start. The labenv.cmd script that is called by the setup.cmd script starts the tlisten process with the correct environment.

Using Windows Explorer, browse to C:\TSAMLabs\bin and double-click the DOSPrompt.cmd file to execute it, which will start a command shell window.

In the command window, type in the following command to run the TuxDemo environment:

setup.cmd

This runs a set of scripts that perform the following tasks:

• Sets up tuxdemo and xpone as hosts for your IPADDRESS variable
• Creates the tsam user for the TSAM database
• Creates the tuxdemo1, tuxdemo2, and tuxdemo3 users for the TuxDemo database
• Runs the TSAM DatabaseDeployer.cmd script to create the TSAM database schema and to configure the TSAM Web application's deployment descriptor
• Runs the TSAM AppServerDeployer.cmd script to deploy the TSAM Web applications
• Deploys the TuxDemo Web applications
• Builds the executables for the Bankapp and BrokerApp Tuxedo domains, including the Oracle TMS server
• Cleans all ULOG, TLOG, TUXCONFIG, BDMCONFIG, and so on files from all domains
• Builds all the UBB, DMBB, TUXCONFIG, BDMCONFIG, SALTCONFIG, *.WSDF, GWWS.deploy, metadata.rps, and TLOG files for all domains
• Starts three Tuxedo Bankapp domains, one multimachine Tuxedo Brokerapp domain, and the Tomcat server that runs TSAM and the TuxDemo applications
• Opens another command window to ensure that all domains have connected
• Creates the TuxDemo database schemas.
• Populates the TuxDemo database with application data

When the script is done running, you should have everything running with no errors. You will see some warnings with the build process of the executables, but if all the servers start, you can ignore them.

When the script pauses, it opens another command window that helps ensure that all the domain gateways have established connections with each other. In that window, press the space bar repeatedly until you see that all the domains have connected as shown in the following image:

When all the domains are connected, you can close the second command window, and then press any key in the first command window to continue the set up process. The script will continue with creating the TuxDemo database schemas and populating the TuxDemo database with application data.

You can look at TSAM configuration points in the environment now that it is running. The next section covers this.

Examine Database User Creation :

The following SQL was used to create the tsam user in the database. It can be found in the C:\TSAMLabs\bin\crDemoUsers.ora file.

CREATE USER tsam IDENTIFIED BY tsam;
grant CONNECT, RESOURCE, DBA, all privileges to tsam;

Examine TSAM DatabaseDeployer.cmd Command Line :

The following command was used to create the TSAM database schema, set the administrative user's password, and to configure the TSAM Web application's deployment descriptor with the proper JDBC settings. This can be found in the C:\TSAMLabs\bin\DeployTSAM.cmd script.

DatabaseDeployer.cmd -type oracle -hostname localhost -port 1521 -dbname %ORACLE_SID% -user tsam -password tsam -overwrite yes -adminpassword admin1

Examine TSAM AppServerDeployer.cmd Command Line :

The following command was used to deploy the TSAM Web applications to the TomCat application server. This can be found in the C:\TSAMLabs\bin\DeployTSAM.cmd script.

AppServerDeployer.cmd -type tomcat -directory %TUXDIR%\..\tsam11gR1\%TOMCATDIR%

Examine LMS Server Configurations:

An LMS server is configured for each machine in the TuxDemo environment. Each LMS is configured to connect with the same TSAM Data Server located at localhost:8001/tsam. You can view the Tuxedo ubb configuration file and find the LMS server configurations by examining each of the following files:

• C:\TSAMLabs\tuxedo\brokerapp\ubb
• C:\TSAMLabs\tuxedo\bankapp\chi\ubb
• C:\TSAMLabs\tuxedo\bankapp\ny\ubb
• C:\TSAMLabs\tuxedo\bankapp\sf\ubb

Brokerapp Domain (one on each machine):

LMS SRVGRP=LMSGRP1 SRVID=1 CLOPT="-A -- -l localhost:8001/tsam"
LMS SRVGRP=LMSGRP2 SRVID=1 CLOPT="-A -- -l localhost:8001/tsam"

Bankapp Domains:

LMS SRVGRP=SYSGRP SRVID=50 CLOPT="-A -- -l localhost:8001/tsam"

TSAM Startup Command Line :

The following command is run from within the C:\TSAMLabs\bin\demostart.cmd script. This command starts the TomCat application server that is bundled with the TSAM product.

cd /d %TUXDIR%\..\tsam11gR1\bin
startup.cmd

Examine tmloadcf Commands:

The tmloadcf command can be found several times in the C:\TSAMLabs\bin\buildtux.cmd file. It occurs once for each domain that is part of the environment. This command converts the text ubb configuration file to the binary tuxconfig file containing the LMS server configuration.

tmloadcf -y ubb

Examine Tuxedo Startup Script:

The tmboot command can be found several times in the C:\TSAMLabs\bin\demostart.cmd file. It occurs once for each domain that is part of this environment. This script starts all of the Tuxedo domains. When a Tuxedo domain starts, the LMS servers for that domain are started and the TSAM Agent side is ready.

tmboot -y

Log In to the TSAM Administration Console:

Open a Web browser and browse to http://localhost:8001/tsam to open the TSAM Administration console. Enter admin as the username and admin1 as the password, and then click the Login button.

You should see a screen similar to the following:

Now TSAM is up and running and ready to monitor the TuxDemo environment. The next section gets you started with monitoring policies.

Examine all DOMAINID Parameters:

Open the following files and take note of their DOMAINID values:

• C:\TSAMLabs\tuxedo\brokerapp\ubb:DOMAINID=BROKER
• C:\TSAMLabs\tuxedo\bankapp\chi\ubb:DOMAINID=CHICAGO
• C:\TSAMLabs\tuxedo\bankapp\ny\ubb:DOMAINID=NEWYORK
• C:\TSAMLabs\tuxedo\bankapp\sf\ubb:DOMAINID=SANFRANCISCO

Notice how each one has a unique value. This is required when using TSAM to monitor your domains because TSAM uses the DOMAINID as part of its way of uniquely identifying each domain.

View Tuxedo Configuration Settings:

Within the TSAM Administration console window, examine the left-hand side of the page where the different Tuxedo domain configurations are displayed. Expand the BROKER domain and the two machines (in the case of the screenshot, these are ARCYNE and ARCYNE2). You can play around by examining more of the configuration structure to drill all the way down to services. Click the icon to view more details about the domain. The verbose view provides you with details such as master and slave data, Tuxedo version information, LMID, group ID, and server ID information. The images below show the difference between the regular and verbose views. Take some time and examine some of the other settings.

Import and Examine Monitoring Policy Set:

• Right-click and save the policies.xml file to a location of your choice and open the file for editing. Do a search and replace to change all the @HOSTNAME@ entries to your machine's host name.
• In the TSAM Administration console, select Policy > Tuxedo Monitoring Policy from the menu to display the Monitoring Policy List page. This page does not contain any policies at this time. This tutorial guides you through importing the policy set used for this training, and has you examine and execute functioning policies.
• In the TSAM console, click the Import button, browse to the policies.xml file you saved and modified, and click the Upload button.

You should see a page similar to the following. Select all of the check boxes for the policies, and click the Enable button to ensure that all the policies are enabled so TSAM can begin capturing metrics. Take a few moments to review these policies by selecting the check box next to a policy and clicking the Edit tab to see the policy's details. We will go over each policy in more detail as we cover the respective feature area in the next few sections.

WARNING: Check the paragraph above again to ensure that you enabled the policies (Status=enabled). By default, imported policies are disabled. If you do not enable them, then TSAM will not collect any metrics when you run the TuxDemo application.

Now that you have familiarized yourself with the basics of the monitoring policy console interface, you can move on to the next section that covers Call Path and Pattern tracking.

Open the TuxDemo Web Page:

Browse to the following URL to open the main TuxDemo Web page. Note: Do not use localhost as it will not work properly.

http://hostname:8001/tuxdemo

You should see the following page:

Run Automated Teller Machine:

Click the Automated Teller Machine link to go to the ATM Web page.

• Enter 60006 in the Account field, then click the Inquiry Account button to request data for that account.
• Enter a numeric dollar value (for example, 50) in the Withdrawal field.
• Enter a numeric dollar value in the Deposit field.
• Alternate between clicking the Withdrawal and Deposit buttons while watching the account's balance. This will cause services to be called on the back end. It is alright if some service requests are failures and some are successful .One way that a service request will fail is if you try to withdraw more funds than an account has as its balance. Ensure that you do not click the buttons the same number of times to ensure a more meaningful data graph when viewing your metrics.
• Ensure that when you are done the account has a few thousand dollars in it.
• Click the Back to Start page link to return to the main TuxDemo page.

Run Stock Broker Application:

Click the Stock Broker Application link to go to the Stock Broker Web page. At first, your screen will not look completely similar to the image below. Follow the steps below the image to continue.

• Click the List Account button to populate the Account drop-down list.
• Select the 60006 account from the drop-down list.
• Enter ORCL in the Symbol field.
• Enter 10 in the Shares field.
• Enter 50 in the Price field.
• Alternatively click the Buy Shares and Sell Shares buttons to cause the back end services to get called.
• Once in every few seconds, click the Account Summary button to see how many shares and how much money the account has in it.
• Proceed with the next step when you feel you have pushed enough requests through the system.

Examine Call Path Monitoring Policy:

• Log in to the TSAM Administration console and select Policy > Tuxedo Monitoring Policy from the menu to open the Monitoring Policy List page.
• Select the check box next to the callpath policy and click the Edit button.
• Make sure the Call Path tab is selected and visible.
• Review the settings of this policy:
    - This is a Call Path policy because the Call Path tab is selected, configured, and the Enable check box is selected.
    - This policy is monitoring the GWWS server, which is in the GWWSGRP, on the ARCYNE (or your host name)
      machine, in the BROKER domain based on the selections in the Tuxedo Component panel.
    - This policy will monitor every request because the Ratio setting is 1.
    - This policy will cause Bridge traffic between machines in a Tuxedo MP domain to be decoded so that metric data
      can be captured for the Bridge processes.
    - This policy is monitoring requests that originate from Web service clients that call the GWWS SALT gateway
      server because the Initiator Type selected is Web Service Client.
• After running through these steps verbatim, you can come back to this page and try setting different parameters to see how Call Path tracking metrics change.

Now that you examined the settings for the Call Path monitoring policy, let's take a look at the metrics that the policy captured when you ran the TuxDemo application.

View Call Path Metrics:

• Select Tuxedo Metrics > Call Path from the menu to open the Call Path metrics page.
• "Query by Filter" on the left of the page is set to query for all Call Path metrics in all the domains that were captured at any time. Click the Query button to get the list of Call Paths that were captured.

• Select one of the Call Paths that are returned on the right side of the page. Preferably, select one with a BR_ACNT_SUM root service to get a long Call Path.

• View the Call Path Details panel to see the path the request took from the beginning at the GWWS server to the end when the GWWS server receives the reply from the BR_ACNT_SUM service. Note how the metric data in the columns show where the request has traveled, on which domain, machine, group, and server process. It also shows all system servers that were part of the request.

• You can also see the execution time of each step in the Call Path, as well as the flags made in Tuxedo calls, and other data that is pertinent to each Call Path step.

View Call Pattern Metrics:

• Select Tuxedo Metrics > Call Pattern from the menu to open the Call Pattern metrics page.
• "Query by Filter" on the left of the page is set to query for all Call Pattern metrics in all the domains that were captured at any time. Click the Query button to get the list of Call Patterns that were captured.

• Select one of the Call Patterns that are returned on the right side of the page. Preferably, select one with a BR_ACNT_SUM root service starting the description to get a longer Call Pattern.

• View the Call Pattern Details panel to see the service pattern of the request. Note that although there are fewer details than in the Call Path Details panel, the metric data in the columns still show where the request has traveled, on which domain, machine, group, and server process. It also differs in that it does not show the system servers that were part of the request, and only shows the application server list involved in the request.

Examine Service Monitoring Policy:

• In the TSAM Administration console, select Policy > Tuxedo Monitoring Policy from the menu to open the Monitoring Policy List.
• Select the check box next to the service policy, and click the Edit button.
• Make sure that the Service tab is selected and visible.
• Review the settings of this policy:
    - This is a Service monitoring policy because the Service tab is selected, configured, and the Enable check box is selected.
    - This policy is monitoring all servers in the BROKER domain based on the selections in the Tuxedo Component panel.
    - This policy will monitor every request because the Ratio setting is 1.
    - This policy will not be an Alert Only policy so all metric data will be included in the capture.
    - Service Contract Discovery will not be performed because it is not enabled.
    - This policy is monitoring requests made to the WITHDRAWAL and DEPOSIT Tuxedo services.
• After running through these steps verbatim, you can come back to this page and try setting different parameters to see how Service tracking metrics change.

Now that you examined the settings for the Service monitoring policy, let's take a look at the metrics the policy captured when you ran the TuxDemo application.

View Service Metrics:

• Select Tuxedo Metrics > Service from the menu to open the Service metrics page.
• In the Services Selection panel on the left of the page: Set the query for WITHDRAWAL and DEPOSIT gateway service metrics in the BROKER domain that occurred between one hour ago and a few hours into the future of right now:
    - Select BROKER as the domain.
    - Select All as the machine.
    - Select GWGRP as the group.
    - Leave the server entry empty.
    - Select Selected Services (Historical) as the monitoring mode.
    - Select the DEPOSIT and WITHDRAWAL services from the list of services.
    - Select a time range of one hour ago to a few hours ahead of right now.
    - Click the Submit button to get the Service metrics that were captured.

• You should see a graph on the right side of the page similar to the image below. Try selecting each type of metric from the drop-down list to see more graphs.

• Click the Table button to view all the metrics at a glance.

Examine System Server Monitoring Policy :

• In the TSAM Administration console, select Policy > Tuxedo Monitoring Policy from the menu to open the Monitoring Policy List.
• Select the check box next to the systemserver policy and click the Edit button.
• Make sure the Domain Gateway tab is selected and visible.
• Review the settings of this policy:
    - This is a System Server monitoring policy because the Domain Gateway server is a system server, the Domain Gateway
       tab is selected, configured, and the Enable check box is selected. Also note that clicking the BRIDGE and GWWS tabs
       shows that the same settings are also configured for those system servers in this policy.
    - This policy is monitoring all Domain Gateway, Bridge, and GWWS system servers in the BROKER domain based on the selections in the Tuxedo Component panel.
  
• After running through these steps verbatim, you can come back to this page and try setting different parameters to see how System Server tracking metrics change.

• Review these same settings on the BRIDGE tab.

Review these same settings on the GWWS tab.

Now that you examined the settings for the System Server monitoring policy, let's take a look at the metrics the policy captured when you ran the TuxDemo application.

View System Server Metrics:

• Select Tuxedo Metrics > Domain Gateway from the menu to open the Domain Gateway metrics page.
• Set the Domain Gateway Selection panel on the left of the page to show metrics for all domain gateways that are connected to the BROKER domain that occurred between one hour ago and a few hours in the future from right now:
    - Select BROKER as the domain.
    - Select BROKER as the local access point.
    - Click Move All to move the available remote access points to the selected remote access points list.
    - Select Historical as the monitoring mode.
    - Select a time range of one hour ago to a few hours ahead of right now.
    - Leave the time window of 3600 seconds.
    - Click the Submit button to get the System Server metrics that were captured.

• You should see a graph on the right side of the page similar to the image below. Try selecting each type of metric from the drop-down list to see more graphs, and click the Table button to view all the metrics at a glance.

• Select Tuxedo M etrics > Bridge from the menu to open the Bridge metrics page.
• Set the Bridge Selection panel on the left of the page to show metrics for all the bridges that are connected to your master machine (host name) that occurred between one hour ago and a few hours in the future from right now:
    - Select BROKER as the domain.
    - Select your hostname as the machine.
    - Click Move All to move the available remote machines to the selected remote machine list.
    - Select Historical as the monitoring mode.
    - Select a time range of one hour ago to a few hours ahead of right now.
    - Leave the time window of 3600 seconds.
    - Click the Submit button to get the System Server metrics that were captured.

• You should see a graph on the right side of the page similar to the image below. Try selecting each type of metric from the drop-down list to see more graphs, and click the Table button to view all the metrics at a glance.

• Select Tuxedo Metrics > GWWS from the menu to open the GWWS metrics page.
• Set the "Query by Filter" panel on the left of the page to show metrics for all the GWWS gateways that are part of the BROKER domain that occurred between one hour ago and a few hours in the future from right now:
    - Select BROKER as the domain.
    - Select All as the GWWS.
    - Select Historical as the monitoring mode.
    - Select a time range of one hour ago to a few hours ahead of right now.
    - Leave the time window of 60 seconds.
    - Click the Query button to get the System Server metrics that were captured.

• You should see a graph on the right side of the page similar to the image below. Try selecting each type of metric from the drop-down list to see more graphs, and click the Table button to view all the metrics at a glance.

You just learned about TSAM Service and System Server monitoring. The next section covers XA Transaction monitoring.

Examine XA Transaction Monitoring Policy:

• In the TSAM Administration console, select Policy > Tuxedo Monitoring Policy from the menu to open the Monitoring Policy List.
• Select the check box next to the xatransaction policy, and click the Edit button.
• Make sure that the XA Transaction tab is selected and visible.
• Review the settings of this policy:
    - This is an XA Transaction monitoring policy because the XA Transaction tab is selected, configured, and the Enable check box is selected.
    - This policy is monitoring all servers in the BROKER domain based on the selections in the Tuxedo Component panel.
    - This policy will monitor every request because the Ratio setting is 1.
    - This policy is monitoring requests made by all initiator types because Initiator Type List is set to All.
• After running through these steps verbatim, you can come back to this page and try setting different parameters to see how XA Transaction tracking metrics change.

Now that you examined the settings for the XA Transaction monitoring policy, let's take a look at the metrics the policy captured when you ran the TuxDemo application.

View XA Transaction Result List:

• Select Tuxedo Metrics > XA Transaction from the menu to open the XA Transaction metrics page.
• Set the "Query by Scope" panel on the left side of the page to show metrics for all XA Transactions that occurred between one hour ago and a few hours in the future from right now:
    - Select All as the initiator type.
    - Select Any as the status.
    -Select the Query During option.
    - Select a time range of one hour ago to a few hours ahead of right now.
    - Click the Query button to get the XA Transaction metrics that were captured.

• Select one of the XA Transaction results that are returned on the right side of the page. Preferably, select one that has a parent GTRID entry in order to observe a more complex transaction that spans domain boundaries. Note that these two transactions complete as a single unit of work, and that the domain gateway server on the calling domain serves as the transaction coordinator of the remote domain's transaction. Also, when looking at these metrics, note that the time for each transaction is listed, and only by combining the overall execution times or viewing the duration of the parent transaction do you get the actual execution time of the entire transaction.

View XA Transaction Path and Corresponding Correlation ID Panels:

• When an entry is selected in the result list, the XA Transaction Path panel is populated with the data that reflects that row. It shows the relationship between the parent and child transactions. Clicking each transaction causes the lower level details of that transaction to be revealed in the Corresponding Call Path Correlation ID panel, if an associated Call Path entry exists, and in the XA Transaction Detail panel, which reveals the underlying XA protocol requests from tpbegin() to tpcommit().
• Select each transaction and review these two panels to see the data that is associated with your XA Transactions.

• View the Call Path that is associated with your XA Transaction. You can click the link to view more details about the associated Call Path metrics, or stay on the page and view the details in the XA Transaction Detail panel.

View XA Transaction Detail:

• After you click one of the transactions listed in the XA Transaction Path panel, view the metric data in the XA Transaction Detail panel.
• Note the individual calls made for the transaction, the location where each call was made, the status of each call, and the execution time of each step. This data can help you in spotting where your XA Transactions may be having problems.

Now that you know how to monitor your XA Transactions, continue with the next section that covers TSAM Alerts and Event Generation.

Create Alert Definition:

• In the TSAM Administration console, select Alert > Tuxedo Alert Definition from the menu to open the Alert Definition List.
• Click the Add button to create a new alert definition.
• Enter svcfailure for the name of the alert.
• Select Service as the alert type.
• Do not select the Metrics Independent Checking check box.
• Select Fatal as the alert severity.
• Select 0 as the time interval.
• Leave the Action empty.
• Leave all entries for the Tuxedo Components panel empty.
• In the Metric Evaluation Expressions panel, select Execution Status, is not, and TPOK as the alert trigger.
• Click the Save & Enable button.
• After running through these steps verbatim, you can come back to this page and try setting different parameters to see how TSAM Alert metrics change.

Now that you configured the settings for the alert definition, run the TuxDemo application again to cause some service failures that will trigger the alert.

Run the Stock Broker Application:

In your Web browser, open the Stock Broker Application again and run all the options again. This time, ensure that you buy more shares than you can afford, and make sure to sell more shares than you have. This will cause the underlying services to fail and trigger your new alert.

View Unread Alerts:

• Select Alert > Alert Query from the TSAM Administration window to open the Alert viewing page.
• Select Service for the type.
• Select Any for the severity.
• Click the Submit button to return a list of all matching unread alerts. You can also click the Historical Alerts tab to query for alerts that occurred within a specific time frame.

• Select a check box next to one of the entries and click the Detail button to view the details of a particular alert. Take some time to play around with the different controls on the page.