Introduction

This sample application showcase developing of adaptive application, Integration with Execution manager and PHM manager. With this sample application, users will get familiar about developing applications which will be launched by Pulsar EM and interacting with EM (Reporting execution status to EM) and PHM (Reporting checkpoint to PHM).

More details about the development and actual implementation details can be found at below pages

PHM checkpoint generator tool

Execution state reporting

PHM checkpoint reporting

Execution Manifest

PHM Manifest

About This Tutorial

This Sample application is the basic adaptive application launched by Pulsar Execution Manager using 'AdaptiveApps' function group, reports Execution status ESRunning to Execution Manager after initializing, triggers checkpoint (alive supervision) at particular intervals to inform PHM that application is alive and ESTerminating to EM just before going terminate.

This tutorial make you get familiar about below topics

Developing adaptive applications using Pulsar SDK
Execution Manifest
PHM configurations for checkpoint
Integrating with EM client to report execution status to EM
Integrating with PHM client to report checkpoint status to PHM
Compiling the sample application
Running the application
Output

You can find sample application at <SDK_Path>/samples/phm/appFirst folder.

Configurations

This section provides information about EM & PHM configurations of appFirst application

Execution Manifest configurations

This section guides you on Execution Manifest configurations of appFirst application. you can go through Execution Manifest for Execution Manifest README file.

Make sure 'name' property value as application binary name
```
"name" : "appFirst",
```
provide process name. Make sure this name should be unique. because EM and PHM do perform few operations based on process name and process ID.
```
"name" : "Process_appFirst",
```
provide parameter values for 'schedulingPolicy', 'schedulingPriority' to get desired execution behavior
```
"schedulingPolicy" : "SCHEDULING-POLICY-ROUND-ROBIN",
"schedulingPriority" : 31,
```
If you need to pass any arguments to application, please mention those arguments in 'options' parameter
```
"options" : [
    "-c",
    "./etc/sst_config_app.json"
],
```
If appFrist application depend on any other applications (means appFirst should start after other applications), provide 'executionDependency' parameter
```
"executionDependency" : {
},
```

By default all applications are under 'AdaptiveApps' function group.

functionGroups" : [
    {
        "name" : "AdaptiveApps",
        "states" : [
            "Running"
        ]
    }
],

Specify If you want application to be run on specific CPU cores
```
"cores" : {
    "shallRunOn" : [
        1
    ]
}
```

PHM Configurations

This section guides you through configurations related to Platform health manager for appFirst application.

You can refer PHM Manifest for complete PHM configurations README file.

phm_configuration.json has 'functionGroups' parameter section. provide Supervision mode for 'AdaptiveApps' function group. Each function group state should have one supervision mode.

You can see below snippet AdaptiveApps Function group Running state has AppsRunning supervision mode.

"functionGroups" : [
    {
        "name": "MachineFG",
        "stateInfo" : [
            {
                "fgState": "Running",
                "supervisionMode": "Running"
            },
            {
                "fgState": "state2",
                "supervisionMode": "modeName2"
            }
        ]
    },
    {
        "name": "AdaptiveApps",
        "stateInfo" : [
            {
                "fgState": "Running",
                "supervisionMode": "AppsRunning"
            }
        ]
    }
],

Once you map function group state to supervision mode. please define supervision mode behavior

you can refer phm_configuration.json file available at <SDK Path>/bin/phmService/etc folder

"supervisedEntitiy" : [
    {
        "entity_id" : 1,
        "processName" : "Process_appFirst",
        "isPlatformLevel" : 0,
        "aliveSupervisions" :[
            {
                "name" : "alivesupervision_1",
                "id" : 33,
                "settings": {
                    "expAliveIndication": 2,
                    "maxMargin" : 1,
                    "minMargin" : 1,
                    "aliveReferenceCycle" : 1000,
                    "failedReferenceCyclesTolerance" : 2
                },
                "checkpoint" : 1
            }
        ]
    }
]

processName parameter contains appFirst Process Name. This name should match with process name given in exec_config.json file.

Below snippet is from appFirst execution manifest file.
```
"name" : "Process_appFirst",
```
If you observe 'supervisedEntity' given above, appFirst contains only Alive supervisions. So we have written aliveSupervisions.

We provided Alive supervision name and ID. This ID should be unique and same will be mapped to Global Supervisions

You can see below snippet for mapping elementarySupervisions to globalSupervisions

"supervisionMode" : [
    {
        "mode" : "AppsRunning",
        "globalSupervisions" : [
            {
                "name" : "global_apps1",
                "id" : 333,
                "elementarySupervisions" : [1, 2, 33]
            },
        ]
    }
]

From appFirst application, PHM expecting 2 Alive indications in 1000 ms time. so we have written settings values as above.
Checkpoint parameter assigned value with 1. This value should be unique and same will be provided in checkpoints parameter to generate checkpoint class as shown given below.
```
"checkpoints" : [
    {
        "id": 1,
        "name": "ch1_class"
    },
]
```

linking with Pulsar SDK libraries

You need to add below Pulsar SDK libraries for compilation

EM Client - To report execution state to EM
PHM Client - To trigger checkpoint to PHM
Logger - For logging

target_link_libraries(appFirst em_client phm_client neblogger)

Building the sample

To build the application execute the following commands in a terminal from the sample application folder.

Build appFirst

$ mkdir build
$ cd build
$ cmake -DCMAKE_PREFIX_PATH=<SDK_Path> -DCMAKE_INSTALL_PREFIX=<Output_Path_To_Generated_Binaries> ..
$ make
$ make install

Replace <SDK_Path> with path to the SDK installation folder.

Once build is complete, you can find the opt directory at given <Output_Path_To_Generated_Binaries> directory path

Output_Path_To_Generated_Binaries └── opt └── appFirst ├── bin │ └── appFirst └── etc └── exec_config.json

Running the sample application

You can launch the appFirst sample application by running execution manager. please provide '-d' option with path to opt folder available in <Output_Path_To_Generated_Binaries> folder shown in above picture.

Run executionManager

$ cd <SDK Install Path>
$ export LD_LIBRARY_PATH=<SDK_Path>/lib
$ ./bin/executionManager -d ./bin/ -d <Output_Path_To_Generated_Binaries/opt>

Output

When executed terminal prints many logs including all applications (Execution Manager, PHM, SM, diagnostics applications and appFirst). The initial part contain stack and framework initialization logs.

Initial logs

You can observe Execution Manager started in 'Startup' state of function group 'MachineFG' and it will launch PHM and SM services.

EM_in_startup

Now, nebula stateManager reads configuration files and informs EM about available function groups and it's states.

you can see below image for EM was informed about 'MachineFG' function group. once information received from SM, EM will list out all applications come under which function group state.

EM_machineFG

After 'MachineFG' function group SM sends information about another function group called 'AdaptiveApps' where all sample applications run under.

EM_Adaptiveapps_fg

Now, SM informs EM to change in to 'MachineFG' function group 'Running' state

EM_MachineFG_Running

At this time, you can observe all platform services (PHM, SM, UDS, DOIP) are running.

EM_DOIP_LogS

EM_UDS_logs

Once all system services are launched, StateManager informs Execution Manager about 'AdaptiveApps' function group state change.

EM_adaptiveApps_running

'AdaptiveApps' function group 'Running' state launches 'appFirst' application.

After 'appFirst' started, state set to 'ESInitializing'. When ever application completed initializing section, It sets execution state to 'ESRunning' and informs to EM.

so EM will save this state and launch other applications which are dependent on 'appFirst' applications. For more details about ExecutionState reporting, you can refer Execution state reporting

EM_executionState_reporting

After execution state changed to 'ESRunning', PHM service also ready to perform alive supervision for 'appFirst' application. Application needs to report configured checkpoint at configured interval of time. you can refer PHM checkpoint generator tool document for generating PHM checkpoint and PHM checkpoint reporting document for reporting checkpoint.

PHM_checkpoint_reporting