1 TSAM Plus Server, Command, and API Reference
This chapter contains the following sections:
1.1 Local Monitor Server
This section contains the following topics:
Parent topic: TSAM Plus Server, Command, and API Reference
1.1.3 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]”Parent topic: Local Monitor Server
1.1.4 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/HTTPS protocol
- Other management information exchanges between the LMS and Oracle TSAM Plus manager.
The LMS must be configured in the
UBBCONFIGfile 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 ofUBBCONFIGso that it can retrieve all server information when Tuxedo domain booted. LMS still can synchronize the configuration to TSAM Plus manager periodically.
Parent topic: Local Monitor Server
1.1.6 Example(s)
Listing 1‑1 shows the LMS in UBBCONFIG.
...
*SERVERS
LMS SRVGRP=LMSGRP SRVID=1
CLOPT=”-A -- -l tsamweb.abc.com:8080/tsam -m 20M -t 180 -n 64”
...Parent topic: Local Monitor Server
1.2 tlisten Options for JMX Monitoring
The following tlisten options serve for JMX
monitoring:
| IPv4 | IPv6 |
|---|---|
rmi://IP: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_memcannot be set smaller than the value ofjvm_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
keyStoreabsolute path.
Parent topic: TSAM Plus Server, Command, and API Reference
1.3 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.
Parent topic: TSAM Plus Server, Command, and API Reference
1.4 Call Path Monitoring APIs
This section contains the following topics:
Parent topic: TSAM Plus Server, Command, and API Reference
1.4.1 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.
Parent topic: Call Path Monitoring APIs
1.4.2 tsambegin(3c)
This section contains the following topics:
Parent topic: Call Path Monitoring APIs
1.4.2.1 Name
tsambegin()- Used in pair with tsamend() for users to manually add a segment to the current call path.
Parent topic: tsambegin(3c)
1.4.2.2 Synopsis
#include <tsam_ext.h>
long tsambegin(char* type, char * subtype, int argc, char ** argv, int flags)Parent topic: tsambegin(3c)
1.4.2.3 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.
Parent topic: tsambegin(3c)
1.4.2.4 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.
Parent topic: tsambegin(3c)
1.4.2.5 Errors
Its error codes are defined in the file
tsam_ext.h.
Table 1-1 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
Parent topic: tsambegin(3c)
1.4.3 tsamend(3c)
This section contains the following topics:
Parent topic: Call Path Monitoring APIs
1.4.3.1 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.
Parent topic: tsamend(3c)
1.4.3.2 Synopsis
#include <tsam_ext.h>
int tsamend(long cd, int argc, char ** argv, int flags);Parent topic: tsamend(3c)
1.4.3.3 Description
- 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.
Parent topic: tsamend(3c)
1.4.3.4 Return Values
If succeeded, returns 0; otherwise, returns a negative error code.
Parent topic: tsamend(3c)
1.4.3.5 Errors
Its error codes are defined in the file tsam_ext.h.
| 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
Call Path and Oracle Tuxedo Monitoring Policy in Oracle TSAM Plus User Guide
Parent topic: tsamend(3c)
1.5 TSAM Plus Environment Variable
This section contains the following topics:
Parent topic: TSAM Plus Server, Command, and API Reference
1.5.1 TSAM_LOG_LEVEL
This section contains the following topics:
Parent topic: TSAM Plus Environment Variable
1.5.1.1 Description
The environment variable TSAM_LOG_LEVEL specifies the TSAM Plus Agent log level. The following table lists the supported levels. If the environment variable is not set, the Agent log level is set to the default value INFO.
| 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 |
Parent topic: TSAM_LOG_LEVEL
1.5.1.2 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
Parent topic: TSAM_LOG_LEVEL
1.5.1.3 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.
Parent topic: TSAM_LOG_LEVEL
1.6 TSAM Plus Management Tool
This section contains the following topics:
Parent topic: TSAM Plus Server, Command, and API Reference
1.6.1 tsamadmin
This section contains the following topics:
Parent topic: TSAM Plus Management Tool
1.6.1.2 Description
tsamadmin is a management tool provided by TSAM Plus Agent. It provides the following functions:
- Configures LMS in the Tuxedo
UBBCONFIGfile and generate a newtuxconfigfile 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
TUXDIRandTUXCONFIGare set properly. - The
TUXCONFIGfile is generated properly and you have the read permission.
- The environment variables
Parent topic: tsamadmin
1.6.1.3 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.
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-createdUBBCONFIG 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:
- TSAM agent plug-in is correctly registered in Tuxedo. If the plug-in is not registered yet,
tsamadminhelps users to register the plug-in. - LMS server is configured in UBBCONFIG.
- Invalid format of LMS CLOPT is configured.
- 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 2), 3) and 4), the check can pass. That is, if any machine is not configured with an LMS,managercheckwill fail. In MP mode, ifmanagercheckis invoked on the slave node, only 1) is checked. - TSAM agent plug-in is correctly registered in Tuxedo. If the plug-in is not registered yet,
Following are managercheck options:
Parent topic: tsamadmin