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

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]”

Description

LMS is an Oracle TSAM Plus 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 Plus framework are passed to the plug-in. Oracle TSAM Plus 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 Plus manager data server. The LMS and Oracle TSAM Plus manager use the HTTP+XML 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.

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