Advanced ESM Administration Tasks

Disabling Windows Short Names to enable SASWORK Monitoring

If SASWORK is configured to point to a volume with short names enabled, and you wish to monitor SASWORK with ESM (recommended) you must change your SASWORK configuration to use a volume with short names disabled.

  1. Determine the new location for SASWORK. This guide assumes a drive letter of E:

  2. Query the short name status of drive E: by issuing the following command at a command prompt with elevated/Administrator privileges:

fsutil.exe 8dot3name query E: 
This should produce the following output:
C:\WINDOWS\system32>fsutil.exe 8dot3name query E:
The volume state is: 0 (8dot3 name creation is enabled).
The registry state is: 2 (Per volume setting - the default).
Based on the above two settings, 8dot3 name creation is enabled on E:. If the status returns 8dot3 name creation is enabled on E:, issue the following command to disable it:
C:\WINDOWS\system32>fsutil 8dot3name set E: 1
Successfully disabled 8dot3name generation on E:

  1. Now create a saswork directory (e.g E:\saswork)

  2. Now change the SAS Server configuration to set SASWORK to point to this location. It is recommended to change this setting in the Application Server root sasv9_usermods.cfg file. For example:

    C:\SAS\Lev1\SASApp\sasv9_usermods.cfg
    
    add the following entry to this file:
    -WORK "E:\saswork"
    

  3. Restart the SAS Object Spawners to pick up the new configuration

  4. Start a new SAS Session and re-issue the saswork option query: %put %sysfunc(getoption(work)); If the change has taken effect, you should see output in the SAS log similar to the following:

    E:\saswork\_TD1592_WIN2008R2N1_
    

Installing the ESM Agent as a systemd service on RHEL7

RHEL7 comes with systemd replacing sysvinit and upstart from RHEL6. Systemd lets us configure control the ESM agent on machine startup and if the agent stops.

To configure the ESM agent as a systemd service, create a file in /etc/systemd/system called esm-agent.service:

Update paths

Remember to change the reference to ##ESMHOME## below to point to real install path (eg. /opt/esm/esm-agent).

[Unit]
Description=ESM agent control
After=network.target

[Service]
User=root
ExecStart= ##ESMHOME##/bin/esm-agent-nonforking.sh start
LimitNOFILE=4096
Restart=on-failure
Type=simple
TimeoutStartSec=10
TimeoutStopSec=5
RestartSec=2
ExecStop=  ##ESMHOME##/bin/esm-agent-nonforking.sh stop
ExecStop=  ##ESMHOME##/modules/esm-module-control.sh stop

[Install]
WantedBy=multi-user.target

After creating the file, you can run the following commands as root (or sudo):

  • run systemctl daemon-reload command to make systemd re-read the config
  • run systemctl start esm-agent to have upstart run the agent for you
  • run systemctl enable esm-agent to have the agent start as a service on every subsequent boot
  • run systemctl status esm-agent to see the output of the last start

Installing the ESM agent as an upstart service in RHEL 6

RHEL6.x comes with Upstart as well as sysvinit, which lets us configure it to control the esm agent on machine startup and if the agent stops.

To configure the ESM agent to run as an upstart service, create a file in /etc/init called esm-agent.conf. Remember to change the env ESMHOME to point to real install path.

#!upstart
description "Boemska ESM Agent"

# Set this to location of installed agent
env ESMHOME=/pub/esm/agent/esm-agent

start on runlevel [2345]
stop on runlevel [!2345]

# Be nice and set some limits on open file handles
limit nofile 4096 4096

# But also make sure data gets collected when needed most
nice -15

# Return output about connecting to ESM server to the console
console output

# Restart automatically if agent stops but no more than 3x in the space of a minute
respawn
respawn limit 3 60

# Go
exec $ESMHOME/bin/esm-agent-nonforking.sh start

Following that:

run the initctl --verbose reload-configuration command to make upstart re-read the config run start esm-agent to have upstart run the agent for you

Triggerfile formats

When communicating with the agent through the triggerfile mechanism, processes can output triggerfiles for consumption by the agent as either a space-separated array of quoted values, or in JSON format. The space-separated array depends on field order and is considered legacy, but remains around 40% faster to parse and therefore continues to be supported for high-stress environments with little available overhead.

The following are examples of each format.

Warning

For legacy reasons, the ESM Agent matches triggerfiles based on hostname and will disregard any files where the hostname element of the filename does not match the agent hostname exactly. This check may be removed in a future release.

new event triggerfile

File name: new_12345_thishostname (where 12345 is the PID of the process to be monitored and thishostname is the agent recognised hostname)

File content (json)

{
   "owner": "thisUser",
   "sasUuid": "234801532270870",
   "queue": "defaultQueue",
   "jobName": "Lev1_SASAppTest",
   "workFolder": "/data/saswork/SAS_workC02600003039_thishostname",
   "utilFolder": "/data/sasutil/tempUtil_12345_thishostname",
   "logFile": "/data/logs/someWorkspaceLog.log",
   "esmType": "WS"
}

tag event triggerfile

File name: tag_12345_thishostname_123 (where 12345 is the PID of the process to be monitored, thishostname is the agent recognised hostname and 123 is an identifier that ensures a unique filename for the triggerfile, often an autoincremented counter)

File content (json)

{
   "text": "flagText",
   "tooltip": "tooltipText with more detail",
   "color": "#FAAD39"
}

highlightStart event triggerfile

File name: highlightStart_12345_thishostname (where 12345 is the PID of the process to be monitored and thishostname is the agent recognised hostname)

File content (json)

{
   "uuid": "234801532270870"
}

highlightEnd event triggerfile

File name: highlightEnd_hostname_234801532270870 (where thishostname is the agent recognised hostname and 234801532270870 is the uuid

File content (json)

{
    "uuid":"234801532270870", 
    "text":"myJobName.sas", 
    "returnCode":0, 
    "flow":"1670:thisUser:some_daily_flow:some_daily_subflow:myJobName"
}

ESM Agent Events directories