Apama 10.3.1 | Apama Documentation | Deploying and Managing Apama Applications | Correlator Utilities Reference | Starting the correlator
 
Starting the correlator
 
Specifying log filenames
Examples for specifying log filenames
Descriptions of correlator status log fields
Text internationalization in the logs
Determining whether to disconnect slow receivers
Determining whether to disable the correlator's internal clock
Injection time of compiled runtime
The correlator tool starts the correlator. The executable for this tool is located in the bin directory of the Apama installation. Running the tool in the Apama Command Prompt or using the apama_env wrapper (see Setting up the environment using the Apama Command Prompt) ensures that the environment variables are set correctly.
Synopsis
To start the correlator, run the following command:
correlator [ options ]
When you run this command with the –h option, the usage message for this command is shown.
Description
By default, the correlator tool starts a correlator process on the current host, and configures it to listen on port 15903 for monitoring and management requests.
On start-up, the executable displays the current version number and configuration settings.
To terminate a correlator process, press Ctrl+C in the window in which it was started. Alternatively, you can issue the engine_management command with the --shutdown option. See Shutting down and managing components. Regardless of which technique you use to terminate the correlator, Apama first tries to shut down the correlator cleanly. If this is not possible, for example, perhaps because of a monitor in an infinite loop, Apama forces the correlator to shut down.
Note: If a license file cannot be found, the correlator will run with reduced capabilities. See Running Apama without a license file.
Options
The correlator tool takes the options listed below.
Note: Many of these options can also be specified as elements of a YAML configuration file (with different element names). If an option is specified in both the command line and a YAML configuration file, then the command line takes precedence. For further information, see Configuring the correlator and especially the topic YAML configuration file for the correlator which lists the available elements.
Option
Description
-V | --version
Displays version information for the correlator.
-h | --help
Displays usage information.
-p port | --port port
Specifies the port on which the correlator should listen for monitoring and management requests. The default is 15903.
Alternatively, you can specify the port in a YAML configuration file. See Specifying the correlator port number for details.
-f file | --logfile file
Specifies the path of the main log file that the correlator writes messages to. The default is stdout. See also Specifying log filenames, Descriptions of correlator status log fields and Text internationalization in the logs.
-v level | --loglevel level
or
-v category=level | --loglevel category=level 
Specifies the level of information that the correlator sends to the main correlator log file. Specify one of the following:
*A log level which is to apply to all messages written to the log file.
*A category with the log level for that category. This option can be provided multiple times.
You can also specify the log level in a YAML configuration file. See Setting correlator and plug-in log levels in a YAML configuration file for details. This topic also lists the category names that can be specified.
A log level can be one of the following (in increasing order of verbosity): ERROR, WARN, INFO, DEBUG, TRACE. The default is INFO.
The use of DEBUG and TRACE is not recommended in a production environment as the amount of logging information will impact performance.
The use of ERROR and WARN is not recommended. These log levels may make it impossible to provide support due to the lack of information in the log file. If one of these log levels is used, a warning is printed at the top of the correlator log file.
Note: If OFF, CRIT or FATAL is specified, the log level is reset to ERROR and a warning message is printed at the top of the correlator log file.
-t | --truncate
Specifies that if the main correlator log file already exists, the correlator should empty it first. The default is to append to it.
-N name | --name name
Assigns a name to the correlator. The default is correlator. If you are running a lot of correlators you might find it useful to assign a name to each correlator. A name can make it easier to use the engine_management tool to manage correlators and adapters.
-l file | --license file
Specifies the path to the license file.
-m num | --maxoutstandingack num
Specifies that you want the correlator to buffer messages for up to num seconds for each receiver that the correlator sends events to. The default is 10. For additional information, see Determining whether to disconnect slow receivers.
-M num | --maxoutstandingkb num
Specifies that you want the correlator to buffer the events for each receiver up to the size in kb represented by num.
-x | --qdisconnect
Specifies that you want the correlator to disconnect receivers that are consuming events too slowly. For details, see Determining whether to disconnect slow receivers. The default is that the correlator does not disconnect slow receivers.
--logQueueSizePeriod p
Sets the interval at which the correlator sends information to its log file. The default is 5 seconds. Replace p with a float value for the period you want.
Caution: Setting logQueueSizePeriod to 0 turns logging off. Without correlator logging information, it is impossible to effectively troubleshoot problems. See also Descriptions of correlator status log fields.
--distMemStoreConfig dir
Specifies that the distributed MemoryStore is enabled, using the configuration files in the specified directory. Note that the configuration filenames must end with "*-spring.xml" and the correlator will not start unless the specified directory contains at least one configuration file. For more information on a distributed MemoryStore's configuration files, see Using the distributed MemoryStore.
--jmsConfig dir
Specifies that correlator-integrated messaging is enabled using the configuration files in the specified directory. Note that the configuration filenames must end with "*-spring.xml" and the correlator will not start unless the specified directory contains at least one configuration file. For more information on the configuration files for correlator-integrated messaging for JMS, see Configuration files for JMS.
-j | --java
Enables support for Java applications, which is needed to inject a Java application or plug-in using engine_inject –j.
-J option | --javaopt option
Specifies an option or property that you want the correlator to pass to the embedded JVM. You must specify the -J option for each JVM option. You can specify the -J or --javaopt option multiple times in the same correlator command line. For example:
-J "-Da=value1" -J "-Db=value2" -J "-Xmx400m"
You can use -J as a prefix. In this case, you have to specify it without a space: -Joption. For example:
-J-Dproperty=value
You can also specify JVM options in a YAML configuration file. If the same JVM option is specified in both the command line and the configuration file, the command line takes precedence. See also Specifying JVM options.
Note: It is not possible to configure the correlator's system classpath using the CLASSPATH environment variable. We recommend that you set the classpath on a per-plug-in basis, for example, in the descriptor file for an EPL or JMon plug-in (see Specifying the classpath in deployment descriptor files) or in the configuration file for a connectivity plug-in, JMS or distributed MemoryStore library. For cases where you really need to set the global system classpath, you can use -J-Djava.class.path=path. When you use this option to pass the classpath to the JVM, Apama prepends the correlator-internal JAR files to the path you specify.
--inputLog file
Specifies the path of the input log file. The correlator writes only input messages to the input log file. If there is a problem with your application, Software AG Global Support can use the input log to try to diagnose the problem. An input log contains only the external inputs to the correlator. There is no information about multi-context ordering. Consequently, if there is more than one context, there is no guarantee that you can replay execution in the same order as the original execution. See Replaying an input log to diagnose problems.
-XsetRandomSeed int
Starts the correlator with the random seed value you specify. Specify an integer whose value is in the range of 1 to 232. The correlator uses the random seed to calculate the random numbers returned by the integer.rand() and float.rand() functions. The same random seed returns the same sequence of random numbers. This option is useful when your application uses the integer.rand() and float.rand() functions and you are using an input log to capture events and messages coming into a correlator. If you need to reproduce correlator behavior from that input log, you will want the correlator to generate the same random numbers as it generated when the original input was captured.
-XignoreEnqueue
For internal use only. Instructs the correlator to ignore enqueue statements when replaying an input log.
--inputQueueSize int
Sets the maximum number of spaces in every context's input queue. The default is that each input queue has 20,000 spaces. If events are arriving on an input queue faster than the correlator can process them the input queue can fill up. You can set the inputQueueSize option to allow all input queues to accept more events. Typically, the default input queue size is enough so if you find that you need to increase the size of the input queue you should try to understand why the correlator cannot process the events fast enough to leave room on the default-sized queue. If you notice that adapters or applications are blocking it might be because a public context's input queue is full. To determine if a public context's input queue is full, use output from the engine_inspect tool in conjunction with the status messages in the main correlator log file.
-g | --nooptimize
Disables correlator optimizations that hinder debugging. Specify this option when you plan to run the engine_debug tool. You cannot run the engine_debug tool if you did not specify the -g option when you started the correlator.
Software AG Designer automatically uses the -g option when it starts a correlator from a debug launch configuration. However, if you are connecting to an externally-started correlator, and you want to debug in that correlator, you must ensure that the -g option was specified when the externally-started correlator was started.
-P | -Penabled=boolean
-P or -Penabled=true enables correlator persistence. You must specify this option to enable correlator persistence. If you do not specify any other correlator persistence options, the correlator uses the default persistence behavior as described in Enabling correlator persistence. If you specify one or more additional correlator persistence options, the correlator uses the settings you specify for those options and uses the defaults for the other persistence options.
You can also enable and configure correlator persistence using a YAML configuration file. See Configuring persistence in a YAML configuration file for details.
-Penabled=false disables correlator persistence, overriding any value that was specified in a YAML configuration file.
-PsnapshotIntervalMillis=interval
Specifies the period between persistence snapshots. The default is 200 milliseconds.
-PadjustSnapshot=boolean
Indicates whether or not the correlator should automatically adjust the snapshot interval according to application behavior. The default is true, which means that the correlator does automatically adjust the snapshot interval. You might want to set this to false to diagnose a problem or test a new feature.
-PstoreLocation=path
Specifies the path for the directory in which the correlator stores persistent state. The default is the current directory, which is the directory in which the correlator was started.
-PstoreName=file
Specifies the name of the file that contains the persistent state. This is the recovery datastore. The default is persistence.db.
-Pclear
Specifies that you want to clear the contents of the recovery datastore. This option applies to the recovery datastore you specify for the -PstoreName option or to the default persistence.db file if you do not specify the -PstoreName option. When the correlator starts it does not recover from the specified recovery datastore.
-XrecoveryTime num
For correlators that use an external clock, this is a time expression that represents the time of day that a correlator starts at when it recovers persistent state and restarts processing. The default is the time expression that represents the time of day captured in the last committed snapshot. This option is useful only for replaying input logs that contain recovery information. To change the default, specify a number that indicates seconds since the epoch.
-noDatabaseInReplayLog
Specifies that the correlator should not copy the recovery datastore to the input log when it restarts a persistence-enabled correlator. The default is that the correlator does copy the recovery datastore to the input log upon restarting a persistence-enabled correlator. You might set this option if you are using an input log as a record of what the correlator received. The recovery datastore is a large overhead that you probably do not need. Or, if you maintain an independent copy of the recovery datastore, you probably do not want a copy of it in the input log.
--pidfile file
Specifies the name of the file that contains the process identifier. This file is created at process startup and can be used, for example, to externally monitor or terminate the process. The correlator will remove that file after a clean shutdown.
It is recommended that the file name includes the logical name of the correlator and/or port number to distinguish different correlators (for example, my-correlator-15903.pid).
Caution: If the correlator process is terminated uncleanly or if the operating system is restarted, the pidfile usually remains on disk. However, the process identifier it contains is no longer valid or may match some other newly started process.
To prevent mistakenly sending signals to the wrong process, ensure that the pidfile is explicitly deleted after a restart of the operating system or after an unclean termination of the correlator. Alternatively, you can configure the pidfile to be written to a transient location such as /run that is automatically deleted when the operating system is started.
The correlator takes an exclusive lock on the pidfile while it is running. This means that if you have another correlator running using the same pidfile, the second correlator will fail to start up. You should not run multiple correlators from the same configuration using the same pidfile. In other cases, existing pidfiles will be overwritten, even if they contain a process identifier of a running process.
--runtime mode
On Linux 64-bit systems, you can specify whether you want the correlator to use the compiled runtime or the interpreted runtime, which is the default. Specify --runtime compiled or --runtime interpreted.
The interpreted runtime compiles EPL into bytecode whereas the compiled runtime compiles EPL into native code that is directly executed by the CPU. For many applications, the compiled runtime provides significantly faster performance than the interpreted runtime. Applications that perform dense numerical calculations are most likely to have the greatest performance improvement when the correlator uses the compiled runtime. Applications that spend most of their time managing listeners and searching for matches among listeners typically show a smaller performance improvement.
Using the compiled runtime requires that the binutils package is installed on the Linux system.
Other than performance, the behavior of the two runtimes is the same except for the following:
*The interpreted runtime allows for the profiler and debugger to be switched on during the execution of EPL. The compiled runtime does not permit this. For example, you cannot switch on the profiler or debugger in the middle of a loop.
*The amount of stack space available is different for the two runtimes. This means that recursive functions run out of stack space at a different level of recursion on the two runtimes.
Note: If you are using both correlator persistence and the compiled runtime (--runtime compiled option), we recommend the use of the --runtime-cache option to improve recovery times.
--runtime-cache dir
Enables caching of compiled runtime objects in the specified directory. Subsequent injections of the same files to any correlator using that cache will be quicker. For more information, see Injection time of compiled runtime.
--frequency num
Instructs the correlator to generate clock ticks at a frequency of num per second. Defaults to 10, which means there is a clock tick every 0.1 seconds. Be aware that there is no value in increasing num above the rate at which your operating system can generate its own clock ticks internally. On UNIX and some Windows machines this is 100 and on other Windows machines it is 64.
-Xclock | --externalClock
Instructs the correlator to disable its internal clock. By default, the correlator uses internally generated clock ticks to assign a timestamp to each incoming event. When you specify the -Xclock option, you must send time events (&TIME) to the correlator. These time events set the correlator's clock. For additional information, see Determining whether to disable the correlator's internal clock.
--config file
Used to configure the correlator. Specifies one of the following:
*The name of a .properties file. See also Using properties files.
*The name of a .yaml file. See also Using YAML configuration files.
*The name of a directory containing .yaml files and .properties files. In this case, the files are processed in alphabetical order.
*A semicolon-delimited list of .properties files, .yaml files and directories.
This option can be specified multiple times. The options are processed in the same sequence in which they are specified on the command line.
If multiple .yaml files are specified, they are merged together based on the contents of the top-level maps they each contain. For example, if two files have a top-level map called connectivityPlugins, the merged document has a single connectivityPlugins map with all keys and values. Both maps, however, must not contain the same keys, otherwise an error will occur.
For more information, see Configuring the correlator.
-Dkey=value
Specifies a value for a substitution property to be used by the Apama configuration files. The -D arguments always take precedence over any arguments defined in a .properties file. Therefore, they are processed before any --config arguments, regardless of the order on the command line.
Using this option is similar to specifying the substitution using a .properties file for YAML (see also Using properties files).
Correlator-integrated messaging for JMS and the distributed MemoryStore have their own properties files, which are Spring files. Keep in mind that any properties that are specified with the --config file or -Dkey=value option take precedence and override the properties defined in a Spring properties file. See also Configuration files for JMS and Configuration files for distributed stores.
-D properties are not related to Java system properties. If your intention is to set a Java system property, use -J-Dkey=value (and not -Dkey=value).
--applicationLogLevel level
Specifies the level of information that the correlator sends to the EPL log file. The log level must be one of the following (in increasing order of verbosity): OFF, CRIT, FATAL, ERROR, WARN, INFO, DEBUG, TRACE. The default is the current setting of the -v (or --loglevel) option.
You can also specify the log level in a YAML configuration file. See Setting EPL log files and log levels in a YAML configuration file for details.
--applicationLogFile file
Specifies the path of the EPL log file that the correlator writes messages to. The default is the current setting of the -f (or --logfile) option.
You can also specify the EPL log file in a YAML configuration file. See Setting EPL log files and log levels in a YAML configuration file for details.
--python=boolean
--python or --python=true enables Python support. By default, Python support is not enabled.
You can also enable Python support using a YAML configuration file. For more information, see Using Python plug-ins.
--python=false disables Python support, overriding any value that was specified in a YAML configuration file.
Exit status
The correlator tool returns the following exit values:
Value
Description
0
The correlator terminated successfully.
1
An error occurred which caused the correlator to terminate abnormally.

Copyright © 2013-2019 | Software AG, Darmstadt, Germany and/or Software AG USA, Inc., Reston, VA, USA, and/or its subsidiaries and/or its affiliates and/or their licensors.