Plug-in Programming Guide

Creating a BEA TSAM Agent Custom Plug-in

This topic contains the following sections:

Overview

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. BEA TSAM Agent also use the Tuxedo plug-in framework to attach different data receivers.

Tuxedo Plug-in Framework Concepts

The following section highlights Tuxedo plug-in framework key concepts.

Interface

An Interface is the contract format between the plug-in implementation and the plug-in caller. An interface requires the following attributes:

Implementation

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 BEA TSAM Agent uses the Fan-out interceptors. Figure 3-1 displays the BEA 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.

BEA TSAM Agent provides the Fan-out plug-in which allows you to write/create an interceptor plug-in.

Plug-in Register/Un-register/Modifications

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:

Developing a BEA TSAM Agent Plug-in

BEA TSAM Agent plug-in invocation begins at the monitoring points. The BEA TSAM Agent collects and computes the metrics, and composes the arguments passed to the plug-in. The BEA TSAM Agent Fan-out plug-in invokes the interceptor plug-in according to the registration sequence.

A simple BEA 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 BEA TSAM Agent default plug-in.

Create Plug-in Source Code

Listing 3-1 displays an example of the BEA 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 BEA 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);
}

Build the Plug-in

cc -c customplugin.c -I$TUXDIR/include

cc -G -KPIC -o customplugin.so -L$TUXDIR/lib -lfml customplugin.o

Register the Plug-in

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 BEA TSAM Monitoring

Enable TSAM Monitoring using the TMMONITOR environment variable: tmadmin->chmo or by using the BEA TSAM console

For more information, see the BEA TSAM Administration Guide.

Run a Call and Check the Standard Output.

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

BEA TSAM Agent Plug-in Interface

All BEA TSAM Plug-in interface interface contents are defined in the $TUXDIR/include/e_perf_mon.h file. When you build a BEA 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:

Version and Interface Identifier

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 BEA 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-2 lists the MONITORCTL array sze definitions.

Table 3-4 lists the mon_flag Values.

Function Table

Listing 3-6 defines the plug-in implementation methods.

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:

Field Map Operation Facility

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 BEA TSAM framework.

Other Help Header Files

BEA TSAM Agent Plug-in Implementation

BEA TSAM Agent plug-in implementation requires the following steps:

Define "perf_mon_1" in the "e_perf_mon.h" Function Table

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,
};

Define the Plug-in Information Variable

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 BEA 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 BEA 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);
}

Write the Plug-in Entry Routine

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);
}

Writing Concrete Plug-in Implementations

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.

Call Path Monitoring Plug-in Routine

The call path monitoring plug-in routine are invoked at the monitoring points. For more information, see BEA TSAM Agent Data Collection Framework

A Basic Implementation

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 Points

Call path monitoring is the most comprehensive Tuxedo application interceptor. It provides a variety of metrics for recording and analysis.

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.

Check Commonly Used Metrics

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.

Change Required Fields

BEA 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.

The default behavior is all the available metrics are collected by the BEA 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 BEA TSAM framework to update the required fields. This change impacts all the monitoring points on the call path.

Generate Call Path Correlation ID

The correlation ID must be given by the plug-in at the monitoring initiating stage, which is the TA_MONSTAGE value is "STMO". The BEA TSAM framework sets PI_CORRID_REQUIRED in the MONITORCTL mon_flag. If no correlation ID is given, an error is reported. The BEA TSAM default plug-in provides the correlation ID also. Two scenarios need to consider,

"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 BEA 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);
	}
}
...

Service Monitoring Plug-in Routine

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.

A Basic Implementation

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);

}

.

Check Commonly Used Metrics

System Server Monitoring Plug-in Routine

BEA 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 BEA TSAM framework. The interval is specified by "sysinterval" policy of TMMONITOR specification. Data collection occurs on the on-going server operations.

A Basic Implementation

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);

}

Check Commonly Used Metrics

Transaction Monitoring Plug-in Routine

BEA TSAM also traces critical routines invocation in XA transaction. The scope includes tpbegin,tpcommit, tpabort,xa_xxx calls and GWTDOMAINS transaction routines.

A Basic Implementation

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);

}

Check Commonly Used Metrics

Listing 3-10 lists the commonly used transaction monitoring plug-in routine metrics.

Configure the Plug-in to Tuxedo

Register to Tuxedo

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. BEA TSAM uses the BEA 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.

Un-register from Tuxedo

"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

BEA TSAM Agent Plug-in Development/Deployment Notes