• The Oracle TSAM Plus Agent framework collects the performance metrics when Oracle TSAM Plus is enabled. The framework covers the major performance sensitive areas in Tuxedo applications, that is call path stages, services, transactions and system servers. Oracle TSAM Plus Agent uses Oracle Tuxedo FML32 typed buffers to contain the metrics collected so that each metric is defined as a built-in FML32 field. The monitoring points depend on the monitoring types and only apply to Oracle Tuxedo ATMI applications. Table 3‑1 lists the call path monitoring points.
Table 3‑1 Call Path Monitoring Points Table 3‑2 lists the service monitoring points.
Table 3‑2 Service Monitoring Points Table 3‑3 lists the system server monitoring points.
Table 3‑3 System Server Monitoring Points Main Loop1
Table 3‑4 lists the transaction monitoring points.
Table 3‑4 Transaction Monitoring Points
• Oracle Tuxedo has a built-in plug-in framework that facilitates additional functionality. For example, the Oracle Tuxedo security mechanism is constructed on the plug-in framework. Oracle Tuxedo defines an interface set as a contract between a service provider and end user. The term “service” here is used as a general term; not an Oracle Tuxedo ATMI service. Oracle TSAM Plus Agent also use the Oracle Tuxedo plug-in framework to attach different data receivers.
• Oracle Tuxedo supports two types of interceptors: Fan-out interceptors and Stack interceptors. The Oracle TSAM Plus Agent uses the Fan-out interceptors. Figure 3‑1 displays the Oracle TSAM Plus Agent plug-in architecture.Figure 3‑1 Oracle TSAM Plus Agent Plug-in ArchitectureWhen the Oracle Tuxedo infrastructure invokes plug-in A method X, plug-in A invokes method X of the intercepting plug-ins in the order specified by the InterceptionSeq attribute as follows:
• Plug-in n method X is invoked
• Plug-in n method X of is returned
• epifreg: registers a plug-in
• epifunreg: un-registers a plug-in
• epifregedt: edits a plug-inListing 3‑1 displays an example of the Oracle TSAM Plus plug-in customplugin.c.Listing 3‑1 Oracle TSAM Plus Agent customplugin.c Plug-in Source Code Example
2. Listing 3‑2 displays an example of the reg.sh shell scriptListing 3‑2 reg.h Shell ScriptListing 3‑3 displays the metrics print out.Listing 3‑3 Metrics Print Out ExampleAll Oracle TSAM Plus Plug-in interface contents are defined in the $TUXDIR/include/e_perf_mon.h file. When you build a Oracle TSAM Plus Plug-in, this file must be included in your plug-in source code.The $TUXDIR/include/e_perf_mon.h file definitions are as follows:Listing 3‑4 provides a version and identifier example.Listing 3‑4 Version and Interface IdentifierListing 3‑5 displays the Oracle TSAM Plus framework and plug-in core data structure.Listing 3‑5 Core Data StructureTable 3‑5 lists the MONITORCTL members.
Table 3‑5 MONITORCTL Members
Table 3‑6 MONITORCTL Array Size Definitions
Table 3‑7 mon_flag Values Listing 3‑6 defines the plug-in implementation method function table.Listing 3‑6 Plug-in Implementation Method Function TableEach method corresponds to a monitoring type. “_ec_perf_mon_app” is for call path monitoring, “_ec_perf_mon_svc” is for service monitoring, “_ec_perf_mon_sys” is for system server monitoring and “_ec_perf_mon_tran” is for transaction monitoring. Each method will be invoked at the corresponding monitoring type’s monitoring points.The method arguments are:
• struct perf_mon_1_Vtbl *ip: the virtual table pointer e.
• FBFR32 **buf: the address of the metrics buffer in FML32 type.
• MONITORCTL *mon_ctl: the control structure.
• TM32U flags: the bit flag in a 32-byte, unsigned integer.The metrics collected are stored in an Oracle Tuxedo FML32 buffer. To access these items, FML32 routines must be used; fml32.h must be included.Listing 3‑8 shows how to define the plug-in information variable.Listing 3‑8 Define the Plug-in Information Variableplugin_destroy and plugin_copy are the general Oracle Tuxedo plug-in routines for destroy and copy. For a Oracle TSAM Plus Plug-in, you can write two empty functions as shown in Listing 3‑9.Listing 3‑9 plugin_destroy and plugin_copyListing 3‑10 shows a plug-in routine example.Listing 3‑10 Plug-in Entry Routine
WARNING: Do not make Oracle Tuxedo ATMI calls (except for FML32 operations, tpalloc/tprealloc/tpfree and tptypes) in the plug-in. It may result un-expected behavior as Oracle Tuxedo context may be compromised.The call path monitoring plug-in routine are invoked at the monitoring points. For more information, see “Oracle TSAM Plus Agent Data Collection Framework” on page 2‑1.The monitoring stage itself is a metric with the FML32 field name TA_MONSTAGE. Table 3‑8 lists TA_MONSTAGE values.
Table 3‑8 TA_MONSTAGE Values Listing 3‑11 displays a judge monitoring stage example.Listing 3‑11 Judge Monitoring StageTable 3‑9 lists the TA_MONMSGTYPE values.
Table 3‑9 TA_MONMSGTYPE Values The monitoring points always are located in processes of Oracle Tuxedo applications. So understand current process is important. Oracle TSAM Plus framework uses the fields TA_DOMAINID, TA_PID, TA_LMID,TA_MONPROCNAME,TA_GROUPNAME and TA_SRVID (as defined in Table 3‑10) to tell the process location.
Table 3‑10 Current Process Location Fields The domain identifier. Its format is: domainid: mastername:ipckey. Table 3‑11 lists the commonly used metrics.
Table 3‑11 Commonly Used Metrics All1
The correlation ID must be given by the plug-in at the monitoring initiating stage, which is the TA_MONSTAGE value is “STMO”. The Oracle TSAM Plus framework sets PI_CORRID_REQUIRED in the MONITORCTL mon_flag. If no correlation ID is given, an error is reported. The Oracle TSAM Plus default plug-in provides the correlation ID also. Two scenarios need to consider,if (monctl->mon_flag & PI_CORRID_REQUIRED) {“mygetid()” is an assumed ID generation routine. The length of the new ID must not exceed the size of corr_id of MONITORCTL.To help ID generation, the custom plug-in can use a Oracle TSAM Plus framework service to get a correlation ID. Listing 3‑12 displays an ID generation example.Listing 3‑12 ID Generation Example
Note: When using the Oracle TSAM Plus framework correlation ID generation routine, libtsam must be linked with the plug-in.Table 3‑12 lists the service monitoring plug-in routine metrics.
Table 3‑12 Service Monitoring Plug-in Routine Metrics Table 3‑13 lists the system server monitoring plug-in routine metrics.
Oracle TSAM Plus also traces critical routines invocation in XA transaction. The scope includes tpbegin,tpcommit, tpabort,xa_xxx calls and GWTDOMAINS transaction routines.Listing 3‑10 lists the commonly used transaction monitoring plug-in routine metrics.
Oracle Tuxedo uses the epifreg command to register the plug-ins to the Oracle Tuxedo registry so that the infrastructure can invoke the plug-in at run time. Oracle TSAM Plus uses the Oracle TSAM Plus framework to invoke the plug-in.Listing 3‑13 shows how the epifreg command is used to invoke a plug-in.Listing 3‑13 Using epifreg to Invoke a Plug-in
a. “-p” option specifies the implementation id and it must be consistent the value specified in source code.
b. “-v” indicates the version number.
c. “-f” specifies the dynamic library path.
d. “-e” specifies the “entry” routine described in the “General Steps” section.
2. The “-a InterceptionSeq=xxx” option tells the Fan-out plug-in invokes the interceptor plug-in using the specified order. “xxx” is the implementation id. In this example, the Oracle Tuxedo default interceptor plug-in implementation ID, “bea/performance/monshm”, is invoked before the custom plug-in implementation ID “abc/tuxedo/tsam”.
3. If you have multiple custom plug-in developed, you need to register them first with “epifreg”, then modify the invocation sequence with “epifregedt” with the proper “InterceptionSeq” sequence.“epifunreg” can be used to un-register a specified plug-in, for example,After unregistering the custom plug-in, you must use “epifregedt” to modify the Fan-out plug-in invocation again based on current available plug-ins. For example:
• Do not use Oracle Tuxedo ATMI calls in the plug-in except for the FML32 operations tpalloc/tprealloc/tpfree and tptypes. The monitoring points are embedded in the Oracle Tuxedo communication framework. Embedded ATMI calls may compromise current Oracle Tuxedo context.