4
The Agent Data Gatherer

The Data Gatherer, which collects performance data used by the Oracle Capacity Planner and the new Java-based Oracle Performance Manager, is installed along with the Intelligent Agent.

Configuring the Agent Data Gatherer

This section contains the following topics:

• Description of the Data Gathering Service on page 4-45

• How the Data Gathering Service is Installed on page 4-45

• Understanding Where to Configure the Oracle Data Gatherer to Collect Database and Operating System Data on page 4-45

• Running the Oracle Data Gatherer on an Intermediate Host on page 4-46

• How to Configure the Data Gatherer on page 4-47

• Upgrading From a Previous Version of the Data Gatherer when You Install the New Data Gatherer into a Different Oracle Home on page 4-47

• Controlling Operations of the NT and UNIX Data Gathering Service on page 4-48

• Additional Methods for Controlling Operations on Windows NT on page 4-49

• Verify Data Gathering Service is Running on page 4-50

• Troubleshooting the Configuration of the Oracle Data Gatherer on page 4-51

• Obtaining Trace Information on the Oracle Data Gatherer on page 4-52

Description of the Data Gathering Service

The data gathering service (also known as Oracle Data Gatherer) is used to collect performance data.

The Oracle Data Gatherer is responsible for handling requests from client applications (for example, Oracle Capacity Planner and Oracle Performance Manager) that want to collect data. For each client application, you specify the performance data to collect (for example, file I/O or CPU usage data) and the time interval between data samples. The Oracle Data Gatherer then collects the requested data for the client at the specified interval.

How the Data Gathering Service is Installed

The Oracle Data Gatherer is part of the Oracle Intelligent Agent, and it is automatically installed when the agent is installed on a managed host. Therefore, in the following sections, any reference to the Oracle Data Gatherer being installed on a host means that the Oracle Data Gatherer service was installed on the host when the agent was installed on the host.

Understanding Where to Configure the Oracle Data Gatherer to Collect Database and Operating System Data

The Oracle Data Gatherer can collect two kinds of performance data:

• database data

• operating system data

In general, the Oracle Data Gatherer should be configured on the host where the target (database or host) to be monitored is physically located. In other words, if you want the Oracle Data Gatherer to collect database data from the MEDICAL database on host BENEFITS, then the Oracle Data Gatherer should be installed and configured on host BENEFITS. Similarly, if you want the Oracle Data Gatherer to collect operating system data on host EMPLOYEES, then the Oracle Data Gatherer should be installed and configured on host EMPLOYEES.

In some cases, however, it may not be possible to install and configure the Oracle Data Gatherer on a particular host. The Oracle Data Gatherer can be installed on a host only when both the following requirements are met:

1. The host operating system must support the installation and configuration of the Oracle Data Gatherer.

2. An Oracle Home for Oracle 8.0.4 or later must exist on the host. Note that the host does not have to have an Oracle 8.0.4 or later database, just an Oracle Home directory for Oracle 8.0.4 or later.

If a host does not meet these requirements, the Oracle Data Gatherer cannot be installed on the host, which means that the Oracle Data Gatherer will not be able to collect operating system statistics from the host. However, you can collect database data from a host on which the Oracle Data Gatherer cannot be installed and configured.

Running the Oracle Data Gatherer on an Intermediate Host

To collect database data from a host on which the Oracle Data Gatherer cannot be installed and configured, install and configure the Oracle Data Gatherer on a different host that meets both of the requirements. You can then use the Oracle Data Gatherer on this host to collect database data remotely on hosts that do not have the Oracle Data Gatherer installed. This is called using an intermediate host Oracle Data Gatherer.

For example, suppose you want to collect database data for the CONSULTANTS database on host EMPLOYEES, but the Oracle Data Gatherer cannot be installed and configured on host EMPLOYEES. If the Oracle Data Gatherer is installed and configured on host BENEFITS, you can use the Oracle Data Gatherer on BENEFITS as an intermediate host Oracle Data Gatherer. The Oracle Data Gatherer on BENEFITS is able to collect database statistics from the CONSULTANTS database on host EMPLOYEES.

You might also want to use an intermediate host Oracle Data Gatherer if an additional process footprint/overhead cannot be tolerated on the host where you want to collect database data. Of course, in this situation the collection activity will still take place against the database. This minimal collection activity overhead will be present regardless of the host where the Oracle Data Gatherer is located.

How to Configure the Data Gatherer

You must configure the Oracle Data Gatherer after it is installed on a host.

The Oracle Data Gatherer, by default, tries to use the username/password account set up as the preferred credentials for the database to locate the Data Gatherer. If the preferred credentials are incorrect or if the Data Gatherer is not located on that host the client will reprompt you for the location of the Data Gatherer.

You may want to set up the preferred credentials for the database before starting the client applications (Performance Manager and Capacity Planner).

The TNSNAMES.ORA file on the host where the Oracle Data Gatherer is installed must include entries for:

• the target database

• the repository for Oracle Capacity Planner and Oracle Performance Manager. The repository location was defined using the Oracle Configuration Assistant.

Upgrading From a Previous Version of the Data Gatherer when You Install the New Data Gatherer into a Different Oracle Home

It is possible to install the new version of the Oracle Data Gatherer into a different Oracle Home than the previous version. If you plan to do this, follow these steps:

1. Stop the previous version of the Oracle Data Gatherer. See Controlling Operations of the NT and UNIX Data Gathering Service on page 4-48 for more information on stopping the Oracle Data Gatherer.

2. Install the new version of the Oracle Data Gatherer, but do not start it.

3. Move the Capacity Planning configuration files (state files) and data files associated with the previous version of Oracle Data Gatherer to the Oracle Home where you have installed the new version of Oracle Data Gatherer.

   The Oracle Data Gatherer state and data files are located in the $ORACLE_HOME/odg/reco directory. You need to copy the files into the new $ORACLE_HOME/odg/reco directory before you use Oracle Capacity Planner to connect to the new version of the Oracle Data Gatherer and set up any new collections.

   If you do not move these files, the following problems will occur:

   1. Binary data is not loaded.

      Any binary data files created by Oracle Data Gatherer which have not yet been loaded into the Capacity Planner database will not be loaded.

   2. Data collection definitions are not maintained.

      You will need to redefine your Capacity Planner data collections.

   If you have installed the new version of Oracle Data Gatherer into the same Oracle Home as the previous version or if you do not currently use the Oracle Capacity Planner, do not move the state and data files.

4. Start the new version of the Oracle Data Gatherer. See Controlling Operations of the NT and UNIX Data Gathering Service on page 4-48 for more information about starting the Oracle Data Gatherer.

Controlling Operations of the NT and UNIX Data Gathering Service

On UNIX and NT, Oracle Enterprise Manager uses the vppcntl command to manage the data gathering service. The vppcntl executable is located in ORACLE_HOME/bin.

Commands to control Oracle Data Gatherer are listed in the table below:

If you want to...	Enter the command...
Start Oracle Data Gatherer	vppcntl -start
Stop Oracle Data Gatherer	vppcntl -stop
Verify that Oracle Data Gatherer is running	vppcntl -ping
Identify the version of Oracle Data Gatherer	vppcntl -version

If you are running Oracle Enterprise Manager in a mixed environment, it is recommended that you upgrade to the latest client. Refer to the compatibility matrix below for more information.

Oracle Enterprise Manager Versions	Data Gatherer Version
Enterprise Manager 1.5.5 and 1.6.0 clients	Runs with 8.0.4 and 8.0.5 Data Gatherer Does not run with 8.1.5 Data Gatherer
Data Gatherer 2.0.4 clients	Runs with 8.0.4, 8.0.5, or 8.1.5 Data Gatherer

Additional Methods for Controlling Operations on Windows NT

This section contains information on controlling the Oracle Data Gatherer through Windows NT.

By default, you start the Oracle Data Gatherer manually on a host. To start Oracle Data Gatherer automatically through the Control Panel on Windows NT, perform the following steps:

1. Double-click the Services icon in the Control Panel folder.

2. Select the name of the Oracle Data Gatherer service you want to start.

   If the host has one Oracle Home, then the name of the Oracle Data Gatherer service is OracleDataGatherer.

   If the host has multiple Oracle Homes and the Oracle Data Gatherer has been installed into more than one Oracle Home, then multiple data gatherer services are displayed. When the Oracle Data Gatherer is installed into multiple Oracle Homes, the names of the data gathering services use the naming convention Oracle<Oracle_Home_name>DataGatherer. For example, suppose a host has two Oracle Homes, named 804 and 805, and the data gathering service has been installed both homes. The Oracle Data Gathering services for those Oracle Homes are named Oracle804DataGatherer and Oracle805DataGatherer, respectively.

   The Startup Type is set to Manual, which allows the data gathering service to be started by a user. If you want Oracle Data Gatherer to start automatically whenever you start the system, set the Startup Type for Automatic.

   1. Click the Startup push-button. A Service Startup dialog box appears.

   2. Choose Automatic under the Startup Type.

   3. Click OK on the Service Startup dialog box.

3. Click the Start push-button to start the data gathering service.

To stop Oracle Data Gatherer through the Control Panel on Windows NT, perform the following steps:

1. Double-click the Services icon in the Control Panel folder.

2. Select the name of the Oracle Data Gatherer service that you want to stop.

3. Click the Stop push-button to stop the data gathering service.

Verify Data Gathering Service is Running

On Windows NT, there are several ways to determine if the Oracle Data Gatherer is running by checking the:

• Status returned by the vppcntl -ping command.

• Status in the NT control panel services.

• vppdc process information in the NT Task Manager.

Oracle recommends that you use the vppcntl -ping command because it tells you if the Oracle Data Gatherer is running and also performs a test to determine whether it is responsive and running properly.

The data gathering service's alert/warning log is ORACLE_HOME\odg\bin\alert_dg.log.

On UNIX, use vppcntl -ping to verify if Oracle Data Gatherer is running. The data gathering service's alert/warning log is $ORACLE_HOME/odg/bin/alert_dg.log.

Troubleshooting the Configuration of the Oracle Data Gatherer

This section describes possible configuration problems and how to solve them.

Table 4-1 Troubleshooting Oracle Data Gatherer Configuration Problems

Problem	Steps for FIxing the Problem
The client host (where Oracle Capacity Planner or Oracle Performance Manager is installed) cannot connect to the host where the Oracle Data Gatherer is installed.	From the client host, use the ping utility to ping the Oracle Data Gatherer host: ping Oracle-data-gatherer-host-name If you have set preferred credentials for the database and a Data Gatherer exists on that host, you are not prompted for the Data Gatherer location. The Data Gatherer on that host is used as the default. If you have not set the preferred credentials for the database or if no Data Gatherer exists on that host, the Oracle Database Logon dialog box prompts you for the name of an Oracle Data Gatherer host. You must enter exactly the same host name as you entered in the ping command. For example, if you successfully pinged host DAVID.COMP.COM from the client host, you cannot specify DAVID as the name of the Oracle Data Gatherer host in the Oracle Database Logon dialog box. You must specify DAVID.COMP.COM as the name of the Oracle Data Gatherer host in the Oracle Database Logon dialog box.
The host where the Oracle Data Gatherer is located cannot connect to the target database.	From the host where the Oracle Data Gatherer is located, connect to the target database using SQL*Plus by specifying the username, password, and service of the target database: SQLPLUS> connect username/password@service-name If you have set preferred credentials for the database and a Data Gatherer exists on that host, you are not prompted for the Data Gatherer location. The Data Gatherer on that host is used as the default. If you have not set the preferred credentials for the database or if no Data Gatherer exists on that host, the Oracle Database Logon dialog box prompts you for the username, password, and service of the target database. Be sure to enter exactly the same username, password, and service information that you entered in SQL*Plus.

If the steps for fixing the configuration problems fail, verify that your TNSNAMES.ORA entries are configured correctly, as described in How to Configure the Data Gatherer on page 4-47.

Obtaining Trace Information on the Oracle Data Gatherer

You can also obtain trace information on the Oracle Data Gatherer. To obtain this information, you must run the Oracle Data Gatherer from the Oracle Enterprise Manager console.

To view the Oracle Data Gatherer trace information on the screen, type the following command at the DOS prompt or UNIX command line:

vppdc -console -debug

To send the Oracle Data Gatherer trace information to a file, type the following command at the DOS prompt or UNIX command line:

vppdc -console -debug > trace.txt

If the above command is used, the trace file is named trace.txt. If you prefer, you can specify a different name for the trace file.

Note: If you want to run the Data Gatherer in debug mode and a Data Gatherer is already running, you must stop the Data Gatherer, and then run it from the command line as shown above using the -debug flag.

---