JBoss Server on Windows Server 2000 or Later

Detailed instructions for installing and configuring Sensor for JBoss Server 4.0.5 or later running under Microsoft Windows Server 2000 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:

• JBoss Server 4.0.5 or later running on Microsoft Windows Server 2000 or later.

To install and configure Sensor, you must perform the following steps:

Install the Program Files

Procedure to extract and install the program files for Sensor.

1. On your JBoss Server, create a directory in which to install the Sensor program files. Keep in mind that your disk queue resides in this directory, so be sure the device you choose has sufficient space to hold a queue of the size you need.

   C:\VisualSensor
   

2. Extract the contents of the installation file into the directory you just created. During this step, Sensor installs the following files:

Edit the Sensor Configuration File

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.

• Required parameters are settings that you must specify when you install Sensor. Without these settings, Sensor does not run successfully.
• Optional parameters are settings that default to pre-defined values (which you can modify) or enable optional features.

To edit the Sensor configuration file

• Open the /etc/txlogd.conf file in a text editor and set the required parameters as well as any desired optional parameters.
• Save and close the file.

To edit the Sensor configuration file

1. Open the /etc/txlogd.conf file in a text editor and set the required parameters as well as any desired optional parameters.
2. Save and close the file.

Start the Transmitter and Create the Disk Queue

After you configure the txlogd.conf file, you can start the transmitter program, register it as a Windows service, and create the disk queue.

1. From the Start menu in Windows, select Accessories > Command Prompt.

2. In the command prompt window, navigate to the directory in which you installed Sensor and execute the following command:

   txlog /regserver
   

   This command starts the transmitter, creates the disk queue, and registers Sensor as a Windows service.

3. To confirm that the transmitter is running correctly, click Start > Control Panel > Administrative Tools > Services.

   NOTE

   This command sequence might vary depending on which version of Windows you are using.

   1. In the service list, locate the entry for Sensor and confirm that its status is Started and its startup type is Automatic.
   2. Close the Services control panel.

4. To check whether transmitter experienced any errors during start-up, click Start > Control Panel > Administrative Tools > Event Viewer to open the Event Viewer.

   1. In the left pane of the Event Viewer window, select the Applications log.
   2. In the right pane, look for events with “Adobe” in the Source column.
   3. If you find an error from “Adobe,” double-click the error to display the Event Properties window. This window provides detailed information about the error.

5. When you finish examining the Applications log, close the Event Viewer.

6. Verify that the transmitter has created the disk queue (Diskq2000.log) in the directory where you installed the Sensor program files and that it is the size that you specified in the QueueSize parameter in the txlogd.conf file.

   If the queue has not been created correctly:

   1. Examine the txtlogd.conf file and verify that the QueueSize parameter is set correctly.

   2. Check that the device on which you installed Sensor has sufficient space available to hold a file of the size specified in the QueueSize parameter.

   3. Using the Services control panel in Windows, stop the transmitter.

   4. Delete the queue file.

   5. Re-register Sensor as a Windows service: from the Start menu in Windows, select Accessories > Command Prompt. In the command prompt window, navigate to the directory in which you installed Sensor and execute the following command:

      txlog /regserver
      

The transmitter is designed to run continuously. If you restart the machine, the transmitter restarts automatically. If you need to start and stop the transmitter manually, you can do so using the Services control panel in Windows.

Add the Collector to the Web Server

For JBoss servers, the collector operates as a filter in the servlet container.

To add the collector to your web server, you must edit the web.xml file as described below and restart your web application.

1. Using a text editor, open the web.xml file for the web server whose events Sensor captures.

2. Add the following <filter> and <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 <param-value> element:

   <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>C:/VisualSensor/txlogd.conf</param-value>
     <description></description>
     </init-param>
   </filter>
   
   <filter-mapping>
     <filter-name>VSCollectorFilter</filter-name>
     <url-pattern>/*</url-pattern>
   </filter-mapping>
   
   

   NOTE

   These lines are case sensitive. Type them exactly as they appear above.

3. 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.

Modify the Startup Script

Before modifying the startup script, ensure that the JAVA_HOME variable is defined in the Windows environment.

In the run.bat file (for example, C:\jboss-4.0.5.GA\bin\run.bat), add the following lines near the end of the file just before the “echo” lines that precede the startup command of the JBoss server:

set JBOSS_CLASSPATH=%JBOSS_CLASSPATH%;C:\jboss-4.0.5.GA\server\default\lib\javax.servlet.jar;C:\VisualSciences\J2EECollector.jar
set JAVA_OPTS=%JAVA_OPTS% -Djava.library.path=C:\VisualSciences

Capturing Additional Data

You can capture additional measurement data from J2EE-based web applications using the appendToLog() functionality.

1. Add the following code to the top of the .jsp page from which you want to capture data:

   <%@ page import="com.visualsciences.collector.VSCollector" %>
   
   

2. 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.

3. Repeat this procedure for each .jsp page from which you want to capture additional data.