C
Installing a Standalone Collector Agent

This appendix describes how to install a standalone Clickstream Intelligence Collector Agent.

This appendix contains the following sections:

Introduction to the Collector Agent

The Collector Agent is the component of Oracle9iAS Clickstream Intelligence that resides on the Web server machine and collects Web server logs files. The Collector Agent compresses log files into units of manageable size called data packets, which enable more efficient storage of Web log data.

If you want to collect Web logs from a Web server other than Oracle HTTP Web Server, a standalone Collector Agent must be installed on your server machine. Data packets created by the standalone Collector Agent are retrieved by the Collector Server using HTTP or FTP protocol, and then parsed and loaded into the database by the Clickstream Loader. The platform of the server on which you install the standalone Collector Agent can differ from the platform on which you installed Oracle9iAS. (See "Installing a Standalone Collector Agent" in this appendix for further details.

To help determine if a standalone Collector Agent is needed for your Web server, see the criteria below. If any of the following criteria are met, you do not need to install a standalone Collector Agent:

Data is collected from a local data source: installation of a standalone Collector Agent is not required because all log files reside on the same machine on which you installed Oracle9iAS Clickstream Intelligence. For more information about Data Sources, see Chapter 3, "Configuring Clickstream Intelligence".
Log files are collected from Oracle HTTP Server: when Oracle HTTP Server is installed as part of Oracle9iAS core install, a Collector Agent is automatically installed to collect your Web log files (and can be managed via the Oracle Enterprise Manager (OEM) Management Console).

Note:

All log files from which the Collector Agent creates data packets must be unzipped (uncompressed). If a log file is zipped, the Collector Agent will still create data packets from it - which ultimately causes failure of the "Load Clickstream" process.

Installing a Standalone Collector Agent

During a typical Oracle9iAS Clickstream Intelligence install, the Collector Agent is pre-configured to retrieve Apache Web logs from Oracle HTTP Server. To install one or more Collector Agents for data sources other than Oracle HTTP Server, you must follow the installation steps described in the sections that follow.

Pre-installation Requirements

In order to successfully install, configure, and use a standalone Collector Agent, the following conditions must be met:

Java Runtime Environment (JRE) 1.3.1 or higher must be installed on your computer to enable use of the Collector Agent's install files.
Approximately 10 MB of disk space is required to enable successful installation.

Note:

Data packets consume disk space on the server machine; therefore, disk space requirements will increase as the number of data packets stored on the server increases.

Installation

The platform of the server on which you install the Collector Agent can be the same as, or may differ from, the platform of your Oracle9iAS CD. In both cases, installation files can be downloaded from the Oracle Technology Network Web site.

Go to the Oracle Technology Network Web site located at:
```
 http://otn.oracle.com/ 
```
Download the standalone Collector Agent install files that match the platform of your server.
Next, unpack the Collector Agent files in accordance with the platform you are using. (For example, .tar or .zip files correspond to UNIX or Windows, respectively.)

Go to the appropriate directory below:

(UNIX)  INSTALL_DIR/click/utl

(Windows)  INSTALL_DIR\click\utl

Then, enter the appropriate command below to create the standalone Collector Agent configuration files:
```
(UNIX)  ./instantiate-collagent JDK_HOME COLAGENT_PACKET_HOME COLAGENT_PORT 
COLAGENT_LOGS APACHE_LOGS 

(Windows)  .\instantiate-collagent-java JDK_HOME COLAGENT_PACKET_HOME 
COLAGENT_PORT COLAGENT_LOGS APACHE_LOGS 
```
In the expressions above, substitute values for the appropriate environment variables below:
- INSTALL_DIR - represents the directory into which the standalone Collector Agent was unpacked
- JDK_HOME - represents the Java Development Kit home directory
- COLAGENT_PACKET_HOME - the data packets destination home directory
- COLAGENT_PORT - the port corresponding to the Collector Agent you are installing
- COLAGENT_LOGS - location of the Collector Agent log files
- APACHE_LOGS - location of the Web server log files you want to collect
Go to the appropriate directory:
```
(UNIX)  INSTALL_DIR/click/bin

(Windows)  INSTALL_DIR\click\bin
```
The INSTALL_DIR environment variable represents the directory in which you unpacked the standalone Collector Agent.
Now, you can execute any of the commands listed in the following section of this appendix: "How to Start and Stop the Collector Agent".

Configuring the Collector Agent

Upon installation and instantiation of a standalone Collector Agent, all configuration file attributes are set to default values . If you want to modify the default values, you can use a text editor (such as Notepad) to manually configure the following files:

(UNIX)  INSTALL_DIR/click/conf/collector-agent.properties


INSTALL_DIR/click/conf/agent.xml


(Windows)  INSTALL_DIR\click\conf\collector-agent.properties


INSTALL_DIR\click\conf\agent.xml

The following sections describe all attributes associated with the standalone Collector Agent configuration files.

The collector-agent.properties File

The collector-agent.properties file contains name=value pairs. You can configure the following attributes:

loggingHome: the directory in which you want the Collector Agent to log information.
collectorPort: the port on which the Collector Agent will communicate. This port must be used by Clickstream Intelligence only.

The agent.xml File

The agent.xml file may contain several entries, wherein each entry corresponds to a specific data source. All configurable attributes for each entry are listed below.

logFileLoc: the location of the log files that need to be processed by the Collector Agent.
packetSize: the size, in lines, of the data packets that the Collector Agent will create.
packetHome: the location in which the completed (compressed) data packets are placed after they are created from the log files.
timeToSleep: the time (milliseconds) that elapses between the intervals in which the Collector Agent checks for new Web log files to compress into data packets.
packetTimeout: the length of time, in days, after which data packets are flushed from the packet directory on the Web server.
filterPattern: the pattern to use when targeting the files on the Web server you want to process. It is important to note that the filter pattern is used to select (and not exclude) the files you want to process from the Web server. Data packets are created from log data in the files that are selected according to your filter pattern definition.

For example, if you want to process from the Web server only the files that contain "dms" in the file name, then enter *dms* as your filter pattern identifier (the * represents a wild-card character).

Note:
The value of packetHome must be exclusive (unique) among all standalone Collector Agents.

How to Start and Stop the Collector Agent

To start, stop, and view the status of one or more Collector Agents, use the commands listed in the following sections. For each command, note the following variable definitions:

INSTALL_DIR: the directory in which the standalone Collector Agent is installed.
agentName: the name of the standalone Collector Agent to which the command pertains.

Commands for Specific Collector Agents

The following commands apply only to a specific Collector Agent:

Start a Collector Agent:

(UNIX)  INSTALL_DIR/click/bin/clkagtctl start agentName

(Windows)  INSTALL_DIR\click\bin\clkagtctl start agentName

Stop a Collector Agent:

(UNIX)  INSTALL_DIR/click/bin/clkagtctl stop agentName

(Windows)  INSTALL_DIR\click\bin\clkagtctl stop agentName

View the Status of a Specific Agent:

(UNIX)  INSTALL_DIR/click/bin/clkagtctl status agentName

(Windows)  INSTALL_DIR\click\bin\clkagtctl status agentName

Commands for All Collector Agents

The following commands pertain to all Collector Agents in your system:

Start All Agents:

(UNIX)  INSTALL_DIR/click/bin/clkagtctl startAll

(Windows)  INSTALL_DIR\click\bin\clkagtctl startAll

Stop All Agents:

(UNIX)  INSTALL_DIR/click/bin/clkagtctl stopAll

(Windows)  INSTALL_DIR\click\bin\clkagtctl stopAll

View the Status of the Collector Agent Manager:

(UNIX)  INSTALL_DIR/click/bin/clkagtctl managerStatus

(Windows)  INSTALL_DIR\click\bin\clkagtctl managerStatus

C Installing a Standalone Collector Agent