Install the z/OS Java code module

The z/OS Java code module traces incoming web requests on WebSphere Application Server and WebSphere Liberty.

It traces requests to CICS SOAP, CICS Transaction Gateway, IMS SOAP Gateway.
It traces messages of IBM MQ and JMS (Java Message Service), and database calls via JDBC.
It traces outgoing web requests via Apache HttpClient, and outgoing CICS Transaction Gateway requests via CICS Transaction Gateway client.

The z/OS Java code module traces incoming web requests on z/OS Connect Enterprise Edition.

It traces outgoing requests to CICS and IMS.

Requirements

Activate the OneAgent feature Forward Tag 4 trace context extension.
- Note: All OneAgent code modules participating in a trace must meet the minimum OneAgent version of 1.193 for this setting.

Download

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

In the Dynatrace menu, select Deploy Dynatrace > OneAgent > Download OneAgent > z/OS.
Download the JAR file (dynatrace-oneagent-zos-java.jar) and transfer it to your mainframe in binary mode.
Create a new file with the name dtconfig.json in the folder on your mainframe where the code module is located.
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:
```
json
{
  "Tenant": "mytenant",
  "ClusterID": 11223344,
  "ZdcName": "DEFAULT"
}
```
If the zDC name is defined as DEFAULT, the code 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 subsystem ID in the SYSIN parameters of your zDC JCL (the default is MEPC).
```
plaintext
//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.

Notes

EBCDIC 1047, UTF-8, and ASCII encodings are supported for the dtconfig.json file.
The code module automatically reads dtconfig.json when it's placed in the same folder as dynatrace-oneagent-zos-java.jar.
If you put dtconfig.json in a different folder, you need to specify the path to it via the environment variable DT_CONFIG_FILE. The path must include the filename. You can use an absolute path or a path relative to the working folder of the process.

Installation

Application server

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

WebSphere Application ServerWebSphere LibertyWebSphere Liberty inside a CICS region

Open the WebSphere Application Server Admin Console and navigate to Application servers.
Select <YOUR_SERVER> > Process definition > Servant, and choose Java Virtual Machine.
Copy the JVM argument from your Dynatrace environment and paste it into the Generic JVM arguments:
```
shell
-javaagent:/PATH_TO/dynatrace-oneagent-zos-java.jar
```
Replace PATH_TO with the path to your JAR file.
Save the changes and restart your WebSphere Application Server.

Notes

It's only necessary to add the code module to the Servant processes.
We recommend adding the code module as the first JVM argument.
The code module must not be appended at the end of the command line.

Create the jvm.options file in the root folder of your WebSphere Liberty (this folder typically also contains the server.xml file) or edit an existing file.
Copy the JVM argument from your Dynatrace environment and paste it into the jvm.options file:
```
console
-javaagent:/PATH_TO/dynatrace-oneagent-zos-java.jar
```
Replace PATH_TO with the path to your JAR file.
Add the monitor-1.0 feature to your featureManager in the server.xml file to collect additional metrics like connection pools or thread pools:
```
xml
<server>
    <featureManager>
      <feature>monitor-1.0</feature>
    </featureManager>
</server>
```
Save the changes and restart your WebSphere Liberty.

Notes

We recommend to add the code module as the first JVM argument.
The code module must not be appended at the end of the command line.
We use the WebSphere Liberty server name as process group instance name per default. If you want to use a different process group instance name, you can override it by adding the following system property to your JVM command line: -Dwlp.server.name=yourServerName. Replace yourServerName with your individual name.

Create the .jvmprofile file in your CICS region that belongs to the CICS JVMSERVER that is executing WebSphere Liberty or edit an existing file.
Copy the JVM argument from your Dynatrace environment and paste it into the .jvmprofile file:
```
shell
-javaagent:/PATH_TO/dynatrace-oneagent-zos-java.jar
```
Replace PATH_TO with the path to your JAR file.
Add the monitor-1.0 feature to your featureManager in the server.xml file to collect additional metrics like connection pools or thread pools:
```
xml
<server>
    <featureManager>
      <feature>monitor-1.0</feature>
    </featureManager>
</server>
```
Save the changes and restart your WebSphere Liberty.

Notes

Monitoring of both the CICS region and the WebSphere Liberty that operates inside this CICS region is not supported. You need to decide between CICS region monitoring or WebSphere Liberty monitoring.
The WebSphere Liberty server name cannot be detected when it operates inside a CICS region. This will be addressed in the future.

Middleware

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

z/OS Connect Enterprise EditionCICS Transaction GatewayIMS SOAP Gateway

Add the code module to the JVM_OPTIONS STDENV variable:
```
shell
JVM_OPTIONS=-javaagent:/PATH_TO/dynatrace-oneagent-zos-java.jar
```
Replace PATH_TO with the path to your JAR file.
optional Add the monitor-1.0 feature to your featureManager in the server.xml file to collect additional metrics like connection pools or thread pools:
```
xml
<server>
    <featureManager>
      <feature>monitor-1.0</feature>
    </featureManager>
</server>
```
Save the changes and restart your z/OS Connect Enterprise Edition.
For the CICS service provider, activate the OneAgent feature z/OS CICS z/OS Connect.
OneAgent version 1.235+ For the IMS service provider:
1. Add the IMS code module to IMS Connect as described in Install the IMS code module.
2. Activate the OneAgent feature z/OS IMS z/OS Connect.

Add the code module to the CTGENV member and to the CTGSTART_OPTS variable:
```
shell
-j-javaagent:/PATH_TO/dynatrace-oneagent-zos-java.jar
```
Replace PATH_TO with the path to your JAR file.
Save the changes and restart your CICS Transaction Gateway.

Notes

Only the EXCI and IPIC protocols are supported.
WAS local mode configuration of the CICS Transaction Gateway configuration is not supported.

Add the code module as a zDT option to the IMS SOAP Gateway parameters:
```
shell
zDT="-javaagent:/PATH_TO/dynatrace-oneagent-zos-java.jar"
```
Replace PATH_TO with the path to your JAR file.
Export the defined zDT option so that IBM_JAVA_OPTIONS includes it.
```
shell
export IBM_JAVA_OPTIONS="$zDT $JAVA_OPTS"
```
Save your changes and restart the IMS SOAP Gateway.

OneAgent version 1.243+ JDBC database calls

By default, tracing of JDBC database calls is disabled for the z/OS Java code module.

To activate JDBC database calls tracing, add DisableJdbctransformer to your dtconfig.json file. For example

json
{
  "Tenant": "mytenant",
  "ClusterID": 11223344,
  "ZdcName": "DEFAULT",
  "DisableJdbctransformer": false
}

Note

Only the DB2 JDBC driver types 2 and 4 are supported.

Logging

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

Option	Default value	Description
log-stdout	`false`	If `true`, write logs to the standard output stream.
log-stderr	`false`	If `true`, write logs to the standard error stream.
log-file	`false`	If `true`, write logs to a file using file rotation (persisting the file with index 0). Naming scheme: `dynatrace-oneagent-java.<PID>.<LPAR>.<INDEX>.log`.

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

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

Option Default value Description

log-file-dir

Option	Default value	Description
log-file-dir	`<CODEMODULE_FOLDER>/logs`	By default, write log files to the z/OS Java code module folder. It's also possible to write the log files to an absolute path (schema: `/<PATH_TO>/logs`) or to a path relative to the working folder of the process (schema: `<PATH_TO>/logs`).

<CODEMODULE_FOLDER>/logs

By default, write log files to the z/OS Java code module folder.

It's also possible to write the log files to an absolute path (schema: /<PATH_TO>/logs) or to a path relative to the working folder of the process (schema: <PATH_TO>/logs).

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:

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

Notes

Ensure that the application server has appropriate write permissions for the folder where the code module should write the log files.
The zDC may be located at a different location in your installation.

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:

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

This usually means that the z/OS Java code module must be program controlled.

To define the code module to be program controlled:

Expand dynatrace-oneagent-zos-java.jar that you downloaded into a program controlled folder.
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:
```
console
extattr +p libdynatrace-oneagent-odin-java_64.so
```
Add zos-native-library-override to your JVM argument.
```
plaintext
-javaagent:/PATH_TO/dynatrace-oneagent-zos-java.jar=zos-native-library-override=<PATH_TO_SO>/<FILE>.so
```
1. Replace <PATH_TO> with the path to your JAR file.
2. Replace <PATH_TO_SO> with the absolute path to the .so file that you marked program controlled.
3. Replace <FILE> with libdynatrace-oneagent-odin-java_64.
Restart the application server.