Configuring SAS9 for ESM

Having successfully installed the ESM Server and Agent components, SAS configuration is now required to enable ESM to monitor the various components of your SAS installation.

Important Note

If your environment uses the -autoexec system option this will override the behaviour configured below. A small modification can be made to your launching scripts to change -autoexec to -insert autoexec and then the below integration method will work.

For more information, please see the official SAS documentation on this option.

Linux

Source the bootstrap script

  1. Copy and paste the below code block into the sasenv_local file of your SAS installation (!SASROOT/bin/sasenv_local) updating the value of the ESMHOME variable to the location of you ESM agent.
    # ESM CONFIG START
    export ESMACTIVE=1
    export ESMHOME=/path/to/esm-agent
    if [ -f $ESMHOME/bin/esm-bootstrap.sh ]; then
      . $ESMHOME/bin/esm-bootstrap.sh
    fi
    # ESM CONFIG END
    
  2. Edit the esm-bootstrap.sh file which you will find in the bin directory of your ESM agent to include any additional application server contexts. The order of this list is important. If your application server contexts are named SASApp_Something_ then you need to make sure that they are before the default SASApp context otherwise the default matching mechanism will always pickup the standard "SASApp".

[OPTIONAL] Update sasbatch.sh

In order to be able to report on the FLOW and job completion status of programs submitted using the SAS Data Step Batch Server, some changes must be made to the sasbatch.sh script. If you use the SAS Data Step Batch server to submit workload, you should implement this step. You will need perfom the below steps for every SAS Data Step Batch server that is configured in your environment.

  1. In sasbatch.sh replace the line starting exec "$SAS_COMMAND" .... with the following code block updating line two (2) of the block below whith the path to your esm-agent folder.

Pre-modified sasbatch.sh files

If you have already made changes to the "$SAS_COMMAND" line in your sasbatch.sh script, please ensure that you replace the "$SAS_COMMAND"... line in the code block below with your pre-existing SAS command but without the exec at the start of the line.

# ESM CONFIG START
export ESMHOME=/path/to/esm/esm-agent
source $ESMHOME/conf/esmconfig.sh
# ESM CONFIG END
"$SAS_COMMAND" -noxcmd -lrecl 32767 "$@" "${USERMODS_OPTIONS[@]}"
# ESM CONFIG START
rc=$?
$ESMHOME/reportOut.sh $ESMGUID $ESMJOBNAME $rc "$LSB_JOBNAME"
# ESM CONFIG END

Windows

Source the bootsrap script

  1. If one doesn't exist already, create a file called autoexec.sas in the root of your SAS installation (!SASROOT). If the file already exists, skip to step two.
  2. Add the below lines to the autoexec.sas file updating the value of the ESMHOME variable for the location of your ESM agent installation:
    /* START ESM CONFIG */
    %let ESMHOME = "C:\path\to\esm-agent";
    options set = ESMHOME = &ESMHOME.;
    options set = ESMACTIVE = 1;
    %let esmh=%sysget(ESMHOME);
    %include "&esmh.\sasautos\esm-bootstrap-win.sas";
    /* END ESM CONFIG */
    
  3. Update the esm-bootstrap-win.sas file to include any additional application server contexts. The order of this list is important. If your application server contexts are named SASApp_Something_ then you need to make sure that they are before the default SASApp context otherwise the default matching mechanism will always pickup the standard "SASApp".
    when setting like '%SASMeta%' then 'SASMeta'
    when setting like '%SASAppOther%' then 'SASAppOther'
    when setting like '%SASApp%' then 'SASApp'
    else 'Other'
    
  4. For each application server context in your environment modify the appserver_autoexec_usermods.sas file by adding the below line modifying for the location of your SAS installation:
    /* START ESM CONFIG */
    %let ESMROOTEXEC = "C:\Program Files\SASHome\SASFoundation\9.4\autoexec.sas";
    %if %sysfunc(fileexist(&ESMROOTEXEC)) %then %do; 
      %include &ESMROOTEXEC; 
    %end;
    /* END ESM CONFIG */
    

[OPTIONAL] Update sasbatch.bat

In order to be able to report on the FLOW and job completion status of programs submitted using the SAS Data Step Batch Server, some some changes must be made to the sasbatch.bat script. If you use the SAS Data Step Batch server to submit workload, you should implement this step. You will need perfom the below steps for every SAS Data Step Batch server that is configured in your environment.

  1. Paste the following code block immediately before the line "%SAS_COMMAND%" %CMD_OPTIONS% %*% with the following code block updating line two (2) of the block below whith the path to your esm-agent folder.

Pre-modified sasbatch.bat files

If you have already made changes to the "$SAS_COMMAND" line in your sasbatch.sh script, please ensure that you replace the "$SAS_COMMAND"... line in the code block below with your pre-existing SAS command but without the exec at the start of the line.

REM ESM CONFIG START
call "C:\esm\esm-agent\conf\esmconfig.bat"
SETLOCAL=ENABLEDELAYEDEXPANSION
set esmfound=false
REM Find out what the name of the sysin job was
for %%x in (%*) do (
    if !esmfound! equ true (
        set ESMJOBNAME=%%~nxx
    )
    if %%x equ -sysin (
        set esmfound=true
    ) else (
        set esmfound=false
    )
)

REM It is interactive if there was no sysin
if [!ESMJOBNAME!] equ [] (
    Set ESMJOBNAME=Interactive
)
REM ESM CONFIG END
2. Paste the following code block immediately after the `set rc=%ERRORLEVEL% line:

REM ESM CONFIG START
call "%ESMHOME%\reportOut.bat" %ESMGUID% %ESMJOBNAME% %rc% %LSB_JOBNAME%
REM ESM CONFIG END

All Platforms

Stored Process Server

Stored Process Server requests are executed by a pool of Multibridge sessions. Multibridge sessions are runner processes often pre-initialised by the SAS Object Spawner which execute Stored Process program code when requested to do so by the user. In order to capture the attributes of each request into an Event so that ESM can identify the program and person currently using that multibridge session, a Request Initiation program must be specified in metadata.

In Management Console, under: Environment Management -> Server Manager -> SASApp* -> Logical Stored Process Server -> Properties -> Options ->Set Server Properties->Request

Set the Initialisation Program value to be $ESMHOME/sasautos/startstp.sas

The SAS Stored Process Server Metadata configuration:
STP Server Metadata Configuration

Validating ESM configuration changes

The configuration changes for each Server can be validated as follows:

Workspace Server

This can be done either using SAS Management console, or using a client such as SAS Enterprise Guide.

To do this via SAS Management Console, navigate to the Server Manager plugin, and locate the SAS Workspace Server under the context that has been configured (eg. SASApp). Right click, and select the Validate option.

Management Console server validation

The following two things should happen as a result:

  1. You should see the following 'Validation Successful' message
    Management Console successful validation

  2. A few seconds later, a session should appear in the List Portlet of the ESM Live View:
    ESM Config Workspace Validation

Note

When SAS Management Console is used to validate the Workspace Server, the session that it spawns is terminated immediately following validation. It is therefore normal for the session to be greyed out as soon as it appears in the ESM Live View. Standard Workspace Sessions started by a client application should persist as expected.*

Alternatively, to validate the Workspace Server via a client such as SAS Enterprise Guide, simply connect to the Server Context in question and execute some SAS code. Your session should appear in the ESM Live View, and should be correctly associated to your SAS Metadata username.

Connect Server

The procedure for validating the SAS/CONNECT Server is very similar to that of a standard SAS Workspace Server. However, instead of right-clicking on the Logical Server definition in SAS Management Console, right-click the server definition itself.

Management Console server validation

SAS/CONNECT sessions should also be validated by connecting to the SAS/CONNECT server using a suitable client.

SAS OLAP Server

The procedure for validating the SAS OLAP Server configuration uses the SAS Management Console based Validate command, similarly to the validation for the SAS/CONNECT Server or SAS Workspace Server.

SAS Stored Process Server

The Stored Process Server configuration can also be validated from SAS Management Console in the same way as the Workspace Server configuration. However, if the Start Size in the Load Balancer configuration is set to a number higher than zero, the Multibridge Sessions will be started by the spawner, making the Management Console based validation unneccessary.

In either case, there should be at least one Multibridge Session visible in the Live View list portlet:

STP Session Live Validation

Note that the Multibridge Port (8611 in this example) should be identified correctly.

To validate the addition to the Metadata configuration which allows each individual request to be identified, execute a stored process using a supported client (such as the SAS Stored Process Web Application). Depending on the Load Balancing configuration, a flag should be drawn against one of the Multibridge Session portlets.

STP Session Live Validation

Hovering over the flag should display a tooltip correctly identifying the test program executed.

Pooled Workspace Server

The Pooled Workspace Server configuration should be validated in the same way as the Stored Process Server configuration. However, to issue a request to a Pooled Workspace session in order to validate the identification of that request, you will need to execute an Information Map against that session. This can be done via a Pooled Workspace client application such as SAS Information Map Studio or SAS Web Report Studio.

Pooled Workspace Session Live Validation

SAS Batch Server

To help validate the extended functionality for monitoring SAS Batch Jobs, ESM ships with a test Job which is to be used when validating the configuration of the SAS Batch Server. To trigger the batch job, navigate to a directory where you have write permissions, and invoke the sasbatch.sh / sasbatch.bat script, passing it the ESM Validation Job as input. Here is an example using the Windows platform:

C:\> c:\sas\Config\Lev1\SASApp\BatchServer\sasbatch.bat -sysin c:\bts\esm-agent\sasautos\validateBatch.sas

The following should happen:

  1. The Batch Job should appear among the other active sessions in the Live View Session List portlet, showing validateBatch.sas in the Name column.

Batch Server Session Live Validation

  1. Once finished, the Session Portlet for the job should look similar to this: Batch Server Session Portlet Validation It should exhibit the following features:

    • The job should be roughly bound by a light blue background, signifying it is a job.
    • The background area should be titled with the name of the job across the top.
    • If SASWORK monitoring is permitted to the agent at the Operating System level, blue bars should show the SASWORK tracking working correctly.
    • A white tag titled 'User Tag' should be showing halfway through the job.
    • An ERROR and a WARNING flag should be apparent, highlighting the (artificial) error and warning in the job log.
  2. Clicking on one of the E or W flags should retrieve the Job Log from the node's filesystem (if permitted by OS) Batch Server Session Log Retrieval

  3. Selecting Sessions and Jobs from the side-nav and typing 'validate' in the Job Name box and clicking the Graph button should load a graph showing the execution of the ValidateBatch.sas job, signified with a green bar.

Batch Server Session Job Status

If you are unable to see any of the above, please contact Boemska Suport at support@boemskats.com.

This concludes the Validation step of ESM Configuration.

SAS Client Configuration

SAS Enterprise Guide

Tags

Annotations of ESM charts using tags allows SAS developers to highlight the different steps of a program when evaluating or comparing performance. ESM tags can be automatically be created in the most common SAS clients including SAS Studio and SAS Enterprise Guide.

Tags being shown for the example process flow ESM tags for the sample process flow from Enterprise Guide

Tasks

Tasks within SAS Enterprise Guide can be automatically picked up and annotations added to the ESM charts by using the &_CLIENTTASKLABEL macro variable that is always configured by SAS Enterprise Guide.

To configure tasks to be automatically annotated in ESM, select Tools > Options within SAS Enterprise Guide and, from the side-bar menu of the dialog that appears, select Tasks > Custom Code.

Selecting Edit... for both the before and after task and query code options, add the following:

  • Insert custom SAS code before task and query code;
    %esmtag(Start &_CLIENTTASKLABEL);
    
  • Insert custom SAS code after taks and query code:
    %esmtag(End &_CLIENTTASKLABEL);
    
Programs

To configure programs to be automatically annotated in ESM, select Tools > Options within SAS Enterprise Guide and, from the side-bar menu of the dialog that appears, select SAS Programs.

Selecting Edit... for both the before and after task and query code options, add the following:

  • Insert custom SAS code before submitted code;
    %esmtag(Start &_CLIENTTASKLABEL);
    
  • Insert custom SAS code after submitted code:
    %esmtag(End &_CLIENTTASKLABEL);