Table of Contents
There are two programmatic interfaces to the Trigger Service: information is collected using an Aggregator Source and acted upon by an executable program.
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 the Aggregator Sources Reference; information about how to create new aggregator sources can be found in the WS MDS Aggregator Framework Developer's Guide.
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).
The trigger service inherits its WSDL interface from the aggregator framework module, included below:
The aggregator framework builds on the WS-ServiceGroup and WS-ResourceLifetime specifications. Those specifications should be consulted for details on the syntax of each operation.
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
group 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 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:
- WSRF service group schema
- WSRF resource lifetime schema
- MDS Usefulrp schema.
The AggregatorConfig element must contain an element of xsi:type
TriggerRuleType, defining the conditions upon which this
trigger registration will fire. This element is documented further
in the
Additional configuration for the Trigger Service in the System Administrator's Guide.
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 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 stdout, and
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:
<fire>
<message>
The message which caused the rule to file.
</message>
<MemberEPR>
The EPR of the service registered for the firing rule.
</MemberEPR>
<AggregatorConfig>
The aggregator configuration element for this rule.
</AggregatorConfig>
</fire>
The presence of the aggregator framework configuration element allows for additional parameters to be passed to the action script in registrations.
The trigger service is an MDS aggregator service, and so inherits much of its configuration system from the aggregator framework module.
The aggregator framework does not have its own service side configuration, although services which are based on the framework have their own service side configuration options (such as MDS Index and MDS Trigger) which are documented in the per-service documentation.
Registrations to a working aggregator framework are configured for the mds-servicegroup-add tool. This tool takes an XML configuration file listing registrations, and causes those registrations to be made.
In general, configuration of aggregator services involves configuring the service to get information from one or more sources in a Grid. The mechanism for doing this is defined by (inherited from) the aggregator framework and described in this section.
Configuring an Aggregating Service Group to perform a data aggregation is performed by specifying an AggregatorContent object as the content parameter of a ServiceGroup add method invocation. An AggregatorContent object is composed of two xsd:any arrays: AggregatorConfig and AggregatorData:
- The AggregatorConfig xsd:any array is used to specify parameters that are to be passed to the underlying AggregatorSource when the ServiceGroup add method is invoked. These parameters are generally type-specific to the implementation of the AggregatorSource and/or AggregatorSink being used.
- The AggregatorData xsd:any array is used as the storage location for aggregated data that is the result of message deliveries to the AggregatorSink. Generally, the AggregatorData parameter of the AggregatorContent is not populated when the ServiceGroup add method is invoked, but rather is populated by message delivery from the AggregatorSource.
The following links provide information for configuring the three types of aggregator sources provided by the Globus Toolkit:
An aggregator sink may require sink-specific configuration (the MDS Trigger service requires sink-specific configuration; the MDS Index service does not). See the documentation for the specific aggregator service being used for details on sink-specific documentation.
In addition to the source parameters specified
above, the TriggerRuleType element must be added to all registrations
made to the trigger service.
The TriggerRuleType is defined in
trigger-types.xsd in trigger/source.
This registration parameter contains the following options:
matchingRule: XPath rule to be applied against incoming data. The XPath expression will be evaluated against aggregated data, and will be regarded as matching the incoming data if it matches one or more nodes in that data.actionScript: the name of a script in$GLOBUS_LOCATION/libexec/trigger/that will be executed when the matchingRule matches (except as rate limited by the following parameters).minimumFiringInterval: the action script will not be executed more than once in this number of seconds. If unspecified, there will be no minimum interval.minimumMatchTime: the matchingRule must be true for this number of seconds before the actionScript will be executed. If unspecified, there is no minimum time period that the rule must match and the rule will fire immediately the matchingRule becomes true.outputXSL: (UNIMPLEMENTED in GT 3.9.3). The delivered message will be transformed by the specified XSLT stylesheet and fed into the stdin of the action script. It is intended that this will be implemented in a subsequent release of the GT3.9.x series.
The rate limiting parameters behave in such a way that the rate of action
script executions can be decreased by increasing the minimumFiringInterval and/or by increasing the minimumMatchTime.
A complete and working example of a trigger registration file can be viewed
at $GLOBUS_LOCATION/etc/globus_wsrf_mds_trigger/trigger-aggregator-registration.xml
This file causes a small test script to be run when it detects that the GLUE
RP appears in the DefaultIndexService. (Please refer to the GLUE
RP documentation for more information about configuring and using
it). By default, the registration example fires no more than once in every
10 minute interval. As you can see, that is dictated by the minimumFiringInterval
value specified. The sample registration also causes the GLUE RP to be polled
(i.e. updated) every 10 minutes to make sure that the entry is still valid.
Currently, the example trigger registration file will fire on the default
installation because the MJFS (i.e. GRAM) contains the GLUE RP and the matchingRule is
indicated as the XPath indicator for the node-set containing the GLUE RP in
particular (i.e. //*[local-name()='GLUECE']). However, you can easily substitute
more advanced XPath queries for firing on more specific value changes. For
example, locating a specific node-set within the GLUE RP using XPath can look
something like this:
//*[local-name()='GLUECE']//ns1:ComputingElement//ns1:State
Please see Deploying the Trigger Service for the method of registering the sample trigger scenario with your globus deployment.