Install OneAgent for Java on z/OS

The Java code module of OneAgent traces web requests on WebSphere Application Server and WebSphere Liberty (incoming requests via Servlets and outgoing requests via Apache HTTP client). It traces requests to CICS SOAP, CICS Transaction Gateway, IBM MQ and IMS SOAP Gateway. It traces outgoing CICS Transaction Gateway requests via CTG client.

The Java code module also traces incoming web requests on z/OS Connect Enterprise Edition and outgoing requests to CICS (via the CICS service provider).

Requirements

• You need a zDC. See Install the zDC for details.
• You need a zRemote. See Install the zRemote for details.
• Forward Tag 4 trace context extension is a required Deep monitoring setting. Please confirm it in New OneAgent features. If it's already confirmed but disabled, enable it in Troubleshooting.

Download OneAgent

You can directly download OneAgent from your Dynatrace environment as described below:

1. In the Dynatrace menu, select Deploy Dynatrace.

2. Select OneAgent > Download OneAgent, and choose z/OS.

3. Download OneAgent (dynatrace-oneagent-zos-java.jar) and transfer it to your mainframe in binary mode.

4. Create a new file with the name dtconfig.json in the OneAgent folder of your mainframe.

5. Paste the provided connection details from your Dynatrace environment into this file.

   A minimal dtconfig.json file contains your Dynatrace environment ID (Tenant), cluster ID (ClusterID), and zDC name (ZdcName). For example:

   dnscopydownload
   {
     "Tenant": "mytenant",
     "ClusterID": 11223344,
     "ZdcName": "DEFAULT"
   }

   If the zDC name is defined as DEFAULT, OneAgent will connect to the default zDC subsystem ID. To use a different zDC, replace DEFAULT with an alternative subsystem ID.

   You can find the subsystem ID in the SYSIN parameters of your zDC JCL (the default is MEPC).

   dnscopydownload
   //SYSIN   DD DISP=SHR,DSN=hlq.LZDT720.SZDTSAMP(ZDCSYSIN)
   
   SUBSYSTEM_ID(MEPC)
   DEFAULT(YES)

   If DEFAULT is set to YES in the SYSIN parameters, then you can also use DEFAULT in the dtconfig.json file.

Add OneAgent to WebSphere Application Server

Add OneAgent to the JVM arguments of each WebSphere Application Server that you want to monitor. JVM arguments can be specified in the WebSphere Application Server Admin Console.

1. Open the WebSphere Application Server Admin Console and navigate to Application servers.

   Select <YOUR_SERVER> > Process definition > Servant, and choose Java Virtual Machine.

2. Copy the OneAgent JVM argument from your Dynatrace environment and paste it into the Generic JVM arguments:

   dnscopydownload
   -javaagent:/PATH_TO/dynatrace-oneagent-zos-java.jar

   Replace PATH_TO with the path to your OneAgent file.

3. Save the changes and restart your WebSphere Application Server.

Add OneAgent to WebSphere Liberty

Add OneAgent to the JVM arguments of each WebSphere Liberty that you want to monitor. You can specify JVM arguments in the jvm.options file from the root folder of your WebSphere Liberty server instance.

1. Edit or create the jvm.options file in the root folder of your WebSphere Liberty server instance (this folder typically also contains the server.xml file).

2. Copy the OneAgent JVM argument from your Dynatrace environment and paste it into the jvm.options file:

   dnscopydownload
   -javaagent:/PATH_TO/dynatrace-oneagent-zos-java.jar

   Replace PATH_TO with the path to your OneAgent file.

3. Add the monitor-1.0 feature to your featureManager in the server.xml file to enable metrics:

   dnscopydownload
   <server>
       <featureManager>
          <feature>monitor-1.0</feature>
       </featureManager>
   </server>

4. Save the changes and restart your WebSphere Liberty.

Add OneAgent to CICS Transaction Gateway

OneAgent version 1.215+ Dynatrace version 1.216+

Add OneAgent to each CICS Transaction Gateway that you want to monitor.

1. Add OneAgent to the CTGENV member and to the CTGSTART_OPTS variable:

   dnscopydownload
   -j-javaagent:/PATH_TO/dynatrace-oneagent-zos-java.jar

   Replace PATH_TO with the path to your OneAgent file.

2. Save the changes and restart your CICS Transaction Gateway.

Add OneAgent to IMS SOAP Gateway

OneAgent version 1.215+ Dynatrace version 1.216+

Add OneAgent to each IMS SOAP Gateway that you want to monitor.

1. Add OneAgent as zDT option to the IMS SOAP Gateway parameters:

   dnscopydownload
   zDT="-javaagent:/PATH_TO/dynatrace-oneagent-zos-java.jar"

   Replace PATH_TO with the path to your OneAgent file.

2. Export the defined zDT option so that the IBM_JAVA_OPTIONS include it.

   dnscopydownload
   export IBM_JAVA_OPTIONS="$zDT $JAVA_OPTS"

3. Save the changes and restart your IMS SOAP Gateway.

Add OneAgent to z/OS Connect Enterprise Edition

OneAgent version 1.223+ Dynatrace version 1.224+

Add OneAgent to each z/OS Connect Enterprise Edition that you want to monitor.

1. Add OneAgent to the JVM_OPTIONS STDENV variable:

   dnscopydownload
   JVM_OPTIONS=-javaagent:/PATH_TO/dynatrace-oneagent-zos-java.jar

   Replace PATH_TO with the path to your OneAgent file.

2. Save the changes and restart your z/OS Connect Enterprise Edition.

Enable logging

By default, logging is disabled for the Java code module of OneAgent. To enable logging, add one of the following options to the JVM argument:

If needed, you can log to multiple locations. For example:

dnscopydownload
-javaagent:/PATH_TO/dynatrace-oneagent-zos-java.jar=log-stdout=true,log-file=true

If needed, you can customize the file logging with the following options:

OneAgent diagnostics

We recommend to write the logs to the shared log folder of the zDC so that they are included into the OneAgent diagnostics workflow. For example, if the dtzagent binary is located at /u/dt/agent/lib64/dtzagent, the log folder is /u/dt/log. Typically, a shared zDC log folder already exists and contains some zDC logs.

To enable file logging to an absolute path such as the shared zDC log folder /u/dt/log on your mainframe, specify the JVM arguments as follows:

dnscopydownload
-javaagent:/PATH_TO/dynatrace-oneagent-zos-java.jar=log-file=true,log-file-dir=/u/dt/log

JVM is executing in a program controlled environment

After starting the application server that you want to monitor, you might see Not Marked Program Controlled messages or errors with the return code 139:

dnscopydownload
BPXP015I HFS PROGRAM /tmp/libdynatrace-oneagent-odin-java5848811742465559217.so
IS NOT MARKED PROGRAM CONTROLLED.

This usually means that OneAgent must be program controlled.

To define OneAgent to be program controlled:

1. Expand dynatrace-oneagent-zos-java.jar that you downloaded into a program controlled folder.

2. Mark the appropriate .so file (31 or 64 bit) in the lib/zos-s390/ directory as program controlled.

   Switch to the path that contains the .so files and issue the following command using the 31 or 64 bit file:

   dnscopydownload
   extattr +p libdynatrace-oneagent-odin-java_64.so

3. Add to the -javaagent argument:

   dnscopydownload
   ,zos-native-library-override=<PATH_TO>/<FILE>.so

   Replace <PATH_TO> with the absolute path to the .so file that you marked program controlled.

   Replace <FILE> with libdynatrace-oneagent-odin-java_64.

4. Restart the application server.

Known limitations

Known limitations of the Java code module of OneAgent:

• It doesn't support runtime settings.