Processing

Online section / Guides / User Guide / Datasinks / Processing contact | download | sitemap

Processing datasinks

Trigger datasink

The trigger datasink can be used to evaluate various expressions online and to execute some action based on the result of the evaluation.

<name>.tran.list: specifies a list of trigger names to evaluate for each measured transaction.
<name>.<triggername>.filter: defines the filter for the trigger named <triggername>.
<name>.<triggername>.execute: defines the action to execute if the corresponding filter evaluates to true.
<name>.<triggername>.stop: if set to true, stop processing of defined triggers.

A transaction trigger filter defines the set of transaction instances to evaluate trigger expressions. Filters are defined by transaction and/or application definition names. A transaction filter is defined as follows:

match tran'='<appName>':'<tranName> '{' <expression> '}' 
      [or|and '{' <expression> '}']

where

match: is the literal string starting a trigger filter.
tran: is the literal string indicating a transaction filter.
<appName>: is the application definition name or the asterisk character ('*') matching any application definition name.
<tranName>: is the transaction definition name or the the asterisk character ('*') matching any transaction definition name.
<expression>: is the expression to evaluate for each transaction instance matching the application and/or transaction definition names specified before.
or: logical or-operator between two expressions.
and: logical and-operator between two expressions.

Transaction expression

A transaction expression defined in a transaction filter is evaluated for each transaction instance. The expression can use various values of the current transaction instance for its evaluation. For example it is very easy to execute some action for any failed transaction:

match tran=*:* { tran.status == tran:failed }

The field references the status of the current transaction and is compared to the status value.

Currently the following transaction values are supported in an expression:

tran.duration: duration (response time) of the current transaction.
tran.status: execution status of the current transaction.

The following section describes the complete filter in EBNF (Extended Backus-Naur Form).

Transaction filter EBNF

The following EBNF (Extended Backus-Naur Form) grammar describes the syntax of the complete transaction filter where the following terminals are

APPNAME: application definition name of the current transaction.
TRANNAME: transaction definition name of the current transaction.
METNAME: metric definition name of an associated metric of the current transaction.
NUMBER: a numeric constant.

input	::=	"MATCH" "TRAN" "=" match_tran match_expression
match_tran	::=	APPNAME ":" TRANNAME
match_expression	::=	"{" expression "}" match_logical
match_logical	::=	empty
	\|	"OR" match_expression
	\|	"AND" match_expression
expression	::=	"TRAN" tran_expr
	\|	NUMBER
	\|	expression "+" expression
	\|	expression "-" expression
	\|	expression "*" expression
	\|	expression "/" expression
	\|	expression "<" "=" expression
	\|	expression ">" "=" expression
	\|	expression "=" "=" expression
	\|	expression "!" "=" expression
	\|	expression "<" expression
	\|	expression ">" expression
	\|	"!" expression
	\|	"(" expression ")"
tran_expr	::=	"." tran_field
	\|	":" tran_const
tran_field	::=	"STATUS" \| "DURATION" \| "METRIC" "." METNAME
tran_const	::=	"GOOD" \| "FAILED" \| "ABORTED" \| "UNKNOWN"
empty	::=

Trigger action

The trigger action defines which action should be executed if the trigger expression evaluated to true. The following actions are currently supported:

log:

logs the following string to the configured log facility. For example:

log: info: Transaction \%a:\%t for \$(tran.uri} failed.

command:

executes the following string as a shell command.

Note this operation can be much expensive regarding performance thus it should not be used inside instrumented applications. You can use this trigger action in one of the MyARM daemon processes like myarmfiled or myarmtcpd. For example:

command: /usr/local/bin/sendemail.sh \
         -s "Transaction %a:%t for $(tran.uri} failed." \
         fatal@yourdomain.com

Trigger action text substitution

Within the trigger action string the following text substitution are done by the trigger sink:

%a

is substituted by the application definition name of the current transaction.

%t

is substituted by the transaction definition name of the current transaction.

$(tran.value)

is substituted by the appropriate transaction value. where value is one of the following transaction data field names:

metric.name: the contents of the metric named name.
uri: the URI field of the current transaction.
status: the stop status of the current transaction.
duration: the duration of the current transaction (response time).