TSAM Plus Server, Command, and API Reference

This chapter contains the following sections:

•	Local Monitor Server

•	tlisten Options for JMX Monitoring

•	GWTDOMAIN Option for BTM Monitoring

•	tmadmin Command

•	Call Path Monitoring APIs

•	TSAM Plus Environment Variable

•	TSAM Plus Management Tool

•	Deployment Utilities

Local Monitor Server

LMS

Name

LMS—The Oracle TSAM Plus Agent Local Monitor Server

Synopsis

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

CLOPT= "-A -- -l tsam-manager-dataserver-url[,tsam-manager-backupdataserver-url,…][;tsam-manager-dataserver-url, tsam-manager-dataserver-url,…] [-t heartbeat-interval] [-n fetch_coll_capacity] [-m metrics-shm-size] [-T data-thread-number][-e log-warning-interval][-p PayloadFileDIR][-M conditional-call-path-metrics-shm-size] [-F flush-interval]”

Description

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

•	Acts as the local Tuxedo machine data collection proxy

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

•	Plug-in metrics are stored in the LMS before being sent to the Oracle TSAM Plus manager data server. The LMS communicates with Oracle TSAM Plus Manager via HTTP protocol.

•	Other management information exchanges between the LMS and Oracle TSAM Plus 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 Plus manager periodically.

Options

-l

Mandatory parameter. It specifies the Oracle TSAM Plus manager data servers addresses. You can set one or multiple addresses. The host address and port number are set based on your Oracle TSAM Plus manager installation. The format is:

host:port/tsam, host:port/tsam, …[; host:port/tsam, host:port/tsam, …]

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

•	port is the TCP port number.

•	tsam is the Oracle TSAM Plus manager reserved path name.

TSAM Plus server addresses can consist of two parts using semicolon (;): the first active data servers part and the second standby data servers part. Each part contains multiple TSAM Plus server addresses separated by comma (,).

LMS logs on with the TSAM Plus manager specified by the first address. If failed to connect, LMS tries the next server. If no active data server is available, the standby data Server is used. At most 126 servers can be configured.

If a connected server is failed for health checking, LMS reconnects the servers from first to last.

When the connection to a data server is broken, the thread reconnects the data servers from first to last to get another active data server which connection number does not meet the maximum value. If there is no server available, the thread keeps reconnecting the data server one by one with an incremental sleep interval specified by the -r option.

Note:

Configuring multiple TSAM Plus manager addresses has been supported since TSAM Plus 12.1.3.

-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.

-r

Specifies the maximum sleep time (in milliseconds) of reconnecting when TSAM agent keeps failing to connect TSAM manager. The default value is 60,000 milliseconds.

-t

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

-n

Optional parameter, introduced since TSAM Plus 12.1.1.1. It specifies the amount of monitoring data sent by TSAM Plus agent to TSAM Plus manager per request. Valid value range is from 1 to 100 and the default value is 16. If configuring a value that is greater than 100, 100 will be used.

-T

LMS creates multiple threads to fetch data from Ring Buffer and sends the data to Manager Server. This option specifies the total number of threads the data servers can be connected. The threads number is distributed to each active data server evenly. The maximum value is 1023.

-e

Optional parameter. It specifies the time interval LMS sends a warning message to ULOG if performance metrics data is dropped due to shared memory size limit. Its range is [1-65535]. The default value is equal the -t value. The warning message reports how many messages have been lost during the past interval.

-p

Optional parameter. It specifies the local file path where the user payload data is stored. If not specified, the default user payload local file is generated at APPDIR with the main file name payload. If the parameter is specified as a relative path, it is relative to APPDIR. The payload in local file naming format is <domain>_<machine>_<yyyymmddhh24miss>.payload. If the file size is greater than 2G, a new file will be produced.

-F

Optional parameter. It specifies the time interval (in minutes) that LMS flushes payload data to disk only when the user payload data is stored in hadoop. The default value is 20 minutes.

-M

This parameter can be used when a conditional call path policy is enabled. It specifies the size of shared memory used to store conditional call path 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 100MB is used if this option is not specified. The suitable value of "-M" would be set according to the Tuxedo call load and the matching rate of the conditional filer of the policy. The shared memory size does not grow at run time when there is no storage space for new data. In this case the new data overwrites the oldest data stored.

If no conditional call path policy is enabled, you can set the value to 0 to avoid memory allocation.

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 -n 64”

...

 

tlisten Options for JMX Monitoring

The following tlisten options serve for JMX monitoring:

-j jmxaddr

Used to start the embedded JMX agent.

jmxaddr specifies the address of RMI connector of embedded JMX agent. If the address has been occupied by another process, an error message is printed into ULOG and JMX agent fails to start up. Table 1 lists the jmxaddr adress formats.

 

Table 1 IPv4 and IPv6 Address Formats

IPv4	IPv6
rmi://IP:port rmi://hostname:port_number	rmi://[IPv6 address]:port rmi://hostname:port_number
rmi://#.#.#.#:port_number	Hex format is not supported

Note:

For the MP domain, you need to configure the -j option for tlisten on all machine nodes.

-m jvm_min_mem

Specifies the minimal memory size (in MB), that should be allocated for the JVM used by JMX agent. The default value is 200MB.

-M jvm_max_mem

Specifies the maximum memory size (in MB) that can be allocated for the JVM used by JMX agent. The value of jvm_max_mem cannot be set smaller than the value of jvm_min_mem, otherwise the JVM are not created and JMX agent fails to start up. The default value is 500MB.

-S

Specifies SSL connection rather than the default connection between EM OMS/Agent and JMX agent.

-C keyStore

Specifies the keyStore absolute path.

-P keyStorePassword

Specifies the environment variable in which the password for the key store is stored. This variable is only usefully when no tty is attached.

GWTDOMAIN Option for BTM Monitoring

A new CLOPT option is introduced for GWTDOMAIN.

-m

The BTM monitor URL. The format is http://<HOST>:<PORT>/btmmonitor/agent/agent/.

Example:

GWTDOMAIN SRVGRP="gwgrp" SRVID=1003 CLOPT="-A -- -m http://bej301493.cn.oracle.com:9001/btmmonitor/agent/agent/"

When this option is specified, GWTDOMIAN starts an embedded JVM and runs a BTM delegate observer to monitor bidirectional calls between WTC and itself.

tmadmin Command

Oracle TSAM Plus Agent provides a tmadmin command to turn on/off. If you want to turn off Oracle TSAM Plus temporally, this command can be used. The format is as follows:

changemonitor (chmo) [-m machine] on|off

The -m parameter specifies the logic machine name where the Oracle TSAM Plus collection is disabled. Without this option, monitoring on all machines is disabled. By default, monitoring is turned on. If monitoring is turned off, all data collection is stopped even if there is a monitoring policy defined.

Call Path Monitoring APIs

tpgetcallinfo(3c)

tpgetcallinfo is used for call path monitoring. Using tpgetcallinfo allows applications to make dynamic decisions based on application performance metrics. When call path monitoring is enabled, tpgetcallinfo allows applications to get the corresponding call path information, for example, correlation ID and various timestamps.

For more information, see tpgetcallinfo(3c) in the ATMI C Function Reference.

tsambegin(3c)

Name

tsambegin()- Used in pair with tsamend() for users to manually add a segment to the current call path.

Synopsis

#include <tsam_ext.h>

long tsambegin(char* type, char * subtype, int argc, char ** argv, int flags)

Description

type

Specifies the monitoring type defined by users. Its value is a NULL-terminated string with a length limit of 255. For example, it could be "CICS" or "Database".

subtype

Specifies the subordinate command type defined by users. Its value is a NULL-terminated string with a length limit of 255. For example, it could be "insert" or "update". Both type and subtype values can be potentially specified as filters when users submit a query.

argc

Specifies the number of string pointed by argv. It must not less than 0.

argv

Specifies a list of properties transferred to TSAM, in which every string should be formatted like (%s=%s). The property name and value are defined by users. The maximum total length of argv is 4000 bytes.

flags

Reserved.

Return Values

If succeeded, TSAM Plus returns a positive description in long type denoting a sequence ID. The sequence ID is transferred to tsamend(), by which TSAM Plus can correlate the two APIs.

Otherwise, TSAM Plus returns a negative error code.

Errors

Its error codes are defined in the file tsam_ext.h.

 

Table 1‑1 tsambegin Error Codes

Error Macro Name	Value	Description
TSAM_EXT_ERROR_NOTENABLE	-1	TSAM Plus is not enabled
TSAM_EXT_ERROR_NOTMONABLE	-2	TSAM Plus is not monitorable
TSAM_EXT_ERROR_INVALIDARG	-3	argc or argv value is invalid
TSAM_EXT_ERROR_INVALIDTYPE	-4	type value is invalid
TSAM_EXT_ERROR_INVALIDSUBTYPE	-5	subtype value is invalid

See Also

tsamend(3c)

tsamend(3c)

Name

tsamend()- Used in pair with tsambegin() for users to manually add a segment to the current call path. It must be used with tsambegin() in the same thread.

Synopsis

#include <tsam_ext.h>

int tsamend(long cd, int argc, char ** argv, int flags);

Description

cd

Specifies the sequence ID returned by tsambegin().

argc

Specifies the number of string pointed by argv. It must not less than 0.

argv

Specifies a list of properties transferred to TSAM Plus, in which every string should be formatted like (%s=%s). The property name and value are defined by users. The maximum total length of argv is 4000 bytes.

flags

Reserved.

Return Values

If succeeded, returns 0; otherwise, returns a negative error code.

Errors

Its error codes are defined in the file tsam_ext.h.

 

Table 1‑2 tsamend Error Codes

Error Macro Name	Value	Description
TSAM_EXT_ERROR_NOTENABLE	-1	TSAM Plus is not enabled
TSAM_EXT_ERROR_NOTMONABLE	-2	TSAM Plus is not monitorable
TSAM_EXT_ERROR_INVALIDARG	-3	argc or argv value is invalid
TSAM_EXT_ERROR_INVALIDCD	-6	cd value is invalid

See Also

tsambegin(3c)

Call Path and Tuxedo Monitoring Policy in Oracle TSAM Plus User Guide

TSAM Plus Environment Variable

TSAM_LOG_LEVEL

Description

The environment variable TSAM_LOG_LEVEL specifies the TSAM Plus Agent log level. Table 1‑3 lists the supported levels. If the environment variable is not set, the Agent log level is set to the default value INFO.

 

Table 1‑3 Supported Log Levels

Levels	Description
OFF	Does not log messages
ERROR	Only logs ERROR messages
WARN	Logs ERROR and WARN messages
INFO	Logs ERROR, WARN, and INFO messages
DEBUG	Logs DEBUG, ERROR, WARN, and INFO messages
TRACE	Logs all messages

Output and Style

Most of log messages are outputted to ULOG.

The TRACE messages of the metrics generated by Agent plug-in are outputted to the file raw.agent.log.

The TRACE messages of the metrics to be reported to Manager are outputted to the file raw.LMS.log.

When the log level is "OFF" to "INFO", the log message in ULOG is like this:

155843.bjlinux99.cn.oracle.com!LMS.6519.285202160.0: INFO: thread pool init success with 1 thread(s)

When the log level is TRACE, the log messages in ULOG contain indents:

154521.bjlinux99.cn.oracle.com!LMS.6441.2304538352.0: LMS.c:tpsvrinit():2091: TRACE: hbinterval(100),rawshmsize(10485760),datathreadcnt(1), maxinterval(60000)

154521.bjlinux99.cn.oracle.com!LMS.6441.2304538352.0: LMS.c:tsam_thrpool_init():416: TRACE: enter

154521.bjlinux99.cn.oracle.com!LMS.6441.2304538352.0: LMS.c:tsam_thrpool_init():433: INFO: thread pool init success with 1 thread(s)

154521.bjlinux99.cn.oracle.com!LMS.6441.2304538352.0: LMS.c:tsam_thrpool_init():435: TRACE: leave

Examples

To set the log level of LMS to TRACE, set TSAM_LOG_LEVEL to TRACE, and then boot (or reboot) LMS in the same console.

To set the log level of Agent plug-in to TRACE, set TSAM_LOG_LEVEL to TRACE, and then boot (or reboot) Oracle Tuxedo servers in the same console.

TSAM Plus Management Tool

tsamadmin

Synopsis

tsamadmin <sub-command> <options>|<target>

Description

tsamadmin is a management tool provided by TSAM Plus Agent. It provides the following functions:

•	Configures LMS in the Tuxedo UBBCONFIG file and generate a new tuxconfig file automatically.

•	Runs a sanity check to check configurations for TSAM Plus Agent and Manager.

Note:

Before you can run this command, the following prerequisites must be met:

•	The environment variables TUXDIR and TUXCONFIG are set properly.

•	The TUXCONFIG file is generated properly and you have the read permission.

Sub Commands

autoconfig(ac){-s|--static} {–H|--hostname} hostname:port

This command is used to configure LMS in the Tuxedo UBBCONFIG file and generate a new tuxconfig file automatically. Only one LMS configuration is allowed on one machine. If the LMS configuration already exists, the command sends a notification and exits.

-s | --static

Uses the static method to generate the tuxconfig.

-H | --hostname

Specifies the hostname and port of TSAM Plus Manager.

For example, suppose you run the command:

tsamadmin autoconfig -s -H tsamhost.com:7001

A new UBBCONFIG file is created and the LMS is configured in the new-created group (Group1), as shown below:

GROUP1 LMID=SITE1 GRPNO=1

LMS SRVGRP=GROUP1 SRVID=90 CLOPT="-A -- -l tsamhost.com:7001/tsam "

Note:

The new-created UBBCONFIG file is named “UBB”. Before you run tsamadmin autoconfig, make sure your existing UBBCONFIG file does not use the same name if you do not want the old file to be overwritten.

After the command is executed successfully, a new tuxconfig is generated with the original file name and then the old file is renamed as <original name. + timestamp>.

managercheck(mc)[options]

Checks if TSAM Plus Agent is able to communicate with the Manager. It checks the following configurations in sequence:

a.	TSAM agent plug-in is correctly registered in Tuxedo. If the plug-in is not registered yet, tsamadmin helps users to register the plug-in.

b.	LMS server is configured in UBBCONFIG.

c.	Invalid format of LMS CLOPT is configured.

d.	The TSAM Manager host and port configured in LMS CLOPT can be reached.

If any step fails, the check is terminated and an error report is shown.

Note:

This check can be processed on SHM and MP mode. For the MP mode, only if all the configured domains meet b), c) and d), the check can pass. That is, if any machine is not configured with an LMS, managercheck will fail. In MP mode, if managercheck is invoked on the slave node, only a) is checked.

Following are managercheck options:

-h | --help

Display tsamadmin managercheck usage.

-s | --slave

Run the check on slave node. It only checks TSAM Plus Agent plug-in registration and tuxconfig is not required.

Deployment Utilities

Database Deployment Utilities

Oracle TSAM Plus provides the following database deployment utilities:

•	Unix/Linux Database Deployment: DatabaseDeployer.sh

•	Windows Database Deployment: DatabaseDeployer.cmd

Database deployment utilities are used to create a TSAM Plus database, update the database information in the tsam_wls12c.ear file (located at <TSAM_DIR>/deploy), or reset the administrator password. The syntax is as follows:

DatabaseDeployer.sh/cmd -type derby|oracle [-enable_partition yes|no] -hostname XXX -port XXX [-dbname XXX] [-url XXX] [-user XXX [-password XXX] [-dbSysdbaUser XXX -dbSysdbaPwd XXX -tsamDbTablespace XXX]] [-overwrite yes|no] [-admingid XXX] [-viewergid] [-adminpassword XXX]] [-maxActive XXX] | [-wlsdsJNDIname XXX] [-resetpassword yes|no]

Table 1‑4 lists the database deployment utility parameters.

 

Table 1‑4 database Deployment Utility Parameters

Parameters	Description
type	Mandatory. The database type. The value is derby or oracle.
enable_partition	Whether to enable partition. It is mandatory when creating a new database. The value is yes or no.
hostname	Database server host name. It is mandatory when -url is not specified.
port	Database port. It is mandatory when -url is not specified.
dbname	Optional. Database name. Default is TSAM.
url	Optional. The database URL directly. The parameter hostname, port, dbname will be ignored if it is specified.
user	Optional. database user name
password	Optional. database user password
dbSysdbaUser	The DBA user name to create the TSAM Plus user when DB type is Oracle. It is mandatory when creating a new Oracle schema.
dbSysdbaPwd	DBA password to create TSAM user when DB type is Oracle. It is mandatory when creating a new Oracle schema.
tsamDbTablespace	Table space to create the TSAM Plus user when DB type is Oracle. It is mandatory when creating a new Oracle schema.
overwrite	Optional. whether overwrite if database has existed. The value is yes or no. Default is no.
admingid	Optional. The GID of the default administrator group. Default is 0.
viewergid	Optional. The GID of the default viewer group. It should be an integer and not equal to admingid. Default is 1.
adminpassword	Optional. The password of the default admin user. Default is admin1.
resetpassword	Optional. Whether reset the password of the default admin user. The value is yes or no. Default is no.
wlsdsJNDIname	Optional. Non-JTA data source JNDI name (for Weblogic only). All the above arguments are ignored if it is specified.
maxActive	Optional. The Max DB connection number. Default is 30.

Application Server Deployment Utilities

Oracle TSAM Plus provides the following application server deployment utilities:

•	Unix/Linux Application Server Deployment: AppServerDeployer.sh

•	Windows Application Server Deployment: AppServerDeployer.cmd

Application Server Deployment Utilities are used to deploy the tsam_wls12c.ear file (located at <TSAM_DIR>/deploy) to a WebLogic domain. The syntax is as follows:

AppServerDeployer.sh/cmd -directory XXX [-adminurl XXX ] -user XXX -password XXX

Table 1‑5 lists the application server deployment utility parameters.

 

Table 1‑5 Application Server Deployment Utility Parameters

Parameters	Description
directory	Mandatory. WebLogic server directory
adminurl	Optional. WebLogic domain URL. Default is localhost:7001.
user	Mandatory. WebLogic user name
password	Mandatory. WebLogic user password