- Doc Structure
- A Globus Primer
- Installing GT
- Platform Notes
- Migrating from GT2
- Migrating from GT3
- PDF version
- Best Practices
- Coding Guidelines
- API docs
- Public Interfaces
- Resource Properties
- Performance Studies
Table of Contents
The WS MDS Trigger Service collects information about Grid resources and can be configured to execute a program if the collected data meets certain conditions. This document describes the programmatic interfaces to the Trigger Service.
Before you begin:
Features new in release 4.1.0
- Multiple TriggerRules per data source aggregation is now supported. Each trigger rule will be evaluated against the incoming message in the order specified in the aggregator configuration.
- Support for XML Namespace resolution in the TriggerRule Xpath statement. This allows namespace prefixes to be specified in the TriggerRule XPath matching rule string parameter.
- Invalidity time ranges for action script execution. A given TriggerRule will not execute an actionScript if the current time falls within a valid InvalidyTime datetime-range pair.
- Additional options for configuring input to action scripts. It is now possible to disable the sending of the original trigger message data as input to the action script. It is also now possible to specify that any filtered result set returned by the XPath matching rule statement should be included as input to the action script.
Other Supported Features
- Uses the Aggregator Framework to monitor XML data for matching trigger conditions
- When a trigger condition matches, fires a customizable action: for example, sends email to an administrator.
- Monitored services are managed through service group-based registration API, allowing use of many of the same clients that can be used in the Index Service.
- Not applicable
Tested Platforms for WS-MDS Trigger Service
- Linux on i386
- Windows XP
Tested containers for WS-MDS Trigger Service:
- Java WS Core container
- Tomcat 5.0.28
The Trigger Service is a new component for GT 4.1.0 and so has no compatibility statement.
The Trigger Service depends on the following GT components:
The Trigger Service depends on the following 3rd party software:
The security considerations for the Aggregator Framework also apply to the Trigger Service:
By default, the aggregator sources do not use authentication credentials -- they retrieve information using anonymous SSL authentication or no authentication at all, and thus retrieve only publicly-available information. If a user or administrator changes that configuration so that a service's aggregator source uses credentials to acquire non-privileged data, then that user or administrator must configure the service's aggregator sink to limit access to authorized users.
The Trigger Service collects information and acts on it, by executing an administrator-supplied executable program when certain conditions (expressed as XPath matches on the collected information) are met. There are two programmatic interfaces to the Trigger Service: information is collected using an aggregator source and acted upon by an executable program.
There is no "client" interface to the Trigger Service -- "clients" will typically interact with the Trigger Service indirectly, using some mechanism specific to the triggered executable program (for example, an executable program may send mail to an end-user or write a structured log file that will later be read by some other program).
There are two programmatic interfaces to the Trigger Service: information is collected using an Aggregator Source and acted upon by an executable program.
There is no specialized client interface to the Trigger Service -- "clients" will typically interact with the Trigger Service indirectly by creating triggers using mds-servicegroup-add. The trigger parameters are contained within the TriggerRuleType XML type which is specified as one or more elements in the AggregatorConfig section of the registration message.
Information about how to configure existing aggregator sources (such as the aggregator sources distributed with the Globus Toolkit, which include one that polls for resource property information, one that collects resource property information through subscription/notification, and one that collects information by executing an executable program) is found in Aggregator Sources Reference; information about how to create new aggregator sources can be found in Aggregator Developer's Guide.
The administrator of a Globus installation configures the set of available executable programs that are available to be used as action scripts (for example, an executable program may send mail to an end-user or write a structured log file that will later be read by some other program).
The trigger service inherits its WSDL interface from the Aggregator Framework module, included below:
Each Aggregator Framework is represented as a WS-ServiceGroup (specifically, an AggregatorServiceGroup).
Resources may be registered to an AggregatorServiceGroup using
the AggregatorServiceGroup Add operation. Each registration will be
represented as a ServiceGroupEntry resource. Resources may be
registered to an AggregatorServiceGroup using the service
add operation, which will cause an entry to be
added to the service group.
The entry will include configuration parameters for the aggregator source; when the registration is made, the following will happen:
- The appropriate aggregation source and sinks will be informed,
- the aggregator source will begin collecting data and inserting it into the corresponding service group entry,
- and the aggregator sink will begin processing the information in the service group entries.
The method of collection by source and processing by the sink is dependent on the particular instantiation of the aggregator framework (see per-source documentation for source information and per-service documentation for sink information - for example the Index Service and the Trigger Service.)
add:This operation is used to register a specified resource with the Aggregator Framework. In addition to the requirements made by the WS-ServiceGroup specification, the Content element of each registration must be an AggregatorContent type, with the AggregatorConfig element containing configuration information specific to each source and sink (documented in the Aggregator System Administrator's Guide).
Entry:This resource property publishes details of each registered resource, including both an EPR to the resource, the Aggregator Framework configuration information, and data from the sink.
RegistrationCount:This resource property publishes registration load information (the total number of registrations since service startup and decaying averages)
The Aggregator Framework throws standard WS-ServiceGroup, WS-ResourceLifetime, and WS-ResourceProperties faults and does not define any new faults of its own.
Other relevant source files are the:
The AggregatorConfig element must contain an element of
TriggerRuleType, defining the conditions upon which this
trigger registration will fire. This element is documented further
in the "Additional configuration for the Trigger Service" section under Configuring the Trigger Service.
In addition to the resource properties for the Aggregator Framework, the Trigger Service exposes the following:
ActionsFiredCount:This resource property counts the total number and average rate of rule firings. This is an accumulator resource property, which is defined in the usefulrp/schema module.
The Trigger Service itself does not have any command-line clients for end users; instead, the trigger service is configured to run an executable program to take some action (for example, send mail to a set of users, or write a log entry to a file).
The mds-servicegroup-add(1) command in the Aggregator Framework is used to configure the Trigger Service to collect information from various sources.
There is no GUI specifically for the Trigger Service. The release contains WebMDS which can be used to display the status of resources registered to a Trigger Service in a normal web browser.
The trigger service provides an API to action scripts, which are executed when trigger rules fire. These take the form of fork-exec executables (written in any language) which are supplied with rule information on stdin and must output status information on stdout.
Trigger action scripts take the form of native OS executables, and so can be written in any language that can generate such (for example, bash, PERL, C).
Information on the match that caused an action to fire is fed
into the action script through
stdin. Status information
from the action script should be sent to
will reported in the content of the ServiceGroupEntry for the rule.
An XML document of the following format will be piped to the stdin of the action script:
<actionInput> <inputMessage> The message which caused the rule to fire. </inputMessage> <xpathResult> The result produced by the evaluation of the XPath matching rule. </xpathResult> <MemberEPR> The EPR of the service registered for the firing rule. </MemberEPR> <AggregatorConfig> The aggregator configuration element for this rule. </AggregatorConfig> </actionInput>
The inputMessage element may or may not be present in the action script input, based on how the boolean variable disableUnmodifiedActionScriptInput is set in TriggerRuleType. Defaults to false.
The xpathResult element may or may not be presentin the action script input, based on how the boolean variable enableFilteredActionScriptInput is set in TriggerRuleType. Defaults to false.
The presence of the Aggregator Framework AggregatorConfig configuration element allows for additional parameters to be passed to the action script in registrations.
Please see the Configuring section of the System Administrator's Guide.
Please see Deploying the Trigger Service for the method of registering the sample trigger scenario with your globus deployment.
The public interfaces for creating and configuring aggregator sources -- sources of information used by the trigger service -- can be found in Aggregator Sources Reference.
Information is collected by the Trigger Service by way of an aggregator source. The Globus Toolkit distribution includes several standard aggregator sources (see Aggregator Sources Reference for more details). To create your own custom information source, see the Aggregator Developer's Guide.
This is handled through configuration options (see Configuring the Trigger Service for details).
The executable program triggered by the Trigger Service can be written in any programming or scripting language. The specifications for this program are documented in Execution Aggregator Sources Reference.
See Section 7, “Debugging” for general information on logging, including which files to edit to set logging properties.
To turn on debug logging for the Trigger Service, add the line:
to the appropriate properties file. Since the Trigger Service is implemented using the Aggregator Framework, you may also want to turn on aggregator debugging by adding this line:
General troubleshooting information can be found in Section 8, “Troubleshooting”.
Specifications for resource properties, service groups, and subscription/notification are available at http://www.globus.org/wsrf/.