Install OneAgent on WAS and WebSphere Liberty

The Java code module of OneAgent traces incoming web requests on WebSphere Application Server and WebSphere Liberty (via Servlets). It traces requests to IBM MQ, CICS Transaction Gateway, CICS SOAP, or IMS SOAP Gateway. It traces outgoing web requests via Apache HTTP client.

Requirements

Download OneAgent

You can directly download OneAgent from your Dynatrace environment as described below:

Select Deploy Dynatrace from the navigation menu.

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, 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).

//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
  • OneAgent will automatically read the dtconfig.json file when it's placed in the same folder as the dynatrace-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 variable DT_CONFIG_FILE. 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.

Notes
  • 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 the server.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.

Save the changes and restart your WebSphere Liberty.

Notes
  • We recommend to add OneAgent as the first JVM argument.
  • OneAgent must not be appended at the end of the command line.

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: /<PATH_TO>/logs) or to a path relative to the working folder of the process (schema: <PATH_TO>/logs).

Based on that example for file logging to an absolute path, you will find the log files in /my/logs on your mainframe:

-javaagent:/PATH_TO/dynatrace-oneagent-zos-java.jar,log-file=true,log-file-dir=/my/logs
Note

Ensure that the application server has appropriate write permissions for the folder where the OneAgent should write the log files.

JVM is executing in a program controlled environment

After starting WebSphere Application Server or WebSphere Liberty 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 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:

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> with libdynatrace-oneagent-odin-java_64.

Restart the WebSphere Application Server or WebSphere Liberty.

Known limitations

Known limitations of the Java code module of OneAgent:

  • It will not immediately connect with Dynatrace during startup, but it will connect as soon as it captures the first transaction that executes on the WebSphere Application Server or WebSphere Liberty.
  • It doesn't support runtime settings.
  • It doesn't support OneAgent diagnostics.