Configuring the file system logger interceptor

The file system logger interceptor enables IBM® z/OS® Connect users to log information about API and service requests in a file. It is not called for API requester invocations.

About this task

zosConnect-2.0 Applies to zosConnect-2.0.

This function is available when you configure z/OS Connect. The file system logger writes UTF-8 data (not EBCDIC). In z/OS Explorer, set the log file as File encoding > Other > UTF-8 to view the file in its original ASCII format.

The file that is written by the interceptor can be tagged as ASCII in USS by using the chtag command. For example,

chtag -t -c ISO8859-1 input.log

To view the data in an EBCIDIC environment, the data can be converted to EBCDIC data by using the USS chtag command. For example,

iconv -f ISO8859-1 -t IBM-1047 input.log > output.log

Note: z/OS Connect does not automatically delete the files that are created by the file system logger interceptor. Users are responsible for managing the files that are created.

Table 1. Descriptions of the entries that are in the generated log file
Entry	Description
DateTime	The date and time that is calculated by the logger interceptor before the service invocation and after the service response. From 3.0.16.0, the time is changed from 12 to 24 hour format and extended to millisecond precision.
Headers	Available from 3.0.74, the headers that are associated with the request or response. This information is only logged for headers that are specified by the `apiProviderRequestHeaders` and `apiProviderResponseHeaders` settings in the configuration.
LocalAddress	The Internet Protocol (IP) address of the interface on which the request was received.
MessageData	A request or response payload.
MessageSize	The character size of the payload.
MessageType	Identifies whether the payload is from a request or a response.
RemoteAddress	The Internet Protocol (IP) address of the client who originated the request or last proxy that sent the request.
RequestID	The request tracking ID generated by z/OS Connect.
RequestURL	Available from 3.0.74, the request method, URL, and query parameters associated with the request or response. This information is only logged when `requestUrl` is set to `true` in the configuration.
ThreadID	The ID of the thread under which the service request is being processed.
UserName	The user name for which the request is being processed.

*****************************************************************************
ServerName: myServer
*****************************************************************************
DateTime:2018-11-27 15:14:56:321 | ThreadId:47 | UserName:Fred | RequestID:0000000000000001000000000000000000000000000000 |
RemoteAddress:127.0.0.1 | LocalAddress:127.0.0.1
MessageType:REQUEST
MessageSize:27
MessageData:{"payload":"HELLO_SERVICE"}
Request URL: PUT https://localhost/zosConnect/services/HelloService?action=invoke
Headers: Content-Type:application/json

DateTime:2018-11-27 15:14:57:867 | ThreadId:47 | UserName:Fred | RequestID:0000000000000001000000000000000000000000000000 |
RemoteAddress:127.0.0.1 | LocalAddress:127.0.0.1
MessageType:RESPONSE
MessageSize:26
MessageData:{"payload":"HELLO_CALLER"}
Request URL: PUT https://localhost/zosConnect/services/HelloService?action=invoke
Headers: Content-Type:application/json

Procedure

Configure the zosconnect_fileSystemloggerInterceptor element globally.
```
<zosconnect_fileSystemloggerInterceptor id="globalFileSystemLogger" logName="globalLog_%SERVERNAME%"/>
    <zosconnect_zosConnectInterceptors id="globalInterceptorList" interceptorRef="globalFileSystemLogger" />
    <zosconnect_zosConnectManager globalInterceptorsRef="globalInterceptorList"/>
```
In the example, all z/OS Connect API and service requests are logged in a file that is called globalLog_myServer1.log, where myServer1 is the name of the server. The only required configuration element is the logName attribute definition. The configuration element accepts a %SERVERNAME% string that is replaced with the name of the server when the log is created. The default log file location is ${server.output.dir}/logs/zosConnect. For more information about available configuration attributes and default values, see zosconnect_fileSystemloggerInterceptor in the Reference section.
You can also configure the fileSystemloggerInterceptor element for specific APIs or services.
For example,
```
 <zosconnect_fileSystemloggerInterceptor id="serviceYFileSystemLogger"
                                 logName="service1Log"
                                 logPath="/zosConnect/logs"
                                 logOption="RESPONSE"
                                 maxPayloadSize="30720"/>
    <zosconnect_zosConnectInterceptors id="serviceYInterceptorList" interceptorRef="serviceYFileSystemLogger" />
    <zosconnect_zosConnectService serviceName="serviceY" serviceRef="serviceY" interceptorsRef="serviceYInterceptorList"/>
    <usr_myService id="serviceY"/>
```
In the example, information is logged in a file that is called service1Log.log, which is located in the path /zosConnect/logs. The log path is a fully qualified path. Only response data is logged for all incoming requests to that target serviceY. The maximum JSON payload is configured to be 30,720 characters, so any JSON response payload that is greater than 30,720 characters is truncated to the configured maximum payload size.
Optional: Configure the bufferedLogging and the bufferSize attributes to enable buffered logging. The default buffer size is 8 KB. All records in the buffer are flushed to the disk when the buffer becomes full. Using buffered logging is appropriate when performance is a concern and when it is acceptable for a possible loss of records from the buffer during a failure condition.
```
 <zosconnect_fileSystemloggerInterceptor id="globalFileSystemLogger"
                                 logName="globalLog_%SERVERNAME%"
                                 bufferedLogging="true"
                                 bufferSize="16384"/>
```
Optional: Configure the rollOffLogPolicy attribute.
This attribute defines when the active log file should be rolled off and a new file that is used for logging. The following options are valid:
- SIZE is the default setting. When the active log file reaches the specified size or default file size of 50 MB, it is rolled off to a new file that contains the date and time that the log was rolled over.
For example,
```
globalLog_myServer1_yyyy-MM-dd_HH_mm_ss_SSS.log
```
.
- DURATION The active log file is rolled off to a new file after the specified number of minutes or the default time of 24 hours. The new file contains the date and time that the log was rolled over.
For example,
```
globalLog_myServer1_yyyy-MM-dd_HH_mm.log
```
.
With the following configuration, a new file is created when the log file reaches 16 KB.
```
<zosconnect_fileSystemloggerInterceptor id="globalFileSystemLogger"
                                 logName="globalLog_%SERVERNAME%"
                                 rollOffLogPolicy="SIZE"
                                 rollOffLogPolicySize="16384"/>
```