The Service element defines a group of configuration settings for service attributes. Multiple service elements can be defined in this section with different configuration settings for each service. Defining multiple services allows you to use more than one service within a single application. You can add or update (or remove) a service to an existing application dynamically using PMC.
Name of the service to run for this application. The service name must be unique within the application.
Identifies a service as the default service, which means that the default service is immediately started when the service instance manager starts.
True if only one service is defined in the application profile. If only one service is defined, that service is identified as the default and is started when the service instance manager starts.
When multiple services are defined, at least one of the services default value should be set to true. Other services' default value are optional.
Applies only when multiple services are used in a single application. Defines the maximum number of other service instances that a single service instance manager can run concurrently, in addition to the current service.
When this parameter is set to 0, no other service instances started by the service instance manager can run at the same time when this service instance manager starts this service. As a result, any other running service instances managed by this service instance manager are stopped when this service is started.
When this parameter is set to a number larger than 0, the service instance manager can keep maxOtherInstances service instances running along with this service concurrently. Setting a value larger than 0 saves service instance loading time, because service instances are not shut down and restarted.
When a service instance manager needs to shut down a service to satisfy maxOtherInstances, it first tries to gracefully shut down the service instance. If the service instance does not exit when the DestroyService timeout (Service > Control > Method > Timeout, duration attribute) expires, the process is killed.
A service instance manager only manages multiple services that have the same serviceToSlotRatio. As soon as a service instance manager needs to manage a service with a different serviceToSlotRatio, it will terminate all of the service instances it is managing and start a new service instance with the new ratio. The other service instances will not be restarted with the new serviceToSlotRatio unless they are required to run workload.
For example, if you have three services with different values for maxOtherInstances:
When the service instance manager starts, it starts service S1 by default. The service instance manager has one child process (S1). When service S2 is started, the service instance manager has 2 child processes (S1 and S2). If service S3 is started, the service instance manager has only one child process, which is S3 (S1 and S2 are shutdown by the service instance manager).
When service S1 is started again, the service instance manager has only one child process, which is S1 (S3 is shutdown by the service instance manager because it’s maxOtherInstances is 0).
Maximum time, in seconds, to allow a service instance to cleanup if an application is disabled or unregistered, or a middleware component becomes unavailable.
Configuration related to the operating system in which services run.
Operating system environment in which to run the service. Symphony uses this information to determine where the executable for the service is located and set up the environment variables for the service instance.
all—This configuration is applied if the osType for the allocated resource is not configured in the application profile.
LINUX86—A 32-bit Linux-based environment, such as RedHat Linux
NTX86—A 32-bit Windows-based environment, such as Windows 2000, Windows NT, and Windows XP
User-defined operating-system types, defined in the ego.shared file
Used for log retrieval through the Platform Management Console. Path to the directory in which logs are written by services for this application. The path can be any desired path and must be the same on all compute hosts.
Used for log retrieval through the Platform Management Console. File naming convention for service log files written to the logDirectory. Specify how your files are named. When retrieving logs for a specific task, the system looks for log files that partially match the file name pattern. If you are going to name files with the task ID or session ID, specify the variables %taskId% or %sessionId%.
Configure logDirectory, fileNamePattern, and subDirectoryPattern for each operating system type defined in your service section.
Used for log retrieval through the Platform Management Console. Convention for naming subdirectories in the logDirectory. If you want to name subdirectories according to session ID or task ID use the variables %sessionId%, %taskId%. When retrieving logs, the system looks for log files in subdirectories that partially match the sub-directory pattern.
Configure logDirectory, fileNamePattern, and subDirectoryPattern for each operating system type defined in your service section.
Path to the program executable for the service. If you deploy a service package using Symphony deployment, the directory where your service package is extracted can be referred to as ${SOAM_DEPLOY_DIR}. If you need to reference a file in your service package, use the ${SOAM_DEPLOY_DIR} variable.
For example, on Windows, if in your service package you have the directory structure \myservice\myservice.exe, indicate ${SOAM_DEPLOY_DIR}\myservice\myservice.exe in startCmd.
For example, on Linux, if in your service package you have the directory structure /myservice/myservice, indicate ${SOAM_DEPLOY_DIR}/myservice/myservice. in startCmd.
When using a deployment tool other than Symphony soamdeploy, the command specified here will run on the compute host and can be used to copy the service program to that host.
Configure envirionment variables for running service instances.
Name of an environment variable to set in the runtime environment of the service. You can also define environment variables so that they get substituted in the startCmd, preExecCmd, and workDir attributes.
One env statement is required for each environment variable.
No environment variables need to be set for the service.
You can refer to defined environment variables in other environment variables. For example:
<env name="ENVAR1">${SOAM_HOME}/work</env>
<env name="ENVAR2">${ENVAR1}/${VERSION_NUM }</env>
Symphony substitutes the following environment variables with system values:
${PATH}—Specifies the path to the relevant executable. The specified path is pre-pended in front of the system Path at runtime. For Windows, specifies the path to any dependent library, including the Symphony libraries.
${LD_LIBRARY_PATH}—Linux only. Specifies the path to the library where the GCC-specific Symphony files are located. The specified path is pre-pended in front of the system LD_LIBRARY_PATH at runtime
${SOAM_HOME}—Directory where Symphony is installed. Replaced with the value of the operating system environment variable SOAM_HOME set on the host.
${VERSION_NUM}—Symphony version on which the service is running.
${EGO_MACHINE_TYPE}—Specifies the host type installation. For example, win32-vc7 specifies a Windows machine. The variable is replaced with the value of the operating system environment variable EGO_MACHINE_TYPE set on the host.
${SOAM_DEPLOY_DIR}—Internal system directory in which the service package is deployed.
${SOAM_SERVICE_EVENT_REPLAY_LOG}— Service is driven by the events logged in the SERL file that this variable references. If this environment variable is not defined, service is driven by the SIM (as through Symphony).
Defines how long to wait for the method specified in <Method name=...> element to complete, and what action to take on service instances, sessions, or tasks, upon timeout of the method.
Action to take on the service instance when a timeout occurs.
blockHost—When a timeout is reached on the method, terminate the running service instance on this host and do not use this host to start any other service instance for the application. The host on which the service instance was running is added to the blocked host list for the application. This host is no longer selected to run work for the application until it is explicitly unblocked through the EGO command line or the Platform Management Console.
restartService—When a timeout is reached on the method, terminate the service instance, start a new service instance on the same host, and recover state. There is no limit to the number of times that a service instance can be restarted.
Not all values are possible with all methods. The table below outlines possible values:
Action to take on sessions and tasks when a timeout occurs.
retry—When a timeout is reached on the method, retry the method up to the number of times configured by the session and task retry limits in the application profile.
For SessionEnter and SessionUpdate, the system attempts to bind the session to the service instance up to the sessionRetryLimit in the application profile before the session is aborted.
The retry count for both of these methods are considered together. For example, if SessionEnter fails once and SessionUpdate fails twice, then the session rerun count is equal to 3. Therefore the SessionRetryCount should be set to a value that accounts for both SessionEnter and SessionUpdate failures.
For Invoke, the system attempts to run the task up to the taskRetryLimit defined in the application profile before the task is failed.
fail—When a timeout is reached on the method, abort the session or fail the task, and propagate errors to the client application.
For SessionEnter or SessionUpdate, immediately abort the session. Do not retry the method.
For Invoke, immediately fail the task. Do not retry the method.
Not all values are possible with all methods. The table below outlines possible actions for methods:
Action to take on sessions and tasks when a timeout occurs and service debugsettion="customized".
writeServiceEventReplayFiles—When Symphony detects that the specified method has timed out, it generates service event replay files to capture the relevant events that lead up to the timeout. This is the recommended setting if method timeout is an unexpected event for your service.
none—When Symphony detects that the specified method has timed out, it does not generate service event replay files. This is the recommended setting if your service times out as a normal occurrence.
Defines what action to take on service instances, sessions, or tasks when the method specified with the <Method> element exits.
Action to take on the service instance when the method exits.
blockHost—When the method exits, terminate the running service instance on this host and do not use this host to start any other service instance for the application. The host on which the service instance was running is added to the blocked host list for the application. This host is no longer selected to run work for the application until it is explicitly unblocked through the EGO command line or the Platform Management Console.
restartService—When the method exits, terminate the service instance, start a new service instance on the same host, and recover state. There is no limit to the number of times that a service instance can be restarted.
Action to take on sessions and tasks when the method exits.
retry—If the service exits during execution of the specified method, retry the method up to the number of times configured by the session and task retry limits in the application profile.
For SessionEnter and SessionUpdate, the system attempts to bind the session to the service instance up to the sessionRetryLimit in the application profile before the session is aborted.
The retry count for both of these methods are considered together. For example, if SessionEnter fails once and SessionUpdate fails twice, then the session rerun count is equal to 3. Therefore the SessionRetryCount should be set to a value that accounts for both SessionEnter and SessionUpdate failures.
For Invoke, the system attempts to run the task up to the taskRetryLimit defined in the application profile before the task is failed.
fail—When the method exits, abort the session or fail the task, and propagate errors to the client application.
For SessionEnter or SessionUpdate, immediately abort the session. Do not retry the method.
For Invoke, immediately fail the task. Do not retry the method.
Not all values are possible with all methods. The table below outlines possible actions for methods:
Action to take on sessions and tasks when the service process exits during the execution of the specified method and service debugSetting="customized"..
writeServiceEventReplayFiles—When Symphony detects that the service process has exited (or crashed) while executing the specified method, it generates service event replay files to capture the relevant events that lead up to the exit. This is the recommended setting if the service process exiting or crashing in the specified method is an unexpected event for your service.
none—When Symphony detects that the service process has exited (or crashed) during execution of the specified method, it does not generate service event replay files. This is the recommended setting if your service exits as a normal occurrence.
Defines what action to take on service instances, sessions, or tasks when the method specified in <Method name=...> returns normally (controlCode=0), or if a control code is defined, what action to take when the method returns with the specified control code.
Action to take on the service instance when the method returns normally or with the specified control code.
blockHost—When the method returns normally or with a specified control code, terminate the running service instance on this host and do not use this host to start any other service instance for the application.
The host on which the service instance was running is added to the blocked host list for the application. This host is no longer selected to run work for the application until it is explicitly unblocked through the EGO command line or the Platform Management Console.
restartService—When the method returns normally or with a specified control code, terminate the service instance, start a new service instance on the same host, and recover state. There is no limit to the number of times that a service instance can be restarted.
keepAlive—When the method returns normally or with a specified control code, take no action on the running service instance. Return an error only.
Action to take on sessions and tasks when the method returns normally, or with a specified control code.
retry—When the method returns normally or with the specified control code, retry the method up to the number of times configured by the session and task retry limits in the application profile.
For SessionEnter and SessionUpdate, the system attempts to bind the session to the service instance up to the sessionRetryLimit in the application profile before the session is aborted.
The retry count for both of these methods are considered together. For example, if SessionEnter fails once and SessionUpdate fails twice, then the session rerun count is equal to 3. Therefore the SessionRetryCount should be set to a value that accounts for both SessionEnter and SessionUpdate failures.
For Invoke, the system attempts to run the task up to the taskRetryLimit defined in the application profile before the task is failed.
fail—When the method returns normally or with the specified control code, abort the session or fail the task, and propagate errors to the client application.
For SessionEnter or SessionUpdate, immediately abort the session. Do not retry the method.
For Invoke, immediately fail the task. Do not retry the method.
succeed—This is a normal return. This is treated as a successful execution of SessionEnter, SessionUpdate, or Invoke.
For Invoke, the taskcompletes successfully (in the Done state).
Not all values are possible with all methods. The table below outlines possible actions for methods:
Action to take on the service instance when the method returns normally or with the specified control code when service debugSetting="customized".
writeServiceEventReplayFiles—When Symphony detects that the specified method has returned normally with or without a specific control code, it generates service event replay files.
none—When Symphony detects that the specified method has returned normally with or without a specific control code, it does not generate service event replay files. This is the recommended setting, as this is typically a normal, successful event.
Defines what action to take on service instances, sessions, or tasks when the method specified in <Method name=...> encounters a fatal or failure exception.
Action to take on the service instance when a failure or fatal exception occurs.
blockHost—When the specified exception occurs, terminate the running service instance on this host and do not use this host to start any other service instance for the application.
The host on which the service instance was running is added to the blocked host list for the application. This host is no longer selected to run work for the application until it is explicitly unblocked through the EGO command line or the Platform Management Console.
restartService—When the specified exception occurs, terminate the service instance, start a new service instance on the same host, and recover state. There is no limit to the number of times that a service instance can be restarted.
keepAlive—When the specified exception occurs, take no action on the running service instance.
Action to take on sessions and tasks when a fatal or failure exception occurs.
retry—When the specified exception occurs, retry the method up to the number of times configured by the session and task retry limits in the application profile.
For SessionEnter and SessionUpdate, the system attempts to bind the session to the service instance up to the sessionRetryLimit in the application profile before the session is aborted.
The retry count for both of these methods are considered together. For example, if SessionEnter fails once and SessionUpdate fails twice, then the session rerun count is equal to 3. Therefore the SessionRetryCount should be set to a value that accounts for both SessionEnter and SessionUpdate failures.
For Invoke, the system attempts to run the task up to the taskRetryLimit defined in the application profile before the task is failed.
fail—When the specified exception occurs, abort the session or fail the task, and propagate errors to the client application.
For SessionEnter or SessionUpdate, immediately abort the session. Do not retry the method.
For Invoke, immediately fail the task. Do not retry the method.
Not all values are possible with all methods. The table below outlines possible actions for methods:
Action to take on sessions and tasks when a fatal or failure exception occurs in the specified method and debugSetting="customized".
writeServiceEventReplayFiles—When Symphony detects that the specified method has thrown a particular exception (FatalException or FailureException), as specified, it generates service event replay files to capture the relevant events that lead up to the exception.
none—When Symphony detects that the specified method has thrown a particular exception (FatalException or FailureException), as specified, it does not generate service event replay files.