Oracle TSAM Reference Guide

The Oracle TSAM Reference Guide describes system processes and commands delivered with the Oracle TSAM software.

Table 1 lists the Oracle TSAM system processes and commands.

 

Table 1 Oracle TSAM System Processes and Commands 

Name	Description
LMS (Local Monitor Server)	The Oracle TSAM Agent Local Monitor Server
tpgetcallinfo	Routine for retrieving call path message monitoring attributes

LMS (Local Monitor Server)

Name

LMS—The Oracle TSAM Agent Local Monitor Server

Synopsis

LMS SRVGRP="identifier" SRVID="number" [other_parms]

CLOPT= "-A -- -l tsam-manager-dataserver-url [-t heartbeat-interval]

[-m metrics-shm-size]”

Description

LMS is an Oracle TSAM Agent Tuxedo server. It provides the following functions:

•	Acts as the local Tuxedo domain data collection proxy

The performance metrics collected by the Oracle TSAM framework are passed to the plug-in. Oracle TSAM default plug-in sends the data to the LMS using the Tuxedo service infrastructure.

•	Plug-in metrics are stored in the LMS before being sent to the Oracle TSAM manager data server. The LMS and Oracle TSAM manager use the HTTP+XML protocol.

•	Other management information exchanges between the LMS and Oracle TSAM manager.

The LMS must be configured in the UBBCONFIG file and set with the proper options. One Tuxedo machine must be configured with one LMS. Multiple LMS on one machine is not supported. LMS is recommended to be configured at the end of UBBCONFIG so that it can retrieve all server information when Tuxedo domain booted. LMS still can synchronize the configuration to TSAM manager periodically.

Options

-l

Mandatory parameter. It is followed by the Oracle TSAM manager data server. The host address and port number are set based on your Oracle TSAM manager installation. The format is:

host:port/tsam

•	host is the host DNS name or IP address of the box where TSAM manager is installed.

•	Port is the TCP port number.

•	tsam is the Oracle TSAM manager reserved path name.

-m

Optional parameter. Specifies the size of shared memory used to store raw data metrics. The optional trailing letter k or m denotes KB or MB bytes, otherwise the unit is in bytes. The effective value is rounded up to 4K size since it is the page size for most platforms.

The default value is 10MB if this option is not present. The size of the shared memory will not grow at run time when there is no free space to store new data. In this case oldest data is replaced with new data.

-t

Optional parameter. It specifies the time interval in seconds that LMS should connect to the Oracle TSAM manager with configuration synchronization. The default value is 100 seconds.

Example(s)

Listing 1‑1 shows the LMS in UBBCONFIG.

Listing 1‑1 LMS in UBBCONFIG

...
*SERVERS
LMS SRVGRP=LMSGRP SRVID=1
CLOPT=”-A -- -l tsamweb.abc.com:8080/tsam/-m 20M -t 180”

...

 

tpgetcallinfo

Name

tpgetcallinfo()— Routine for retrieving call path message monitoring attributes.

Synopsis

int tpgetcallinfo(const char *msg, FBFR32 **obuf, long flags)

Description

tpgetcallinfo() is used for call path monitoring only. It supports the following parameters:

msg

The typed buffer use for measurement.

obuf

The FML32 buffer used to contain the fields.

flags

Reserved for future use.

For monitored calls, tpgetcallinfo()uses the following fields: following fields:

tpgetcallinfo()

Retrieves the message monitoring attributes when call path monitoring is enabled.

tpgetcallinfo()

Can be used in different scenarios to accomplish different functions. Typical usage is as follows:

•	Application server calls tpgetcallinfo() to check the requested message monitoring attributes. It can provide the following information:

- Correlation ID of the request. It is generated by the caller

- Begins time stamping when the monitoring initiator starts the call

- Last stop time stamp on the call path tree of the monitored request. Usually, it is used to measure the process requested message waiting time for a service

- Workstation client address if the request is from a Tuxedo workstation client

•	The monitoring initiator calls tpgetcallinfo() to get the end to the monitored call end time.

Note: tpgetcallinfo() can be called at any time for a reply buffer after a reply is received. This is especially useful with tpacall/tpgetrply.

Table 2 lists the FML monitor metrics field names.

 

Table 2 Monitor Initiator Field Names

Field Name	Type	Description	Service	Monitoring Initiator
TA_MONCORRID	string	The monitored call correlation ID. It is a critical call path monitoring metric.	Y	Y
TA_MONLASTTIMESEC	long	Timestamp for the last stop on the call path tree in seconds.	Y	Y
TA_MONLASTTIMEUSEC	long	Ttimestamp of last stop on the call path tree in microseconds.	Y	Y
TA_MONSTARTTTIMESEC	long	Timestamp when the monitoring initiator starts the call in seconds.	Y	Y
TA_MONSTARTTIMEUSEC	long	Timestamp of the monitoring initiator starts the call in microseconds.	Y	Y
TA_MONCLTADDR	string	The workstation client address	Y	N
TA_MONTOTALTIME	long	The end-to-end time used for a monitored call in milliseconds.	N	Y

Return Values

Upon successfully getting a FML32 buffer containing the monitoring attributes, returns 0.

Upon failure, tpgetcallinfo() returns -1 and sets tperrno to indicate the error condition.

Errors

Upon failure, tpgetcallinfo() sets tperrno to one of the following values,

[TPEINVAL]

Invalid arguments were given (for example, msg is NULL or obuf is not a valid FML32 buffer)

[TPESYSTEM]

The message input does not contain monitoring attributes. Usually this is because the call path monitoring is not turned on for the message.

[TPEOS]

An operating system error has occurred.

Example(s)

Listing 1‑1 provides a service-side tpgetcallinfo example.

Listing 1‑1 Service-Side tpgetcallinfo Example

#include <stdio.h>
#include <atmi.h>
#include <userlog.h>
#include <fml32.h>
#include <tpadm.h>
#if defined(__STDC__) || defined(__cplusplus)
tpsvrinit(int argc, char *argv[])
#else
tpsvrinit(argc, argv)
int argc;
char **argv;
#endif
{

       /* tpsvrinit logic */
#ifdef __cplusplus
extern "C"
#endif
void
#if defined(__STDC__) || defined(__cplusplus)
APPSVC(TPSVCINFO *rqst)
#else
TOUPPER(rqst)
TPSVCINFO *rqst;
#endif
{
       FBFR32 *metainfo;
       int len = 0;
       /* Allocate the metainfo space */
       metainfo = tpalloc("FML32", NULL, 1024);
       if (metainfo == NULL ) {
              userlog("Memory allocation failed");
              tpreturn(TPFAIE, 0, 0, 0);
       }
       /* Get the monitoring attributes*/
       if ( tpgetcallinfo(rqst->data, &metainfo, 0) == 0 )
       {
              char *corrid;
              long laststopsec, starttimesec;
              if ((corrid = Ffind32(metainfo, TA_MONCORRID, 0, &len) ) {
                     userlog("Correlation ID = %s", corrid);
              }
              len = sizeof(starttimesec);
              if (( Fget32(metainfo, TA_MONSTARTTIMESEC, &starttimesec, &len) == 0) {
                     userlog("Message beginning time = %ld", starttimesec);

              }
}
              len = sizeof(lasttimesec);
       if (( Fget32(metainfo, TA_MONLASTTIMESEC, &lasttimesec, &len) == 0) {
              userlog("Message entering my queue time = %ld", lasttimesec);

       }
       }
       tpfree(metainfo);
       /* rest of service processment */
       ......
}