This feature supports the running of remote execution tasks using the Symphony infrastructure. An execution task is a child process executed by a Symphony service instance using a command line specified by a Symphony client.
The Symphony execution task feature provides the ability to deploy existing executables in a grid environment, thereby realizing the benefits of Symphony without necessarily redeveloping your application code. If you have existing executables but are developing new clients, the Symphony SDK API can be used to start and control the remote execution of executable files. Each application consists of an execution service and an executable file that are distributed among compute hosts.
The execution service is common to all execution applications and is primarily responsible for starting the remote execution tasks and returning results to the client. When you install Symphony or Symphony DE, the execution application is pre-deployed but disabled.
Here are the characteristics of a Symphony execution application:
only exit codes from the execution tasks are returned to the client. Note that the execution service, which manages the execution tasks, can still return exceptions
the execution task is started and stopped by the service process for every task, which has more overhead than the method invocation of the ordinary Symphony task within the service process.
There are three ways to run, control, and monitor execution tasks from the client host:
Each interface offers a different level of functionality. For example, with the client SDK you can spawn a second thread to issue a non-blocking fetchTaskStatus() call while the client performs other functions. Or you can use the CLI for scripting execution task commands. For more information, refer to the Interfaces section of this chapter.
For the execution application to work, the executable files must reside on the same compute host as the execution service or at least be accessible from the compute host through a file sharing system or remote shell. Symphony’s service deployment tools can be used to package the executable files and dependencies, and distribute them to the compute hosts.
To help you decide whether the execution application is right for your needs, here is the criteria you should use:
To help grasp the concepts, let’s look at the functional flow of an execution application.
The client application creates a Symphony execution session and passes the following optional session-level data to the execution service:
The execution service ensures that if the pre-execution command completes successfully, the post-execution command will always be executed, even if errors occur in the user’s command during the session.
The client application sends the execution tasks to the execution service., which includes:
Upon receiving the input message on the service side, the execution service spawns a new process based on the execution task data.
While the execution task process is running, the execution service periodically checks for interruptions and suspends or aborts the running process if it detects an administrative action such as session suspend or abort was issued by the CLI or PMC.
When the execution task has completed its process, the exit code of the process is sent back to the client in the execution task status. The error handling associated with this exit code is configurable in the application profile.
The execution service implements the process execution logic as a Symphony service and interacts directly with the service instance manager (SIM).
To allow the execution task to use some unique identities, the service side execution environment is supplemented with the following additional environment variables:
The execution service logs session and command start-up and shutdown audit information in a log file. The path for log files is configurable in the application profile. By default, the log is set to the INFO level, which includes the following data:
This section describes the three interfaces that are available for sending execution tasks.
The Symphony execution task feature extends the existing Symphony API classes for C++ and Java languages:
ExecutionSession: a class to enable the client to manage its execution workload
ExecutionEnumItems: container class for ExecutionStatus objects
ExecutionStatus: container class for the status of an execution task result
ExecutionSessionContext: container class for environment variables, session type, and pre-/post- commands for session-level context
ExecutionCommandContext: container class for environment variables and pre-/post- commands for task-level context
create - creates an execution session in which to run an execution task. The session stays open until it is explicitly closed (detachable session)
send - sends an execution task command in the execution session
fetch - fetches the statuses of finished execution tasks in the execution session
run - creates an un-detachable execution session, runs an execution task, waits and then retrieves the result, and closes the execution session.
For more details such as command syntax and options, refer to the Command Reference.
The management console implements a GUI panel that allows a single execution task to be sent per session. The interface also supports the entry of associated pre- and post- commands, as well as environment variables and their values. Basically, the functionality offered by this panel is identical to the run subcommand of the symexec CLI where "Guest" is the username and password. If you need to send multiple concurrent execution tasks, additional GUI dialogs must be opened.
The management console can retrieve log files that are created by the execution service for each execution session.
For more details, refer to the online help provided with the management console.
Every application requires an application profile to dynamically configure the application’s behavior within Symphony. An application profile for the default symexec application is already registered (but disabled) when Symphony is installed. There is also a second application profile, specific to execution applications, included in the Symexec sample that is packaged with Symphony.
The execution service is common to all execution applications. In cases where different consumers are running execution applications, the name of the application specified in the application profile must be unique. Also, each application profile name must be unique in the cluster and associated with only one consumer. At any time, there can be only one enabled application per consumer.
For the execution application to work properly, the following key parameters must be configured in the application profile:
Set this flag to true since the execution application must be recoverable to support suspend/resume operations.
suspendGracePeriod and taskCleanupPeriod
Set both parameters so that the value is greater than the time it takes to complete the post-execution command that is executed by the service’s onSessionLeave() method. This time period allows for post-execution cleanup.
In the application profile, the SessionEnter and SessionLeave Method elements correspond to the service methods onSessionEnter() and onSessionLeave(). It is within these methods that the session-level pre- and post- execution commands are executed. Similarly, the Invoke Method element corresponds to the onInvoke() service method where task-level pre- and post- execution commands, and the execution task’s command itself are executed. For the default execution application, its application profile is configured so that if the command's exit code has a value of zero, it will be treated as successful completion and any other value will be treated as a failure of the corresponding execution task.
When an execution task’s command or session-level pre- and post- command is able to start and finish, the execution service stores the command’s exit code as a Symphony service context’s control code and then adds 1 to the control code. Therefore you may configure the control code for the Return event in the application profile with a value of 1 greater than the exit code you are expecting from the given command. For example, the default execution application is configured that when the command executes successfully with an exit code of 0, it sets the control code for this result to 1 (exit code +1) so that Symphony processes the result as a successful action.
The default value for all unspecified control codes is 0. It means that if you have specified control code equal to 1 to indicate successful action, all failures or system errors that do not have a corresponding control code in the application profile will be automatically associated with control code 0.
If the command cannot be started by the operating system, the execution service sets the control code to the system error number returned by the operating system. You can configure the Failure events in the application profile with control codes to handle specific exceptions. In this case, if the matching control code is configured as a failure, the exception message with the error code will be propagated back to the client. If an exception occurs with a control code that is not configured, it will automatically be associated with the action for control code 0.
If your execution application has more than one possible exit code to indicate successful completion, you must configure these multiple control codes in the application profile associated with the successful action.
If you are using multiple application profiles for multiple execution applications, you can configure the logDirectory parameter in each profile so that each application stores logs in a unique location. Another way of organizing log files per application is to use different service names and update the respective application profile with the new service name. All application profiles use the service name in the sub directory path (subDirectoryPattern) for logging and this path is fixed on the service side for compute hosts. Changing the service name for each application profile is another way to ensure a unique location for each application’s log files.