Thread: Working with the Sample Application Profile

1. Introduction

As I posted in the blog, developers can take advantage of the Symphony DE sample application, by using it as a working template to base on, when building their own application.

Some questions have been raised in the forum concerning the usage of some parameters in the sample application profile. In addition to the descriptions provided in the Symphony Application Profile Reference Guide, we will take a look at the basic Sample Application profile (samples/CPP/SampleApp/SampleApp.xml), and focus on the configuration of each parameter, as it applies specifically to developing an application in Symphony DE.


2. Consumer Section

Code:

<Consumer applicationName="SampleAppCPP" consumerId="/SampleAppCPP"
          taskHighWaterMark="1.0" taskLowWaterMark="1.0"
          preStartApplication="false" numOfPreloadedServices="1"/>

applicationName

Unique name of your application.

Need to change?
Change it to the name of your own application. When changed, make sure it is matched by the appName parameter passed to SoamFactory::connect() API call in the client.

Note:
Parameters can be changed by editing the application profile directly and then re-register it, or by using the Application Profile Editor (Basic or Advanced Configuration) in the Platform Management Console.

consumerId

Consumer ID associated with the application. In full Symphony Grid, consumers are used to determine resource allocation. In Symphony DE, this does not apply. Consumers do not need to be created and managed, it can be any arbitrary name. Consumer ID is used to match service package to the application. When deploying the service package using "soamdeploy add -c", the Consumer ID provided should match the consumerId specified in the application profile. Alternatively, use "soamdeploy add -a", where the consumerId is obtained from the application profile directly. See related article Service Deployment in Symphony DE for details.


Need to change?
Note that only one application can be enabled within a consumer. Thus if you have multiple applications under development and testing, it is recommended to register them under different Consumer IDs, so they can be enabled at the same time.

taskHighWaterMark

Used to determine CPU slot request. taskHighWaterMark=N, means for every N unprocessed tasks in the system, 1 CPU slot is requested.

Need to change?
Do not need to change for normal testing. taskHighWaterMark=1 already specifies that every single unprocessed task will request a CPU slot if available. In production environment, this value might need to be adjusted, when CPU slots have to be balanced amongst applications to meet different workload demand.

taskLighWaterMark

Used to determine CPU slot release. taskLowWaterMark=N, means for every N unprocessed tasks in the system, there is at most 1 CPU slot allocated. Any additional owned slots will be released.

Need to change?
Do not need to change for normal testing. taskLowWaterMark=1 already specified that every CPU slot that is released must areadly be idle. In production environment, user might set it to 0, meaning any resource allocated will not be returned voluntarily even if there are no unprocessed tasks at the time. This will save allocation overhead when the next wave of workload arrives.

preStartApplication

Whether the session manager (SSM), service instance manager (SIM), and service instances (SI) are pre-started for enabled applications

Need to change?
Change to preStartApplication=true for better performance when sending the first task, as SSM/SIM/SI are already on standby. Keep it as false if only want SSM/SIM/SI processes to start when they are needed.

numOfPreloadedServices

When preStartApplication is set to true, determines the number of SIM/SI to start for enabled applications.

Need to change?
Increase the number if you wish to have more than 1 SIM/SI to be pre-started and ready to serve incoming Tasks.


3. SOAM Section

Code:

<SOAM version="4.0">
    <SSM resReq="" workDir="${EGO_SHARED_TOP}/soam/work">
        <boundaryManagerConfig>
            <boundaries>
                <boundary elementName="AvailableMemory">
                    <event name="BEV_PROACTIVE" value="50"/>
                    <event name="BEV_SEVERE" value="40"/>
                    <event name="BEV_CRITICAL" value="0"/>
                    <event name="BEV_HALT" value="0"/>
                </boundary>
                <boundary elementName="AvailableVirtualAddressSpace">
                    <event name="BEV_PROACTIVE" value="50"/>
                    <event name="BEV_SEVERE" value="40"/>
                    <event name="BEV_CRITICAL" value="25"/>
                    <event name="BEV_HALT" value="15"/>
                </boundary>
            </boundaries>
        </boundaryManagerConfig>
    </SSM>
    <SIM startUpTimeout="120"/>
    <DataHistory fileSwitchSize="100" lastingPeriod="96"/>
    <PagingTasksInput blockSize="4096" diskSpace="4294967296"/>
    <PagingTasksOutput blockSize="4096" diskSpace="4294967296"/>
    <PagingTasksOutput blockSize="102400" diskSpace="8589934592"/>
</SOAM>

version

Version of the Symphony Middleware.

Need to change?
Not in Symphony DE. Only applicable when migrating application profile from previous versions of Symphony.

resReq, workDir

Not applicable to Symphony DE.

Need to change?
Not in Symphony DE. Only applies when the application is running on a full Symphony Grid cluster.

Others

boundaryManagerConfig, DataHistory, PagingTasksInput, PagingTasksOutput, PagingTasksOutput.

Need to change?
No need to change for normal testing. These parameters concerns the system environment in heavy production scenarios. Specifically memory boundary conditions and disk/file related limits.


4. sessionTypes Section

Code:

<SessionTypes>
    <Type name="ShortRunningTasks" priority="1" recoverable="false"
        sessionRetryLimit="3" taskRetryLimit="3"
        abortSessionIfTaskFail="false" abortSessionIfClientDisconnect="true"
        suspendGracePeriod="100"  taskCleanupPeriod="100"/>
</SessionTypes>

name

Unique name of the session type (user may define more than one sessionTypes within one application).

Need to change?
Change it to reflect the nature of your session. When changed, make sure it is matched by the parameter passed to attributes.setSessionType() API call in the client.

priority

If there are multiple open sessions, the session with the higher priority value will receive resources first, over session with lower priority.

Need to change?
Do not need to change for normal testing. Set to higher value, for example priority=10000 (maximum) if wish to give the session type priority over other session types when they are submitted simultaneously.

recoverable

Whether the session and its workload can be recovered if the session manager (SSM) restarts due to failure.

Need to change?
Do not need to change for normal testing. It is uncommon for SSM to crash or hang, especially in an development environment. Setting recoverable=true would also slow down performance, as SSM would have to journal session and task data for recovery purposes.

sessionRetryLimit, taskRetryLimit

Number of times Symphony attempts to bind a session or execute a task after the previous attempt was unsuccessful. If sessionRetryLimit is reached, the session enters Aborted state. If taskRetryLimit is reached, the task enters Error state.

Need to change?
Do not need to change for normal testing. Adjust the value if you prefer to have either more or less (no) retry attempts.

abortSessionIfTaskFail

Whether the entire Session is aborted if just one Task enters Error state.

Need to change?

Set abortSessionIfTaskFail=true if you wish to abandon the session and investigate as soon as one Task goes wrong. Keep it as false if you wish to give a chance for the rest of the Tasks to complete.

abortSessionIfClientDisconnect

Whether the entire Session is aborted if connection between the Client application and the SSM is broken.

Need to change?
Set abortSessionIfClientDisconnect=false if we wish to use the Client recovery feature. Keep it as true if you wish to Abort the session as soon as client disconnects due to self-exit, crash, or just Control-C.

suspendGracePeriod, taskCleanupPeriod

Number of milliseconds to allow a task to continue executing (or clean up) after the session for the task is suspended by a user (suspendGracePeriod) or targeted to be aborted by the system or a user (taskCleanupPeriod).

Need to change?
Do not need to change for normal testing. In production environment, user might wish to expand the value to allow longer grace periods in sudden events of suspension or abortion. Developers can also prolong the value (suspendGracePeriod=5000 for example) just to observe this feature in action.


5. Service Section

Code:

<Service description="The Sample Service" name="SampleService" packageName="SampleServiceCPP">
    <osTypes>
        <osType name="all"
            startCmd="${SOAM_DEPLOY_DIR}/SampleServiceCPP"
            workDir="${SOAM_HOME}/work">
        </osType>
    </osTypes>
    <Control>
        <Method name="Register">
            <Timeout duration="60" actionOnSI="blockHost"/>
            <Exit actionOnSI="blockHost"/>
        </Method>
        <Method name="CreateService">
            <Timeout duration="0" actionOnSI="blockHost"/>
            <Exit actionOnSI="blockHost"/>
            <Return controlCode="0" actionOnSI="keepAlive"/>
            <Exception type="failure" controlCode="0" actionOnSI="blockHost"/>
            <Exception type="fatal" controlCode="0" actionOnSI="blockHost"/>
        </Method>
        <Method name="SessionEnter">
            <Timeout duration="0" actionOnSI="blockHost" actionOnWorkload="retry"/>
            <Exit actionOnSI="blockHost" actionOnWorkload="retry"/>
            <Return controlCode="0" actionOnSI="keepAlive" actionOnWorkload="succeed"/>
            <Exception type="failure" controlCode="0" actionOnSI="keepAlive" actionOnWorkload="retry"/>
            <Exception type="fatal" controlCode="0" actionOnSI="keepAlive" actionOnWorkload="fail"/>
        </Method>
        <Method name="Invoke">
            <Timeout duration="0" actionOnSI="restartService" actionOnWorkload="retry"/>
            <Exit actionOnSI="restartService" actionOnWorkload="retry"/>
            <Return controlCode="0" actionOnSI="keepAlive" actionOnWorkload="succeed"/>
            <Exception type="failure" controlCode="0" actionOnSI="keepAlive" actionOnWorkload="retry"/>
            <Exception type="fatal" controlCode="0" actionOnSI="keepAlive" actionOnWorkload="fail"/>
        </Method>
        <Method name="SessionLeave">
            <Timeout duration="0" actionOnSI="restartService"/>
            <Exit actionOnSI="restartService"/>
            <Return controlCode="0" actionOnSI="keepAlive"/>
            <Exception type="failure" controlCode="0" actionOnSI="keepAlive"/>
            <Exception type="fatal" controlCode="0" actionOnSI="keepAlive"/>
            </Method>
        <Method name="DestroyService">
            <Timeout duration="15"/>
        </Method>
    </Control>
</Service>

name

Unique name of the service (user may define more than one service within one application). If more than one service is defined, one of them has to have default=true set, the default service is the one that is associated to a session type when no serviceName= is defined in the sessionTypes definition.

Need to change?
Change it to reflect the nature of your service. A service can be assigned to a session type by setting serviceName= in the sessionTypes definition. Otherwise the session type will always be associated with the default service.

description

Description of the service.

Need to change?

Change it to reflect the nature of your service. Unlike service name, description does not have to be unique.

packageName

Name given to the service package that is to be used by the application. Not the service package file name.

Need to change?
Must match the package_name entered when deploying the package using "soamdeploy add" CLI or from PMC. The application cannot be registered if the package has not been deployed. Remove the packageName= definition if you do not indend to use service deployment. See tip: Update your Symphony DE service without having to re-deploy every time.

osTypes name

Name of the Operating System type which the configuration applies to.

Need to change?
Not in Symphony DE. In a full Symphony Grid cluster made up of mixed operating systems, use can specify different configurations for Linux, Windows hosts, etc.

osTypes startCmd

Path to the service executable which will be launched by the Service Instance Manager (SIM).

Need to change?
If using service deployment, simply enter ${SOAM_DEPLOY_DIR}/ followed by the name of the service executable that is inside the service package. For example ${SOAM_DEPLOY_DIR}/myservice or ${SOAM_DEPLOY_DIR}/dir/myservice. If not using service deployment, simply enter the path to the service executable on the file system. For example /install/symde/4.0/samples/CPP/SampleApp/Output/SampleServiceCPP.

osTypes workDir

Working directory of the service instance.

Need to change?
Do not need to change for normal testing. By default all Symphony DE daemons uses ${SOAM_HOME}/work as working directory.

Control

Service error handling control configurations. Controls events and corresponding actions to take on sessions, tasks, and service instances when a service is in a specific state of its lifecycle. Refer to Service error handling control feature reference for details.

Need to change?
Do not need to change for normal testing. If necessary, adjust control actions for specific events in any service method. For example, if I intend to:

• In the event of a failure exception in Invoke method, fail the Task instead of having it retry,
• Also fail the Task if Invoke method returns code 9.

Make the following configuration change accordingly:

Code:

<Method name="Invoke">
    <Timeout duration="0" actionOnSI="restartService" actionOnWorkload="retry"/>
    <Exit actionOnSI="restartService" actionOnWorkload="retry"/>
    <Return controlCode="0" actionOnSI="keepAlive" actionOnWorkload="succeed"/>
    <Return controlCode="9" actionOnSI="keepAlive" actionOnWorkload="fail"/>
    <Exception type="failure" controlCode="0" actionOnSI="keepAlive" actionOnWorkload="fail"/>
    <Exception type="fatal" controlCode="0" actionOnSI="keepAlive" actionOnWorkload="fail"/>
</Method>

6. Reference Document

Symphony Application Profile Reference Guide


Comments welcomed.