Oracle Tuxedo monitoring with a sample application using Instana

Published in

IBM Cloud

7 min readMar 6, 2024

Co-authors: Xiao Juan Niu and Pei Ran Han

Oracle Tuxedo is an application server and middleware platform that enables the development and deployment of scalable and reliable distributed enterprise applications. It provides a robust infrastructure for building transaction-oriented systems with features such as transaction management, message queuing, and load balancing. Tuxedo is used in industries where high-performance and fault-tolerant applications are required.

IBM® Instana observability (Instana) is a fully-automated application performance management (APM) solution designed for the challenges of managing microservice and cloud-native applications. Instana has the capability to monitor Oracle Tuxedo. This blog explains how to enable Oracle Tuxedo monitoring with Instana, including how to deploy a sample Tuxedo app and how to config Instana agent to monitor Oracle Tuxedo.

Deploying a sample Tuxedo app

Make sure that you have installed Oracle Tuxedo

Make sure that you are not making changes to the root user.

The following examples are based on Oracle Tuxedo 12.2.2.0

Please create a user and edit the following.

After installing Oracle Tuxedo, go to the tuxedo12.2.2.0.0 directory, where you will find a sample folder with multiple sample applications.

The <Tuxedo_Installation_Dir>/samples/atmi/simpapp directory is used as an example to show how to set up a Tuxedo application and how to monitor it by using Instana.

To set up the simpapp application, complete the following steps:

1. Copy simpapp from samples to a new directory.

A directory myapps is created in the tuxedo12.2.2.0.0 directory and simpapp is copied to the myapps directory.

2. Set tux.env, set the configuration paths in the tux.env file.

A configuration is shown in the following example. Set the configuration as per your system:

source tux.env

Run the following command after modifying the configuration. Every time the system restarts, some of the paths are reset to the default value, so run this command after the system restarts.

3. Set the simpapp environment

a) Create a simpapp.env file anywhere and add TUXDIR, APPDIR, and TUXCONFIG paths into the simpapp.env file.

TUXDIR=/home/txadmin/OraHome_1/tuxedo12.2.2.0.0; export TUXDIR
APPDIR=/home/txadmin/OraHome_1/tuxedo12.2.2.0.0/myapps/simpapp; export APPDIR
TUXCONFIG=/home/txadmin/OraHome_1/tuxedo12.2.2.0.0/myapps/simpapp/tuxconfig; export TUXCONFIG

The following example is only for reference.

b) Run the following command after modifying the configuration:

source simpapp.env

Every time the system restarts, some of the paths are reset to the default values, so run this command after the system restart

4. Edit and load simpapp config file

a) Go to the app directory.

cd $APPDIR

b) Edit the ubbsimple file.

vi ubbsimple

Set IPCKEY between 32,768 and 262,143 because it avoids conflicts with system-assigned IPCkeys and ensures proper functioning of interprocess communication within the Tuxedo environment.
Change MACHINES DEFAULT
a. Add APPDIR, TUXCONFIG and TUXDIR
Change Machine name to hostname of the machine.
Save the ubbsimple file.

c) Load the ubbsimple file.

tmloadcf ubbsimple -y

The “tmloadcf” command is used to load a Tuxedo configuration file. The command “tmloadcf ubbsimple -y” loads the “ubbsimple” configuration file into the Tuxedo system, with the “-y” option indicating a silent mode of operation.

5. Examine, edit, and compile the client.

Add header file in simpcl.c

#include <string.h>

Run the following

Note: Make sure that you have C compiler in your system.

buildclient -o simpcl -f simpcl.c

This command is to compile and build a Tuxedo client program named “simpcl” from the source file “simpcl.c”.

6. Examine and compile the server.

Buildserver -o simpserv -f simpserv.c -s TOUPPER

This command compiles and builds a Tuxedo server program named “simpserv” from the source file “simpserv.c” and registers it with the service name “TOUPPER.” This server program handles requests related to the “TOUPPER” service.

7. Start tlisten.

tlisten -l //apphost1:6502

The command tlisten -l //apphost1:6502 is to start the Tuxedo Listener process (tlisten) on the specified network address and port. The following is a breakdown of the command:

tlisten: It is the command to start the Tuxedo Listener process.
-l: It specifies that the following argument is the network address and port to listen on.
//apphost1:6502: It is the network address and port where the Tuxedo Listener will listen for incoming connections. In this example, the Listener will listen on the host named apphost1 at port 6502.

When you run this command, the Tuxedo Listener process will start and bind to the specified network address and port. It will wait for incoming requests from Tuxedo clients or services and route them to the appropriate Tuxedo server processes based on the configured services and routing rules.

tlisten -l //apphost1:6502

To check whether the listener is started:

Check the ULOG file; the ULOG file name shows the times map in mmddyy format. The following is an example

tail -f ULOG.040823

8. Boot the application

tmboot -y

tmboot can be invoked only by the administrator of the bulletin board (as indicated by the UID parameter in the configuration file) or by root. The tmboot command can be invoked only on the machine identified as MASTER in the RESOURCES section of the configuration file, or the backup acting as the MASTER.

The “-y” option assumes a yes answer to a prompt that asks if all administrative and server processes should be booted.

9. Execute the runtime application

Run the following command to convert the string to upper case.

Make sure that BBL is available:

which BBL

BBL stands for Bulletin Board Liaison. BBL is a crucial component responsible for managing the communication between Tuxedo application servers and clients.

./simpcl “hello, world”

Output:

“Returned string is: HELLO, WORLD”

10. Monitor the run-time application

Run tmadmin command on the app directory

tmadmin

By using these commands in the tmadmin interface, you can monitor the state of server processes and service handlers, which provides valuable insights into the health and performance of your Tuxedo application environment.

psr

psr: The psr command in tmadmin displays the status of Tuxedo server processes. It provides information about the running server processes, their status, process IDs (PIDs), and other relevant details. This command helps you identify the active server processes in the Tuxedo domain.

psc

psc: The psc command in tmadmin displays the status of Tuxedo service handlers. It shows information about the service handlers currently registered in the Tuxedo domain, including their names, statuses, and other attributes. This command helps you monitor the availability and status of service handlers in the Tuxedo domain.

11. Shut down the application

tmshutdown -y

Monitoring Tuxedo application using Instana

Instana collects metrics for Tuxedo Domain, Machine, Server, and Service.
Instana supports only local monitoring with SECURITY configuration as NONE.
Install the agent according to your OS from the Instana. For example, you can see the following steps for Linux:

The procedures to install the agent vary depending on the operating system. For more information, see Installing host agents.

After you install the agent, go to the path in which the agent is installed, for example: /opt/instana/agent
Edit the configuration.yaml file in the <agent>/etc/instana/configuration.yaml file.

Add these details according to your Tuxedo app setup. This image is for your reference.

If the Tuxedo plug-in is correctly configured on the Tuxedo server, the Tuxedo sensor is downloaded and starts automatically. The data is collected at a given pollRate.

Then, go to the Instana UI. In the infrastructure map, you can see your Tuxedo app. Each zone is named according to how you named zones in the availabilityZone. If the zones are not named, you can find them in the Tuxedo Domains Zone.