Skip to content

SAS 9 on Windows

Having successfully installed the SAS Enterprise Monitor Server component and Agent component, SAS configuration changes are 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 documented 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.

Basic Configuration

  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 line 10 of esm-agent\sasautos\esm-bootstrap-win.sas by adding a space separated list of any additional SAS application server contexts that exist in your deployment.

  4. 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 */

Additional Configuration

Collect Job Flow and Exit Status Information

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 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

Identify Stored Process Executions

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 C:\path\to\esm-agent\sasautos\startstp.sas, updating the path to the correct one for your environment.

Monitor SAS Infrastructure Services

In a SAS 9 deployment there are a number of key processes that need to be running in order for users to be able to connect to the environment (Metadata Server, Object Spawner, Web Application Server(s), etc.). In the context of SAS Enterprise Session Monitor we refer to these processes as SAS Infrastructure Services.

To configure an Agent to track the SAS Infrastructure Services, we will configure Active Process Discovery and use a filterSpec configuration that is provided by default.

From within the Agent's bin folder:

  1. Modifyconfig.properties by uncommenting lines 2 and 5.
  2. Copy filterSpec-sas9-inf-win.yaml to a file called filterSpec.yaml
  3. Restart the Agent

Track Session UTILLOC size

Unlike the SAS WORK location which is a directory created at session startup that is unique to each individual SAS session, SAS UTIL directories are created on-the-fly by SAS procedures as they are required. The Agent can be configured to automatically watch one or more directories for these on-the-fly created folders to enable visibility of per-session UTILLOC consumption.

  1. In your Agent's bin directory, create a new file called tempDirectories.yaml
  2. Copy the below contents into the newly created file, updating the path to the SAS WORK directory: 
    tempDirectories:
  warningDuration: 2000  
  scanInterval: 2000 
  directories: 
    - D:\SAS\WORK
  settings:
    - directoryPattern: SAS_util\w{4}(?<dirPid>\w{8})_(?<hostname>[^_]+)_
      directoryPidIsHex: true
      directoryType: util
  3. Restart your Agent

For more information about the tempDirectories.yaml file and options for configuring pre-process UTILLOC and WORK tracking, see the reference guide.

Capture Procedures Executed and Datasets Used

Proceed with Caution

These steps require changes to be made to SAS server logging. Modifications, if not completed correctly, may cause issues on your system.

It is highly recommended that you familiarise yourself with the documentation for the SAS Logging Facility for your version of SAS, and ensure that you take a backup of any SAS configuration file before making changes.

Download the latest version of the sas-proc-mon module. The credentials for the downloads site can be found in the email with the SAS Enterprise Session Monitor license key.

The following steps should be completed for each Agent within your environment unless your Agent is deployed to a shared filesystem. If your Agent is deployed to a shared filesystem, the steps should be completed just once paying particular attention to step 2c.

  1. Unzip the downloaded sas-proc-mon_windows.zip file into the modules folder of your Agent installation.
  2. Update the vars.yaml file changing the following items1:
    1. The value of sasType to v9.
    2. Update the value of sas9ConfigRoot to the location of your LevX folder.
    3. If you are running your ESM agent from a shared directory, set the value of checkLogHasProcess to true.
  3. Create the sas-proc-mon service:
    1. Start an Administrative command prompt and navigate to the nssm folder of your Agent installation directory
    2. Run the following command: nssm.exe install esm-sas-proc-mon a user interface will be presented.
    3. On the "Application" tab:
    4. Select the esm-module.bat file from the sas-proc-mon directory.
    5. The startup directory path should be automatically completed but if it is not, populate it with the path to the sas-proc-mon folder within your Agent's modules folder
    6. Add "start" in the "Arguments"
    7. Click "Install Service". If the installation completed successfully, you should see a message that reads "Service ''esm-sas-proc-mon" installed successfully!"
  4. Start the Module service from the Windows "Services" application.

The module uses SAS logging to collect data. Some modifications need to be made to the default SAS Server logging settings to enable the functionality of the sas-proc-mon module.

Configure Workspace Server Logging

By default, SAS workspace server logging is disabled. Follow the instructions in the SAS Help Center to enable SAS Workspace Server logging for each Workspace Server in your environment.

Add the data access logger

To collect data access metrics, we must enable dataset access audit logging. Add the following logger just above the root logger towards the end of the file:

<!-- START ESM Logger -->
<logger name="esm" additivity="false">
    <appender-ref ref="TimeBasedRollingFile"/>
    <level value="Debug"/>
</logger>
<logger name="Audit.Data.Dataset" additivity="false">
    <appender-ref ref="TimeBasedRollingFile"/>
    <level value="Trace"/>
</logger>
<!-- END ESM Logger  -->
Workspace Server Log Management

With a high number of Workspace sessions the number and size of the log repositories can quickly grow. By default, SAS creates Workspace Server logs in a Logs folder within the Workspace Server folder of your SAS configuration. If filling up this storage location with logfiles poses an issue, consider implementing one or more of the following:

  1. Redirection of log files to another disk. This is most easily accomplished by creating a symbolic link for the Logs directory to an alternate location. Redirecting the files in this way requires fewer SAS configuration file changes.
  2. Regularly delete old logs. For example, schedule a simple script to perform a housekeeping task on your system which deletes files older than a certain age. The following delete files older than 14 days: 
    Get-ChildItem -Path 'C:\sas\config\Lev1\SASApp\WorkspaceServer\Logs' -File | Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-14) } | Remove-Item

Configure Batch Server Logging

By default the SAS Data Step Batch Server uses the -log logging option. Follow these steps to enable SAS Data Step Batch Server logging using a logconfigloc option.

In addition to the above instructions, the following changes are needed in the default Batch Server logconfig.xml:

Modify appender for immediate flush

In order to be able to get near real time procedure and dataset access events for a job we want to enable immediate flushing of logging data to the file. Within the BatchFileAppender starting at roughly line 17, add the following line after the Unique param:

<param name="ImmediateFlush" value="true"/>
Update the conversion pattern

Within the BatchFileAppender starting at roughly line 17, add within the layout tags, update the ConversionPattern value to:

<param name="ConversionPattern" value="%d - %m"/>
Add the data access logger

To collect data access metrics, we must enable dataset access audit logging. Add the following logger just above the root logger towards the end of the file:

<!-- START ESM Logger -->
<logger name="esm" additivity="false">
    <appender-ref ref="BatchFileAppender"/>
    <level value="Debug"/>
</logger>
<logger name="Audit.Data.Dataset" additivity="false">
    <appender-ref ref="BatchFileAppender"/>
    <level value="Trace"/>
</logger>

<!-- END ESM Logger  -->
Update esm-bootstrap.sh

The ESMLOGCONFIG environment variable tells the Agent that we are using the logconfig.xml method for creating a log file for jobs. This setting makes the Agent use a different technique to find the log file for the session.

ESMLOGCONFIG=1

Configure Stored Process Server Logging

By default the SAS Stored Process Server log only captures high level information about the stored process that is being executed. In order to collect PROC and DATA level metrics, we need a more detailed Stored Process Server log. A detailed SAS Stored Process Server log can be created by default by following this SAS Note.

In addition to the changes contained within the SAS Note, we need to make the following SAS Stored Process Server logconfig.xml changes:

Add the data access logger

To collect data access metrics, we want to enable dataset access audit logging. Add the following logger just above the root logger towards the end of the file:

<!-- START ESM Logger -->
<logger name="esm" additivity="false">
    <appender-ref ref="TimeBasedRollingFile"/>
    <level value="Debug"/>
</logger>
<logger name="Audit.Data.Dataset" additivity="false">
    <appender-ref ref="TimeBasedRollingFile"/>
    <level value="Trace"/>
</logger>

<!-- END ESM Logger  -->

Configure Connect Server Logging

By default, SAS Connect Sever logging is disabled. Follow the instructions in the SAS Help Center to enable SAS Connect Server logging for each Connect Server in your environment.

Add the data access logger

To collect data access metrics, we must enable dataset access audit logging. Add the following logger just above the root logger towards the end of the file:

<!-- START ESM Logger -->
<logger name="esm" additivity="false">
    <appender-ref ref="TimeBasedRollingFile"/>
    <level value="Debug"/>
</logger>
<logger name="Audit.Data.Dataset" additivity="false">
    <appender-ref ref="TimeBasedRollingFile"/>
    <level value="Trace"/>
</logger>
<!-- END ESM Logger  -->
Connect Server Log Management

With a high number of Connect sessions the number and size of the log repositories can quickly grow. By default, SAS creates Connect Server logs in a Logs folder within the Connect Server folder of your SAS configuration. If filling up this storage location with logfiles poses an issue, consider implementing one or more of the following:

  1. Redirection of log files to another disk. This is most easily accomplished by creating a symbolic link for the Logs directory to an alternate location. Redirecting the files in this way requires fewer SAS configuration file changes.
  2. Regularly delete old logs. For example, schedule a simple script to perform a housekeeping task on your system which deletes files older than a certain age. The following delete files older than 14 days: 
    Get-ChildItem -Path 'C:\sas\config\Lev1\SASApp\ConnectServer\Logs' -File | Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-14) } | Remove-Item

Validate Configuration

The configuration changes that have been made can be validated by starting a session from each server type and ensuring that the session is discovered, and viewable in the UI.

Note

When SAS Management Console is used to validate a 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 Live View.

Workspace Server Validation

To do this via SAS Management Console, navigate to the Server Manager plugin, expand an application server context (e.g. SASApp), and locate the Logical Workspace Server definition. Right click, and select the "Validate" option.

The following two things should happen as a result:

  1. You should see a "Validation Successful!" message in SAS Management Console
  2. You should see the session appear in the "List Portlet" of the Live View. It should have the following properties:
  3. User: Should match the user that you authenticated with
  4. Name: Should be something similar to Lev1_SASApp depending on your configuration
  5. Type: Should be WS

Connect Server Validation

To do this via SAS Management Console, navigate to the Server Manager plugin, expand an application server context (e.g. SASApp), and locate the Logical Connect Server definition. Expand the Logical definition, showing the actual server definition. Right click, and select the "Validate" option.

The following two things should happen as a result:

  1. You should see a "Validation Successful!" message in SAS Management Console
  2. You should see a new session appear in the "List Portlet" of the Live View. It should have the following properties:
  3. User: Should match the user that you authenticated with
  4. Name: Should be something similar to Lev1_SASApp depending on your configuration
  5. Type: Should be CS

SAS OLAP Server Validation

To do this via SAS Management Console, navigate to the Server Manager plugin, expand an application server context (e.g. SASApp), and locate the Logical OLAP Server definition. Right click, and select the "Validate" option.

The following two things should happen as a result:

  1. You should see a "Validation Successful!" message in SAS Management Console
  2. You should see the session appear in the List Portlet of the Live View. It should have the following properties:
  3. User: Should match the user that you authenticated with
  4. Name: Should be something similar to Lev1_SASApp depending on your configuration
  5. Type: Should be OLAP

SAS Stored Process Server Validation

To validate the Stored Process Server, navigate to the Stored Process Web Application. From the home screen select "Sampe: Hello World" and in the new tab that opens, select "Say Hello".

The following two things should happen as a result:

  1. The stored process completes succssfully, showing "Hello World" in large black text in the browser.
  2. You should see the session appear in the List Portlet of the Live View. It should have the following properties:
  3. User: Should be the service account that is configured to run your Stored Process Server
  4. Name: Should be something similar to Lev1_SASApp p8611 depending on your configuration
  5. Type: Should be STP

SAS Data Step Batch Server Validation

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.bat script, passing it the SAS Enterprise Monitor Validation Job as input:

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

The following things should happen as a result:

  1. You should see the session appear in the "List Portlet" of the Live View. It should have the following properties:

  2. User: Should match the user that you executed the job with

  3. Name: Should be validateBatchWin.sas

  4. Type: Should be Batch

  5. When completed, should have the following in the Process Portlet:

    • The job should be roughly bound by a light blue background.

    • The background area should be titled with the name of the job across the top.

    • A white tag titled 'User Tag' should be showing halfway through the job.

SAS Pooled Workspace Server Validation

To do this via SAS Management Console, navigate to the Server Manager plugin, expand an application server context (e.g. SASApp), and locate the Logical Pooled Workspace Server definition. Right click, and select the "Validate" option.

The following two things should happen as a result:

  1. You should see a "Validation Successful!" message in SAS Management Console
  2. A few seconds later you should see the session appear in the "List Portlet" of the Live View

  1. For information about all of the configuration options available for the sas-proc-mon module, please see the module's reference guide. ↩

Last update: July 31, 2023
Created: April 24, 2023