Configuring for SAS9

Having successfully installed the SAS Enterprise Monitor server and agent components, SAS configuration is now required to enable SAS Enterprise Monitor 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 your SAS Enterprise Monitor 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. Update the $ESMHOME/bin/esm-bootstrap.sh file with the specifics for your environment:
3. Enterprise Session Monitor Agent version 2022.4.x:
   1. If you have one or more additional application server contexts in your environment (in addition to SASMeta and SASApp) please add these as a semi-colon separated list on line 9.
   2. If your Data Step Batch server uses a logconfig.xml based logging mechanism, you will need to set the value of line 12 to 1.
4. Enterprise Session Monitor Agent version 2022.1.1 to 2022.3.3:
   1. Update lines 10 and 11 with the path to your SAS Workspace Server logs. If you have more than one application server context or Lev it's imperative that you leave the _CONTEXT_ and _LEV_ keywords in the file path¹.
   2. If your Data Step Batch server uses a logconfig.xml based logging mechanism, you will need to set the value of line 12 to 1.
   3. If you have one or more additional application server contexts in your environment (in addition to SASMeta and SASApp) please add these as a semi-colon separated list on line 13 with no trailing semi-colon.
5. Enterprise Session Monitor Agent version 2022.1.0 and below:
   1. Update and copy lines 97 through 99 for as many custom application server contexts as you have in your environment.

[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 perform 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
if [[ -z $ESMJOBNAME ]]; then
  ESMFULLPATHFILE=`/bin/bash $ESMHOME/getSysIn.sh "$@"`
  ESMJOBNAME=`basename $ESMFULLPATHFILE | sed 's/"//g' | sed "s/'//g"`
  if [[ -z $ESMJOBNAME ]]; then
    ESMJOBNAME=interactive
  fi
  export ESMJOBNAME
fi
"$SAS_COMMAND" -noxcmd -lrecl 32767 "$@" "${USERMODS_OPTIONS[@]}"
rc=$?
$ESMHOME/reportOut.sh $ESMGUID $ESMJOBNAME $rc "$LSB_JOBNAME"
# ESM CONFIG END

Windows

Source the bootstrap 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 SAS Enterprise Monitor 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-agent\sasautos\esm-bootstrap-win.sas file with the specifics for your environment:
4. Enterprise Session Monitor Agent version 2022.1.1 and above:
   1. Update lines 10 and 11 with the path to your SAS Workspace Server logs. If you have more than one application server context or Lev it's imperative that you leave the CONTEXT keyword in the file path.
   2. If your Data Step Batch server uses a logconfig.xml based logging mechanism, you will need to set the value of line 12 to 1.
   3. If you have one or more additional application server contexts in your environment (in addition to SASMeta and SASApp) please add these as a space separated list on line 13 with no trailing space.
5. Enterprise Session Monitor Agent version 2022.1.0 and below:
   1. Update and copy line 139 for as many custom application server contexts as you have in your environment. Paste additional entries immediately below and above the "SASApp" line (originally 140)
6. For each application server context in your environment modify the appserver_autoexec_usermods.sas file by adding the below lines 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 the 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 to perform 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 with the path to your esm-agent folder.

     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
   set FLOW=%LSB_JOBNAME:\=\\%
   call "%ESMHOME%\reportOut.bat" %ESMGUID% %ESMJOBNAME% %rc% %FLOW%
   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 SAS Enterprise Monitor can identify the program and person currently using that multibridge session, a Request Initiation program must be specified in metadata.

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

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

The SAS Stored Process Server Metadata configuration:

Validating SAS Enterprise Monitor 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.

The following two things should happen as a result:

1. You should see the following 'Validation Successful' message
   

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

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.

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 SAS Management Console based validation unnecessary.

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

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.

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.

SAS Batch Server

To help validate the extended functionality for monitoring SAS Batch Jobs, SAS Enterprise Monitor 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 SAS Enterprise Monitor 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.

1. Once finished, the Session Portlet for the job should look similar to this: 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)

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.

If you are unable to see any of the above, please contact SAS Technical Support.

This concludes the Validation step of SAS Enterprise Monitor Configuration.

SAS Client Configuration

SAS Enterprise Guide

Tags

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

SAS Enterprise Monitor 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 SAS Enterprise Monitor charts by using the &_CLIENTTASKLABEL macro variable that is always configured by SAS Enterprise Guide.

To configure tasks to be automatically annotated in SAS Enterprise Monitor, 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 task and query code:

  %esmtag(End &_CLIENTTASKLABEL);
  

Programs

To configure programs to be automatically annotated in SAS Enterprise Monitor, 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);
  

---

1. If your Logs are configured to go to multiple alternate paths (for example, you have multiple application contexts and Levs logging to a custom directory) then you must configure symbolic links from the Logs directory of the configured server type to the respective file system path. ↩