APAMA EVENT MANAGER 2.

OPERATIONS

Copyright Notice Copyright (c) 2005 Apama Inc and Apama (UK) Limited. All Rights Reserved. This document may not, in whole or in part, be copied, photocopied, reproduced, translated, or reduced to any electronic medium or machine-readable form without prior consent in writing from Apama. Intellectual Property Notice Apama may have patents and/or patent pending applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. Trademarks Notice All Apama brands and product names are trademarks or registered trademarks of Apama. Other brands and product names may be trademarks or registered trademarks of their respective owners. No license is granted to reproduce or use any such brand, product name or trademark, save as permitted in the applicable license agreement. Proprietary Information Apama considers information included in this documentation to be Confidential Information. Your access and use of this Confidential Information is subject to the terms and conditions of the software license agreement, which has been executed and with which you agree to comply. Accordingly, you may not disclose or disseminate any such Confidential Information save in the context of any copying or sublicensing of the documentation permitted under such license agreement. Support If you have a question which you cannot answer by using this documentation, please refer to the support page on our website at http://www.apama.com. Feedback Apama welcomes comments and suggestions on its manuals, please send any feedback to support@apama.com. Document Version: 2.3.0 (1)

ABOUT THIS DOCUMENT

At the heart of Event Manager is the Event Correlator. This is Apamas core event processing and correlation engine. This document details the usage of the Correlator, plus the command-line tools used to monitor and manage it. These include tools to: add applications to an Event Correlator remove applications from an Event Correlator stream events to an Event Correlator receive events from an Event Correlator continually monitor the status of an Event Correlator inspect the state of an Event Correlator

CONTENTS
Chapter 1 Introduction ......................................................................................................... 1-1 1.1 Getting started .......................................................................................................... 1-1 Chapter 2 The Event Correlator ........................................................................................... 2-1 2.1 Synopsis.................................................................................................................... 2-1 2.2 Description ................................................................................................................ 2-1 2.3 Options ...................................................................................................................... 2-2 2.4 Exit Status ................................................................................................................. 2-3 2.5 Operating Notes........................................................................................................ 2-3 2.5.1 Status information logging .................................................................................. 2-3 2.5.2 Text localization ................................................................................................... 2-4 Chapter 3 Injecting MonitorScript........................................................................................ 3-1 3.1 Synopsis.................................................................................................................... 3-1 3.2 Description ................................................................................................................ 3-1 3.3 Options ...................................................................................................................... 3-2 3.4 Operands................................................................................................................... 3-2 3.5 Exit Status ................................................................................................................. 3-2 3.6 Operating Notes........................................................................................................ 3-3 3.6.1 Text localization ................................................................................................... 3-3 Chapter 4 Deleting MonitorScript ........................................................................................ 4-1 4.1 Synopsis.................................................................................................................... 4-1 4.2 Description ................................................................................................................ 4-1 4.3 Options ...................................................................................................................... 4-2 4.4 Operands................................................................................................................... 4-2 4.5 Exit Status ................................................................................................................. 4-3 Chapter 5 Sending Events to a Correlator .......................................................................... 5-1 5.1 Synopsis.................................................................................................................... 5-1 5.2 Description ................................................................................................................ 5-1 5.3 Options ...................................................................................................................... 5-1 5.4 Operands................................................................................................................... 5-2 5.5 Exit Status ................................................................................................................. 5-2 5.6 Operating Notes........................................................................................................ 5-2 5.6.1 Text localization ................................................................................................... 5-2 Chapter 6 Reviewing Output from a Correlator .................................................................. 6-1 6.1 Synopsis.................................................................................................................... 6-1 6.2 Description ................................................................................................................ 6-1 6.3 Options ...................................................................................................................... 6-2 6.4 Exit Status ................................................................................................................. 6-2 6.5 Operating Notes........................................................................................................ 6-2 6.5.1 Text localization ................................................................................................... 6-2 Chapter 7 Watching a Correlators runtime status ............................................................. 7-1 7.1 Synopsis.................................................................................................................... 7-1 7.2 Description ................................................................................................................ 7-1 7.3 Options ...................................................................................................................... 7-2 7.4 Exit Status ................................................................................................................. 7-3 Chapter 8 Inspecting the contents of a Correlator ............................................................. 8-1 8.1 Synopsis.................................................................................................................... 8-1 8.2 Description ................................................................................................................ 8-1 8.3 Options ...................................................................................................................... 8-1 8.4 Exit Status ................................................................................................................. 8-2

Chapter 9 Managing the Correlator ..................................................................................... 9-1 9.1 Synopsis .................................................................................................................... 9-1 9.2 Description ................................................................................................................ 9-1 9.3 Options ...................................................................................................................... 9-1 9.4 Exit Status ................................................................................................................. 9-2 Chapter 10 Event file format .............................................................................................. 10-1 10.1 Event representation............................................................................................. 10-1 10.2 Event batching ...................................................................................................... 10-2 10.3 Event timing........................................................................................................... 10-2 10.4 Event data types ................................................................................................... 10-2

Chapter 1 INTRODUCTION
Apama provides real-time matching services to support key business processes. At the heart of the Apama solution lies the Event Correlator a high performance matching and correlation engine that hosts hundreds of applications concurrently and processes thousands of events per second. This document details the usage of the Event Correlator, which provides the core matching and analytic service at the heart of the Apama solution, plus command-line tools used to monitor and manage it. These include tools to: add applications to an Event Correlator remove applications from an Event Correlator stream events to an Event Correlator receive events from an Event Correlator continually monitor the status of an Event Correlator inspect the state of an Event Correlator

1.1 Getting started

This guide assumes that Apama has been installed as per the instructions in the Getting Started guide, and that a Full Install has been performed. All tools (which are prefixed with engine_) and the correlator executable will be located in the bin directory under the location specified in the installer. This is normally /opt/apama/event_manager_2.3.0 on Unix, and \Program Files\Apama Event Manager 2.3.0 on Windows. For information on MonitorScript, event definitions, monitors, namespaces and packages, please refer to the MonitorScript Reference guide included in the Event Manager bundle.

1-1

The Event Correlator

Chapter 2 THE EVENT CORRELATOR

The Correlator is the core Apama event matching and analytic engine.

2.1 Synopsis
The executable for the Event Correlator is correlator.exe (on Windows) or correlator (on Unix). When it is run without any command line options, or with the h option, it displays the following usage information:
Apama Correlator v2.5.0 EMgr 2.3.0 (2.4.10.0) Copyright (c) 2002-2005 Apama Inc., Apama (UK) Ltd. and affiliates This software is the proprietary information of Apama Inc., Apama (UK) Ltd. and affiliates. Use is subject to licence terms. Usage: correlator [ options ] Where options include: -h | --help -p | --port <port> -s | --qsize <size> -b | --qbatchsize <size> -i | --qinterval <interval>

This message Listening on <port> Output queue size is <size> Output queue batch size is <size> Output queue timeout interval is <interval> -m | --mbuffers <num> Buffer at most <num> batches per receiver -x | --qdisconnect Disconnect slow event consumers -j | --java Enable Java application support -J | --javaopt <option> Option to pass to JVM -f | --logfile <file> Log filename is <file> -t | --truncate Truncate log file -v | --loglevel <level> Log level is <level> -l | --licence <file> Licence filename is <file> -d | --decimal <places> Print floats to <places> significant Figures -Xclock | --externalClock Use external clocking (&TIME events) -Xconfig | --configFile <file> Use service configuration file <file> -V | --version Print version info and exit

The loglevel argument must be one of: OFF, CRIT, FATAL, ERROR, WARN, INFO, DEBUG Note: Queue parameter values will be altered if outside acceptable ranges. Note: The -l option is mandatory: you must specify a licence file.

2.2 Description
The tool correlator.exe (on Windows) or correlator (on Unix) starts an Event Correlator process on the current host and listening on the specified port for monitoring and management requests. On start-up, the current version number and settings (some of which can be overridden with command-line arguments) are printed. To terminate an Event Correlator process hit Ctrl-C in the shell window in which it was started.

2-1

Operations Guide

2.3 Options
The tool correlator.exe (on Windows) or correlator (on Unix) takes a number of command line options. These are:
-h -p <port>

Display usage information Port on which the Event Correlator should listen for monitoring and management requests (default is 15903) Sets the size of the Event Correlators output queue (default is 10000) this should not need adjusting in normal operation Sets the batch size of the Event Correlators output queue (default is 100) this should not need adjusting in normal operation Sets the timeout of the Event Correlators output queue (default is 10 ms) this should not need adjusting in normal operation Sets the max number of output event batches to buffer per connected receiver (default is 100) this should not need adjusting in normal operation Tells the Event Correlator to disconnect any receiver whose output queue becomes full i.e. a receiver which cannot consume events fast enough (without this option, the Event Correlator will stop processing events until some output events are consumed by the receiver, freeing space on its output queue) Enables support for Java applications without this, any attempt to inject a Java application using engine_inject j (see below) will result in an error Option/property to pass to the embedded JVM. This option can be used to pass command line options to the embedded JVM. Note that each JVM option must be passed on its own J option. For example,
-J "-Da=value1" -J "-Db=value2" -J "-Xmx400m"

-s <size>

-b <size>

-i <interval>

-m <num>

-x

-j

-J <option>

The Java classpath must not be set using this mechanism, as the Correlator passes that through implicitly as the last option. Set the CLASSPATH environment variable if you want to set a particular classpath.
-f <file>

Sets the log file the Event Correlator should write log messages to (default is stdout) If the log file already exists, empty it first. The default is to append to it. Sets the log level the Event Correlator should log at must be one of OFF, CRIT, FATAL, ERROR, WARN, INFO, DEBUG (in increasing order of verbosity)

-t

-v <loglevel>

2-2

The Event Correlator

-l <file>

Path to file containing the license string this option must be specified and a valid license file provided, unless one of the h or V options are specified Specify the number of significant figures for representing floating point values in output events This instructs the Correlator to disable its internal clock. By default the Correlator clocks all incoming events according to the time of when they were received by on the input queue, and time then flows at the rate with which events are processed. When this option is specified this mechanism is disabled, and the Correlator expects to be sent external time events (&TIME). When a &TIME event is processed it sets the Correlators clock. Note that all temporal operations (like timers and wait statements) would be affected by this. If no &TIME events are received then it is as if time has ceased to flow in the Correlator and every event is received at the same instant. Specified that the Correlator should use a special configuration file to initialize its networking. This should only be used as directed by Apama Technical Support in order to troubleshoot networking problems. Print version information and exit Specify that the Correlator should use UTF8 encoding for all of its output, e.g. logging, printing from MonitorScript. Default is 7bit ASCII.

-d <places>

-Xclock

-Xconfig

-V -u

2.4 Exit Status

The following exit values are returned:
0 1

The Event Correlator terminated successfully An error occurred which caused the Event Correlator to terminate abnormally

2.5 Operating Notes

2.5.1 Status information logging
The Event Correlator will log status information to its log file every five seconds. This information, logged at INFO level, contains the following:
Status: sm=0 ls=0 rq=0 iq=0 oc=0 rx=0 tx=0

Where the fields are as follows:

sm number of sub-monitors

2-3

Operations Guide

ls number of listeners rq number of routed events on the queue iq current size of the input queue oc number of output events created rx number of events received on the input queue tx number of actual events sent out from the Correlator (differs from oc in that this value reflects the actual number of event receivers connected to the Correlator)

2.5.2 Text localization

By default all output logged or printed out by the Correlator is localized to display in the current locale. The u option may be used to force the Correlator to output using UTF8.

2-4

Chapter 3 INJECTING MONITORSCRIPT

In order to inject MonitorScript and JMON applications into the Correlator, a command line tool is provided.

3.1 Synopsis
The executable for injecting MonitorScript and JMON applications into the Correlator is engine_inject.exe (on Windows) or engine_inject (on Unix). When it is run with the h command line option it displays the following usage information:
Apama engine_inject v2.5.0 EMgr 2.3.0 (2.4.10.0) Copyright (c) 2002-2005 Apama Inc., Apama (UK) Ltd. and affiliates This software is the proprietary information of Apama Inc., Apama (UK) Ltd. and affiliates. Use is subject to licence terms. Usage: engine_inject [ options ] [ file1 [ file2 ... ] ] Where options include: -h | --help -n | --hostname <host> -p | --port <port> -v | --verbose -V | --version -j | --java This message Connect to a engine on <host> Engine is listening on <port> Be more verbose Print program version info Inject java applications rather than MonitorScript Use '-' to read from <stdin>

3.2 Description
This tool reads application definitions from the named file(s) and injects them into an Event Correlator. If no filename is provided, or the file name is , data is read from the standard input device (stdin) until end-of-file is typed (CTRL-D on Unix and CTRL-Z on Windows). Application definitions may be monitors scripted in the Apama MonitorScript Language (see the MonitorScript Reference guide for details). Alternatively, if the j option is specified, Java engine applications can be injected where each file is a Java JAR archive containing a single Java application (see the JMON Reference guide). The tool is silent by default unless an error occurs for verbose progress information use the v option. Note that if the MonitorScript or JMON application injected is invalid, a parsing error will be generated by the Event Correlator. This will cause engine_inject to quit, resulting in none of the application data in the offending file being loaded into the Correlator.

3-1

Operations Guide

3.3 Options
The tool engine_inject.exe (on Windows) or engine_inject (on Unix) takes a number of command line options. These are:
-h -n <host>

Display usage information Name of the host on which the Event Correlator is running (default is localhost) Port on which the Event Correlator is listening (default is 15903) Treat each operand as a Java JAR archive containing a single Java engine application Requests verbose output Displays program name and version number Specify that the tool should expect UTF8 encoding for all of its input. Default is 7bit ASCII.

-p <port> -j

-v -V -u

3.4 Operands
The tool engine_inject.exe (on Windows) or engine_inject (on Unix) takes the following operands. These are:
[ file1 [ file2 ... ] ]

The names of zero or more files containing application data in Apama MonitorScript or Java formats.

3.5 Exit Status

The following exit values are returned:
0 1

All definitions were injected into the Event Correlator successfully No connection to the Event Correlator was possible or the connection failed Other error(s) occurred while injecting the supplied definitions

3-2

Injecting MonitorScript

3.6 Operating Notes

3.6.1 Text localization
By default engine_inject will inspect the current character locale and then translate all MonitorScript text submitted to it from this locale into UTF8. It is therefore important that the machines locale is set correctly. The u option may be used to force the tool to treat the input as UTF8.

3-3

Chapter 4 DELETING MONITORSCRIPT

In order to delete MonitorScript and JMON applications from the Correlator, a command line tool is provided.

4.1 Synopsis
The executable for deleting MonitorScript and JMON applications from the Correlator is engine_delete.exe (on Windows) or engine_delete (on Unix). When it is run with the h command line option it displays the following usage information:
Apama engine_delete v2.5.0 EMgr 2.3.0 (2.4.10.0) Copyright (c) 2002-2005 Apama Inc., Apama (UK) Ltd. and affiliates This software is the proprietary information of Apama Inc., Apama (UK) Ltd. and affiliates. Use is subject to licence terms. Usage: engine_delete [ options ] [ name1 [ name2 ... ] ] Where options include: -h | --help -n | --hostname <host> -p | --port <port> -f | --file <filename> -F | --force This message Connect to a engine on <host> Engine is listening on <port> Read names from <filename> Force deletion of names even if they are in use -k | --kill Kill name even if it is a running monitor -a | --all Delete everything in the engine use with care -y | --yes Don't ask 'are you sure?' when deleting all -v | --verbose Be more verbose -V | --version Print program version info Use '-' to read from <stdin> Multiple -f options may be given

4.2 Description
This tool deletes named applications, monitors and event types from an Event Correlator. Names are the full package names as previously assigned to an application monitor or event type when injected into the Event Correlator. Names are read from the command-line and/or from named files, where each name appears on a separate line. If no files or names are provided, or a filename is , the tool will read names from the standard input device (stdin) until an end-of-file is typed (CTRL-D on Unix and CTRL-Z on Windows). The tool is silent by default unless an error occurs for progress information use the v option. The tool permits two kinds of operations; delete and kill. These cause different sideeffects and must be used carefully. When a monitor is deleted, all its active sub-monitors are asked to terminate. If they are responsive (not in some deadlocked state) each will execute the ondie action, and when the last one exits the onunload action will finally be called. This

4-1

Operations Guide

is assuming that the ondie and onunload actions are actually defined in the monitors MonitorScript, since they are optional. Note that this means that it is possible that an unresponsive sub-monitor might not respond to a delete request, in which case the onunload action for the monitor will never be invoked. A kill operation will be required in this case. Kill will immediately terminate all the monitors sub-monitors, without either
ondie or onunload being executed.

4.3 Options
The tool engine_delete.exe (on Windows) or engine_delete (on Unix) takes a number of command line options. These are:
-h -n <host>

Display usage information Name of the host on which the Event Correlator is running (default is localhost) Port on which the Event Correlator is listening (default is 15903) Forces deletion of named event types even if they are still in use (i.e. referenced by existing monitors or applications) Kills the named item is stronger than -F and can be used to delete monitors or applications which are stuck in infinite loops Delete all applications, monitors, event types and events on the Correlators input queue is equivalent to stopping and restarting the Correlator but does not delete events already generated and queued for output. This is the same as manually calling for a delete on every monitor and sub-monitor in the Correlator. Removes the are you sure? prompt when using the -a option Requests verbose output Displays program name and version number Read names from the indicated file

-p <port> -F

-k

-a

-y -v -V -f <filename>

4.4 Operands
The tool engine_delete.exe (on Windows) or engine_delete (on Unix) takes the following operands. These are:
[ name1 [ name2 ... ] ]

The names of zero or more (java) applications, monitors and/or event types to delete from the Event Correlator

4-2

Deleting MonitorScript

4.5 Exit Status

The following exit values are returned:
0 1

The items were deleted from the Event Correlator successfully No connection to the Event Correlator was possible or the connection failed Other error(s) occurred while deleting the named items

4-3

Chapter 5 SENDING EVENTS TO A CORRELATOR

In order to send Apama-format events into the Event Correlator, a command line tool is provided. If the events are not in Apama format, then you need to use or generate an adapter that can transform your format into Apamas.

5.1 Synopsis
The executable for sending Apama events into the Correlator is engine_send.exe (on Windows) or engine_send (on Unix). When it is run with the h command line option it displays the following usage information:
Apama engine_send v2.5.0 EMgr 2.3.0 (2.4.10.0) Copyright (c) 2002-2005 Apama Inc., Apama (UK) Ltd. and affiliates This software is the proprietary information of Apama Inc., Apama (UK) Ltd. and affiliates. Use is subject to licence terms. Usage: engine_send [ options ] [ file1 [ file2 ... ] ] Where options include: -h | --help This message -n | --hostname <host> Connect to a engine on <host> -p | --port <port> Engine is listening on <port> -l | --loop <count> Loop through input <count> times -v | --verbose Be more verbose -V | --version Print program version info Use '-' to read from <stdin> Loop count < 0 means loop forever

5.2 Description
This tool sends events to an Event Correlator in batches of one or more events, optionally at set time intervals. Events and optional timing data are read from a file or from the standard input device (stdin) if no file name is provided or file name is . The latter continues until an end-of-file is typed (CTRL-D on Unix and CTRL-Z on Windows). For information on event file formats see Chapter 10 , Event file format. The tool is silent by default unless an error occurs for progress information use the v option.

5.3 Options
The tool engine_send.exe (on Windows) or engine_send (on Unix) takes a number of command line options. These are:
-h

Display usage information

5-1

Operations Guide

-n <host>

Name of the host on which the Event Correlator (or Event Router) is running (default is localhost) Port on which the Event Correlator (or Event Router) is listening (default is 15903) Requests verbose output Displays program name and version number Number of times to cycle through the input data: 0 <0 >0 Do not cycle (the default) Cycle indefinitely Cycle the indicated number of times

-p <port>

-v -V -l <loop>

Note that this option is ignored when reading events from stdin
-u

Specify that the tool should expect UTF8 encoding for all of its input. Default is 7bit ASCII.

5.4 Operands
The tool engine_send.exe (on Windows) or engine_send (on Unix) takes the following operands. These are:
[ file1 [ file2 ... ] ]

The names of zero or more files containing event data. This must comply with the event file format described in Chapter 10 , Event file format.

5.5 Exit Status

The following exit values are returned:
0 1

The events were sent successfully No connection to the Event Correlator (or Event Router) was possible or the connection failed Other error(s) occurred while sending the events

5.6 Operating Notes

5.6.1 Text localization
engine_inject will inspect the current character locale and then translate all

MonitorScript text submitted to it from this locale into UTF8. It is therefore important that

5-2

Sending Events to a Correlator

the machines locale is set correctly. The u option may be used to force the tool to treat the input as UTF8.

5-3

Chapter 6 REVIEWING OUTPUT FROM A CORRELATOR

A command-line tool is provided to allow you to connect to a running Event Correlator and receive events from it. Events received and displayed by this tool are in Apama event format. This is identical to the format used in sending events to the Correlator, and it is possible to reuse the output of this tool as input to the engine_send tool.

6.1 Synopsis
The executable for receiving Apama events from the Correlator is engine_receive.exe (on Windows) or engine_receive (on Unix). When it is run with the h command line option it displays the following usage information:
Apama engine_receive v2.5.0 EMgr 2.3.0 (2.4.10.0) Copyright (c) 2002-2005 Apama Inc., Apama (UK) Ltd. and affiliates This software is the proprietary information of Apama Inc., Apama (UK) Ltd. and affiliates. Use is subject to licence terms. Usage: engine_receive [ options ] Where options include: -h | --help -n | --hostname <host> -p | --port <port> -c | --channel <channel> -f | --filename <file> This message Connect to a engine on <host> Engine is listening on <port> Listen on output channel <channel> Write to <file> instead of to standard out -z | --zeroatfirstbatch Measure BATCH timestamps from when the First batch arrived, instead of from When engine_receive was started -v | --verbose Be more verbose -V | --version Print program version info Multiple -c options may be given

6.2 Description
This tool receives events from an Event Correlator and writes them to stdout (unless f is specified). The output format is the same as that used for event input described in Chapter 10 , Event file format. Output event channels can be specified using the -c option (the default is to receive all output events) see the MonitorScript Reference manual for information on event channels. For additional progress information use the v option.

6-1

Operations Guide

6.3 Options
The tool engine_send.exe (on Windows) or engine_send (on Unix) takes a number of command line options. These are:
-h -n <host>

Display usage information Name of the host on which the Event Correlator is running (default is localhost) Port on which the Event Correlator is listening (default is 15903) Dump all received events to the named file Requests verbose output Displays program name and version number Records the first received batch of events as occurring at time 0 milliseconds, rather than time equal to the number of milliseconds since engine_receive was started Named channel to listen on for output events default is to listen for all output events Specify that the tool should use UTF8 encoding for all of its output. Default is 7bit ASCII.

-p <port> -f <file> -v -V -z

-c <channel>

-u

6.4 Exit Status

The following exit values are returned:
0 1

All events were received successfully No connection to the Event Correlator was possible or the connection failed Other error(s) occurred while receiving events

6.5 Operating Notes

6.5.1 Text localization
engine_receive will inspect the current character locale and then translate all event

instances it receives from UTF8 into this locale. It is therefore important that the machines locale is set correctly. The u option may be used to force the tool to output using UTF8.

6-2

Chapter 7 WATCHING A CORRELATORS RUNTIME

STATUS
It is possible to monitor the runtime operational status of a running Event Correlator.

7.1 Synopsis
The executable for watching the Event Correlators status is engine_watch.exe (on Windows) or engine_watch (on Unix). When it is run with the h command line option it displays the following usage information:
Apama engine_watch v2.5.0 EMgr 2.3.0 (2.4.10.0) Copyright (c) 2002-2005 Apama Inc., Apama (UK) Ltd. and affiliates This software is the proprietary information of Apama Inc., Apama (UK) Ltd. and affiliates. Use is subject to licence terms. Usage: engine_watch [ options ] Where options include: -h | --help -n | --hostname <host> -p | --port <port> -i | --interval <ms> -f | --filename <file> -r -o -v -V | | | | --raw --once --verbose --version This message Connect to a engine on <host> Engine is listening on <port> Poll every <ms> milliseconds Write to <file> instead of to standard out Raw (i.e. parser friendly) output Poll once then exit Be more verbose Print program version info

7.2 Description
This tool periodically polls an Event Correlator for status information, writing the returned status data to stdout. For additional progress information use the v option. The values returned by engine_watch are as follows:
Uptime (ms) The time in milliseconds since this Correlator was started. This figure is unaffected if the state of the Correlator is restored from a checkpoint file. Number of monitors The current number of MonitorScript monitors injected

and instantiated inside the Correlator. This figure changes upwards and downwards as monitors are injected, deleted or just expire.
Number of sub-monitors The number of MonitorScript sub-monitors. Submonitors are created by spawn actions within MonitorScript monitors. This figure changes upwards and downwards as sub-monitors are spawned, killed or just expire. Number of Java applications The number of Java JMON applications currently loaded into the Correlator. JMON applications do not expire, so this value only decreases when they are explicitly unloaded.

7-1

Operations Guide

Number of listeners The number of event listeners created by MonitorScript monitors, sub-monitors and JMON applications. Number of event types The total number of event types defined within the

Correlator. This figure decreases when event types are deleted from the Correlator.
Events on input queue The number of events awaiting processing on the Correlators input queue Events received The total number of events ever received by the Correlator. This value is preserved by a checkpoint, so if the state of the Correlator is restored from a checkpoint file it will reflect the total number of the events seen by the Correlator from which the checkpoint was originally made. Events on internal queue The number of events awaiting processing on the

Correlators internal routing queue. The internal routing queue is a high priority queue that is used when events are internally routed by the route instruction in MonitorScript. Events on the internal queue are always processed before any events on the normal input queue.
Events routed internally The total number of events ever routed internally via the internal queue on this Correlator. This value is preserved by a checkpoint, so if the state of the Correlator is restored from a checkpoint file it will reflect the total number of the events routed by the Correlator from which the checkpoint was originally made. Number of consumers The number of event consumers registered with the Correlator to receive events emitted by it. Events on output queue The number of events waiting on the output queue to be dispatched to any registered event consumers. Output events created The total number of output events created by the Correlator. This value is preserved by a checkpoint, so if the state of the Correlator is restored from a checkpoint file it will reflect the total number of output events created by the Correlator from which the checkpoint was originally made. Output events sent The total number of output events dispatched to event consumers by the Correlator. This figure varies from the preceding statistic as an output event might be sent to multiple event consumers. This value is preserved by a checkpoint, so if the state of the Correlator is restored from a checkpoint file it will reflect the total number of output events sent out by the Correlator from which the checkpoint was originally made. Event rate over last interval (ev/s) The number of events per second currently being processed by the correlator. This value is computed with every status refresh and is only an approximation.

7.3 Options
The tool engine_watch.exe (on Windows) or engine_watch (on Unix) takes a number of command line options. These are:
-h -n <host>

Display usage information Name of the host on which the Event Correlator is running (default

7-2

Watching a Correlators runtime status

is localhost)
-p <port> -f <file> -r -o -i <ms> -v -V

Port on which the Event Correlator is listening (default is 15903) Write status output to the named file Raw output format more suitable for machine parsing Perform one status request then quit Sets the poll interval to <ms> milliseconds (default is 1000) Requests verbose output Displays program name and version number

7.4 Exit Status

The following exit values are returned:
0 1

All status requests were processed successfully No connection to the Event Correlator was possible or the connection failed Other error(s) occurred while requesting/processing status

7-3

Chapter 8 INSPECTING THE CONTENTS OF A CORRELATOR

It is often useful to inspect the state of a running Event Correlator. This allows one to review the applications loaded and running on the Correlator.

8.1 Synopsis
The executable for watching the Event Correlators status is engine_inspect.exe (on Windows) or engine_inspect (on Unix). When it is run with the h command line option it displays the following usage information:
Apama engine_inspect v2.5.0 EMgr 2.3.0 (2.4.10.0) Copyright (c) 2002-2005 Apama Inc., Apama (UK) Ltd. and affiliates This software is the proprietary information of Apama Inc., Apama (UK) Ltd. and affiliates. Use is subject to licence terms. Usage: engine_inspect [ options ] Where options include: -m | --monitors -j | --java -e | --events -c | --containers -r | --raw -h | --help -n | --hostname <host> -p | --port <port> -v | --verbose -V | --version List monitor types List java applications List event types List container types Raw (i.e. parser friendly) output This message Connect to a engine on <host> Engine is listening on <port> Be more verbose Print program version info

8.2 Description
This tool retrieves state information from a running Event Correlator and prints it to stdout. By default it prints information on the monitors, event types and container types currently injected in an Event Correlator, though this list can be filtered using appropriate command-line arguments.

8.3 Options
The tool engine_inspect.exe (on Windows) or engine_inspect (on Unix) takes a number of command line options. These are:
-h -n <host>

Display usage information Name of the host on which the Event Correlator is running (default is localhost)

8-1

Operations Guide

-p <port> -m

Port on which the Event Correlator is listening (default is 15903) Displays the names of all MonitorScript monitors in the Event Correlator and the number of sub-monitors for each is set by default Displays the names of all Java applications in the Event Correlator and the number of sub-monitors for each is set by default Displays the names of all event types in the Correlator and the number of templates of each type, as defined in listener specifications (See the MonitorScript guide for details) is set by default Displays the current MonitorScript container types (sequences, dictionaries) currently defined in the Event Correlator is set by default Raw output format, more suited for machine parsing Requests verbose output Displays program name and version number

-j

-e

-c

-r -v -V

8.4 Exit Status

The following exit values are returned:
0 1

All status requests were processed successfully No connection to the Event Correlator was possible or the connection failed Other error(s) occurred while requesting/processing status

8-2

Chapter 9 MANAGING THE CORRELATOR

The Correlator implements a management interface with which it can be asked to shut itself down.

9.1 Synopsis
The executable for interfacing with the Event Correlators management interface status is engine_mangement.exe (on Windows) or engine_mangement (on Unix). When it is run with the h command line option it displays the following usage information:
Apama engine_management v2.5.0, EMgr 2.3.0 (build 2.4.10.0) Copyright (c) 2002-2005 Apama Inc., Apama (UK) Ltd. and affiliates This software is the proprietary information of Apama Inc., Apama (UK) Ltd. and affiliates. Use is subject to licence terms. Usage: engine_management [ options ] Where options include: -h | --help -n | --hostname <host> -p | --port <port> -v | --verbose -V | --version -d | --deepping -g | --getpid -s | --shutdown <why> This message Connect to a component on <host> Component is listening on <port> Be more verbose Print program version info Deep-ping the remote component Get the process ID of the remote component Shutdown the component with reason <why>

9.2 Description
This tool can connect to a running Event Correlator and ask it to shutdown. It can also retrieve its process id. Any output information is displayed on stdout.

9.3 Options
The tool engine_management.exe (on Windows) or engine_management (on Unix) takes a number of command line options. These are:
-h -n <host>

Display usage information Name of the host on which the Event Correlator is running (default is localhost) Port on which the Event Correlator is listening (default is 15903) Display Correlator information in a more verbose manner

-p <port> -v

9-1

Operations Guide

-V -d

Displays the tools version details Ping the Correlator. This confirms that the Correlator process is running and acknowledging communications. Displays the process id of the Correlator Asks the Correlator to shutdown specifying a reason. The reason provided is passed to the Correlator and it will log it at CRIT level before it exits

-g -s <why>

9.4 Exit Status

The following exit values are returned:
0 1

All status requests were processed successfully No connection to the Event Correlator was possible or the connection failed Other error(s) occurred while requesting/processing status Deep ping failed

2 3

9-2

Chapter 10 EVENT FILE FORMAT

The engine_send tool can be used to stream a sequence of events through the Event Correlator. engine_send accepts input from one or more data files to support tests or simulations, or from stdin to allow dynamic generation of events. In the latter case, events may be generated through user input or by piping output from an event generation program to engine_send. In all cases engine_send expects event data formatted as described below. Note that the same file format is used by engine_receive to generate output event logs, allowing these events to be fed as input to a second Event Correlator using engine_send.

10.1 Event representation

A single event is identified by the event type name and the values of all fields as defined by that type. Event type names must be fully-qualified by prefixing the package name into which the corresponding event type was injected, unless the event was injected into the default package Each event is given on a separate line, separated by a new-line character. Comments can be inserted by using the normal C / Java style of // for single line comments, or /* */ for multi-line comments. Any blank lines are ignored. For example, the following:
/* This is an event file containing some sample events. */ // Here are three stock price events StockPrice("XRX", 11.1) StockPrice("IBM", 130.6) StockPrice("MSFT", 70.5)

are three valid events given the following event type definition (injected into the default package):
event StockPrice { string stockSymbol; float stockValue; }

If the above events were saved in an .evt file, engine_send would send each event in turn, as soon as the previous event finished transmission. This behavior can optionally be modified in two ways: specifying that events should be sent in a batch and specifying timing data forcing events to be sent at specific time intervals.

10-1

Operations Guide

10.2 Event batching

For some high-volume applications it may be desirable to group events in event batches. To specify a batch, insert the keyword BATCH before the events to be sent in the batch. For example, the sequence:
BATCH StockPrice("XRX", 11.1) StockPrice("IBM", 130.6) StockPrice("MSFT", 70.5)

represents a batch of three events to be sent to the Event Correlator at the same time. A single call to the Event Correlator is made to send the events, instead of the three separate calls in the previous example. If no BATCH tag is encountered then each event is sent individually (i.e. in a batch of one). When the first BATCH tag is encountered it is assumed that subsequent events are part of the same batch until another BATCH tag occurs. (Note that the maximum size of a batch varies across platforms; as a rule of thumb, no more than 200 events should be specified in each batch)

10.3 Event timing

In addition to batching events, it is possible to specify the time intervals at which each batch should be sent to the Correlator. This is achieved by adding a time offset, in milliseconds, after the BATCH tag. For example, the following:
BATCH 50 StockPrice("XRX", 11.1) StockPrice("IBM", 130.6) StockPrice("MSFT", 70.5) BATCH 100 StockPrice("XRX", 11.0) StockPrice("IBM", 130.8) StockPrice("MSFT", 70.1)

specifies two batches of events to be sent 50 milliseconds apart. The addition of a time allows simulations of bursts of events, or more random distributions of event traffic. Times are measured as an offset of from when the current file was opened. If only one file of events is being read and transferred, then this would be the same as since the start of a run (i.e. from the time that the engine_send tool starts processing the event data). If multiple files are being read in, the timing starts all over again upon the (re)opening of each file. If the time given for a batch is less than the current time, or if no time is given following a
BATCH tag (or if no BATCH tag is provided) then the events are sent as soon as they are

read in, immediately following the preceding batch.

10.4 Event data types

The following example illustrates how each data type is specified in an event representation. Given the event type definitions:
event Nested { integer i; }

10-2

Event file format

event EveryType { boolean b; integer i; float f; string s; location l; sequence<integer> si; dictionary<integer, string> dis; Nested n; }

the following is a valid event representation for an EveryType event:

EveryType ( true, -10, 1.73, "foo", (1.0,1.0,5.0,5.0), [1,2,3], {1:"a",2:"b"}, Nested(1) ) # # # # # # # # boolean is true/false (lower-case) positive or negative integer float strings are (double) quoted locations are 4-tuples of float values sequences are enclosed in brackets [] dictionaries are enclosed in braces {} nested events include event type name

Note that this example is split over several lines for clarity; in practice this definition would all be written on the same line. Types can of course be nested to create more complex structures. For example, the following is a valid event field definition:
sequence<dictionary<integer, Nested> >

and the following is a valid representation of a value for this field:

[{1:Nested(1)}, {2:Nested(2)}, {3:Nested(3)}]

10-3