Tracing WAS/Liberty on z/OS

Edit online

To enable tracing of IBM WebSphere® Application Server on z/OS or WebSphere® Liberty on z/OS, you need to configure WAS/Liberty on z/OS, set up the necessary security profile, and set up the Instana Agent.

Procedure

Set up WAS or Liberty on z/OS to include the two parameters:
- Djdk.attach.allowAttachSelf=true
- Dcom.ibm.tools.attach.enable=yes
Set up security profile.
To trace IBM WebSphere® Application Server on z/OS or WebSphere® Liberty on z/OS, security profile needs to be set up using RACF or any other mainframe security products.
- Option 1: Create a Generic Profile
  Create a generic profile named BPX.SRV.** in the SURROGAT class with read permission UACC(READ).
- Option 2: Create Profiles for Specific User IDs
  For specific user IDs (e.g., USERA), create profile BPX.SRV.USERA with UACC(NONE) and then permit read access to individual surrogate users/groups.
Set up Instana Agent (using root user).
1. Download the agent (instana-agent-linux-s390x.tar.gz) from the Instana Server.
  - For On-prem environment:
  - For SaaS environment,
2. Transfer the tar file to a directory in Unix System Services on z/OS with root privileges, and then extract the transferred tar file at the USS layer.
  Note: After you transfer the instana-agent-linux-s390x.tar.gz to USS, if you encounter the error tar: decompress: FSUM6636 not in compressed format, use gunzip on your local system to decompress the file before transferring the instana-agent-linux-s390x.tar.gz to USS. Then execute the command tar -xvf instana-agent-linux-s390x.tar on USS to extract the tar file.
3. Deploy the agent on Unix System Services on z/OS with proper code page setting enabled. This ensures correct character encoding for handling text data. Run the following commands to enable the code page settings:
  1. Enable automatic character conversion:
```
export _BPXK_AUTOCVT=ON
```
  2. Specify the code page:
```
chtag -R -tc 819 instana-agent/bin; chtag -R -tc 819 instana-agent/etc
```
  3. Confirm that the tag is enabled:
```
ls -lTr instana-agent
```
    For example,
```
ROOT:/u/instana/april10/t #>ls -lTr instana-agent
total 610
          drwxr-xr-x  6 ROOT   0      8192 Apr 8 05:42 system
          drwxr-xr-x  2 ROOT   0     16384 Apr 8 05:42 licenses
          drwxr-xr-x  6 ROOT   0      8192 Apr 8 05:42 lib
          drwxr-xr-x  4 ROOT   0      8192 Apr 15 17:11 etc
          drwxr-xr-x  7 ROOT   0      8192 Apr 17 02:43 data
          drwxr-xr-x  2 ROOT   0      8192 Apr 8 05:42 bin
- untagged  T=off -rw-r--r--  1 ROOT   0       7 Apr 8 05:42 VERSION
- untagged  T=off -rw-r--r--  1 ROOT   0     14755 Apr 8 05:42 THIRD_PARTY_LICENSES
- untagged  T=off -rw-r--r--  1 ROOT   0     200967 Apr 8 05:42 THIRD_PARTY.csv
- untagged  T=off -rw-r--r--  1 ROOT   0      886 Apr 8 05:42 README
- untagged  T=off -rw-r--r--  1 ROOT   0      9014 Apr 8 05:42 LICENSE
ROOT:/u/instana/april10/t #>
```
4. Update the instana-agent/etc/instana/com.instana.agent.main.sender.Backend.cfg file with your Instana Server details (Host, Port, and Key).
5. Set the JAVA_HOME environment variable name for Instana agent. Additionally, set the PATH and other environment variables according to your needs. For example:
  - export JAVA_HOME=/usr/lpp/zWebSphere/Liberty/V9R0/java/8.0
  - export PATH=$JAVA_HOME/bin:$PATH
  - export JAVA_OPTS='-Xmx8192m'
6. Initiate the agent. Navigate to instana-agent/bin/ using the command cd instana-agent/bin/and start the agent with root user using script ./start.
7. To review the logs, refer to the file instana-agent/data/log/agent.log.
Note:
- To check the status of the agent, navigate to instana-agent/bin/ using the command cd instana-agent/bin/. Then display the status of the agent with root user using script ./status.
- To terminate the agent, navigate to instana-agent/bin/ using the command cd instana-agent/bin/. Stop the agent with root user using script ./stop.