Install OneAgent for Java on z/OS
The Java code module of OneAgent traces web requests on WebSphere Application Server and WebSphere Liberty.
- It traces incoming web requests via Servlets and outgoing web requests via the Apache HttpClient.
- It traces requests to CICS SOAP, CICS Transaction Gateway, IBM MQ, JMS (Java Message Service), and IMS SOAP Gateway.
- It traces outgoing CICS Transaction Gateway requests via the CICS Transaction Gateway 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) and IMS (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.
- Activate the Forward Tag 4 trace context extension OneAgent feature. In the Dynatrace menu, go to Settings > Preferences > OneAgent features.
- Note: All OneAgents participating in a trace must meet the minimum OneAgent version of 1.193 for this setting.
Download OneAgent
You can directly download OneAgent from your Dynatrace environment as described below:
-
In the Dynatrace menu, select Deploy Dynatrace.
-
Select OneAgent > Download OneAgent, and choose z/OS.
-
Download OneAgent (
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 OneAgent folder of your mainframe. -
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:{ "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, replaceDEFAULT
with an alternative subsystem ID.You can find the subsystem ID in the
SYSIN
parameters of your zDC JCL (the default isMEPC
).//SYSIN DD DISP=SHR,DSN=hlq.LZDT720.SZDTSAMP(ZDCSYSIN) SUBSYSTEM_ID(MEPC) DEFAULT(YES)
If
DEFAULT
is set toYES
in theSYSIN
parameters, then you can also useDEFAULT
in thedtconfig.json
file.
- OneAgent supports EBCDIC 1047, UTF-8 and ASCII encodings for the
dtconfig.json
file. - OneAgent will automatically read the
dtconfig.json
file when it's placed in the same folder as thedynatrace-oneagent-zos-java.jar
file. - If you want to place the
dtconfig.json
file in a different folder, then 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.
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.
-
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 OneAgent 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 OneAgent file. -
Save the changes and restart your WebSphere Application Server.
- It's only necessary to add OneAgent to the Servant processes.
- We recommend adding OneAgent as the first JVM argument.
- OneAgent must not be appended at the end of the command line.
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.
-
Edit or create the
jvm.options
file in the root folder of your WebSphere Liberty server instance (this folder typically also contains theserver.xml
file). -
Copy the OneAgent 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 OneAgent 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 OneAgent as the first JVM argument.
- OneAgent 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.
Add OneAgent to WebSphere Liberty inside a CICS region
You must add OneAgent to the JVM profile of your CICS region for each WebSphere Liberty that you want to monitor.
-
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 OneAgent 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 OneAgent 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 not supported. You must 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.
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.
-
Add OneAgent 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 OneAgent file. -
Save the changes and restart your CICS Transaction Gateway.
- Only EXCI and IPIC protocols are supported.
- Tracing isn't supported when your CICS Transaction Gateway is configured in WAS local mode.
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.
-
Add OneAgent as
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 OneAgent file. -
Export the defined
zDT
option so that theIBM_JAVA_OPTIONS
include it.export IBM_JAVA_OPTIONS="$zDT $JAVA_OPTS"
-
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.
-
Add OneAgent to the
JVM_OPTIONS STDENV
variable:JVM_OPTIONS=-javaagent:/PATH_TO/dynatrace-oneagent-zos-java.jar
Replace
PATH_TO
with the path to your OneAgent 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 z/OS CICS z/OS Connect OneAgent feature. In the Dynatrace menu, go to Settings > Server-side service monitoring > Deep monitoring and expand the New OneAgent features section.
-
OneAgent version 1.235+ For the IMS service provider:
- Add OneAgent to IMS Connect as described in the IMS documentation.
- Activate the z/OS IMS z/OS Connect OneAgent feature. In the Dynatrace menu, go to Settings > Server-side service monitoring > Deep monitoring and expand the New OneAgent features section.
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:
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:
-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 | <ONEAGENT_FOLDER>/logs | By default, write log files to the OneAgent folder. It's also possible to write the log files to an absolute path (schema: |
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:
-javaagent:/PATH_TO/dynatrace-oneagent-zos-java.jar=log-file=true,log-file-dir=/u/dt/log
- Ensure that the application server has appropriate write permissions for the folder where the OneAgent 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:
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:
-
Expand
dynatrace-oneagent-zos-java.jar
that you downloaded into a program controlled folder. -
Mark the appropriate
.so
file (31 or 64 bit) in thelib/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:extattr +p libdynatrace-oneagent-odin-java_64.so
-
Add to the
-javaagent
argument:,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>
withlibdynatrace-oneagent-odin-java_64
. -
Restart the application server.
Known limitations
Known limitations of the Java code module of OneAgent:
- It doesn't support runtime settings.