Introduction
Using SMF records to monitor requests
z/OS® Connect EE can be configured to write SMF 123 records, which capture information about individual API provider, API requester and administration requests. This data can be used for auditing, workload monitoring, capacity planning, and problem determination.
Monitoring API provider and API requester requests
SMF 123 records have two subtypes and each subtype can have different versions.
SMF type 123 subtype 1 recordsVersion 1 contains some basic information about both API provider and API requester requests.Version 2 supersedes version 1 and contains more detailed information about each API provider request, including information about which system of record (SOR) the request was sent to. The version 2 record contains data for multiple requests in one record, making it more efficient as the server information is captured once per record rather than for each request.SMF type 123 subtype 2 recordsVersion 2 supersedes subtype 1 version 1 and contains more detailed information about each API requester request, including information about what HTTP endpoint the request was sent to. The version 2 record contains data for multiple requests in one record, making it more efficient as the server information is captured once per record rather than for each request.
Important: SMF 123 subtype 1 version 2 and SMF 123 subtype 2 version 2 together are known as version 2 of the SMF 123 records. Version 2 records contain data for multiple requests in a single SMF record. Therefore, the record is only written when either of the following conditions is met:
The server processes the required number of requests to fill a record. Currently this is 20.
The server is shutdown.
z/OS Connect EE provides the audit interceptor to capture SMF 123 records, see Configuring the audit interceptor. By default the audit interceptor captures version 1 records. To enable version 2 records, you must specify the required attributes for API provider and API requester.
CAUTION:
SMF 123 version 2 records are not a compatible extension of the version 1 records. Therefore, before you select version 2 of the records, check that the tools you use to format SMF 123 records support the version 2 format.
Monitoring administration requests
The audit interceptor monitors all administration requests sent to z/OS Connect EE. This includes administration requests for APIs, services and API requester resources.
Note: All administration requests are classified as API provider requests and are therefore written as SMF 123 subtype 1 records.
API provider data from SMF type 123 subtype 1 version 2 records.
The SMF type 123 subtype 1 version 2 record is used to capture enhanced data for individual API provider requests.
API requester data from SMF type 123 subtype 2 version 2 records.
The SMF type 123 subtype 2 version 2 record is used to capture enhanced data for individual API requester requests.
Request data from SMF type 123 subtype 1 version 1 records
The SMF type 123 subtype 1 version 1 record is used to capture some basic data for individual requests.
zOS Connect is a product used to make easier the interface between user applications and mainframe, and auditing is made through SMF record 123.
SMF 123 has 2 subtypes, subtype 1 used to list API Provider fields and subtype 2, used to list API requester fields.
Both subtypes can be produced with less and simple information, what is called VERSION 1, which is the default, and with more details and with more data (VERSION 2). To produce VERSION 2 SMF records is necessary to modify the configuration in zOS Connect parameters.
Fields
Stored in zcoap
| SMF Field | DB Column name | Description | Unit |
|---|---|---|---|
| zcohd_record_type | Value is always ZC01 | ||
| SMF123_SID | zcohd_sid | System ID from the SID parameter | |
| SMF123_DATE | zcohd_recorded_datetime | Date when record was moved into the SMF buffer | |
| SERVER_SYSTEM (V2) | zcohd_server_system | System name (CVTSNAME) | |
| SERVER_SYSPLEX (V2) | zcohd_server_sysplex | Sysplex name (ECVTSPLX) | |
| SERVER_JOBID | zcohd_server_job_id | Job ID of the server (JSABJBID) | |
| SERVER_JOBNAME (V2) | zcohd_server_jobname | Job name of the server (JSABJBNM) | |
| SERVER_STOKEN (V2) | zcohd_server_stoken | SToken of the server (ASS-BSTKN) | |
| SMF123_SERVER_CONFIG_DIR (V2) | zcohd_server_config_dir | The path to where server.xml for the server is located, this includes the server name | |
| SMF123_SERVER_VERSION (V2) | zcohd_server_version | Version of the server <v.r.m.f> | |
| TIME_ZC_ENTRY | zcoap_dttm_zc_entry | ARRIVAL DATE/TIME, FORMAT dd/mm/yyyy hh:mm:ss.ddd | |
| TIME_ZC_EXIT | zcoap_dttm_zc_exit | Completion datetime | |
| SMF123S1_TIME_SOR_SENT | zcoap_dttm_sor_sent | Datetime when the request was ready | |
| SMF123S1_TIME_SOR_RECV | zcoap_dttm_sor_recv | Datetime when response was received | |
| SMF123S1_HTTP_RESP_CODE | zcoap_http_resp_code | HTTP response code | |
| SMF123S1_RESP_FLAGS | zcoap_http_resp_flags | Response flags | |
| SMF123S1_USER_NAME | zcoap_user_name | Distributed or SAF ID | |
| SMF123S1_USER_NAME_MAPPED | zcoap_user_name_mapped | If a distributed ID was sent on the request and is mapped to a SAF username, then this value is the authenticated SAF username. Otherwise, this value is blank | |
| SMF123S1_CLIENT_IP_ADDR | zcoap_client_api_addr | Client IP address | |
| SMF123S1_API_NAME | zcoap_api_name | API name | |
| SMF123S1_API_VERSION | zcoap_api_version | API version | |
| SMF123S1_SERVICE_NAME | zcoap_service_name | z/OS asset name | |
| SMF123S1_SERVICE_VERSION | zcoap_service_version | z/OS asset version | |
| SMF123S1_REQ_METHOD | zcoap_req_method | Method GET/POST/PUT/DELETE | |
| SMF123S1_REQ_QUERY_STR | zcoap_req_query_str | Query string | |
| SMF123S1_REQ_TARGET_URI | zcoap_req_target_uri | Target URI | |
| SMF123S1_REQ_PAYLOAD_LEN | zcoap_req_payload_len | Request payload length | byte |
| SMF123S1_RESP_PAYLOAD_LEN | zcoap_resp_payload_len | Response payload length | byte |
| SMF123S1_SOR_REFERENCE | zcoap_sor_reference | Reference to the element in server.xml that identifies the connection to the system of record | |
| SMF123S1_SOR_IDENTIFIER | zcoap_sor_identifier | System of record identifier | |
| SMF123S1_REQ_ID | zcoap_req_id | Request identifier that is unique within a z/OS Connect server instance | |
| SMF123S1_REQ_TYPE | zcoap_req_type | Request Type
|
|
| SMF123S1_SP_NAME | zcoap_sp_name | Type of the z/OS asset |