Detailed instructions for installing and configuring Sensor for J2EE implementations running on RedHat Linux 7.x or later, Sun Solaris SPARC 2.6 or later, or Sun Solaris x86 9 or later.
The program files for Sensor are packaged in an installation file that you obtain from the Adobe download site. If you do not already have the Sensor installation file for your particular web server, download it (or obtain it from your Adobe representative) before you begin the following procedures.
Supported J2EE implementations include:
To install and configure Sensor, you must perform the following steps:
Procedure to extract and install the program files for Sensor.
Log on as the root user or as a user with root authority.
Decompress and unpack the installation file using the following command:
tar -zxf installationFilename.tar.gz
unzip -d installationFilename.tar.gz tar -xf installationFilename.tar
Copy the unpacked program files to the directories identified in the following table:
|mod_visual_sciences.so||The collector load module.||IBMHttpServer/modules|
|The transmitter program.||
|txlogd.conf||The Sensor configuration file.||/etc|
|trust_ca_cert.pem||The certificate used to validate the digital certificate that Insight Server presents during the connection process||/usr/local/visual_sciences|
The installation package contains a spreadsheet file called TestExperiment.xls. This spreadsheet is a tool that architects use to configure a controlled experiment. Sensor itself does not use this file, so it is not necessary to install the file on the machine where Sensor is running (although you can choose to do so). You might want to, instead, copy the file to a location where your architects can access it or simply extract the file from the installation package as needed. For more information about controlled experimentation, see the Insight Controlled Experiments Guide.
Permissions on the Program Files
Incorrect permissions on the program files cause the majority of problems encountered when installing Sensor. Please make sure that you set the permissions exactly as stated in this section.
By default, the program files in the tar file have the following permissions. Depending on how your system is configured, these settings might be altered (unmasked) when you extract the files. To reset the permissions to the recommended default settings, use the chmod commands below. Check that the directories into which you have installed the files permit at least this level of access.
|File||Default Permissions||chmod command|
|mod_visual_sciences.so||rwx r-x r-x||chmod 775|
|txlogd||rwx --x --x||chmod 711|
|txlogd.conf||rw- r-- r–||chmod 664|
|trust_ca_cert.pem||rw- r-- r–||chmod 664|
The txlogd.conf file contains the configuration parameters for Sensor.
You must edit this file to specify, among other things, the size and location of the disk queue file, the address of the Insight Server, and the ID that will be attached to the event data produced by this sensor.
The configuration file contains required parameters and optional parameters.
To edit the Sensor configuration file
To edit the Sensor configuration file
After you configure the txlogd.conf file, you can start the transmitter program, register it as a Windows service, and create the disk queue.
If the directory in which the disk queue resides does not already exist, create it. Make sure that the directory provides both the collector module and the transmitter program with read/write access to the file.
For more information about the permissions required by the disk queue files, see Sensor UNIX File Permissions.
On the computer where Sensor is installed, execute the following command to start the transmitter:
/usr/local/bin/txlogd -ic -f /etc/txlogd.conf
For additional information about the options you can use when starting the transmitter, see Sensor Transmitter Command-Line Options.
Verify that the transmitter has created the disk queue in the location specified in the QueueFile parameter and of the size specified in the QueueSize parameter.
f the queue has not been created correctly, type Ctrl+C to terminate the transmitter, then do the following:
For Apache servers, the collector is a dynamic shared object that you load into your web server process.
To add the collector to your web server, you must edit the httpd.conf file as described below and restart your web server.
If Sensor is capturing data for multiple web servers on the server computer, you must perform the following procedure for each web server.
Using a text editor, open the httpd.conffile for the web server whose events Sensor captures.
Add the following
<filter-mapping> elements to the descriptor file. If you did not install txlogd.conf in the /etc directory, you need to enter the correct path to this file in the
<filter> <filter-name>VSCollectorFilter</filter-name> <description></description> <filter-class> com.visualsciences.collector.VSCollectorFilter </filter-class> <init-param> <param-name>configPath</param-name> <param-value>/etc/txlogd.conf</param-value> <description></description> </init-param> </filter> <filter-mapping> <filter-name>VSCollectorFilter</filter-name> <url-pattern>/*</url-pattern> </filter-mapping>
These lines are case sensitive. Type them exactly as they appear above.
Restart the web server process (you do not have to reboot the entire server computer, simply restart the web server process). The collector is loaded with the web server and begins collecting event data and writing it to the disk queue.
Verify that the collector is collecting event data and the transmitter is transmitting it to the target Insight Server.
To verify that the transmitter can successfully send event data to the Insight Server, make sure that the target Insight Server is installed and running before you begin the following test.
If the transmitter is not already running, restart it using the following command:
/usr/local/bin/txlogd -i -f /etc/txlogd.conf
Open a browser (on any machine) and request a page from the web server on which Sensor is running (be sure to select a page that Sensor is monitoring).
After you issue the request, check the transmitter’s console for messages indicating that it is sending event data to the target Insight Server.
f Sensor is not transmitting data successfully, verify that:
Information about automatically loading the transmitter to your system startup script.
To ensure that the transmitter loads automatically when the web server machine is restarted, add the following command (which launches the transmitter) to your system startup script:
/usr/local/bin/txlogd -f /etc/txlogd.conf
This command starts the transmitter as a daemon. Operating and error messages that the transmitter generates are written to syslog.
The default Solaris setting is 60. Based on tests conducted with Sensor, which uses three semaphores for each instance, Adobe recommends that you use 1024 as your setting. This number is high enough for Sensor to function along with any other applications on the server that may require semaphores, but does not affect performance. To support this recommendation, please note that Adrian Cockcroft stated the following in his book Sun Performance and Tuning (Prentice Hall, October 1994): “Databases tend to use lots of shared memory and semaphore settings. These do not affect performance; as long as they are big enough, the programs will run.”
Sensors for all platforms can collect any of the data available in the HTTP request and response headers.
The Sensors for the J2EE Platform provide a mechanism for collecting data that is not available on other platforms. The collector for the J2EE platform (J2EE collector) sits on the application layer, which enables it to collect sensitive data that is available only to the application and should not be exposed through page tagging or in the headers.
While page tags and header modification can hide the data, it is still available to those who examine the source code of a page or look at the headers using browser plug-in tools.
For example, the J2EE collector can be used to capture cost per click (CPC) data for links displayed on a page, sensitive partner information on a page, and many other data points. The J2EE environment makes it easy for you to modify your WEBAPP to capture this custom data using our collector class.
When a Sensor for the J2EE Platform receives a request, it invokes a collector class that imports the appendToLog function. The appendToLog function appends to the initial request the query string parameters specified in the appendToLog function. This results in the URI of the initial request containing additional query string name-value pairs that correspond to the names and values of the data that is being captured. For example, CPC=20 would be appended to the initial request when the value of a particular ad placement or click-through link is 20 cents. Insight Server processes these values into the dataset for analysis. One additional benefit to this collection methodology is that it allows the collection of additional data without creating extra log entries, as might be created using page tagging methodologies.
For more information about processing, see the Dataset Configuration Guide.
To capture additional data from a page
Add the following code to the top of the .jsp page from which you want to capture data:
<%@ page import="com.visualsciences.collector.VSCollector" %>
Use the appendToLog() method of the collector object to append the desired name-value pairs to the requested .jsp page’s query string. The following example appends “A=1” and “B=2” to the requested .jsp page’s query string for the /index.jsp page:
<html> <body> <h1>Hello World</h1> <% VSCollector collector = new VSCollector(request, response); collector.appendToLog("A", "1"); collector.appendToLog("B", "2"); %> </body> </html>
The resulting request URI is /index.jsp?A=1&B=2.
Repeat this procedure for each .jsp page from which you want to capture additional data.