Installing Z APM Connect request monitoring exits

First update the CICS TG environment, and install AGMServerExit, and AGMClientExit, the components of Z APM Connect request monitoring exits.

1. Update your CICS TG environment.
   1. Apply CICS TG maintenance that allows transaction tracking capabilities.
      • (Deprecated) For CICS TG V9.1, apply at least APAR PH12365/PTF UI65325.
      • For CICS TG V9.2 or later, apply APAR PH12635/PTF UI65916.
   2. In USS, locate your updated CICS TG libraries. Download ctgclient.jar and cicseci.rar.
   3. Move the ctgclient.jar file to the system that you plan to run client applications on. Replace the ctgclient.jar file that your client application previously used as a dependency with the newer one.
   4. Optional: Replace the CICS TG ECI resource adapter (if using) with the updated version.
2. Download the latest 6.2.0-INSTANA-FP<version_number>-plugins.tar.gz file delivered in the latest fix pack from Fix Central.
3. Extract the 6.2.0-INSTANA-FP<version_number>-plugins.tar.gz file with the following command:

   tar -xvzf 6.2.0-INSTANA-FP<version_number>-plugins.tar.gz

   The following two files are extracted:

   plugins
   ├── AGM-RequestExit.tar
   └── ibm-agm-tmra-plugin-6.2.0-V.jar

4. Extract the AGM-RequestExit.tar file with the following command:

   tar -xvzf AGM-RequestExit.tar

   The following files are extracted:

   AGM-RequestExit
   ├── AGM-RequestExit-Plugin.jar (for AppDynamics only)
   └── AGM-RequestExit.jar
   └── agmconfig.properties
   └── log4j2.xml

   • AGM-RequestExit.jar, which contains the AGMClientExit and AGMServerExit classes.
   • agmconfig.properties, a sample properties file that can be further configured for your monitoring flow.
   • log4j2.xml, a sample logging configuration file.

   Note: These files also exist on the host side, in the /usr/lpp/IBM/agm directory. The tar file is called AGMREQE.
5. Attach the Z APM Connect supplied client-side monitoring exit to your client application.
   1. Move the AGM-RequestExit.jar file to the machine that hosts your client application.
   2. Add AGM-RequestExit.jar to the classpath.
      If you use the CICS TG ECI resource adapter, add AGM-RequestExit.jar to the resource adapter's classpath instead of the client application's JVM.
   3. Add the following system properties to your client application's JVM:

      allow.unsigned.sdk.extension.jars=true

      AGM.CONF.LOCATION=

      AGM.CONF.LOCATION specifies a directory you want to use for Z APM Connect configuration.

   4. In your configuration directory specified by the environment variable AGM_CONF_LOCATION, add a .properties file named agmconfig.properties and set the property bootstrap.servers to the address of your Z APM Connect DG in the form of hostname:port.
      Note: A sample agmconfig.properties file is provided with AGM-RequestExit.tar.

      • If the Z APM Connect DG standalone Docker distribution is used, the hostname must be the fully qualified domain name (FQDN) of Z APM Connect DG; port must be set to 30090 to connect properly. For example,

        bootstrap.servers=DGM1.sub.company.ibm.com:30090

      • If the Z APM Connect DG cluster distribution is used, the hostname is the cluster's kafka ingress/route; if using OpenShift, port must be set to 443 to use OpenShift routes. For example,

        bootstrap.servers=kafka.apps.DGM2.sub.company.ibm.com:443

   5. When invoking your client application, attach the client exit by setting the system property requestExits to com.ibm.zapm.ctg.exit.AGMClientExit.
      For example,

      java -DrequestExits="com.ibm.zapm.ctg.exit.AGMClientExit" mySampleApplication

   6. Optional: If you are using the CICS TG ECI Resource Adapter, ensure that your J2C Connection Factory's property trackingtoken is set to true.
   7. Start the Instana agent to monitor your client application. AGMClientExit assumes that the client application is already traced by an Instana agent.
   8. Obtain an Instana Java SDK package. Add the built jar to the class path. If using the CTG ECI resource adapter, add the built jar to the resource adapter's classpath.
   9. Add the Z APM CICS TG tracking java package (com.ibm.zapm.ctg.exit) to your Instana agent's configuration.yaml. For more information about using the Instana java SDK package, see Using the instana-java-sdk.
6. Attach the Z APM Connect supplied server-side monitoring exit to your CICS TG.
   1. Move the AGM-RequestExit.jar file to the machine on which your CICS TG runs.
   2. Add the AGM-RequestExit.jar file to the classpath.
   3. In your CICS TG .ini file, add com.ibm.zapm.ctg.exit.AGMServerExit to the requestexits property.
   4. Add the following system property to your JVM:

      AGM.CONF.LOCATION=

      AGM.CONF.LOCATION specifies a directory you want to use for Z APM Connect configuration. If you are using an ENV file, you can add this property to the CTGSTART_OPTS parameters.
   5. In your configuration directory specified by the environment variable AGM_CONF_LOCATION, add a .properties file named agmconfig.properties and set the property bootstrap.servers to the address of your Z APM Connect DG in the form of hostname:port.
      Note: A sample agmconfig.properties file is provided with AGM-RequestExit.tar

      • If the Z APM Connect DG standalone Docker distribution is used, the hostname must be the fully qualified domain name (FQDN) of Z APM Connect DG; port must be set to 30090 to connect properly. For example,

        bootstrap.servers=DGM1.sub.company.ibm.com:30090

      • If the Z APM Connect DG cluster distribution is used, the hostname is the cluster's kafka ingress/route; if using OpenShift, port must be set to 443 to use OpenShift routes. For example,

        bootstrap.servers=kafka.apps.DGM2.sub.company.ibm.com:443

7. Check the z/OS system’s /etc/hosts file to be sure the hostname and IP of the DG are defined. For example,
   • If Z APM Connect DG is installed on a Linux Machine with Docker, specify

     10.11.12.13 DGM1.sub.company.ibm.com DGM1

   • If Z APM Connect DG is installed in OpenShift clusters, specify

     10.01.02.03    ingress.apps.DGM2.sub.company.ibm.com DGM2 
     10.01.02.03    kafka.apps.DGM2.sub.company.ibm.com   DGM2

AGMG0034D AGMClientExit completed initialization

AGMG0035I AGMServerExit completed initialization