|
|
This topic contains the following sections:
To effectively and correctly use the Oracle TSAM Agent, please note the following prerequisites:
Oracle TSAM provides flexible and comprehensive monitoring management functionality. It provides the following features:
Before monitoring starts, you must specify what Tuxedo system components and applications you want monitored, and how you want to monitor them by configuring respective monitoring policies. A monitoring policy defines the monitored Tuxedo component, monitoring categories, and monitoring properties.
The monitored Tuxedo component can be a machine, group and/or server. At the machine level, all Tuxedo application processes are effected. At the group level, all the servers running in a group are effected. For a particular server, only the server instance is effected.
| Note: | The later setting of a monitoring policy overwrites previous settings. For example, if a server has enabled “service” monitoring, and the last group that the server belonged to is set to “call path” monitoring, the “call path” attribute overwrites the existing “service” monitoring setting. |
Oracle TSAM Agent has 4 monitoring categories:
When call path monitoring is enabled, the Oracle TSAM framework tracks a requesting calls (using tpcall or tpacall) until a reply is received by the initiating caller. All back-end services track and compose the call path tree nodes. The edge connecting service nodes carry the transport information
Call path monitoring can be initiated from a client, server or WSH/JSH. When a reply is received from the initiating caller, the monitoring activity for the call is complete.
If “app” is specified for a process, the process becomes the “monitoring initiator”. A call from this process can be tracked throughout the Tuxedo system until a reply is received. The Oracle TSAM console tracks the call path tree in real time. Monitoring initiator processes are limited to the following:
for a particular call is started by the “initiator,” monitoring attributes are propagated with this call along its call path. All processes handling this call recognize monitoring characteristics and update related metrics.
An application server has two specific and important functions:
| Note: | Oracle TSAM uses the “monitoring initiator” as part of the correlation ID. For a server process, it is the process name. For a client process, you should specify the name the same as specified using
userlog(3c). If no name is given, Oracle TSAM uses “client” as the fixed name. |
Unlike call path monitoring (which focuses on message correlation triggered by a particular call), service monitoring focuses on pure service execution. It records service execution status including the request waiting time, service routine execution time, execution status and buffer size, and so on.
Enables service monitoring. It applies to normal Tuxedo application services and services imported by GWTDOMAIN.
The Tuxedo framework has two key servers, BRIDGE and GWTDOMAIN, that connect machines and domains in a distributed computing environment. Oracle TSAM also monitors the activity on the these servers. System server monitoring tracks the overall data for each network connection, and does not differentiate what service or call is passed through.
Enables system server monitoring for the current process. It only applies to Tuxedo BRIDGE and GWTDOMAIN servers. When sys is set, Oracle TSAM periodically reports the data on the connected network link.
A major Tuxedo function is transaction monitoring (following XA specifications). A global transaction may have multiple resource managers involved. Because the XA interface is implemented by the vendor, it is difficult for Tuxedo users to measure how much time is used by the XA calls. Oracle TSAM provides transaction monitoring functionality.
Besides transaction call time tracking, Oracle TSAM agent also reports the return code and transaction ID. If a transaction is sent across domains, Oracle TSAM also reports mapping between local transactions and remote transactions.
Enables transaction monitoring. Each transaction call is measured and the execution status sent to the Oracle TSAM manager.
All the four monitoring types can be used together or individually. The Oracle TSAM console organizes the functionality pages based on the defined monitoring type(s).
Oracle TSAM Agent has 4 monitoring properties:
Call path monitoring properties use the following keywords:
Enables monitoring frequency. Its range is [0-65535]. “0” indicates that monitoring is stopped. If not specified, the default value is 1 which specifies that every request is monitored.
appratio only applies to the “monitoring initiator” and controls the request monitoring frequency. For example, if a client process is set to appratio=3 and issues 10 tpcalls, then request calls 1, 4, 7, 10 are tracked.
Initiates the time interval (in seconds) for a monitored action. Its range is [0-65535]. If not specified, the default value is “0” which specifies that there is no time limitation.
Similar to appratio, appinterval only applies to the “monitoring initiator.” For example, if a client process is set to “appinterval=10” and continually issues calls for 60 seconds, then calls are tracked at the following time intervals: 0, 10, 20, 30, 40, 50, 60.
| Note: | “appratio” and “appinterval” are exclusive. If they are not specified, then every call is monitored. |
For monitored call path requests, by default every process that participates on a call path tree invokes the monitoring plug-in. In some instances, you may not want to trigger the plug-in. Here are two scenarios:
tpgetcallinfo() to retrieve information.
Using “appnolog” allows the Oracle TSAM framework to track the calls in Tuxedo system, but without initiating the plug-in invocation. “appnolog” default value is 0 which permits the plug-in to be invoked If “appnolog” is set to 1, the plug-in is not invoked.
Here are two appnolog usage examples:
Plug-in invocation is only allowed when “appnolog” is not set in both examples.
| Note: | If “appnolog” is used in part of process on the call path tree, the call path tree on Oracle TSAM Web console is not complete. |
Used only for Tuxedo BRIDGE call path monitoring. By default, messages passing through BRIDGE are encoded. This means the Oracle TSAM framework cannot extract the monitoring attributes from the message. If BRIDGE is monitored, appdecode must be set for BRIDGE processes. The default value is 0, which means BRIDGE will not decode the message and will not appear in the call path tree. If “appdecode” is set to 1, BRIDGE decodes the “monitored message” and composes the transportation information on the call path tree.
| Note: | If “BRIDGE” is set with “appdecode=1”, it will not decode non-monitored messages. |
Controls service execution monitoring frequency. Similar to appratio.
Controls service time interval monitoring. Similar to appinterval.
| Note: | svcratio and svcinterval are exclusive. If both of are not specified, all services are monitored. |
Controls the plug-in invocation interval of the monitored BRIDGE or GWTDOMAIN. Its range (in seconds) is [30-65535]. The default value is 300.
Controls the transaction call monitoring process-level frequency. Its range is [0-65535]. The default value is 1. A 0 value stops transaction monitoring.
| Note: | It is recommended that you use the default value since other values may cause a loss of transaction monitoring data. |
Oracle TSAM provides four policy monitoring configuration interfaces:
Policy monitoring information must use the following format:
monitoring category:monitoring properties:required fields
Table 2-1 lists the corresponding keywords
The TMMONITOR environment variable enables monitoring for required processes. It can be defined in ENVFILE parameter in the UBBCONFIG file *MACHINES section or in Tuxedo application startup scripts. Usually Tuxedo client programs use environment variables to control the behavior.
| Note: | Oracle TSAM does not restore the original process monitoring settings if the process is restarted unless TMMONITOR is used. |
Listing 2-1 provides a TMMONITOR example with all four monitoring areas turned on. The policies are using default values.
TMMONITOR=app,svc,tran,sys::
Listing 2-2 provides a TMMONITOR example with call path and service monitoring turned on. appratio is set to 10 and svcin terval is set to 30.
TMMONITOR=app,svc:appratio=10,svcinterval=30:
Using the tmadmin changemonitor command allows you to dynamically change monitoring settings. Listing 2-3 provides a changemonitor usage example.
> help chmo
changemonitor (chmo)[-m machine] | [-g groupname] | [-g groupname -i srvid] newspec
Listing 2-4 provides a changemonitor example that enables all the service monitoring for processes running on machine SITE1.
tmadmin
chmo -m SITE1 svc::
Listing 2-5 provides a changemonitor example that enables service and transaction monitoring for all GROUP1 servers. svcinterval is set to 30 seconds.
tmadmin
chmo -g GROUP1 svc,tran:svcinterval=30:
Listing 2-6 provides a changemonitor example that enables GWTDOMAIN system monitoring with sysinterval set to 30 seconds. The GWTDOMAIN is located at group GWGRP, server ID 10.
tmadmin
chmo -g GWGRP -i 10 sys:sysinterval=30:
Oracle TSAM framework also opens the Tuxedo MIB interface for developers. The TA_TMMONITOR attribute set in the following MIB(5) classes can be used to control Oracle TSAM monitoring. TA_TMMONITOR accepts the same string format used in the command line and environment variables.
For more information, see MIB(5) in reference in the File Formats, Data Descriptions, MIBs, and System Processes Reference.
| Note: | TA_TMMONITOR is a local MIB attribute, so when using the MIB for set operation, the MIB_LOCAL field must be set. The MIB “get” operation is not supported in the current release. |
The monitoring policy can also be configured using the Oracle TSAM Console policy management page. The Oracle TSAM Console policy management page allows you to:
| Note: | It is not recommended that you use Tuxedo-side control mechanisms and Oracle TSAM console-side policy management together; monitoring consistency and accuracy may be affected. |
| Note: | For example, a monitoring policy is created using the Oracle TSAM console and applied to Tuxedo components, but the monitoring policy is changed later using Tuxedo-side command line settings. The Oracle TSAM is not aware of the Tuxedo-side changes and still shows its original settings. |
If you use the TMMONITOR, changemonitor command, or MIB, cancel monitoring is initiated in the same way as you enable monitoring. Setting the string specification to “::” cancels monitoring on the effected process. The Oracle TSAM Console allows to cancel using the GUI interface.
User application can take advantage of the monitoring attributes by using tpgetcallinfo. tpgetcallinfo is designed for call path monitoring. Using tpgetcallinfo, allows applications to make dynamic decisions based on application performance metrics.
For more information, see
tpgetcallinfo() in the Oracle TSAM Reference Guide.
Local Monitor Server (LMS) is a component of Oracle TSAM Agent. It performs the following tasks:
For more information, see LMS in the Oracle TSAM Reference Guide.
You can also define and generate event monitoring using Oracle TSAM. Event monitoring data is collected by the Oracle TSAM Agent and sent to the Oracle TSAM Manager. This process may increase system overhead.
The Oracle TSAM Event Plug-in help minimizes system overhead. It checks monitor data against pre-defined rules at the plug-in level. If the specified rule is satisfied, the event is sent to the Tuxedo Event Broker and/or Oracle TSAM Manager (specified in the rule definition).
Tuxedo Event Broker plug-in generated events are subscribed by application. The data portion of the event is an FML32 typed buffer which contains generated event information and monitoring data. Oracle TSAM Manager generated events can be queried from the Oracle TSAM Console TSAM > Alerts > Events menu (based on the plug-in contents).
Enabling the Oracle TSAM Event Plug-in requires the following administrative tasks:
To configure Oracle TSAM events plug-in the UBBCONFIG file, do the following two steps:
MAXSPDATA is needed to setup to reserve space in BB to store Plug-in event rules if the size of rules file is bigger than 8192 bytes.
| Note: | More precisely, it should be the effective size instead of the size of rules file. The effective size is approximately equal to: (the file size) - (size of comments) + (size of ignored optional items), all in bytes. |
The MAXSPDATA value should not be less than MAXQUEUES*514+32+max{8192, <the size of rules file>}.
The MAXSPDATA minimum value can be retrieved using the ctsamverify command in tmadmin if the rules file exists (tsamrules is the rules file name) and is formatted properly.
| Note: | The rule file <tsamrules> requires that MAXSPDATA is set to at least <41120>. |
The Tuxedo Event Broker and/or LMS must be setup in the *SERVERS section to enable the Oracle TSAM events plug-in. Listing 2-7 displays an LMS setup.A snippet UBBCONFIG is as following:
*SERVERS
TMSYSEVT SRVGRP=SYSGRP SRVID=1 CLOPT="-A --"
TMUSREVT SRVGRP=SYSGRP SRVID=2 CLOPT="-A --"
LMS jSRVGRP=SYSGRP SRVID=3
CLOPT="-A -- -l <tsam-hostname>:8080/tsam/dataserver -t 60"The rules file is a text file which contains Oracle TSAM event plug-in rule definitions. For more information, see Configuration Reference. Listing 2-8 lists an example rules file.
*GENERAL_RULESSVCCHECKALL=N
CALLCHECKALL=Y
*SVC_TRIGGER
SVCTRIGGER=TA_SVCRNAM[?]=='TOLOWER':TA_MONERRNO!=0:event(name=TSAM_svcerr,severity=Warn,destination=tsammanager+eventbroker)
*CALL_TRIGGER
CALLTRIGGER=TA_SERVERNAME=='simpserv':TA_MONELAPSETIME>=5000:event(name=TSAM_longcall,severity=Warn,destination=eventbroker+tsammanager)
*BBL_TRIGGER
BBLTRIGGER=TA_SVCRNAM[?]=='TESTCALL':TA_MONEXECTIME>=30000:event(name=TSAM_hang,severity=Warn,destination=tsammanager+eventbroker)
*REPORT_POLICY
SVCSENDTOLMS=Y
CALLSENDTOLMS=Y
The plug-in rules file is loaded at startup if the name of the file is specified using the TSAMPLUGINRULES (Listing 2-9) environment variable in MASTER node. The loaded rules are saved to the Bulletin Board and automatically sent to all machines in MP mode.
The plug-in rules file can be loaded or reloaded later at runtime using tmadmin from MASTER node (Listing 2-10). Two tmadmin commands (configtsam and ctsamverify) support the event plug-in rules file operation at runtime. For more in formation, see
tmadmin(1) in the Oracle Tuxedo Command Reference.
| Note: | Please note that all previous setting will be lost after reloading rules file. |
The BBL (or DBBL in MP mode) logs the messages LIBTUX_CAT:6775 or LIBTUX_CAT:6776 in ULOG if the rules file does not load successfully. New rules will not take effect if the LIBTUX_CAT:6775 message is logged since the rules file was not loaded successfully.
LIBTUX_CAT:6775:ERROR: Failed to load TSAM Event Trigger rules from file <%s>. Reason:<%s>
LIBTUX_CT:6776:INFO: Load TSAM Event Trigger rules from file <%s>. Rules size <%d>
TSAMPLUGINRULES=$APPDIR/tsamrules; export TSAMPLUGINRULES
tmboot -y\
tmadmin
> configtsam load tsamrules
INFO: TSAM Event Trigger successfully loaded.
Oracle TSAM Manager plug-in generated events can be queried from the Oracle TSAM console TSAM > Alerts > Events page. These events belong to a separate event catalog named, Plugin, that distinguishes it from events generated by the Oracle TSAM Manager alert definition (which belongs to another catalog named Alert).
Tuxedo Event Broker plug-in generated events are subscribed by application. The data portion of the event is an FML32 typed buffer which contains information of the generated event and monitor data.
Three trigger types are defined in the rules file:
Table 2-2 lists the common FML 32 data fields for all events. Table 2-3, Table 2-4 and Table 2-5 show other available data fields.
An Oracle TSAM rules file is made up of several possible specification sections. Lines beginning with an asterisk (*) indicate the beginning of a specification section. Each line contains the name of the section immediately following the *. Allowable section names are:
Parameters are generally specified using the following format: KEYWORD = value. A space (space or tab character) is allowed on either side of the equal sign (=). This format sets a value to KEYWORD. Valid keywords are described within each section.
The rules file may contain comments that start with a ‘#’ (pound sign). A “newline” ends a comment. Blank lines and comments are ignored.
These sections can be divided into three independent groups:
This section provides global event plug-in settings. Lines in the GENERAL_RULES section use the following format: KEYWORD=value; where KEYWORD is the name of the parameter, and the value is its associated value. Valid KEYWORDs are as follows:
SVCCHECKALL={ Y | N }
SVC_TRIGGER section should be evaluated. If SVCCHECKALL is not specified, the default is Y.
SVCCHECKALL is set to N, evaluation stops when a rule is evaluated as true. This means that, at most, one event is generated in this case. The rules are evaluated in the same order as they appear in the rules file.
CALLCHECKALL={ Y | N }
CALL_TRIGGER section should be evaluated. If CALLCHECKALL is not specified, the default is Y.
CALLCHECKALL is set to N, evaluation stops when a rule is evaluated astrue. This means that, at most, one event is generated in this case. The rules are evaluated in the same order as they appear in the rules file.
This section provides service event plug-in trigger rules based on service monitor data. The check is done upon the completion of service execution.
Lines in the SVC_TRIGGER section use the following format: KEYWORD=value; where KEYWORD is the name of the parameter, and value is its associated value. Valid KEYWORDs are as follows:
SVCTRIGGER=components filter:metrics filter:actions
components filter, optional) and under what conditions (metrics filter) the plug-in should execute the actions. For the syntax for filter and action, refer to Plug-in Event Trigger Format.
Multiple SVCTRIGGER plug-ins can be defined (each on a separate line) in this section.
This section provides call path trigger rules for Plug-in event based on call path monitor data. The check is done in all steps of call path.
Lines in the CALL_TRIGGER section are of the form: KEYWORD=value where KEYWORD is the name of the parameter, and value its associated value. Valid KEYWORDs are as follows:
CALLTRIGGER=components filter:metrics filter:actions
components filter, optional) and under what conditions (metrics filter) the plug-in should execute the actions. For the syntax for filter and action, refer to Plug-in Event Trigger Format.
Multiple CALLTRIGGER plug-ins can be defined (each on a separate line) in this section..
This section provides trigger rules used by BBL to post events when a service execution time is longer than pre-defined value. BBL will check executing services in every SCANUNIT. Events only be posted once for a hang service.
This enable Tuxedo to detect potential service “hang” problem but bring no impact to the server which executing the service. On the contrary, the server will be terminated with the service time-out feature.
Lines in the BBL_TRIGGER section are of the form: KEYWORD=value where KEYWORD is the name of the parameter, and value its associated value. Valid KEYWORDs are as follows:
BBLTRIGGER=components filter:metrics filter:actions
components filter, optional) and under what conditions (metrics filter) the BBL should execute the actions. For the syntax for filter and action, refer to Plug-in Event Trigger Format.
Multiple BBLTRIGGER plug-ins can be defined (each on a separate line) in this section.
This section specifies whether or not collected service and call path monitor data should report to Oracle TSAM Manager when default Plug-in is used. Lines in the REPORT_POLICY section are of the form: KEYWORD=value where KEYWORD is the name of the parameter, and value its associated value. Valid KEYWORDs are as follows:
Y.
Y.
The Plug-in Event trigger contains three fragments separated by a ‘:’ (colon): components filter, metrics filter, and actions.
The filter fragment is a boolean expression based on FML32 fields provided by Tuxedo infrastructure. For more information, see
Boolean Expressions of Fielded Buffers in the Programming an Oracle Tuxedo ATMI Application Using FML, Field Manipulations chapter.
The events plug-in first evaluates components filter with the location information of the process where the monitor data is collected. If the evaluation output is false, this rule is ignored. Otherwise metrics filter will be evaluated and if the result is true, Plug-in will execute the actions.
The available FML32 fields for components filter is listed in Table 2-6. The available FML32 fields for metrics filter is listed in Table 2-7, Table 2-8 and Table 2-9, for SVC_TRIGGER, CALL_TRIGGER and BBL_TRIGGER respectively.
Each action is defined in the following format: name(key1=value1,key2=value2+value3,...). name specifies the action type. Configurable parameters for the action are specified in () following the name using the following format: KEYWORD=values, separated by a ‘,’(comma). Separating each value with a ‘+’(plus) if a parameter can contain multiple values. Separating actions with ‘,’(comma) if there are more than one actions are defined.
Only the event action is supported, and can only be defined once. It is used to post event to Tuxedo Event Broker and/or Oracle TSAM Manager, when components filter and metrics filter are all evaluated as true. The parameters for event is listed in Table 2-10 lists event parameters.
|
|||
|
|||
|