diff --git a/versioned_docs/version-v2.18.x/user-guide/api-mediation/wto-message-on-startup.md b/versioned_docs/version-v2.18.x/user-guide/api-mediation/wto-message-on-startup.md new file mode 100644 index 0000000000..ada571d80a --- /dev/null +++ b/versioned_docs/version-v2.18.x/user-guide/api-mediation/wto-message-on-startup.md @@ -0,0 +1,108 @@ +# Configuring initial API Mediation Layer startup message for Syslog + +:::info Role: system programmer +::: + +:::note Functionality of this feature is available from Zowe 2.18. +::: + +Startup of the API Mediation Layer can be configured to present a message in the Syslog that the API Mediation Layer is started and ready. This setup is typically used in combination with Workload Automation tools to manage the lifecycle of Zowe. + +This functionality requires the following changes to the zowe.yaml: + +1. Change the property `zowe.sysMessages` by adding the value `- "ZWEAM001I"` + ``` + zowe: + # >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> + # You can define any Zowe message portions to be checked for and the message added to the + # system log upon its logging, truncated to 126 characters. + sysMessages: + - "ZWEAM001I" + ``` + This property change ensures that the message containing `ZWEAM001I` is presented in the Syslog. + + **Example of the Syslog:** + + `2024-09-30 10:17:53.814 jb892003 INFO ((o.z.a.g.c.GatewayHealthIndicator)) ZWEAM001I API Mediation Layer started` + +2. Prepare custom logging configuration. + The current default logging implementation starts with information about the current time. This message content is unlike the message id which is typical in z/OS. To change this message behavior, it is necessary to change the logback.xml configuration. The following example shows the custom logback.xml which prepends the message with the first 9 characters of the message. + + **Example:** + + ``` + + + + + + + + + + + + + + + + + + 0 + + + + + + + + ${apimlLogPattern} + + + + + + ${STORAGE_LOCATION}/${logbackServiceName}.log + + + ${STORAGE_LOCATION}/${logbackServiceName}.%i.log + ${MIN_INDEX} + ${MAX_INDEX} + + + + ${MAX_FILE_SIZE} + + + + + ${apimlLogPattern} + + + + + + + + + + ``` + Custom configuration that changes the structure of the message to prepend 9 characters to the beginning is prepared. + + :::tip + For detailed information about how to provide this changed configuration, see [Customizing Zowe API Mediation Layer logging](./configuration-logging.md). + ::: + +3. Validate that API Mediation Layer properly uses this new configuration for the Gateway service, which issues the message that the API Mediation Layer started. + + ``` + components: + gateway: + logging: + config: /path/to/logback.xml + ``` + +You successfully changed the structure of the log message if you see the message `ZWEAM001I` in the Syslog when the API Mediation Layer fully starts and is ready to handle requests. + +**Message example:** +`ZWEAM001I 2024-09-30 10:17:53.814 jb892003 INFO ((o.z.a.g.c.GatewayHealthIndicator)) ZWEAM001I API Mediation Layer started` diff --git a/versioned_sidebars/version-v2.18.x-sidebars.json b/versioned_sidebars/version-v2.18.x-sidebars.json index 14715cb666..4d61b540d6 100644 --- a/versioned_sidebars/version-v2.18.x-sidebars.json +++ b/versioned_sidebars/version-v2.18.x-sidebars.json @@ -388,7 +388,8 @@ ] }, "user-guide/api-mediation/configuration-customizing-the-api-catalog-ui", - "user-guide/api-mediation/configuration-logging" + "user-guide/api-mediation/configuration-logging", + "user-guide/api-mediation/wto-message-on-startup" ] } ]