ZFtrace from The ZeroFault Group

Contents

Legal Notices

Chapter 1:
  Quick Start

Chapter 2:
  Introduction and Installation

Chapter 3:
  Startup Options

Chapter 4:
  Viewing Trace Files

Chapter 5:
  Tips and Techniques

Chapter 6:
  Troubleshooting

Chapter 7:
  Obtaining Support

Chapter 2: Introduction and Installation

ZFtrace is a tool that traces run-time execution in software programs. ZFtrace accomplishes this by using TZG's emulation technology to emulate the microprocessor in your machine. This run-time approach automatically covers shared libraries and dynamically loaded modules, including ones that come with the operating system or from third parties. You don't need to have source code for the program being traced.

Before using ZFtrace, you should have a working knowledge of the AIX operating system and how to issue commands to AIX.

System Requirements

ZFtrace requires a 32Bit AIX 43, 51, or 52 system or a 64Bit AIX 51 or 52 system and:

at least 32MB of RAM

If you do not know how much RAM your AIX system has, use the command
lsattr -H -E -l sys0
The line starting with the word "realmem" indicates the amount of RAM in kilobytes. Also, the data area ulimit should be unset or set to a very large value, because ZFtrace uses a large data area.
at least 10MB of available hard disk space

If you do not know how much available disk space you have, use the df command to find out.
at least 100MB of paging space

If you do not know how much paging space you have, use the command lsps -a to find out. The total amount of paging space required will depend on the size of the process being traced by ZFtrace.

When working with large applications you may want to refer to the performance tips.

Installing ZFtrace

If you haven't already downloaded the ZFtrace distribution files, they are available as follows...
The evaluation version: here
The Full Version is available from a custom web link provided by TZG Support teams after purchase.

After downloading, place the distribution file in a working directory. You will need approximately 10Mb of disk space to hold the download and extract it. To extract the installation image, enter the following command as the root user:

  tar xf zftr*.tar

To install the product, cd to the temporary directory and enter the following command as the root user:

./install -NORMAL

Please read the README provided with the installation image for custom details.

Installing the License Key

When you purchased ZFtrace you received email containing a license key in the form:

  1111 2222 3333 4444 5555 6666 7777 8888

ZFtrace will not run if this key is not properly installed. There are two types of license keys, Standard (desktop) and Deluxe (floating), and the installation procedure is a bit different for each.

Standard Desktop License Installation

With a desktop license, the license key is installed in a directory on the local machine. To install the key, enter the following commands as root:

  mkdir /usr/lib/elm
  chmod 755 /usr/lib/elm
  /usr/lpp/ZFtrace/bin/tkg_lmadmin -c -r1/"license_key"

where license_key is replaced by the string of digits that is your license key. Once the key file is created in the /usr/lib/elm directory, ZFtrace should be ready for use.

Deluxe Floating License Installation

Floating licenses are dispensed by a license manager, which is a daemon, or background, process that runs on a server machine. The server must be reachable ("pingable") from the machines where ZFtrace is to be run. The license server should also be a machine that is available most of the time, as ZFtrace will not run if the license server is down or unreachable. It is also most convenient if the license server is on the same subnet as the machines where ZFtrace will be run (see License Server Considerations for more information).

The license manager distribution file should be obtained with this link: tkg_lm.obj. To install the license manager, run the following commands as the root user on the machine that is to act as the license server:

        mkdir /usr/lib/elm
        chmod 755 /usr/lib/elm
        installp -acXd tkg_lm.obj all
        mkitab "tkg_lmd:2:respawn:/usr/lpp/tkg_lm/bin/tkg_lmd -l /tmp/tkg_lmd.log -m1"
        init Q
       /usr/lpp/tkg_lm/bin/tkg_lmadmin -c -r1/"license_key"

where license_key is replaced by the string of digits that is your license key. Once the key file is created in the /usr/lib/elm directory and the license manager process is running (the init Q command should start it), ZFtrace should be ready for use.

License Server Considerations

If you are using a floating license and your license server is on a different subnet than a machine that will be using ZFtrace, you need to set the TKG_LMHOST environment variable in the user's environment. One way to do this is to put it in the /etc/profile of every machine that is using ZFtrace:

  export TKG_LMHOST=@license_server_hostname

You can also specify the TKG_LMHOST variable in each user's $HOME/.profile or $HOME/.login script. Alternatively, you can replace the zftr command with a shell script that sets the variable and then executes the zftr executable. For example:

  cd /usr/lpp/ZFtrace/bin
  mv zftr zftr.real
  cat > zftr <<\EOF
  #!/bin/ksh
  export TKG_LMHOST=@licsrvr
  exec zftr.real "$@"
  EOF
  chmod +x zftr

This method is particularly useful when the ZFtrace installation directory is remote-mounted by users, as opposed to being installed on each user's machine.

The "@" preceding the license server hostname specifies that ZFtrace should only contact that host, and not try to broadcast on the local subnet to find a license server. The procedure for finding a license server is:

If TKG_LMHOST is not set, then broadcast on the local subnet to find a license server.
If TKG_LMHOST is set and the first character is not "@", then send a message to the server specified in TKG_LMHOST and also broadcast on the local subnet to find a license server.
If TKG_LMHOST is set and the first character is "@", then send a message only to the server specified in TKG_LMHOST.

This provides a great deal of flexibility in setting up your license server environment, and allows for the possibility of having redundant servers if desired. Please contact via email custserv '@' zerofault.com
for ZFtrace support if you wish to set up redundant license servers.

ZFtrace Documentation

ZFtrace documentation is distributed in HTML format, and is installed into the doc subdirectory, which is by default /usr/lpp/ZFtrace/doc. You may use any browser to view the documentation, e.g.:

  netscape file:/usr/lpp/ZFtrace/doc/manuals.html

The latest documentation is also available at:

http://www.zerofault.com/doc.zftr/manuals.html