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 zcoar
| SMF Field | DB Column name | Description | |
|---|---|---|---|
| zcohd_record_type | Value is always ZC02 | ||
| SMF123_SID | zcohd_sid | System ID from the SID parameter | |
| SMF123_DATE | zcohd_recorded_datetime | Date when record was moved into the SMF buffer | |
| SMF123_SERVER_SYSTEM (V2) | zcohd_server_system | System name (CVTSNAME) | |
| SMF123_SERVER_SYSPLEX (V2) | zcohd_server_sysplex | Sysplex name (ECVTSPLX) | |
| SMF123_SERVER_JOBID | zcohd_server_job_id | Job ID of the server (JSABJBID) | |
| SMF123_SERVER_JOBNAME (V2) | zcohd_server_jobname | Job name of the server (JSABJBNM) | |
| SMF123_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> | |
| SMF123S2_REQ_APP_TYPE | zcoar_req_app_type | Request Type
|
|
| SMF123S2_TIME_ZC_ENTRY | zcoar_zc_entry_datetime | Time of z/OS Connect Entry | |
| SMF123S2_TIME_ZC_EXIT | zcoar_zc_exit_datetime | Time of z/OS Connect Exit | |
| SMF123S2_TIME_STUB_SENT | zcoar_stub_sent_datetime | Time the request left the calling application | |
| SMF123S2_TIME_TOKEN_GET_START | zcoar_token_get_start_datetime | Time z/OS Connect started to obtain one or more access tokens | |
| SMF123S2_TIME_TOKEN_GET_FINISH | zcoar_token_get_finish_datetime | Time z/OS Connect completed obtaining the access token(s) | |
| SMF123S2_TIME_ENDPOINT_SENT | zcoar_endpoint_sent_datetime | Time z/OS Connect sent the request to the endpoint | |
| SMF123S2_TIME_ENDPOINT_RECEIVED | zcoar_endpoint_received_datetime | Time z/OS Connect received a response from the endpoint | |
| SMF123S2_HTTP_RESP_CODE | zcoar_http_resp_code | HTTP response code returned from the API endpoint | |
| SMF123S2_REQ_STATUS_CODE | zcoar_req_status_code | HTTP status code that is returned to the z/OS application | |
| SMF123S2_RESP_FLAGS | zcoar_resp_flags | Response flags | |
| SMF123S2_USER_NAME | zcoar_user_name | Distributed or SAF ID | |
| SMF123S2_USER_NAME_MAPPED | zcoar_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 | |
| SMF123S2_USER_NAME_ASSERTED | zcoar_user_name_asserted | z/OS application asserted user ID | |
| SMF123S2_API_REQ_NAME | zcoar_api_req_name | API requester name | |
| SMF123S2_API_REQ_VERSION | zcoar_api_req_version | API requester version | |
| SMF123S2_ENDPOINT_REFERENCE | zcoar_endpoint_reference | Reference to the element in server.xml that identifies the connection to the API endpoint | |
| SMF123S2_ENDPOINT_HOST | zcoar_endpoint_host | The value of the host property of the API endpoint | |
| SMF123S2_ENDPOINT_PORT | zcoar_endpoint_port | The value of the port property of the API endpoint | |
| SMF123S2_ENDPOINT_FULL_PATH | zcoar_endpoint_full_path | The full path invoked on the API endpoint | |
| SMF123S2_ENDPOINT_METHOD | zcoar_endpoint_method | The HTTP method used for the API endpoint request, GET/POST/PUT/DELETE/OPTIONS | |
| SMF123S2_ENDPOINT_QUERY_STRING | zcoar_endpoint_query_string | The query string that is passed to the API endpoint | |
| SMF123S2_REQ_PAYLOAD_LEN | zcoar_req_payload_len | Length of the request payload sent to the API endpoint | byte |
| SMF123S2_RESP_PAYLOAD_LEN | zcoar_resp_payload_len | Length of the response payload received from the API endpoint | byte |
| SMF123S2_MVS_JOBNAME | zcoar_mvs_jobname | MVS Job Name of the calling application (JSAB -> JSABJBNM) | |
| SMF123S2_MVS_JOBID | zcoar_mvs_jobid | MVS Job ID of the calling application (JSAB -> JSABJBID) | |
| SMF123S2_MVS_SYSNAME | zcoar_mvs_sysname | MVS System Name of the calling application (CVT -> CVTSNAME) | |
| SMF123S2_MVS_ASID | zcoar_mvs_asid | MVS ASID of the calling application (ASCB -> ASCBASID) | |
| SMF123S2_MVS_SID | zcoar_mvs_sid | MVS SID of the calling application (SMCA -> SMCASID) | |
| SMF123S2_CICS_APPLID | zcoar_cics_applid | The APPLID of the CICS region | |
| SMF123S2_CICS_TASK_NUMBER | zcoar_cics_task_number | The CICS task number of the calling application | |
| SMF123S2_CICS_TRANSID | zcoar_cics_transid | The CICS transaction ID of the calling application | |
| SMF123S2_CICS_RMUOWID | zcoar_cics_rmuowid | The CICS Recovery Manager UOW ID of the calling application | |
| SMF123S2_IMS_IDENTIFIER | zcoar_ims_identifier | The identifier from the execution parameters of the calling application | |
| SMF123S2_IMS_REGION_ID | zcoar_ims_region_id | The region identifier of the calling application | |
| SMF123S2_IMS_TRANSNAME | zcoar_ims_transname | The transaction name of the calling application | |
| SMF123S2_IMS_APPNAME | zcoar_ims_appname | The name of the application | |
| SMF123S2_IMS_PSBNAME | zcoar_ims_psbname | The name of the PSB | |
| SMF123S2_IMS_RECOVERY_TOKEN | zcoar_ims_recovery_token | The recovery token for the UOW of the calling application | |
| SMF123S2_REQ_ID | zcoar_req_id | Request identifier that is unique within a z/OS Connect server instance |