• Tuxedo has a built-in plug-in framework that facilitates additional functionality. For example, the Tuxedo security mechanism is constructed on the plug-in framework. 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 a Tuxedo ATMI service. Oracle TSAM Agent also use the Tuxedo plug-in framework to attach different data receivers.
• Tuxedo supports two types of interceptors: Fan-out interceptors and Stack interceptors. The Oracle TSAM Agent uses the Fan-out interceptors. Figure 3‑1 displays the Oracle TSAM Agent plug-in architecture.Figure 3‑1 Oracle TSAM Agent Plug-in ArchitectureWhen the 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 plug-in customplugin.c.Listing 3‑1 Oracle TSAM 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 Plug-in interface contents are defined in the $TUXDIR/include/e_perf_mon.h file. When you build a Oracle TSAM 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 framework and plug-in core data structure.Listing 3‑5 Core Data StructureTable 3‑1 lists the MONITORCTL members.
Table 3‑1 MONITORCTL Members
Table 3‑2 MONITORCTL Array Size Definitions
Table 3‑3 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 a 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 Tuxedo plug-in routines for destroy and copy. For a Oracle TSAM 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 Tuxedo ATMI calls (except for FML32 operations, tpalloc/tprealloc/tpfree and tptypes) in the plug-in. It may result un-expected behavior as Tuxedo context may be compromised.The call path monitoring plug-in routine are invoked at the monitoring points. For more information, see “Oracle TSAM Agent Data Collection Framework” on page 2‑1.The monitoring stage itself is a metric with the FML32 field name TA_MONSTAGE. Table 3‑4 lists TA_MONSTAGE values.
Table 3‑4 TA_MONSTAGE Values Listing 3‑11 displays a judge monitoring stage example.Listing 3‑11 Judge Monitoring StageTable 3‑5 lists the TA_MONMSGTYPE values.
Table 3‑5 TA_MONMSGTYPE Values The monitoring points always are located in processes of Tuxedo applications. So understand current process is important. Oracle TSAM framework uses the fields TA_DOMAINID, TA_PID, TA_LMID,TA_MONPROCNAME,TA_GROUPNAME and TA_SRVID (as defined in Table 3‑6) to tell the process location.
Table 3‑6 Current Process Location Fields The domain identifier. Its format is: domainid: mastername:ipckey. Table 3‑7 lists the commonly used metrics.
Table 3‑7 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 framework sets PI_CORRID_REQUIRED in the MONITORCTL mon_flag. If no correlation ID is given, an error is reported. The Oracle TSAM 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 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 framework correlation ID generation routine, libtsam must be linked with the plug-in.Table 3‑8 lists the service monitoring plug-in routine metrics.
Table 3‑9 lists the system server monitoring plug-in routine metrics.
Oracle TSAM 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.
Tuxedo uses the epifreg command to register the plug-ins to the Tuxedo registry so that the infrastructure can invoke the plug-in at run time. Oracle TSAM uses the Oracle TSAM 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 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 Tuxedo communication framework. Embedded ATMI calls may compromise current Tuxedo context.