# Administration Guide

# BEA TSAM Agent

This topic contains the following sections:

- Prerequisites
- Monitoring Policy Management
- Configuring Monitoring Policies
- tpcallinfo API
- LMS (Local Monitor Server)
- Plug-in Level Events

## Prerequisites

To effectively and correctly use the BEA TSAM Agent, please note the following prerequisites:

- The system clocks for all monitored Tuxedo machines and the BEA TSAM Manager are synchronized. A uniform time server is recommended.
- Set each Tuxedo domain to a unique DOMAINID in the UBBCONFIG file.

## Monitoring Policy Management

BEA TSAM provides flexible and comprehensive monitoring management functionality. It provides the following features:

- Monitoring can be turned on or off dynamically without rebooting Tuxedo applications
- Monitoring can be applied to Tuxedo components at the server, group or machine level
- Multiple monitoring management interfaces:

- tmadmin command
- environment variable
- MIB
- BEA TSAM Console

- Fine grained monitoring properties based on time intervals and ratios

### Concepts

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.

#### Monitoring Tuxedo Components

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.

#### Monitoring Categories

BEA TSAM Agent has 4 monitoring categories:

- Call Path Monitoring
- Service Monitoring
- System Server Monitoring
- Transaction Monitoring

##### Call Path Monitoring

When call path monitoring is enabled, the BEA 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.

Key Word: “app”.

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 BEA TSAM console tracks the call path tree in real time. Monitoring initiator processes are limited to the following:

- client process (ATMIs)
- WSH/JSH
- application server processes

Once monitoring 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:

- If the incoming request already indicates it is being monitored, then any call made in the service routine is deemed as part of the original call path tree, whether “app” is set for the server or not.
- If the incoming request does not have monitoring attribute, and “app” is set for the current process, then any service implementation call will start a new monitoring process. The application server becxomes the “monitoring initiator”.

Note: | BEA 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, BEA TSAM uses “client” as the fixed name.

##### Service Monitoring

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.

Key Word: “svc”.

Enables service monitoring. It applies to normal Tuxedo application services and services imported by GWTDOMAIN.

##### System Server Monitoring

The Tuxedo framework has two key servers, BRIDGE and GWTDOMAIN, that connect machines and domains in a distributed computing environment. BEA 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.

Key Word: “sys”.

Enables system server monitoring for the current process. It only applies to Tuxedo BRIDGE and GWTDOMAIN servers. When `sys` is set, BEA TSAM periodically reports the data on the connected network link .

##### Transaction Monitoring

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. BEA TSAM provides transaction monitoring functionality.

Besides transaction call time tracking, BEA TSAM agent also reports the return code and transaction ID. If a transaction is sent across domains, BEA TSAM also reports mapping between local transactions and remote transactions.

Key Word: “tran”.

Enables transaction monitoring. Each transaction call is measured and the execution status sent to the BEA TSAM manager.

All the four monitoring types can be used together or individually. The BEA TSAM console organizes the functionality pages based on the defined monitoring type(s).

#### Monitoring Properties

BEA TSAM Agent has 4 monitoring properties:

- Call Path Monitoring Properties
- Service Monitoring Properties
- System Server Monitoring Properties
- Transaction Monitoring Properties

##### Call Path Monitoring Properties

Call path monitoring properties use the following keywords:

`appratio`

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.

`appinterval`

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.

`appnolog`

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 twoscenarios:

- An application server or domain gateway administrator may want to disable the plug-in (to increase performance) even though the pass-through message indicates it is being monitored.
- The monitoring initiator does not want trigger the plug-in invocation on its call path tree, but the monitoring attributes are preferred in the message so a program can use `tpgetcallinfo()` to retrieve information.

Using “`appnolog`” allows the BEA 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:

- If “appnolog” is specified by the monitoring initiator, the plug-in invocation is not allowed on its call path tree
- If “appnolog” is specified by a “pass-through” process, the plug-in invocation is not allowed in this process.

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 BEA TSAM Web console is not complete.

`appdecode`

Used only for Tuxedo BRIDGE call path monitoring. By default, messages passing through BRIDGE are encoded. This means the BEA 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.

##### Service Monitoring Properties

`svcratio`

Controls service execution monitoring frequency. Similar to `appratio`.

`svcinterval`

Controls service time interval monitoring. Similar to `appinterval`.

Note: | `svcratio` and `svcinterval` are exclusive. If both of are not specified, all services are monitored.

##### System Server Monitoring Properties

`sysinterval`

Controls the plug-in invocation interval of the monitored BRIDGE or GWTDOMAIN. Its range (in seconds) is [30-65535]. The default value is 300.

##### Transaction Monitoring Properties

`tranratio`

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.

## Configuring Monitoring Policies

BEA TSAM provides four policy monitoring configuration interfaces:

- TMMONITOR Environment Variable
- changemonitor Command
- MIB Interface
- BEA TSAM Console

Policy monitoring information must use the following format:

monitoring category:monitoring properties:required fields

- `monitoring category`: defines the monitoring category
- `monitoring properties`: defines the monitoring properties
- `required fields:` reserved for BEA TSAM plug-in development. It should not be configured for the BEA TSAM default plug-in.

Table 2-1 lists the corresponding keywords

Table 2-1 BEA TSAM Monitoring String Specification Keywords
Monitoring Category Keywords | Monitoring Property Keywords
`app` | `appratio, appinterval, appnolog, appdecode`
`svc` | `svcratio, svcinterval`
`sys` | `sysinterval`
`tran` | `tranratio`

### TMMONITOR Environment Variable

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

Listing 2-1 TMMONITOR Environment Variable: Example1

    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 `svcinterval` is set to 30.

Listing 2-2 TMMONITOR Environment Variable: Example2 pro

    TMMONITOR=app,svc:appratio=10,svcinterval=30:

### changemonitor Command

Using the tmadmin changemonitor command allows you to dynamically change monitoring settings. Listing 2-3 provides a changemonitor usage example.

Listing 2-3 Using changemonitor

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

Listing 2-4 changemonitor: Example 1

    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.

Listing 2-5 changemonitor: Example 2

    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.

Listing 2-6 changemonitor: Example 3

    tmadmin

    chmo -g GWGRP -i 10 sys:sysinterval=30:

### MIB Interface

BEA 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 BEA TSAM monitoring. `TA_TMMONITOR` accepts the same string format used in the command line and environment variables.

- T_CLIENT Class
- T_SERVER Class
- T_MACHINE Class

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.

### BEA TSAM Console

The monitoring policy can also be configured using the BEA TSAM Console policy management page. The BEA TSAM Console policy management page allows you to:

- create policy definitions
- group policies in a monitoring policy set
- track policy usage

Note: | It is not recommended that you use Tuxedo-side control mechanisms and BEA TSAM console-side policy management together; monitoring consistency and accuracy may be affected.

Note: | For example, a monitoring policy is created using the BEA TSAM console and applied to Tuxedo components, but the monitoring policy is changed later using Tuxedo-side command line settings. The BEA TSAM is not aware of the Tuxedo-side changes and still shows its original settings.

#### Cancel Monitoring

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 BEA TSAM Console allows to cancel using the GUI interface.

## tpcallinfo API

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 BEA TSAM Reference Guide.

## LMS (Local Monitor Server)

LMS (Local Monitor Server) is a component of BEA TSAM Agent. It performs the following tasks:

- Act as a data proxy server between BEA TSAM default plug-in and BEA TSAM Manager
- Accept management request from BEA TSAM Manager and apply to Tuxedo domain
- Accept Tuxedo event request from BEA TSAM Manager and post it to Tuxedo Event Broker
- Send Tuxedo domain configuration to BEA TSAM Manager
- Other help functionality

For more information, see LMS in the BEA TSAM Reference Guide.

## Plug-in Level Events

### Overview

You can also define and generate event monitoring using BEA TSAM. Event monitoring data is collected by the BEA TSAM Agent and sent to the BEA TSAM Manager. This process may increase system overhead.

The BEA 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 BEA 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. BEA TSAM Manager generated events can be queried from the BEA TSAM Console `TSAM > Alerts > Events` `menu` (based on the plug-in contents).

### Administration Tasks

Enabling the BEA TSAM Event Plug-in requires the following administrative tasks:

1. Configuring the UBBCONFIG File
2. Composing the Plug-in Rules File
3. Activating the Rules File.

#### Configuring the UBBCONFIG File

To configure BEA TSAM events plug-in the UBBCONFIG file, do the following two steps:

1. Define MAXSPDATA in the *RESOURCE section to reserve bulletin board space for storing plug-in event rules.

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.

> `ctsamverify tsamrules`

Note: | The rule file `<tsamrules>` requires that `MAXSPDATA` is set to at least `<41120>`.

2. Add the Tuxedo Event Broker and/or LMS to the *SERVER section.

The Tuxedo Event Broker and/or LMS must be setup in the `*SERVERS` section to enable the BEA TSAM events plug-in. Listing 2-7 displays an LMS setup.A snippet UBBCONFIG is as following:

Listing 2-7 LMS Set in the UBBCONFIG File

`*SERVERS`

`TMSYSEVT SRVGRP=SYSGRP SRVID=1 CLOPT="-A --"`

`TMUSREVT SRVGRP=SYSGRP SRVID=2 CLOPT="-A --"`

`LMS SRVGRP=SYSGRP SRVID=3`

`CLOPT="-A -- -l <tsam-hostname>:8080/tsam/dataserver -t 60"`

#### Composing the Plug-in Rules File

The rules file is a text file which contains BEA TSAM and event plug-in. For more information, see Configuration Reference. Listing 2-8 lists an example rules file.

Listing 2-8 Event Plug-in Rules File Example (tsamrules)

    *GENERAL_RULES

    SVCCHECKALL=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

#### Activating the Rules File

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

Listing 2-9 Load Rules File at Startup Example

    TSAMPLUGINRULES=$APPDIR/tsamrules; export TSAMPLUGINRULES

    tmboot -y\

Listing 2-10 Load Rules File at Runtime Example

    tmadmin - Copyright (c) 1996-1999 BEA Systems, Inc.
    Portions * Copyright 1986-1997 RSA Data Security, Inc.
    All Rights Reserved.
    Tuxedo is a registered trademark.

    > configtsam load tsamrules
    INFO: TSAM Event Trigger successfully loaded.

### Check Plug-in Generated Events Using the BEA TSAM Console

BEA TSAM Manager plug-in generated events can be queried from the BEA TSAM console `TSAM > Alerts > Events` page. These events belong to a separate event catalog named, `Plugin`, that distinguishes it from events generated by the BEA TSAM Manager alert definition (which belongs to another catalog named Alert).

### Subscribing to Plug-in Generated Events

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:

- SVC_TRIGGER
- CALL_TRIGGER
- BBL_TRIGGER.

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.

Table 2-2 Common FML32 Fields for Plug-in Events
Name | Description
--- | ---
`TA_MONEVENTNAME` | Event name specified in event action.
`TA_MONSEVERITY` | Event severity specified in event action.
`TA_GRPNO` | Group number.
`TA_SRVGRP` | Group name.
`TA_SRVID` | Server ID.
`TA_MONLOCATION` | Location where the monitor data is collected, in the format of: <DOMAINID>:<master machine name>:<IPCKEY> <Logical Machine ID> <Group Name> <Process Name> <SRVID if process is a server> <Process ID>.
`TA_MONLOGTIMESEC` | The second when the event is posted.
`TA_MONLOGTIMEUSEC` | The microsecond when the event is posted.

Table 2-3 SVC_TRIGGER FML32 fields
Name | Description
--- | ---
`TA_MONSVCNAME` | Service name
`TA_MONMSGQUEUED` | Number of messages queued on the IPC queue of the server which providing this service
`TA_MONERRNO` | Return code of the service
`TA_MONURCODE` | User return code of the service
`TA_MONEXECTIME` | Response time of the service

Table 2-4 CALL_TRIGGER FML32 fields
Name | Description
--- | ---
`TA_MONSVCNAME` | The service name
`TA_MONELAPSETIME` | The elapse time in milliseconds since the call started from the monitoring initiator
`TA_MONDEPTH` | The call path tree depth, counting from 0 (initiator).
`TA_MONCORRID` | The correlation id of the monitored call
`TA_MONERRNO` | Return code of the service
`TA_MONURCODE` | User return code of the service

Table 2-5 BBL_TRIGGER FML32 fields
Name | Description
--- | ---
`TA_MONSVCNAME` | Service name
`TA_MONEXECTIME` | The elapsed time in milliseconds since the service started execution.

### Configuration Reference

A BEA 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:

- GENERAL_RULES
- SVC_TRIGGER
- CALL_TRIGGER
- BBL_TRIGGER
- REPORT_POLICY

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:

- Plug-in Event rules (the first three sections)
- BBL service execution time trigger (BBL_TRIGGER)
- BEA TSAM Manager data reporting policy (REPORT_POLICY).

#### GENERAL_RULES

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 `KEYWORD`s are as follows:

#### `SVCCHECKALL={ Y | N }`

Specifies whether or not all triggers defined in `SVC_TRIGGER` section should be evaluated. If `SVCCHECKALL` is not specified, the default is `Y`.
If `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 }`

Specifies whether or not all triggers defined in `CALL_TRIGGER``` section should be evaluated. If `CALLCHECKALL` is not specified, the default is `Y`.
If `CALLCHECKALL` 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.

#### SVC_TRIGGER

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 `KEYWORD`s are as follows:

#### `SVCTRIGGER=components filter:metrics filter:actions`

Specifies for which Tuxedo server (`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.

#### CALL_TRIGGER

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`

Specifies for which Tuxedo server (`components filter`, optional), under what condition (`metrics filter`) 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.

#### BBL_TRIGGER

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`

Specifies for which Tuxedo server (`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.

#### REPORT_POLICY

This section specifies whether or not collected service and call path monitor data should report to BEA 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:

`SVCSENDTOLMS={ Y | N }`

Specifies whether or not service monitor data should report to BEA TSAM Manager by default Plug-in. The default value is `Y`.

`CALLSENDTOLMS={ Y | N }`

Specifies whether or not call path monitor data should report to BEA TSAM Manager by default Plug-in. The default value is `Y`.

### Plug-in Event Trigger Format

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

Table 2-6 Components Filter FML32 Fields
Name | Description
--- | ---
`TA_LMID` | Logical machine ID.
Note: | Not available for `BBL_TRIGGER`.
`TA_SERVERNAME` | Server name.
Note: | Not available for `BBL_TRIGGER`.
`TA_SRVGRP` | Group name
`TA_GRPNO` | Group number
`TA_SRVID` | Server ID
`TA_SVCRNAM` | For `SVC_TRIGGER` and `CALL_TRIGGER`, it’s the service name(s) provided by the server. It will have multiple occurrences if the server provides multiple services. Since the order of service is undefined, please use `TA_SVCRNAM[?]` if you want to check for service name in the filter. For `BBL_TRIGGER`, it’s the service name under checking.

Table 2-7 SVC_TRIGGER Metrics Filter FML32 fields
Name | Description
--- | ---
`TA_MONSVCNAME` | Service name
`TA_MONMSGQUEUED` | Number of messages queued on the IPC queue of the server which providing this service
`TA_MONERRNO` | Return code of the service
`TA_MONURCODE` | User return code of the service
`TA_MONEXECTIME` | Response time of the service

Table 2-8 CALL_TRIGGER Metrics Filter FML32 fields
Name | Description
--- | ---
`TA_MONSVCNAME` | The service name
`TA_MONELAPSETIME` | The elapse time in milliseconds since the call started from the monitoring initiator
`TA_MONDEPTH` | The call path tree depth, counting from 0 (initiator).
`TA_MONCORRID` | The correlation id of the monitored call
`TA_MONERRNO` | Return code of current service. It only applies to reply stage
`TA_MONURCODE` | User return code of current service. It only applies to reply stage

Table 2-9 BBL_TRIGGER Metrics Filter FML32 Fields
Name | Description
--- | ---
`TA_MONSVCNAME` | The service name.
`TA_MONEXECTIME` | The elapsed time in milliseconds since the service started executing.

Table 2-10 Event Parameters
Name | Description
--- | ---
`name` | Event name, a string of at most 31 characters. Valid characters are ‘0’..’9’, ‘a’..’z’, ‘A’..’Z’ and ‘_’.
`severity` | Message severity level. Can be one value of `Information`, `Warn`, `Critical`, and `Fatal`. The default value is `Information`.
`destination` | There are two supported destinations: `eventbroker` (Tuxedo Event Broker) and `tsammanager` (BEA TSAM Manager). This parameter can contains multiple values (separated by `‘+’`). The default value is `tsammanager`.