Apama 10.15.0 | Deploying and Managing Apama Applications | Correlator Utilities Reference | Shutting down and managing components
 
Shutting down and managing components
 
Viewing garbage collection and application events information
Using the EPL memory profiler
Using the CPU profiler
Setting EPL log files and log levels dynamically
Rotating correlator log files
Rotating all correlator log files
Rotating specified log files
All Apama components (correlator, IAF, dashboard data server, and dashboard display server) implement an interface with which they can be asked to shut themselves down, provide their process identifier, and respond to communication checks.
For historical reasons, there are several tools that all do the same thing. You can use any of these tools to manage any component:
*engine_management
*component_management
*iaf_management
When managing a correlator, the recommendation is to use the engine_management tool, which provides some additional correlator-specific options that are not available in the other tools. The only other differences in behavior among these tools are:
*engine_management and component_management default to the local correlator port (15903).
*iaf_management defaults to the default IAF port (16903).
The executable for the engine_management 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.
Note: 
Some of the functions of the engine_management tool can be performed from within EPL. For more information, see Using the Management interface.
Synopsis
To use the correlator's management tool, run the following command:
engine_management [ options ]
When you run this command with the –h option, the usage message for this command is shown.
Description
Use the engine_management tool to connect to a running component. Once connected, the tool can shut down the component or return information about the component. The engine_management tool can connect to any of the following types of components:
*Correlator
*Adapter
*Dashboard data server and dashboard display server (using the management port, and not the data port)
If you want to use the dedicated dashboard_management tool, see Managing and stopping the data server and display server.
The engine_management tool sends output to stdout.
Options
The engine_management tool takes the following options. These options are also available for the component_management and iaf_management tools. Keep in mind that all of these tools use different ports (see above). To obtain all information for a particular component, specify the -a option. All options are optional.
Option
Description
-V | --version
Displays version information for the engine_management tool.
-h | --help
Display usage information.
-v | --verbose
Displays information in a more verbose manner. For example, when you specify the -v option, the engine_management tool displays status messages that indicate that it is trying to connect to the component, has connected to the component, is disconnecting, is disconnected, and so on. If you are having trouble obtaining the information you want, specify the -v option to help determine where the problem is.
-n host | --hostname host
Name of the host on which the component is running. The default is localhost. Non-ASCII characters are not allowed in host names.
-p port | --port port
Port on which the component you want to connect to is listening. The default is 15903.
-w | --wait
Instructs the engine_management tool to wait for the component to start and be in a state that is ready to receive EPL files. This option is similar to the -W option, except that this option (the -w option) instructs the tool to wait forever. The -W option lets you specify how many seconds to wait. See the information for the -W option for an example.
-W num | --waitFor num
Instructs the engine_management tool to wait num seconds for the component to start and be in a state that is ready to receive EPL files. If the component is not ready to receive EPL files before the specified number of seconds has elapsed, the engine_management tool terminates with an exit code of 1.
This option is most useful in scripts, when the component you want to operate on has not yet started. For example, suppose a script specifies the following commands:
correlator.exe options
engine_inject some_EPL_files
It can sometimes take a few seconds for a component to start, and this number of seconds is not always exactly predictable. If the engine_inject tool runs before the correlator is ready to receive EPL files, the engine_inject tool fails. To avoid this for a local correlator that is listening on the default port, insert the following command between these commands:
engine_management -W 10
This lets the engine_management tool wait for up to 10 seconds for the correlator's management interface to be available. To set an appropriate wait time for your application, monitor your application's performance and adjust as needed.
-N | --getname
Displays the name of the component. For example, when you start a correlator, you can give it a name with the -N option. This is the name that the engine_management tool returns. If you do not assign a name to a correlator when you start it, the default name is correlator.
-T | --gettype
Displays the type of the component that the engine_management tool connects to. The returned value is one of the following: correlator or iaf. If you see that a port is in use, you can specify this option to determine the type of component that is using that port.
-M | --getuptime
Gets the uptime of the component in milliseconds. This can be useful if you wish to track when and for how long a particular component has been running for.
-Vm | --getvmemory
Gets the virtual memory usage of the component in megabytes. This can be useful if you wish to measure the virtual memory usage of a component, for example, to identify possible memory leaks.
For the Java-based dashboard data server and display server, the virtual memory value returned is the total of the heap and non-heap used memory, as given by the java.lang.management.MemoryMXBean class.
-Pm | --getpmemory
Gets the physical memory usage of the component in megabytes. This can be useful if you wish to measure the physical memory usage of a component, for example, to identify possible memory leaks.
For the Java-based dashboard data server and display server, the physical memory value returned is the total of the heap and non-heap committed memory, as given by the java.lang.management.MemoryMXBean class.
-Y | --getphysical
Displays the physical ID of the component. This can be useful if you are looking at log information that identifies components by their physical IDs.
-L | --getlogical
Displays the logical ID of the component. This can be useful if you are looking at log information that identifies components by their logical IDs.
-O | --getloglevel
Displays the log level of the component. The returned value is one of the following: TRACE, DEBUG, INFO, WARN, ERROR, CRIT, FATAL, or OFF.
-C | --getversion
Displays the version of the component. For example, when the tool connects to a correlator, it displays the version of the correlator software that is running.
-R | --getproduct
Displays the product version of the component. For example, when the tool connects to a correlator, it displays the version of the UNIX software that is running.
-B | --getbuild
Displays the build number of the component. This information is helpful if you need technical support. It indicates the exact software contained by the component you connected to.
-F | --getplatform
Displays the build platform of the component. This information is helpful if you need technical support. It indicates the set of libraries required by the component you connected to.
-P | --getpid
Displays the process identifier of the correlator you are connecting to. This can be useful if you are looking at log information that identifies components by their process identifier.
-H | --gethostname
Displays the host name of the component. When debugging connectivity issues, this option is helpful for obtaining the host name of a component that is running behind a proxy or on a multihomed system.
-U | --getusername
Displays the user name of the component. On a multiuser machine, this is useful for determining who owns a component.
-D | --getdirectory
Displays the working (current) directory of the component. This can be helpful if a plug-in writes a file in a component's working directory.
-E | --getport
Displays the port of the component.
-c | --getconnections
This option is for use by technical support. It displays all the connections to the component.
-a | --getall
Displays all information for the component.
-xs id:id  reason | --disconnectsender id:id  reason
Disconnects the sender that has the physical ID you specify. If you specify a reason, the engine_management tool sends the reason to the correlator. The correlator then logs the message, sends the reason to the sender, and disconnects the sender. You can specify the component ID as physical_ID/logical_ID.
-xr id:id  reason | --disconnectreceiver id:id  reason
Disconnects the receiver that has the physical ID you specify. If you specify a reason, the engine_management tool sends the reason to the correlator. The correlator then logs the message, sends the reason to the receiver, and disconnects the receiver. You can specify the component ID as physical_ID/logical_ID.
-I category | --getinfo category
This option is for use by technical support. It displays component-specific information for the specified category.
-d | --deepping
Ping the component. This confirms that the component process is running and acknowledging communications.
-l level | --setloglevel level
Sets the amount of information that the component logs in the component-specific log file. In order of decreasing verbosity, you can specify TRACE, DEBUG, INFO, WARN, ERROR, FATAL, CRIT, or OFF.
Note: 
Setting the log level of the main correlator log file to anything other than INFO is discouraged. See the description of the -v (or --loglevel) option in Starting the correlator for more details.
If --setloglevel and --setApplicationLogFile both use the same log file, then the log file defined with --setApplicationLogFile is not changed.
-r type  arg* | --dorequest type  arg*
This option sends a component-specific request. For example: engine_management -r cpuProfile frequency. This returns the profiling frequency in Hertz.
The following request types are available and apply to the correlator only:
*applicationEventLogging — Sends detailed application information to the correlator log file. See Viewing garbage collection and application events information.
*codeCoverage — Lets you check which lines in an EPL file have been executed. See Recording code coverage information.
*cpuProfile — Lets you profile Apama EPL applications. See Using the CPU profiler.
*eplMemoryProfileOverview — Returns information on all the monitors in the correlator. See Using the EPL memory profiler.
*eplMemoryProfileMonitorInstanceDetail — Returns monitor instance details. See Using the EPL memory profiler.
*eplMemoryProfileMonitorDetail — Returns aggregated monitor instance details. See Using the EPL memory profiler.
*flushAllQueues — Sends a request into the correlator that waits until every event/injection sent or enqueued to a context before the flushAllQueues request started has been processed, and every event emitted as a result of those events has been acknowledged. This may block if a slow receiver is connected to the correlator. Events enqueued to a context after the request has started may or may not be processed. Thus, if you want to see the results of one context enqueueing to a second, which enqueues to a third, you should execute engine_management -r flushAllQueues three times, to ensure it has been processed by each context. This does not change the behavior of the correlator (the correlator will always flush all queues as soon as it is able to), it just waits for events currently on input queues to complete. In addition, flushAllQueues also waits for any queued MemoryStore operations to complete, such as the preparation of a new store.
*flushChannelCache — Notifies all dynamicChainManagers again (for example, Digital Event Services and Universal Messaging) about all channels which contexts are subscribed to or have sent to. This allows the manager to change its decision about whether it needs to subscribe to the channel (for example, when a channel has been created on Universal Messaging after the correlator was started). See also Requirements of a transport chain manager plug-in class.
*setOOB — Enables out of band notifications for a correlator. See Out of band connection notifications.
*startInternalClock — Starts the internal clocking of a correlator which was started with the -Xclock option (see Determining whether to disable the correlator's internal clock for more information on the -Xclock option). startInternalClock first advances the time of all contexts to the current wall-clock time and then continues sending clock ticks at the configured frequency. It will do nothing if the internal clock is already running.
*toStringQueues — Outputs the current contents of all input and output queues within the running correlator. This can be helpful for identifying slow senders/receivers and potential causes (such as very large events or excessive flow).
*verbosegc — Enables logging of garbage collection events. See Viewing garbage collection and application events information.
The following request type applies to the IAF only:
*getEventTypes — Returns a string representation of the event types known to the running IAF.
Certain other requests for the -r option are available for use by Apama technical support.
See Management requests for additional options.
-s why | --shutdown why
Instructs the component to shut down and specifies a message that indicates the reason for termination. The component inserts the string you specify in its log file with a CRIT flag, and then shuts down.
Management requests
The options in the tables below replicate -r (or --dorequest) request types of the same name.
The following options are specific to the correlator:
Option
Description
--rotateLogs
Rotates all the log files. See Rotating all correlator log files.
--setApplicationLogFile [node=]path
Sets the log file for EPL log messages (global or per-package).
For more information on how to set, get and unset the log file, see Setting EPL log files and log levels dynamically.
--setApplicationLogLevel [node=]level
Sets the log level for EPL log messages (global or per-package). For more information on how to set, get and unset the log level, see Setting EPL log files and log levels dynamically.
--getApplicationLogFile node
Displays the EPL log file for this node.
--getApplicationLogLevel node
Displays the EPL log level for this node.
--getRootApplicationLogFile
Displays the root EPL log file.
--getRootApplicationLogLevel
Displays the root EPL log level.
--unsetApplicationLogFile node
Unsets the EPL log file for this node.
--unsetApplicationLogLevel node
Unsets the EPL log level for this node.
--unsetRootApplicationLogFile
Unsets the root EPL log file.
--unsetRootApplicationLogLevel
Unsets the root EPL log level.
The following option is specific to the correlator and the IAF:
Option
Description
--setLogFile path
Instructs the component to close the component-specific log file it is using and to open a new log file with the name you specify. This has no effect on EPL logging which uses a separate log file. See Rotating specified log files and IAF log file rotation.
The following option is specific to the IAF:
Option
Description
--reopenLog
Reopens the log file of the component. See IAF log file rotation.
Exit values
The engine_management tool returns the following exit values:
Value
Description
0
All status requests were processed successfully.
1
Indicates one of the following:
*No connection to the specified component was possible.
*The connection failed.
*You specified the waitFor option and the specified time elapsed without the component starting.
2
One or more errors occurred while requesting/processing status.
3
Deep ping failed.