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 |
|
z/OS Connect |
|
CICS/IMS transactions | Transactions initiated using
|
Database calls | Database calls with their SQL statements from Java applications to Db2 via JDBC |
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:
-
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 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:{ "Tenant": "<tenant>", "ClusterID": <cluster>, "ZdcName": "DEFAULT" }
Replace
<tenant>
andcluster
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, replaceDEFAULT
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 isMEPC
.//SYSIN DD DISP=SHR,DSN=<hlq>.SZDTSAMP(ZDCSYSIN) SUBSYSTEM_ID(MEPC) DEFAULT(YES)
If
DEFAULT
is set toYES
in the SYSIN parameters, you can also useDEFAULT
in thedtconfig.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 asdynatrace-oneagent-zos-java.jar
. - If you put
dtconfig.json
in a different folder, you need to specify the path to it via the environment variableDT_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:
-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.
-
Create the
jvm.options
file in the root folder of your WebSphere Liberty (this folder typically also contains theserver.xml
file) or edit an existing file. -
Copy the JVM argument from your Dynatrace environment and paste it into the
jvm.options
file:-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 yourfeatureManager
in theserver.xml
file to collect additional metrics like connection pools or thread pools:<server> <featureManager> <feature>monitor-1.0</feature> </featureManager> </server>
-
Save the changes and restart your WebSphere Liberty.
- We recommend to add the module as the first JVM argument.
- The 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
. ReplaceyourServerName
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:-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 yourfeatureManager
in theserver.xml
file to collect additional metrics like connection pools or thread pools:<server> <featureManager> <feature>monitor-1.0</feature> </featureManager> </server>
-
Save the changes and restart your WebSphere Liberty.
- Monitoring of both the CICS region and the WebSphere Liberty that operates inside this CICS region is only supported if they report to a different zDC subsystem. If they report to different zDC subsystems, at least one of those zDCs must be started as non-default (see
SUBSYSTEM_ID
in the zDC SYSIN parameters). However, both zDCs can report to the same zRemote module.- For the CICS module, the zDC subsystem name is defined in the CICS SYSIN parameters.
- For the z/OS Java module, the zDC subsystem name is defined in the
dt.config.json
file.
- 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 module to each product that you want to monitor.
-
Add the module to the
JVM_OPTIONS STDENV
variable: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 yourfeatureManager
in theserver.xml
file to collect additional metrics like connection pools or thread pools:<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.
-
z/OS Java module version 1.235+ For the IMS service provider:
- Add the IMS module to IMS Connect as described in Install the IMS module.
- 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.
-
Add the module to the
CTGENV
member and to theCTGSTART_OPTS
variable:-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.
- Only the EXCI and IPIC protocols are supported.
- WAS local mode configuration of the CICS Transaction Gateway configuration is not supported.
-
Add the module as a
zDT
option to the IMS SOAP Gateway parameters: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 thatIBM_JAVA_OPTIONS
includes it.export IBM_JAVA_OPTIONS="$zDT $JAVA_OPTS"
-
Save your changes and restart the IMS SOAP Gateway.
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
{
"DisableJdbctransformer": false
}
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 |
| If |
log-stderr |
| If |
log-file |
| If |
If needed, you can log to multiple locations. For example:
-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 |
| 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: |
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:
-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 the JAR file from your Dynatrace environment and transfer it 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.