Logging: How To

View Log Messages

A logging configuration can define an appender that writes log messages somewhere other than the stdout or stderr stream. Review the defined output location to know where to view the log messages.

If this is not the case and log messages are written to the stdout or stderr stream, see Ways to View Log Messages to learn about the tools that are available in SAS Viya platform for viewing log messages.

Specify Server Logging Configuration

Logging Values and Configuration Instances

The run-time server logging configuration is located in the server configuration. Logging values for the servers are specified in configuration instances. A configuration instance specifies the loggers and logging thresholds that are used by its associated server.

Remember these considerations when preparing to make changes to a logconfig configuration instance:

Changes to the logconfig configuration instance can affect any enabled log-message monitoring.
Do not remove the consoleAppender logger. Otherwise, servers fail to write log messages that the Kubernetes APIs can provide via kubectl logs or to log-message monitoring.
Invalid changes to the XML in a logconfig configuration instance can result in server launch failures.

Note: logconfig configuration instances are disabled by default. In order to enable a configuration instance, a Kubernetes administrator must set SAS_ALLOW_ADMIN_SCRIPTS to true in the sas-shared-config configMap. For more information, see $deploy/sas-bases/overlays/sas-programming-environment/README.md.

CAUTION

Use caution if you choose to modify the logconfig configuration instances. Performance issues can result depending on the modification. SAS recommends that you consult with SAS Technical Support before making changes.

Use SAS Environment Manager to view and edit the server configuration. See Edit Server Configuration Instances in SAS Environment Manager: User’s Guide.

Modify Server Logging Configuration

Use SAS Environment Manager to view and edit the server configuration. See Edit Server Configuration Instances in SAS Environment Manager: User’s Guide.

Follow these steps to modify server logging configuration:

The following table specifies the configuration instance of the run-time server that you edit.

Server	Configuration Instance	Links to Steps to Perform
CAS	`cas-shared-default: logconfig`	Edit Configuration Instances in SAS Viya Platform: SAS Cloud Analytic Services.
SAS Compute	`sas.compute.server: logconfig`	Editing logconfig Configuration Instance of SAS Compute Server in SAS Viya Platform: Programming Run-Time Servers.
SAS/CONNECT server	`sas.connect.server: logconfig`	Editing logconfig Configuration Instance of SAS/CONNECT Server and SAS/CONNECT Spawner in SAS Viya Platform: Programming Run-Time Servers. For more information about modifying SAS/CONNECT Server and SAS/CONNECT Spawner configuration instances, see Edit Configuration Instances in SAS Viya Platform: Programming Run-Time Servers.
SAS/CONNECT Spawner	`sas.connect.spawner: logconfig`	See above.

Enter the logger XML element into the logconfig. For the syntax, description, and examples of using the logger XML, see About Logger Syntax.
```
<logger> 
</logger>
```
In the logger XML, specify the name of the logger that you want to use. For available run-time server loggers, see Reference: Loggers for Servers.
```
<logger name="logger-name"> 
</logger>
```
Note: Each logging configuration includes at least one logger.
(Optional) To pass the log events to loggers that are higher in the hierarchy, specify TRUE for the additivity option. For the syntax, description, and examples of using the logger XML, see About Logger Syntax.
```
<logger name="logger-name" additivity="TRUE">
</logger>
```
(Optional) To set that SAS jobs cannot change additivity and level values and cannot add appenders, specify TRUE for the immutability option. For the syntax, description, and examples of using the logger XML, see About Logger Syntax.
```
<logger name="logger-name immutability="TRUE">
</logger>
```
(Optional) Specify the lowest event level value (the threshold level) for the logger to process. In this example, the ERROR level is specified.
```
<logger name="logger-name 
<level value="ERROR"/>
</logger>
```
(Optional) Specify an appender for the logger. The appender has its own substructure that you reference by its name appender-name. For detailed steps about the appender substructure, see Specify an Appender.
```
<logger name="logger-name" additivity="TRUE" immutability="TRUE"> 
<level value="ERROR"/>
<appender-ref ref="appender-name"/>
</logger>
```
Note: You can define multiple appenders for a logger. An appender can pass messages to the appenders that are defined in the same logger, based on filters in the appenders.
Click Save.
The logging configuration in SAS Environment Manager is read when the run-time server starts.

Example

The following example shows a logger and an appender that are defined in the SAS Compute server logging configuration:

<logger name="Admin" immutability="true">
     <level value="Info"/>
</logger>

  <appender name="Console" class="ConsoleAppender">
     <param name="SkipEmpty" value="true"/>
     <param name="ImmediateFlush" value="true"/>
     <layout type="Json">
       <param name="Individual" value="true" />
       <param name="version#" value="%S{eventModel.payload.version}" />
       <param name="timeStamp" value="%d{LEMZone}" />
       <param name="level" value="%S{eventModel.payload.level}" />
       <param name="source" value="%S{OSENV.SAS_PAYLOAD_SOURCE|sas}" />
       <param name="messageKey" value="%K" />
       <param name="messageParameters{}" value="%S{eventModel.payload.parameters}" />
       <param name="message" value="%m" />
       <param name="properties.thread" value="%t" />
       <param name="properties.caller" value="%F:%L" />
       <param name="properties.logger" value="%c" />
       <param name="properties.pod" value="%S{hostname}" />
     </layout>
  </appender>

<logger name="Admin" immutability="true">
     <level value="Info"/>
</logger>

  <appender name="Console" class="ConsoleAppender">
     <param name="SkipEmpty" value="true"/>
     <param name="ImmediateFlush" value="true"/>
     <layout type="Json">
       <param name="Individual" value="true" />
       <param name="version#" value="%S{eventModel.payload.version}" />
       <param name="timeStamp" value="%d{LEMZone}" />
       <param name="level" value="%S{eventModel.payload.level}" />
       <param name="source" value="%S{OSENV.SAS_PAYLOAD_SOURCE|sas}" />
       <param name="messageKey" value="%K" />
       <param name="messageParameters{}" value="%S{eventModel.payload.parameters}" />
       <param name="message" value="%m" />
       <param name="properties.thread" value="%t" />
       <param name="properties.caller" value="%F:%L" />
       <param name="properties.logger" value="%c" />
       <param name="properties.pod" value="%S{hostname}" />
     </layout>
  </appender>

Temporarily Modify CAS Server Logging Values

There might be instances, such as when working with SAS Technical Support, when you need to temporarily change the threshold level of a logger, add a logger, or delete a logger. You can use the Servers area in SAS Environment Manager to make these changes on a temporary basis.

Any change that you make remains in effect until you restart the server.
When you restart the server, the loggers and threshold levels are reset to the values that are specified in the logging configuration file.

To temporarily modify CAS server logging, complete the following steps:

In SAS Environment Manager, select Servers from the left navigation menu.
In the Servers table, select a server whose logging levels you want to view or edit.
If you want to modify the logging levels for a server, add a logger, or delete a logger, select Assume the Superuser role.
Note: You can ignore this step if you want to view the server logging levels only.
Select Settings.
In the Server Settings window, select the Logging tab.
The Logging tab displays a list of the loggers that are specified for the selected server and the current threshold level for each logger. For more information about server loggers, see CAS Server Loggers.
To change the threshold level for one or more loggers, select Edit. This icon is visible only if you have assumed the Superuser role for the server.
From the Level menu, select the threshold level that you want to use for each logger that you want to change. See Threshold-Level Definitions for more information.
To add a logger, select Add.
A blank entry appears in the table. Specify the name of the logger and the threshold level for the logger.
To delete a logger, select the logger and select Delete.
Select Save when you have finished making changes to the CAS server loggers.
Select Close to close the Server Settings window and return to the Servers table.
To relinquish the Superuser role, select Relinquish. From the pop-up menu, select the server for which you have assumed the Superuser role.

Specify an Appender

Specifying an appender-ref when you specify a logger is optional. However, the logging configuration must define at least one appender, which is referenced in the root logger's appender-ref as the default:

<!-- Root logger -->
  <root>
     <level value="Error"/>
     <appender-ref ref="Console"/>
  </root>

<!-- Root logger -->
  <root>
     <level value="Error"/>
     <appender-ref ref="Console"/>
  </root>

The appender syntax is a subelement in the logger syntax. The appender syntax can potentially contain many subelements, too. For details about available appenders, see Reference: Appenders.

TipYou can also use appenders to specify database connections. See Reference: Appenders for Database Connection.

Note: In the server configuration file, you can specify an appender that can be referenced by SAS programs and jobs. See Use Server-Based Appender Classes in SAS Viya Logging Facility for SAS Programs and Jobs.

Enter the appender XML in the logger configuration of the server configuration instance. See General Syntax for Appenders.


<appender> 
</appender>
<logger name="logger-name" additivity="TRUE" immutability="TRUE"> 
<level value="ERROR"/>
<appender-ref ref="appender-name"/>
</logger>

Add the class option. Specify the type of appender to use. See the list of supported appenders types in the general syntax. You can access detailed descriptions of each type from the syntax.
```
<appender class="appender-class">
</appender>
```
In the name option, specify a name for the appender that you are defining. This value is used for the value of the appender-ref option in the logger XML.
```
<appender class="appender-class" name="appender-name">
</appender>
```
(Optional) To specify information that is required by the selected appender type, specify the associated param name and a value.
For example, FileAppender writes messages to a user-specified file. FileAppender provides a param with the name File. In the value for the File param, you can specify the location and name of the log file in which to write the messages.
```
<appender class="appender-class" name="appender-name">
      <param name="parameter-name" value="parameter-value"/>
</appender>
```
Note: You can specify multiple param options. Be sure to review the syntax for the selected appender to learn its available param options.
(Optional) To control how messages are formatted in the log, specify the layout option. For detailed steps, see Define a Pattern Layout in the Appender.
```
<appender class="appender-class" name="appender-name">
      <param name="parameter-name" value="parameter-value"/>
      <layout>
            <layout-parameters/>
      </layout>
</appender>
```
For syntax, descriptions, and examples of the available pattern names, see Reference: Pattern Layout Elements.
(Optional) Specify a filter to manage whether messages are accepted by the logger. For detailed steps, see Filter Log Messages via the Appender.
```
<appender class="appender-class" name="appender-name">
      <param name="parameter-name" value="parameter-value"/>
      <layout>
            <layout-parameters/>
      </layout> 
      <filter>
      </filter>
</appender>
```
For syntax, descriptions, and examples of the available filters, see Reference: Filters.

Define a Pattern Layout in the Appender

Adding a pattern layout is optional. For concepts, see About Pattern Layouts.

Enter the layout XML subelement into the appender XML.

<appender class="appender-class" name="appender-name">
      <param name="parameter-name" value="parameter-value"/> 
      <layout>
            <layout-parameters/>
      </layout>
</appender>

Specify the name of a pattern to use when the appender generates content for the log.
```
<layout>
      <param name="pattern-name"  />
</layout>
```
Note: The pattern names ConversionPattern and XmlEscape are supported for all appender classes. All other pattern names are supported for only these appender classes: File, RollingFile, and Console. See the descriptions of the pattern names in Pattern Layout Syntax.
If you selected the pattern name Header or Footer, specify the applicable text that the appender uses when it starts or ends a new log. The specified text is literal text without any conversion characters or format modifiers.
```
<layout>
      <param name="pattern-name" value="text"/>
</layout>
```
If you selected the pattern name HeaderPattern, ConversionPattern, or FooterPattern, construct the conversion pattern to specify for the value conversion-pattern. If you do not specify a conversion pattern, the log event produces an empty string.
```
<layout>
      <param name="pattern-name" value="conversion-pattern"/>
</layout>
```
Here is the syntax for conversion patterns:
```
[literal-text]%[format-modifier-1] conversion-character-1
     [… [literal-text] %[format-modifier-n] conversion-character-n] />
```
For the syntax and descriptions of available conversion characters and format modifiers, see Reference: Pattern Layout Elements.

TipFor an example and explanation of a conversion pattern, see Example of a Conversion Pattern.
Note: Remember these key points:
- Conversion specifiers are case sensitive.
- The specification of format modifiers is optional.
- There is no explicit separator between literal text and a conversion specifier. The pattern parser recognizes the end of a conversion specifier when it detects a conversion character.
- Review the pattern name descriptions for specific key points and restrictions that affect each pattern name. See Syntax Description.

Filter Log Messages via the Appender

Specify the Filter

Adding a filter is optional. For concepts, see About Filters and Filter Policy.

The following steps use an example of a simple filtering policy to log only performance messages for the ARM subsystem:

Enter the filter XML subelement into the appender XML.

<appender class="appender-class" name="appender-name">
      <param name="parameter-name" value="parameter-value"/>
      <layout>
            <layout-parameters/>
      </layout> 
      <filter>
      </filter>
</appender>

Specify the filter class that you want to use. The first filter in this example specifies the StringMatchFilter class.
```
<filter class="StringMatchFilter">
</filter>
```
To specify a string for the filter to match, use the StringToMatch parameter and specify the string value to match. To configure the behavior of the filter when a match occurs, specify the AcceptOnMatch parameter and the value TRUE.
```
<filter class="StringMatchFilter">
   <param name="StringToMatch" value="Perf.ARM"/>
   <param name="AcceptOnMatch" value="true"/>
</filter>
```
See the filter syntax to learn about all of the parameters available for each filter class. See Reference: Filters.
To complete the filter policy, specify a second filter and use the DenyAllFilter class. It denies any log events that do not meet the prior filters in the filtering policy.
```
<filter class="StringMatchFilter">
   <param name="StringToMatch" value="Perf.ARM"/>
   <param name="AcceptOnMatch" value="true"/>
</filter>
<filter class="DenyAllFilter">
</filter>
```
TipThe DenyAllFilter class must be the last filter in the filter policy.

Filter Examples

Example 1: Filter for a Specific User's Error Messages

In this example, the filtering policy performs the following checks in order:

Determines whether the message has already been logged.
Identifies and writes the messages whose log event threshold is ERROR and which are issued by user sasuser1.
Denies all messages that do not meet the criteria of the prior steps.


<filter class="RepeatMatchFilter">
      <param name="AcceptOnMatch" value="false"/>
</filter>
<filter class="AndFilter">
      <param name="AcceptOnMatch" value="true"/>
            <filter class="LevelMatchFilter">
               <param name="LevelToMatch" value="error"/>
               <param name="AcceptOnMatch" value="true"/>
            </filter>
            <filter class="StringMatchFilter">
               <param name="StringToMatch" value="sasuser1"/>
               <param name="AcceptOnMatch" value="true"/>
            </filter>
</filter>
<filter class="DenyAllFilter">
</filter>

Example 2: Filter for a Specific Date

The following filtering policy denies log events that were sent on 2011–09–22:

<filter class="StringMatchFilter">
   <param name="StringToMatch" value="2011-09-22"/>
   <param name="AcceptOnMatch" value="false"/>
</filter>

Example: Capture WHERE Clauses from Server Logs

SAS ARM Interface Overview

Application Response Measurement (ARM) enables you to measure application availability, performance, usage, and transaction response time. The SAS ARM interface implements a number of features, which are compliant with the ARM 4.0 standards. SAS cooperates with open source ARM agents or vendor products that implement the ARM open API standard.

The SAS ARM interface is available in SAS Viya.

Capture WHERE Clauses Using ARM Logging

This example uses ARM logging to capture where clauses from compute or batch server logs.

The following code block is an XML-formatted log configuration file that you add to the sas.compute.server: logconfig configuration instance. You cannot access or edit these instances directly in a Kubernetes environment. However, SAS Environment Manager enables you to edit the configuration instances. For more information, see Edit Configuration Instances in SAS Viya Platform: Programming Run-Time Servers.

The XML file includes the following elements:

%X{ARM2.Record}: %X{ARM2.Record} is the specification that creates the output message format. The option is in the form of a pattern layout, which consists of a named diagnostic context recognized by the ARM appender.
ARMAppender: The ARM appender is a standard SAS logging facility appender, which is configured and customized for accessing performance data. The ARM appender processes all ARM transaction events and sends the events to a specified output destination
Perf.ARM.INTERNAL.SAS.DSIO: The DSIO (Data Set I/O) ARM logger that is required for data access (input and output data set events). It is configured with a diagnostic level of info.
Audit.Data: The logger that is required to capture data. It is configured with a diagnostic level of trace.

Note: This example writes the messages to both pod logs JSON/kubectl logs) and a separate log file (/tmp/dataaccess.log). You can redirect the output to a PVC or elsewhere with additional configuration.

Note: Specifying an appender-ref when you specify a logger is optional. However, the logging configuration must define at least one appender, which is referenced in the root logger's appender-ref as the default

<log4sas:configuration>
   <!-- Console (JSON output for K8s logs) -->
   <appender name="Console" class="ConsoleAppender">
      <layout type="Json">
        <param name="properties.dataAccessRecord" value="%X{ARM2.Record}" />
      </layout>
   </appender>

   <!-- File output -->
   <appender class="FileAppender" name="datalog">
      <param name="File" value="/tmp/dataaccess.log"/>
      <layout>
         <param name="ConversionPattern"
                value="%d, %X{ARM2.Record}"/>
      </layout>
   </appender>

   <!-- ARM appender -->
   <appender class="ARMAppender" name="ARM">
      <param name="AppName" value="ComputeServer"/>
      <appender-ref ref="datalog"/>
      <appender-ref ref="Console"/>
   </appender>

   <!-- Required for data access -->
   <logger name="Perf.ARM.INTERNAL.SAS.DSIO" additivity="false">
       <level value="info"/>
       <appender-ref ref="ARM"/>
   </logger>

   <!-- Enable audit data (needed for capture) -->
   <logger name="Audit.Data">
      <level value="trace"/>
   </logger>

   <root>
      <level value="Error"/>
      <appender-ref ref="Console"/>
   </root>

</log4sas:configuration>

<log4sas:configuration>
   <!-- Console (JSON output for K8s logs) -->
   <appender name="Console" class="ConsoleAppender">
      <layout type="Json">
        <param name="properties.dataAccessRecord" value="%X{ARM2.Record}" />
      </layout>
   </appender>

   <!-- File output -->
   <appender class="FileAppender" name="datalog">
      <param name="File" value="/tmp/dataaccess.log"/>
      <layout>
         <param name="ConversionPattern"
                value="%d, %X{ARM2.Record}"/>
      </layout>
   </appender>

   <!-- ARM appender -->
   <appender class="ARMAppender" name="ARM">
      <param name="AppName" value="ComputeServer"/>
      <appender-ref ref="datalog"/>
      <appender-ref ref="Console"/>
   </appender>

   <!-- Required for data access -->
   <logger name="Perf.ARM.INTERNAL.SAS.DSIO" additivity="false">
       <level value="info"/>
       <appender-ref ref="ARM"/>
   </logger>

   <!-- Enable audit data (needed for capture) -->
   <logger name="Audit.Data">
      <level value="trace"/>
   </logger>

   <root>
      <level value="Error"/>
      <appender-ref ref="Console"/>
   </root>

</log4sas:configuration>

Administer Run-Time Servers

Set System Options That Affect the Logging Facility

The SAS Viya logging facility references the values of the following system options. These values are set when an instance of a run-time server is launched.

Enable the Logging Facility for Run-Time Server Logging

The run-time servers set LOGCONFIGLOC= system option in their scripts automatically. You should not have to enable the option manually.

This option specifies the name of the XML configuration file or a basic logging configuration that is used to initialize the SAS logging facility. For details, see LOGCONFIGLOC System Option in SAS Viya Platform: Programming Run-Time Servers.

Note: If this option is set to an invalid or inaccessible path, the server fails to start.

Enable the Logging Facility in SAS Programs

The logging facility is enabled for SAS programs at all times. That is, it is not necessary to set the LOGCONFIGLOC= system option in order for SAS programs to use the logging facility.

If you use the logging facility autocall macros, the MAUTOSOURCE system option must be set and the %LOG4SAS autocall macro must be invoked before any other logging facility autocall macros are invoked. The MAUTOSOURCE system option is set by default. No further action is required unless this option is turned off. For more information, see MAUTOSOURCE System Option in SAS Macro Language: Reference.

The logging facility functions and DATA step objects have no initialization requirements.

Specify a SAS Session to Include in Messages

Logging facility messages can be set to include the name of the SAS session. This might help you to read the log and to diagnose problems.

To identify a SAS session by name, you specify a session name as the value of the LOGAPPLNAME= system option.

To display the value of the LOGAPPLNAME= system option in a message, you must include the S conversion character in the conversion pattern layout, using the key App.Name.

For details, see LOGAPPLNAME System Option in SAS Viya Platform: Programming Run-Time Servers. Also see S Conversion Character.

Retain Log Messages in a Persistent Volume

Instructions about how to add a persistent volume to a run-time server are located in the README files for the affected server. For concepts, see About Log-Message Retention and Persistent Storage.