1. User’s Guide
  2. Collecting Diagnostic Data and Triaging, Diagnosing, and Resolving Issues
  3. Getting Started with Oracle Trace File Analyzer

14 Getting Started with Oracle Trace File Analyzer

This section explains how to install Oracle Trace File Analyzer on different operating systems.

14.1 Supported Environments

You can use Oracle Trace File Analyzer with all supported versions of Oracle Database and Oracle Clusterware.

Oracle Trace File Analyzer works on the following operating systems:

  • Linux OEL

  • Linux RedHat

  • Linux SuSE

  • Linux Itanium

  • zLinux

  • Oracle Solaris SPARC

  • Oracle Solaris x86-64

  • AIX

  • HPUX Itanium

  • HPUX PA-RISC

  • Microsoft Windows 64-bit

Oracle Trace File Analyzer is supported on the operating system versions supported by Oracle Database. Use a Java Runtime Edition of version 1.8.

The Oracle Clusterware install is shipped with Oracle Trace File Analyzer since versions 11.2.0.4 and 12.1.0.2. However, this install does not include many of the Oracle Database tools. Oracle releases new versions of Oracle Trace File Analyzer several times a year. These new releases include new features and bug fixes.

Ensure that you get the latest Oracle Trace File Analyzer with Oracle Database support tools bundle from My Oracle Support note 1513912.1.

Related Topics

14.2 Installing Oracle Trace File Analyzer on Linux or UNIX as root User in Daemon Mode

To obtain the fullest capabilities of Oracle Trace File Analyzer, install it as root.

Oracle Trace File Analyzer maintains Access Control Lists (ACLs) to determine which users are allowed access. By default, the GRID_HOME owner and ORACLE_HOME owner have access to their respective diagnostics. No other users can perform diagnostic collections.

If Oracle Trace File Analyzer is already installed, then reinstalling performs an upgrade to the existing ___location. If Oracle Trace File Analyzer is not already installed, then the recommended ___location is /opt/oracle.tfa.

To install as root:

  1. Download appropriate Oracle Trace File Analyzer zipped file, copy the downloaded file to the required machine, and then unzip.
  2. Run the installTFA command:
    $ ./installTFAplatform

The installation prompts you to do a local or cluster install.

Cluster install requires passwordless SSH user equivalency for root to all cluster nodes. If not already configured, then the installation optionally sets up passwordless SSH user equivalency and then removes at the end.

If you do not wish to use passwordless SSH, then you install on each host using a local install. Run the tfactl syncnodes command to generate and deploy relevant SSL certificates.

The Cluster Ready Services (CRS) do not manage Oracle Trace File Analyzer because Oracle Trace File Analyzer must be available if CRS go down.

The installation configures Oracle Trace File Analyzer for auto-start. The implementation of auto-start is platform-dependent. Linux uses init, or an init replacement, such as upstart or systemd. Microsoft Windows uses a Windows service.

Related Topics

14.3 Installing Oracle Trace File Analyzer on Linux or UNIX as Non-root User in Non-Daemon Mode

If you are unable to install as root, then install Oracle Trace File Analyzer as the Oracle home owner.

Oracle Trace File Analyzer has reduced capabilities in this installation mode.

You cannot complete the following tasks:

  • Automate diagnostic collections

  • Collect diagnostics from remote hosts

  • Collect files that are not readable by the Oracle home owner, for example, /var/log/messages, or certain Oracle Clusterware daemon logs

To install as the Oracle home owner, use the –extractto option. Using the –extractto option tells Oracle Trace File Analyzer where to install to. Also, use the –javahome option to indicate which JRE to use. Use the JRE already available in the Oracle home, unless you have a later version available. 

./installTFAplatform -extractto install_dir -javahome jre_home

14.4 Installing Oracle Trace File Analyzer on Microsoft Windows

  1. Download appropriate Oracle Trace File Analyzer zipped file, copy the downloaded file to one of the required machines, and then unzip.
  2. Open a command prompt as administrator and then run the installation script by specifying a Perl home.

    For example:

    install.bat -perlhome D:\oracle\product\12.2.0\dbhome_1\perl

The installer prompts you to do a local or cluster install. If you select cluster install, then the installer installs Oracle Trace File Analyzer remotely on cluster nodes.

Alternatively, you can perform a local install on each host. Run the tfactl syncnodes command to generate and deploy relevant SSL certificates.

14.5 Installing Oracle Trace File Analyzer on Microsoft Windows in Non-Daemon Mode

If you do not want Oracle Trace File Analyzer to run automatically as a windows service, then install it in non-daemon mode. Oracle Trace File Analyzer has reduced capabilities in this installation mode.

You cannot complete the following tasks:

  • Automate diagnostic collections

  • Collect diagnostics from remote hosts

  • Collect files that are not readable by the Oracle home owner

  1. Download appropriate Oracle Trace File Analyzer zipped file, copy the downloaded file to one of the required machines, and then unzip.
  2. Open a command prompt as administrator and then run the installation script.
    tfa_home\bin\tfactl.bat -setupnd

14.6 Oracle Trace File Analyzer Key Directories

Based on your installation type, the ora_home and the bin directories can differ.

If you have installed Oracle Trace File Analyzer with Oracle Clusterware, then tfa_home is within GRID_HOME.

Table 14-1 Key Oracle Trace File Analyzer Directories

Directory Description

tfa/bin

Contains the command-line interface tfactl

If Oracle Clusterware is installed, then tfactl is also installed in the GRID_HOME/bin directory.

tfa/repository

Directory where Oracle Trace File Analyzer stores diagnostic collections.

tfa/node/tfa_home/database

Contains Berkeley database that stores data about the system.

tfa/node/tfa_home/diag

Tools for troubleshooting Oracle Trace File Analyzer.

tfa/node/tfa_home/diagnostics_to_collect

Place files here to include them in the next collection, then have them deleted afterwards.

tfa/node/tfa_home/log

Contains logs about Oracle Trace File Analyzer operation.

tfa/node/tfa_home/resources

Contains resource files, for example, the log masking control file.

tfa/node/tfa_home/output

Contains extra metadata about the environment.

14.7 Oracle Trace File Analyzer Command Interfaces

The tfactl tool functions as command-line interface, shell interface, and menu interface.

Table 14-2 Oracle Trace File Interfaces

Interface Command How to use

Command-line

$ tfactl command

Specify all command options at the command line.

Shell interface

$ tfactl

Set and change the context and then run commands from within the shell.

Menu Interface

$ tfactl menu

Select the menu navigation options and then choose the command that you want to run.

14.8 Masking Sensitive Data

Masking sensitive data is an optional feature that you can configure Oracle Trace File Analyzer to mask sensitive data in log files.

Oracle Trace File Analyzer masks information such as host names or IP addresses and replaces sensitive data consistently throughout all files. Replacing consistently means that the information is still relevant and useful for the purposes of diagnosis without sharing any sensitive data.

To configure masking:

  1. Create a file called mask_strings.xml in the directory tfa_home/resources.
  2. Define a mask_strings element then within that a mask_string element, with original and replacement for each string you wish to replace:
    For example:
    <mask_strings>
     <mask_string>
          <original>WidgetNode1</original>
          <replacement>Node1</replacement>
     </mask_string>
     <mask_string>
          <original>192.168.5.1</original>
          <replacement>Node1-IP</replacement>
     </mask_string>
     <mask_string>
          <original>WidgetNode2</original>
          <replacement>Node2</replacement>
     </mask_string>
     <mask_string>
          <original>192.168.5.2</original>
          <replacement>Node2-IP</replacement>
     </mask_string>
</mask_strings>

    Oracle Trace File Analyzer automatically locates the mask_strings.xml files, and starts replacing the sensitive data in the diagnostics it collects.

14.9 Securing Access to Oracle Trace File Analyzer

Running tfactl commands is restricted to authorized users.

tfactl provides a command-line interface and shell to do the following:

  • Run diagnostics and collect all relevant log data from a time of your choosing

  • Trim log files around the time, collecting only what is necessary for diagnosis

  • Collect and package all trimmed diagnostics from any desired nodes in the cluster and consolidate everything in one package on a single node

Authorized non-root users can run a subset of the tfactl commands. All other tfactl commands require root access. Users who are not authorized cannot run any tfactl command.

By default, the following users are authorized to access a subset of tfactl commands:

  • Oracle Grid Infrastructure home owner

  • Oracle Database home owners

User access is applicable only if Oracle Trace File Analyzer is installed as root on Linux and UNIX. User access is not applicable if Oracle Trace File Analyzer is installed as non-root, or on Microsoft Windows.

To provision user access to tfactl:

  • To list the users who have access to tfactl: 

    tfactl access lsusers

  • To add a user to access tfactl: 

    tfactl access add –user user [-local]

    By default, access commands apply to cluster-wide unless –local is used to restrict to local node.

  • To remove a user from accessing tfactl: 

    tfactl access remove –user user [-local]

  • To remove all users from accessing tfactl: 

    tfactl access removeall [-local]

  • To reset user access to default:

    tfactl access reset

  • To enable user access:

    tfactl access enable

  • To disable user access:

    tfactl access disable

Related Topics

14.10 Uninstalling Oracle Trace File Analyzer

  1. To uninstall Oracle Trace File Analyzer, run the uninstall command asroot, or install user.
    $ tfactl uninstall