Custom Event Parsers

SAS Enterprise Session Monitor can be configured to automatically scan log files that it is aware of to detect events that users might want to know about such as ERROR and WARN events in SAS. These log file markers are used to annotate the process portlet charts.

Log file marker rules can be defined in two ways, through the SAS Enterprise Session Monitor user interface or via a JSON import mechanism¹.

UI Adding and Editing¶

Clicking Add or Edit while highlighting an existing log file marker pattern will bring up the Add/Edit regex dialog box. From this screen you can create or modify SAS Enterprise Session Monitor log file marker patterns.

Regex parameters¶

The regex parameters are used to define the rules which are applied when the log file parser is run.

Filename pattern - When log files are found to be associated with a session the filename rule is applied first. This ensures that only those rules which match the file name pattern are applied when reading the contents of the file. This is done for performance reasons.

The file name in this context includes the full path to the file. If you wish to just distinguish between files of different names you can use the .* regex to start the filename, for example, .*WorkspaceServer_\d{4}-\d{2}-\d{2}_.*[0-9]+.log. If you wish the rule that you are creating or editing to apply to all files, leave this field blank
Hostname pattern - After the file name pattern is run, the hostname of the server from which the session is associated is checked. The hostname pattern accepts a valid regex pattern or, if you wish for the rule to applied to all host, can be left blank.
Log line filter - For each line of the applicable log files that are read by the agent this is the rule that gets applied. Parts or all of the line can be used in either the tag text or the tool tip text by capturing the relevant data using named regular expression capture groups. For example, capturing the whole line in a capture group called line could be done with (?<line>.*). The variable ${line} would then be available for both the tag text and tooltip text properties.
Tag text - The tag text is the value that is visible in the chart annotation (see below). Valid values can be from a named capture group from the log line filter accessed using the notation ${cgname}where cgname is the name of the capture group, hard coded text, or blank.

We recommend keeping these values has short as possible so as not to clutter the charts. You'll notice that the default log marker patterns shipped with SAS Enterprise Session Monitor are a single character like E or W.
Tooltip text - The Tooltip text is the text that you see when you hover your mouse over the chart annotation. In most cases this will be the value from a named capture group from the log line filter. For example, if you had a capture group called msg in your log line filter, the value of the tooltip text might be: ${msg}.
Marker color - The marker color defines the background color of the chart annotations. A valid color-hex code is required².

Sample Input¶

This is where you can test the rules that you have configured with sample data.

Sample file name - This is an example of a full file path, including the file name, that you wish to test the filename pattern.
Sample hostname - This is an example of a hostname to test the hostname pattern filter. The hostnames that are passed to this filter will match the hostnames that you see in the live view and that were configured during the agent installation process. For a SAS system, this should match the value of the &syshostname macro variable.
Sample log data - This is the data that we are going to test the log line rule, tooltip text rule and the tag text rule. This area should be populated with a sample for the type of log file that you wish to test. It should contain one or more lines that you wish to match

Sample Output¶

Having defined a rule (at a minimum the log line filter, tag text, tooltip text, and marker color) and provided some sample data, the bottom half of the add/edit regex dialog provides an example of what a chart will look like based on the sample input and the rules that you have defined.

JSON Import / Export¶

The log marker settings import export functionality is available starting in SAS Enterprise Session Monitor 2020.4. It provides a simple way of importing and exporting large and complex log marker rule sets between SAS Enterprise Session Monitor installations.

Export¶

Clicking on the Export button will automatically download an export.json file containing all of the rules that you have in configured and saved within your environment. The file is downloaded to your browser's default downloads directory.

Import¶

Clicking on the Import button will bring up an Open File dialog prompting you to select a file to upload.

File format¶

The SAS Enterprise Session Monitor log marker upload parser accepts an array of JSON objects. Each object in the array must contain the following properties (all properties are required by can be set to null):

Special regex characters, for example, \s, used to denote a space will need to be escaped within the JSON string. Special characters are escaped by using backslash: \\s.

fileName - This is the filename pattern. Specify null for the rule to apply to all filenames
hostnameRegex - This is the hostname pattern. Specify null for the rule to apply to all hostnames
searchRegex - This is the log line filter. A valid JSON escaped regular expression string must be provided for this field.
fixedOutputTitle - This is the tag text field. A string value must be provided for this field.
outputRegex - This is the tooltip text field. A string value must be provided for this field. This field can contain variables in the form of ${name} where name is a named capture group in the searchRegex string.
color - This is the color value for the rule. Must be a string value, starting with a # and be a valid hexadecimal color value.

An example of a valid file might be:

[
    {
        "fileName":".*ObjectSpawner_\\d{4}-\\d{2}-\\d{2}_.*[0-9]+.log", 
        "hostnameRegex":null, 
        "outputRegex":"${msg}", 
        "fixedOutputTitle":"E", 
        "color":"#FF9999", 
        "searchRegex":"^(?<timestamp>\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2},\\d{3})\\sERROR\\s[^:]+:\\w+\\s-\\s(?<msg>.*)"
    },
    {
        "fileName":".*ObjectSpawner_\\d{4}-\\d{2}-\\d{2}_.*[0-9]+.log", 
        "hostnameRegex":null, 
        "outputRegex":"${msg}", 
        "fixedOutputTitle":"W", 
        "color":"#F5ED0F", 
        "searchRegex":"^(?<timestamp>\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2},\\d{3})\\sERROR\\s[^:]+:\\w+\\s-\\s(?<msg>.*)"
    }
]

The log marker settings import functionality is available in SAS Enterprise Session Monitor 2020.4 and later. ↩
A great site for finding colors that you like can be found at https://www.color-hex.com/. For your assistance and reference, the SAS Enterprise Session Monitor default ERROR color is #FF9999 and WARN is #F5ED0F. ↩

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