Managing Global settings

The Admin Settings overview

Clicking on the admin settings menu button will prompt you for you ESM credentials. Once you have entered your ESM username and password you will be presented with the Admin overview screen.

The overview screen displays a list of all of the agents that have been configured to talk to the ESM server and provides an interface for updating agent configuration settings.

Update agent settings

Selecting an agent from the top table list of agents will populate the Update Agent Settings form automatically.

Setting Default Value Editable Description
Agent Hostname N/A No Hostname of the agent for who's settings we are viewing/editing.
App Version N/A No The version of the agent that this node is running.
Runner Version N/A No The version of the runner that this agent is running.
Cores N/A No The number of cores that the agent is reporting that the node has.
Events folder $ESM_AGENT_HOME/events/$HOSTNAME Yes This is the directory on the node that the Agent monitors for trigger (Event) files created by SAS sessions configured with ESM. The initial value is set upon initial connection by the Agent, using the ESMEVENTS variable set in the Agent's esmconfig file.

The location can be changed here for debugging purposes without restarting the Agent. When the ESMEVENTS variable is reconfigured in esmconfig, it must also be updated here. Alternatively, te node configuration can be removed entirely to allow the agent to set its default values.

Note: For ESM to function correctly, the Agents directory constructed by the SAS code located in the file must, for each node, match the directory configured here. Changing this setting from the default is generally not recommended.
Data collecting interval 2 Yes This setting changes the resolution of the data collected by the agent on that node. The default interval is 2 seconds, which is the lowest acceptable value. Increasing this number will lower the resolution of the data collected, therefore decreasing the amount of data stored in the database. This can also improve UI performance when looking at data over longer intervals, or when working with web browsers less capable of rendering a high number of data points.
Disk read ratio 5 Yes This setting dictates how often the sizes of a Session's SASWork and SASUtil directories are measured. The default ratio of 5, means that the size of these directories is measured every fifth Data Collection Interval (see above). With a default Data Collection Interval of 2 seconds, and a ratio of 5, these directories are sized for each session every 10 seconds. With a data collection Interval of 5 seconds and a ratio of 12, the size of these directories will be checked once per minute.
Reporting interval 0 Yes This setting changes how often the Agent sends a data packet to the Server. With the default setting of 0, the agent sends its data to the server after every Collection Interval. This interval can be increased to lower the frequency of network calls being made if desired.

The default setting of 0 is recommended.
Sum CPU cores (set max load to cores x 100%) False Yes This setting allows the overall CPU usage on the Server to be presented using the same scale as a Session graph. For example:

With this setting disabled, on a node with 20 available threads, a 100% saturated CPU core will appear to consume 5% of the overall node CPU. The node CPU axis will be fixed at a maximum of 100%.

With this setting enabled, on a node with 20 available threads, a 100% saturated CPU core will appear to be consuming 100% of the overall node CPU. Five 100% saturated CPU cores will appear as 500% CPU consumption on the node. The node graph will go to a maximum of 2,000%.

This setting is generally not recommended.

Database Maintenance

ESM has a built-in configurable scheduler designed to ease the maintenance of the ESM database. It allows the ESM Administrator to adjust the time of day that the maintenance routines are triggered.

Changing the Perform Database Maintenance time, and clicking the Save button, will update the time at which the daily maintenance of the database is performed. It is advised that this is set to a time of day when the number of concurrently active jobs will be at its minimum.


To avoid clashing with other batch routines that may be scheduled to start 'on the hour' or a similar rounded interval, the scheduler will delay its maintenance routine for a random time between 1 and 30 minutes before the database maintenance jobs are triggered.

Classification Interface

When the timeseries data for a session is archived by the database, a 'cost item' is created in place of the timeseries data. Cost items are held in the database and calculated on a hourly basis. Each cost item is marked with the name of the session or Job, the name of the user under which it executed, and the amount of resource that the session consumed during that hour.

The ESM Classification Interface allows those cost items to be grouped into categories, so that overall system usage per category can be calculated for a given time period.

To access the ESM Classification Interface, click the Open Classification Interface button at the bottom of the Admin Settings tab. You will be presented with the following settings:

Item Limit This number controls the maximum number of cost items that are shown in the Unclassified Items list. By default it is set to a conservative number of 2000. If, after setting the Target Confidence and Billing Period the Unclassified Items list still contains 2,000 unique items, this limit can be increased. The number of items shown are always sorted in descending order, therefore a limited list always contains the specified number of most significant cost items.

Target Confidence Like the Item Limit, this setting also controls the maximum number of cost items that are presented in the Unclassified Items list. Whereas the Item Limit setting is a Count of the total number of cost items presented for classification, the Target Confidence setting limits the cost items shown according to their significance.

For example, if the database contains 15 cost items, where the first 6 items make up 90% of the total Cost and the last 9 items make up the other 20%, then setting a Target confidence of 90% will mean that only those 6 items will be presented to the user for categorization, and the other 9 items will be considered as insignificant. If items 7 and 8 together add up to another 5% of cost, then setting the Target confidence to 95% will include the first 8 items in the list of items to be classified, ignoring the remaining 8 that make up the smallest 5% of cost.

Billing Period This setting allows the Cost Items to be filtered according to the period during which they occurred. Any cost items that sit outside the specified date range are ignored.

Allocating Cost ESM groups the cost items into unique job name / user combinations and calculates their share of the overall CPU consumed, taking into account the filter settings above. In order for the desired Target Confidence to be achieved, each of the cost items needs to be classified into Department.

Departments are created by clicking the Add Department button, which will prompt the user for a Department Name to be added to the list. When all departments have been added, their cost buckets can be opened by clicking each department in the Choose Department list.

From this point, each of the cost items in the Unclassified Items list must be allocated into a Department. This can be done by dragging and dropping each item in the list into a Departmental Bucket, or by selecting multiple items in the Unclassified Items list and clicking the (+) button on the department's cost bucket item. In addition, the Unclassified Items list can be filtered on Job Name or Executing User patterns, and clicking Select All and then (+) will assign all items appearing in a filtered list to the selected Departmental bucket.

The Total CPU Accounted For is designed to act as an indicator of progress. Clicking the Show Report button at any time will show a report detailing the breakdown of costs per department, along with a list of the top Users and Processes responsible for those costs. Clicking the Print Report button in this screen will present the report in a format which can be printed and reviewed by the party responsible for the system usage in each Department.

The username/jobname lookup lists created during the classification process persist in ESM across billing periods. While the first classification exercise may be arduous, subsequent instances will only require the classification of cost items which have newly entered the list of significant cost items, as defined by the Item Limit and Target Confidence settings.

License Interface

The license interface allows an ESM administrator to update the ESM license through the user interface. For more information about updating the ESM license please see the ESM Administration Guide section on updating the ESM license.

Privileged Users

Users in ESM can be separated into the following 'Roles':

  • General Users
  • Privileged Users
  • The Administrator

General Users do not require any authentication within ESM. Privileged Users and the Administrator are prompted for credentials when they attempt to use the advanced features of the application. The roles are hierarchial: Privileged Users and Administrators are able to access all of the functionality available to General Users, and the Administrator is able to access all of the functionality available to Privileged Users.

Privileged Users in ESM are managed by the ESM Administrator. This is done via the Privileged Users Settings page, accessed via the Admin Settings interface.

To add a user to the list of Privileged Users, click the 'Add Privileged User' button. This will change the focus to the username field further down the screen where you'll be prompted to create a password for the user and assign the permissions for the user:


If permitted by the Operating System, the ESM Agent can be used to terminate unresponsive, orphaned or unwanted SAS sessions. Once a session is identified, it can be terminated using a menu accessed by right-clicking on the session in the List Portlet in the Live View.

The menu presents the following options:

  • Terminate Process

This sends the process the equivalent of a SIGTERM signal for UNIX platforms, and a taskkill command on Windows platforms. Once the process is terminated, the Agent ensures that the temporary directories related to that process have been removed.

  • Force Terminate Process

This sends the process the equivalent of a SIGKILL signal for UNIX platforms, and a taskkill /f command on Windows platforms. Once the process is terminated, the Agent ensures that the temporary directories related to that process have been removed.

  • Force Terminate Process leaving temporary directories intact

This sends the process the equivalent of a SIGKILL signal for UNIX platforms, and a taskkill /f command on Windows platforms. Once the process is terminated, the Agent leaves any temporary directories that may be related to that process intact.


If a process is known by ESM to be a System (SYS) process, or if it is not an instance of the sas binary executing, the process can not be acted upon. This limitation is imposed as a security precaution.*

All actions performed using the Session Management menu are audited by ESM. A history of all Session Management actions can be seen in the Privileged Users section of the ESM Admin Settings screen.


When ESM is passed a 'log file' option for a Session, such as in the case of a Batch Job, ESM will continually monitor that log file for occurrences of WARNING and ERROR messages. When either a Warning or Error message occurs, it is plotted against the timeline of that session in real time as a flag. Hovering over the flag using the mouse displays the warning or error text. Clicking on the flag retrieves the log file in question, opens it in a new tab and navigates to the line where the error occurred.

If this behaviour is configured as restricted to Privileged Users, suitable credentials must be entered prior to the logfile being retrieved.


Changing the ESM Administrator Password

The overriding password for the ESM Administrator is stored in a master password file and secured using filesystem-level security.

To change the ESM Administrator username and password, log on to the machine where the ESM Server is running as a suitably privileged user. Then, edit the admin.txt plaintext file, located in

[esm home]/esm-core/glassfish/domains/domain1/config

The format of admin.txt should as follows:


Note: When saving the password file, ensure that the correct permissions continue to be applied to it. It can only be read by the ESM system account, and written by a designated user / administrator of the underlying operating system.

Log file markers

For more information about administering ESM's global settings or for more advanced ESM Administration options please see the ESM Administration Guide