|
|
This topic contains the following sections:
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.
The following section highlights Tuxedo plug-in framework key concepts.
An Interface is the contract format between the plug-in implementation and the plug-in caller. An interface requires the following attributes:
The interface ID is the name of the interface that is uniquely identified in the Tuxedo plug-in framework and uses the following format:
<interface id> ::= <component name>[/<sub-component/name>]/<interface name>
The Oracle TSAM Agent plug-in uses the following format:
An interface has two versions, the major version number and minor version number.
The data structure defines the concrete information conveyed between plug-in caller and implementation.The function declaration defines the routines must be implemented by plug-in.
A plug-in is a dynamic library written in C code. The library implements the methods specified by the interface. The Tuxedo plug-in framework supports multiple implementations (interceptors) for one interface.
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.
When 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:
All plug-ins involved in the interceptor implement the same interface. Multiple occurrences of the same plug-in are not allowed in an interception sequence.
Oracle TSAM Agent provides the Fan-out plug-in which allows you to write/create an interceptor plug-in.
Once the plug-in written it must be registered in the Tuxedo registry so that the functional components will locate the plug-in and invoke the appropriate methods. Tuxedo provides three commands specifically for plug-in use:
Oracle TSAM Agent plug-in invocation begins at the monitoring points. The Oracle TSAM Agent collects and computes the metrics, and composes the arguments passed to the plug-in. The Oracle TSAM Agent Fan-out plug-in invokes the interceptor plug-in according to the registration sequence.
A simple Oracle TSAM custom plug-in development example is provided as a guideline. The system environment is Solaris on Sparc. The functionality is basic and just prints out the metrics buffers. This plug-in works together with the Oracle TSAM Agent default plug-in.
Listing 3-1 displays an example of the Oracle TSAM plug-in customplugin.c.
#include <e_pif.h>
#include <tpadm.h>
#include <fml32.h>
#include <e_perf_mon.h>
static TM32I _TMDLLENTRY print_app(
perf_mon_1 *,
FBFR32 **,
MONITORCTL *,
TM32U);
static TM32I _TMDLLENTRY print_svc(
perf_mon_1 *,
FBFR32 **,
MONITORCTL *,
TM32U);
static TM32I _TMDLLENTRY print_sys(
perf_mon_1 *,
FBFR32 **,
MONITORCTL *,
TM32U);
static TM32I _TMDLLENTRY print_tran(
perf_mon_1 *,
FBFR32 **,
MONITORCTL *,
TM32U);
static TM32I _TMDLLENTRY plugin_destroy (
_TCADEF,
const struct _e_pif_instance_handles *,
TM32U);
static TM32I _TMDLLENTRY plugin_copy (_TCADEF,
void *,
const struct _e_pif_interception_data *,
struct _e_pif_instance_handles *,
TM32U);
static const perf_mon_1 Vtblperfapp_1 = {
print_app,
print_svc,
print_sys,
print_tran,
};
static const _e_pif_plugin_info perf_mon_1_info = {
{ 1, 0 }, /* interface major version */
{ 1, 0 }, /* implementation */
"abc/tuxedo/tsam", /* implementation id */
ED_PERF_MON_INTF_ID, /* interface id */
4, /* virtual table size */
"ABC, Inc.", /* vendor */
"Custom Plug-in for Oracle TSAM", /* product name */
"1.0", /* vendor version */
EF_PIF_SINGLETON, /* m_flags */
plugin_destroy,
plugin_copy
};
int _TMDLLENTRY
plugin_entry(_TCADEF, const char *pIId,
const char *pImplId,
const struct _e_pif_iversion *version,
const struct _e_pif_data *pData,
const struct _e_pif_interception_data *pInterceptionData,
struct _e_pif_instance_handles *pI,
TM32U flags)
{
const char * const * regData = pData->regdata;
char *logfile = NULL;
pI->pVtbl = (void *) &Vtblperfapp_1;
pI->pPluginInfo = (_e_pif_plugin_info *) &perf_mon_1_info;
pI->pPrivData = NULL;
return (EE_SUCCESS);
}
static TM32I _TMDLLENTRY
plugin_destroy (_TCADEF, const struct _e_pif_instance_handles *pIhandles,
TM32U flags)
{
return(EE_SUCCESS);
}
static TM32I _TMDLLENTRY
plugin_copy (_TCADEF, void *iP,
const struct _e_pif_interception_data *pInterceptionData,
struct _e_pif_instance_handles *pIhandles,
TM32U flags)
{
return(EE_SUCCESS);
}
static TM32I _TMDLLENTRY print_app(perf_mon_1 * ip,FBFR32 **buf, MONITORCTL * monctl, TM32U flags)
{
Fprint32(*buf);
return(0);
}
static TM32I _TMDLLENTRY print_svc(perf_mon_1 * ip,FBFR32 **buf, MONITORCTL * monctl, TM32U flags)
{
Fprint32(*buf);
return(0);
}
static TM32I _TMDLLENTRY print_sys(perf_mon_1 * ip,FBFR32 **buf, MONITORCTL * monctl, TM32U flags)
{
Fprint32(*buf);
return(0);
}
static TM32I _TMDLLENTRY print_tran(perf_mon_1 * ip,FBFR32 **buf, MONITORCTL * monctl, TM32U flags)
{
Fprint32(*buf);
return(0);
}
cc -c customplugin.c -I$TUXDIR/include
cc -G -KPIC -o customplugin.so -L$TUXDIR/lib -lfml customplugin.o
To register the plug-in, do the following steps:
Listing 3-2 displays an example of the reg.sh shell script
#!/bin/sh
epifreg -r -p abc/tuxedo/tsam -i engine/performance/monitoring \
-o SYSTEM -v 1.0 \
-f $APPDIR/customplugin.so -e plugin_entry
epifregedt -s -k "SYSTEM/impl/bea/performance/monfan" \
-a InterceptionSeq=bea/performance/mongui \
-a InterceptionSeq=abc/tuxedo/tsam \
Enable TSAM Monitoring using the TMMONITOR environment variable: tmadmin->chmo or by using the Oracle TSAM console
For more information, see the Oracle TSAM Administration Guide.
You will find the metrics collected printed out.
Listing 3-3 displays the metrics print out.
TA_MONDEPTH 1
TA_MONPROCTYPE 2
TA_MONMSGSIZE 6
TA_MONMSGQUEUED 1
TA_MONLASTTIMESEC 1189759850
TA_MONLASTTIMEUSEC 730754
TA_MONSTARTTIMESEC 1189759850
TA_MONSTARTTIMEUSEC 730754
TA_MONCORRID JOLTDOM:bjsol18:72854 SITE1 client 9597 1 1
TA_MONMSGTYPE ARQ
TA_MONSTAGE Q2ME
TA_MONLOCATION JOLTDOM:bjsol18:72854 SITE1 GROUP2 simpserv 18 9588
TA_MONSVCNAME TOUPPER
TA_MONHOSTSVC TOUPPER
TA_MONSVCSEQ client-TOUPPER-18218-0
TA_MONPSVCSEQ INITIATOR
TA_MONQID 14441475-00004.00018
TA_MONDEPTH 1
TA_MONPROCTYPE 2
TA_MONMSGSIZE 6
TA_MONLASTTIMESEC 1189759850
TA_MONLASTTIMEUSEC 730754
TA_MONSTARTTIMESEC 1189759850
TA_MONSTARTTIMEUSEC 730754
TA_MONERRNO 0
TA_MONURCODE 0
TA_MONCORRID JOLTDOM:bjsol18:72854 SITE1 client 9597 1 1|
TA_MONMSGTYPE ARP
TA_MONSTAGE ME2Q
TA_MONLOCATION JOLTDOM:bjsol18:72854 SITE1 GROUP2 simpserv 18 9588
TA_MONSVCNAME TOUPPER
TA_MONHOSTSVC TOUPPER
TA_MONSVCSEQ client-TOUPPER-18218-0
TA_MONPSVCSEQ INITIATOR
All Oracle TSAM Plug-in interface 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 indentifier example.
#define ED_PERF_MON_MAJOR_VERSION 1
#define ED_PERF_MON_MINOR_VERSION 0
/* Interfaces defined in this module */
#define ED_PERF_MON_INTF_ID "engine/performance/monitoring"
Value Definitions and Data Structure
Listing 3-5 displays the Oracle TSAM framework and plug-in core data structure.
typedef struct {
unsigned char fieldsmap[MAXMAPSIZE];
char monitoring_policy[MAXPOLICYLEN]; /* monitor policy of TMMONITOR */
char corr_id[MAXCORRIDLEN]; /* plug-in supplied correlation ID */
int ulen;
void * udata;
long mon_flag;
} MONITORCTL;Table 3-1 lists the MONITORCTL members.
Table 3-2 lists the MONITORCTL array size definitions. Table 3-3 lists the mon_flag Values.
Listing 3-6 defines the plug-in implementation method function table.
typedef struct perf_mon_1_Vtbl {TM32I (_TMDLLENTRY *_ec_perf_mon_app) _((
struct perf_mon_1_Vtbl * ip,
FBFR32 **buf,
MONITORCTL *mon_ctl,
TM32U flags
));
TM32I (_TMDLLENTRY *_ec_perf_mon_svc) _((
struct perf_mon_1_Vtbl * ip,
FBFR32 **buf,
MONITORCTL *mon_ctl,
TM32U flags
));
TM32I (_TMDLLENTRY *_ec_perf_mon_sys) _((
struct perf_mon_1_Vtbl * ip,
FBFR32 **buf,
MONITORCTL *mon_ctl,
TM32U flags
));
TM32I (_TMDLLENTRY *_ec_perf_mon_tran) _((
struct perf_mon_1_Vtbl * ip,
FBFR32 **buf,
MONITORCTL *mon_ctl,
TM32U flags
));
} perf_mon_1, *perf_mon_1_ptr;
Each 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:
The fieldsmap contains the quick reference of which metrics are stored in the buf parameter of the interface methods. A set of operation facilities are designed to check/set the filedsmap data.
#define BASENUM 30002401
BASENUM is the base number of TSAM FML32 metrics fields. The performance metrics are defined as Tuxedo built-in FML32 fields which are included $TUXDIR/include/tpadm.h.
#define IS_FIELDSET(FIELDSMAP, FIELDID) ( FIELDSMAP[Fldno32(FIELDID) - BASENUM ])
#define SET_FIELD(FIELDSMAP, FIELDID) { FIELDSMAP[Fldno32(FIELDID) - BASENUM ] = 1;}#define UNSET_FIELD(FIELDSMAP, FIELDID) { FIELDSMAP[Fldno32(FIELDID) - BASENUM ] = 0;}IS_FIELDSET is used to determine a field is set or not in a “fieldsmap”. SET_FIELD is used to set a field to a “fieldsmap” and UNSET_FIELD is to clear a field set in a “fieldsmap”. These operation facilities can be used in the plug-in if it needs to relay the required field changes to thee Oracle TSAM framework.
$TUXDIR/include/e_pif.hIt is the Tuxedo general plug-in definition file. It must be included in the plug-in source code.
$TUXDIR/include/tpadm.hIt is the Tuxedo built-in FML32 fields definition files. All performance metrics are defined as FML32 fields.
$TUXDIR/include/fml32.hThe metrics collected are stored in a Tuxedo FML32 buffer. To access these items, FML32 routines must be used. So the “fml32.h” must be included.
Oracle TSAM Agent plug-in implementation requires the following steps:
Listing 3-7 shows a perf_mon_1 defined in the e_perf_mon.h function table example.
static const perf_mon_1 Vtblperfapp_1 = {
print_app,
print_svc,
print_sys,
print_tran,
};Listing 3-8 shows how to define the plug-in information variable.
static const _e_pif_plugin_info perf_mon_1_info = {
{ 1, 0 }, /* interface version */
{ 1, 0 }, /* implementation version */
"abc/tuxedo/tsam", /* implementation id */
ED_PERF_MON_INTF_ID, /* interface id */
4, /* virtual table size */
"ABC, Inc.", /* vendor */
"Custom Plug-in for Oracle TSAM", /* product name */
"1.0", /* vendor version */
EF_PIF_SINGLETON, /* m_flags */
plugin_destroy,
plugin_copy
};The changeable members are “implementation version”, “implementation id”, “vendor”, “product name”, “vendor version”. Other items must be kept with same with the sample.
plugin_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.
static TM32I _TMDLLENTRY
plugin_destroy (_TCADEF, const struct _e_pif_instance_handles *pIhandles, TM32U flags)
{
return(EE_SUCCESS);
}
static TM32I _TMDLLENTRY
plugin_copy (_TCADEF, void *iP,
const struct _e_pif_interception_data *pInterceptionData,
struct _e_pif_instance_handles *pIhandles, TM32U flags)
{
return(EE_SUCCESS);
}Each plug-in must have an “entry” routine and specified in plug-in registration process. In this routine, the virtual function table and plug-in information structure must be supplied to the plug-in instance handler.
Listing 3-10 displays a plug-in routine example.
int _TMDLLENTRY
plugin_entry(_TCADEF, const char *pIId,
const char *pImplId,
const struct _e_pif_iversion *version,
const struct _e_pif_data *pData,
const struct _e_pif_interception_data *pInterceptionData,
struct _e_pif_instance_handles *pI,
TM32U flags)
{
const char * const * regData = pData->regdata;
char *logfile = NULL;
pI->pVtbl = (void *) &Vtblperfapp_1;
pI->pPluginInfo = (_e_pif_plugin_info *) &perf_mon_1_info;
pI->pPrivData = NULL;
return (EE_SUCCESS);
}| Note: | It is recommends that you t to use the fixed process shown in the sample. The “entry” routine is called only once to instantiate the plug-in. |
The implementation function table is registered to Tuxedo in the “entry” routine. Then following chapters will focus on how to write TSAM plug-in based on the corresponding monitoring types.
| 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.
In this example, the routine prints out the passed FML32 buffer:
static TM32I _TMDLLENTRY print_app(perf_mon_1 * ip,FBFR32 **buf, MONITORCTL * monctl, TM32U flags)
{
Fprint32(*buf);
return(0);
}
Understanding Current Monitoring PointsCall path monitoring is the most comprehensive Tuxedo application interceptor. It provides a variety of metrics for recording and analysis.
The monitoring stage itself is a metric with the FML32 field name TA_MONSTAGE. Table 3-4 lists TA_MONSTAGE values.
Listing 3-11 displays a judge monitoring stage example.
{
char *stage;
FLDLEN32 len;
stage = Ffind32(*obuf, TA_MONSTAGE,0,&len);
if (stage != NULL ) {
if (strcmp(stage,”STMO”) == 0 ) {
/* ... */
}else if (strcmp(stage,”Q2ME” == 0 ) {
/* ... */
/* other processment */
}
}For “STRING” field type, we recommend to use “Ffind32” routine to get a more fast process.
Table 3-5 lists the TA_MONMSGTYPE values.
The monitoring points always are located in processes of Tuxedo applications. So understand current process is important. TSAM framework uses the field TA_MONLOCATION to tell the plug-in the process location of current monitoring point. The format of TA_MONLOCATION is different for Tuxedo client process and server process. The major goal is to provide enough information to locate the process uniquely in this Tuxedo domain.
Table 3-6 lists the TA_MONLOCATION format.
WSH/JSH1
|
1The group of WSH/JSH is the group of its listeners, that is WSL/JSL |
After get the necessary information on the monitoring stage, message type and process location, the next step is to check the common used metrics also carried in the FML32 buffer. The metrics will be available depending on the conditions mentioned above.
Table 3-7 lists the TA_MONLOCATION format metrics.
All1
|
|||
1For some self-describe buffer types, such as STRING, the size might be zero. |
Oracle TSAM Agent allows to reduce the metrics collected by specifying the required fields of TMMONITOR specification. TMMONITOR syntax consists of t hree parts: monitoring type, monitoring policy and required fields. They are separated by a colon. The usage of monitoring type and policy can be referred at TSAM User Guide. The required fields supported by call path monitoring and service monitoring.
| Note: | The required fields option is only for custom plug-ins. It cannot apply to the Oracle TSAM default plug-in. If required fields are used, the Oracle TSAM default plug-in will not function normally, which means the Oracle TSAM Manager cannot function normally. It also means you cannot use the Oracle TSAM default plug-in together with custom plug-ins. |
| Note: | Normally, using required fields is not recommended. |
The default behavior is all the available metrics are collected by the Oracle TSAM framework.
If required fields are specified, only the specified and basic information is available in the metrics buffer.
To enable the TMMONITOR required fields, set TMMONITOR specifications in the environment variable or tmadmin. For example:
export TMMONITOR=app::appfields=TA_MONSVCNAME,TA_MONSTAGE,TA_MONLOCATION
To change the required fields, the plug-in must see whether the mon_flag of MONITORCTL allows to change it.
if (monctl->monflag & PI_EDITABLE_FIELDS ) {
UNSET_FIELD(monctl->fieldsmap,TA_MONLOCATION);
SET_FIELD(monctl->fieldsmap,TA_MONMSGSIZE);
SET_FIELD(monctl->fieldsmap,TA_MONLDOM);
monctl->monflag |= PI_UPDATED_FIELDS;}
The MONITORCTL monflag must be set to PI_UPDATED_FIELDS to tell the Oracle TSAM framework to update the required fields. This change impacts all the monitoring points on the call path.
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,
The custom plug-in can skip the correlation ID generation. If the custom plug-in wants to overwrite the correlation ID generated by the Oracle TSAM default plug-in, the interceptor sequence of custom plug-in must come after the Oracle TSAM default plug-in.
If the Oracle TSAM default plug-in is removed fromthe Tuxedo plug-in framework, the custom plug-in must supply the correlation ID i. For example:
if (monctl->mon_flag & PI_CORRID_REQUIRED) {strcpy(monctl->corr_id, mygetid());
}
“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.
extern int _TMDLLENTRY tmmon_getcorrid(char *obuf, int len);
...
if (monctl->mon_flag & PI_CORRID_REQUIRED) {
char new_corrid[MAXCORRIDLEN];
if (tmmon_getcorrid(new_corrid, sizeof(new_corrid)) == 0 ) {
strpcy(monctl->corr_id,new_corrid);
}
}
...| Note: | When using the correlation ID generation routine of TSAM framework, libtsam must be linked with the plug-in. |
Service monitoring is a straightforward procedure. The data collection points are before and after the service routine invocation. The plug-in is invoked only when service execution is completed.
In this example, the routine prints out the passed FML32 buffer:
static TM32I _TMDLLENTRY print_svc(perf_mon_1 * ip,FBFR32 **buf, MONITORCTL * monctl, TM32U flags)
{Fprint32(*buf);
return(0);
}
Table 3-8 lists the service monitoring plug-in routine metrics.
Oracle TSAM supports two Tuxedo built-in servers monitoring, GWTDOMAIN and BRIDGE. The monitoring focus on the throughput, outstanding request number and message number queued on network. The plug-in is invoked periodically by the Oracle TSAM framework. The interval is specified by “sysinterval” policy of TMMONITOR specification. Data collection occurs on the on-going server operations.
In this example, the routine prints out the passed FML32 buffer:
static TM32I _TMDLLENTRY print_sys(perf_mon_1 * ip,FBFR32 **buf, MONITORCTL * monctl, TM32U flags)
{
Fprint32(*buf);
return(0);
}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.
In this example, the routine prints out the passed FML32 buffer:
static TM32I _TMDLLENTRY print_tran(perf_mon_1 * ip,FBFR32 **buf, MONITORCTL * monctl, TM32U flags)
{
Fprint32(*buf);
return(0);
}Listing 3-10 lists the commonly used transaction monitoring plug-in routine metrics.
| Note: | The plug-in will run in Tuxedo infrastructure. It must be well tested before configure to Tuxedo production environment. |
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.
epifreg -r -p abc/tuxedo/tsam -i engine/performance/monitoring \
-o SYSTEM -v 1.0 -f /test/abc/customplugin.so -e plugin_entry
epifregedt -s -k "SYSTEM/impl/bea/performance/monfan" \
-a InterceptionSeq=bea/performance/mongui \
-a InterceptionSeq=abc/tuxedo/tsam
In this, there are two steps required to register the custom plug-in in Tuxedo.
epifregedt” to change the fan-out plug-in “InterceptionSeq” attribute. Oracle TSAM supports a Fan-out plug-in mechanism which means multiple plug-ins can work together. Oracle TSAM Agent provides the Fan-out plug-in and a default interceptor plug-in. The custom plug-in is an additional interceptor plug-in.
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/mongui”, is invoked before the custom plug-in implementation ID “abc/tuxedo/tsam”.
epifregedt” withthe proper “InterceptionSeq” sequence.
“epifunreg” can be used to un-register a specified plug-in, for example,
epifunreg -p abc/tuxedo/tsam
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:
epifregedt -s -k "SYSTEM/impl/bea/performance/monfan" \
-a InterceptionSeq=bea/performance/mongui
| Note: | It is strongly recommended to register/unregister/modify the plug-in after shutting down a Tuxedo application. |
tpalloc/tprealloc/tpfree and tptypes. The monitoring points are embedded in the Tuxedo communication framework. Embedded ATMI calls may compromise current Tuxedo context.tprealloc must be used to extend the buffer space. | Note: | Changed buffer s are passed to the plug-in invocation sequence that is after the current one. |
|