Install the z/OS Java module

With the z/OS Java module, you can get observability for your Java applications including IBM MQ and database calls.

Prerequisite

Activate the OneAgent feature Forward Tag 4 trace context extension.

Download

You can directly download the z/OS Java module from your Dynatrace environment as described below:

1. In the Dynatrace menu, select Deploy Dynatrace > OneAgent > Download OneAgent > z/OS.

2. Download the JAR file (dynatrace-oneagent-zos-java.jar) and transfer it to your z/OS Unix System Services (USS) environment in binary mode.

3. Create a new file with the name dtconfig.json in the z/OS USS folder where the module is located.

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

   jsoncopydownload
   {
     "Tenant": "<tenant>",
     "ClusterID": <cluster>,
     "ZdcName": "DEFAULT"
   }

   Replace <tenant> and cluster with your Dynatrace environment values (see step 1 on where to get them).

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

   You can find the zDC subsystem name in the SYSIN parameters of your JCL SYSIN member ZDCSYSIN. The default zDC subsystem name is MEPC.

   plaintextcopydownload
   //SYSIN DD DISP=SHR,DSN=<hlq>.SZDTSAMP(ZDCSYSIN)
   
   SUBSYSTEM_ID(MEPC)
   DEFAULT(YES)

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

Installation

Application server

You need to add the z/OS Java module to the JVM arguments of each application server that you want to monitor.

Middleware

You need to add the z/OS Java module to each product that you want to monitor.

JDBC database calls tracing

z/OS Java module version 1.243+ Tracing of JDBC database calls requires an opt-in.

z/OS Java module version 1.251+ Tracing of JDBC database calls is activated per default, no opt-in is required.

To opt-in for JDBC database calls tracing, add DisableJdbctransformer to your dtconfig.json file with the value false. For example

jsoncopydownload
{
  "DisableJdbctransformer": false
}

Logging

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

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

bashcopydownload
-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:

By changing the default folder, ensure that the application server has appropriate write permissions for the folder in which the module should write the log files.

OneAgent diagnostics

Dynatrace recommends 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 in the z/OS USS environment, 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, specify the JVM argument as follows:

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

If your zDC is installed in a different location, you must adopt the absolute path of the shared zDC log folder.

Update

To update your z/OS Java module to a newer version

1. Download the JAR file from your Dynatrace environment and transfer it to your z/OS USS environment in binary mode.
2. Stop your monitored application server or middleware.
3. Replace your current JAR file with the new JAR file.
4. Start your application server or middleware.

Troubleshooting

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

jsoncopydownload
{
  "Sensors": {
    "Enable": {
      "CTG": {
        "Server": "false",
        "Client": "false"
      },
      "HttpClient": {
        "Apache": "false"
      },
      "JDBC": "false",
      "JMS": "false",
      "IbmMQ": "false",
      "Servlet": "false",
      "ZosConnect": "false"
    }
  }
}