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.

Observability for	Including
WebSphere Application Server WebSphere Liberty	Incoming web requests on WebSphere Application Server and Liberty Outgoing web requests from WebSphere Application Server and Liberty via the Apache HttpClient Outgoing CICS Transaction Gateway requests from WebSphere Application Server and Liberty via the CTG client Websphere Application Server Websphere Liberty specific metrics (PMI and JMX) JVM specific managed memory metrics (JMX)
z/OS Connect	Incoming web requests on z/OS Connect Outgoing requests from z/OS Connect via the CICS, IMS, and IBM MQ service providers z/OS Connect specific metrics (JMX) JVM specific managed memory metrics (JMX)
CICS/IMS transactions	Transactions initiated using IBM MQ and JMS CICS SOAP and CICS Transaction Gateway IMS SOAP Gateway
Database calls	Database calls with their SQL statements from Java applications to Db2 via JDBC

Analyze the performance of your transactions end-to-end using the Service flow.

Use the PurePath distributed traces to drill down to the code level and to optimize your programs.

Quickly detect anomalies with the Service response time hotspots.

Analyze failures and exceptions with detailed stack traces.

Gain insights into your JVM with the Dynatrace managed memory metrics:

Understand the health and performance of your application servers with technology-specific metrics:

JVM specific metrics:

Metric group	Metric	Source
JVM memory	Garbage collection total activation count	JMX
JVM memory	Garbage collection total collection time	JMX
JVM memory pool	Garbage collection count	JMX
JVM memory pool	Garbage collection time	JMX
JVM memory pool	Heap memory pool maximum bytes	JMX
JVM memory pool	Heap memory pool committed bytes	JMX
JVM memory pool	Heap memory pool used bytes	JMX
JVM memory runtime	Runtime maximum memory	JMX
JVM memory runtime	Runtime total memory	JMX
JVM memory runtime	Runtime free memory	JMX
JVM threads	Thread count	JMX
JVM classes	Total number of loaded classes	JMX
JVM classes	Number of loaded classes	JMX
JVM classes	Number of unloaded classes	JMX

WebSphere Liberty and z/OS Connect specific metrics:

Metric group	Metric	Metric description	Source
JDBC connection pool	In use connections	The number of connections in use. This number might include multiple connections that are shared from a single managed connection.	JMX
JDBC connection pool	Free connections	The number of managed connections in the free pool.	JMX
JDBC connection pool	Managed connections	The total number of managed connections in the free, shared, and unshared pools.	JMX
JDBC connection pool	In use time	The average time in milliseconds that a connection is in use.	JMX
JDBC connection pool	Wait time	The average waiting time in milliseconds until a connection is granted if a connection is not currently available.	JMX
Thread pool	Pool size	The average number of threads in pool.	JMX
Thread pool	Active threads	The number of active threads that are serving requests.	JMX
Servlet	Request count	The total number of requests that a servlet processed.	JMX

Websphere Application Server specific metrics:

Metric group	Metric	Metric description	Source
JDBC connection pool	Pool size	The size of the connection pool.	PMI
JDBC connection pool	Free pool size	The number of managed connections that are in the free pool.	PMI
JDBC connection pool	Concurrent waiters	The number of threads that are currently waiting for a connection.	PMI
JDBC connection pool	Average wait time	The average waiting time in milliseconds until a connection is granted if a connection is not currently available.	PMI
JDBC connection pool	Average use time	The average time in milliseconds that a connection is in use.	PMI
JDBC connection pool	Percent used	The percent of the pool that is in use.	PMI
Thread pool	Pool size	The average number of threads in pool.	PMI
Thread pool	Active threads	The number of concurrently active threads.	PMI
Servlet	Live sessions	The number of local sessions that are currently cached in memory from the time at which this metric is enabled.	PMI
Servlet	Total requests	The total number of requests that a servlet processed.	PMI

Yes, you can use the z/OS Java module to monitor custom JMX metrics. For more information, see Monitor JMX metrics on z/OS.

Prerequisite

Activate the OneAgent feature Forward Tag 4 trace context extension.

Download

Download z/OS product datasets and extract the JAR file (dynatrace-oneagent-zos-java.jar).
Transfer the JAR file to your z/OS Unix System Services (USS) environment in binary mode.
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:
```
1{
2  "Tenant": "<tenant>",
3  "ClusterID": <cluster>,
4  "ZdcName": "DEFAULT"
5}
```
Replace <tenant> and <cluster> with your Dynatrace environment values. To find these values, in the Dynatrace menu, go to Deploy Dynatrace > Start installation > z/OS.

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.
```
1//SYSIN DD DISP=SHR,DSN=<hlq>.SZDTSAMP(ZDCSYSIN)
2
3SUBSYSTEM_ID(MEPC)
4DEFAULT(YES)
```
If DEFAULT is set to YES in the SYSIN parameters, you can also use DEFAULT in the dtconfig.json file.

EBCDIC 1047, UTF-8, and ASCII encodings are supported for the dtconfig.json file.
The 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 module to the JVM arguments of each application server that you want to monitor.

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:
```
1-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.

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

Middleware

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

Add the module to the JVM_OPTIONS STDENV variable:
```
1JVM_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:
```
1<server>
2    <featureManager>
3      <feature>monitor-1.0</feature>
4    </featureManager>
5</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.
z/OS Java module version 1.235+ For the IMS service provider:
1. Add the IMS module to IMS Connect as described in Install the IMS module.
2. Activate the OneAgent feature z/OS IMS z/OS Connect.
z/OS Java module version 1.251+ For the MQ service provider, no additional configuration is needed.

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

1{
2  "DisableJdbctransformer": false
3}

Limitation

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

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:

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:

1-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

Option	Default value	Description
log-file-dir	`<CODEMODULE_FOLDER>/logs`	By default, write log files to the z/OS Java 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`).

log-file-dir

<CODEMODULE_FOLDER>/logs

By default, write log files to the z/OS Java 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).

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:

1-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

Download z/OS product datasets and transfer the JAR file (dynatrace-oneagent-zos-java.jar) to your z/OS USS environment in binary mode.
Stop your monitored application server or middleware.
Replace your current JAR file with the new JAR file.
Start your application server or middleware.

Troubleshooting

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:

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

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

To define the 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:
```
1extattr +p libdynatrace-oneagent-odin-java_64.so
```
Add zos-native-library-override to your JVM argument.
```
1-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 your application server.

z/OS Java module version 1.251+

All sensors of the z/OS Java module are enabled per default. In case of problems, you can disable specific sensors via the dt.config.json file by setting their value to false. For example

1{
2  "Sensors": {
3    "Enable": {
4      "CTG": {
5        "Server": "false",
6        "Client": "false"
7      },
8      "HttpClient": {
9        "Apache": "false"
10      },
11      "JDBC": "false",
12      "JMS": "false",
13      "IbmMQ": "false",
14      "Servlet": "false",
15      "ZosConnect": "false"
16    }
17  }
18}