Configuring Precise for Web

This section includes the following topics:

• About configuring Precise for Web Collectors
• Configuring registry settings
• Adding Web filter parameters
• Grouping consecutive URLs by pattern
• Temporarily stopping the maximum number of table rows test
• Dynamic instrumentation

About configuring Precise for Web Collectors

To configure the Precise for Web Collectors, you can perform one of the following tasks:

1. Add and change parameters to the Precise registry file.
2. Add parameters to the Web server’s configuration mechanism.
3. Add and change parameters to the dynamic instrumentation agent via the instrument.xml file.

Configuring registry settings

This section describes the registry settings configuration process.

Registry structure and inheritance

Some configurations are relevant per instance (e.g. collect-post-parameters) and some are relevant for the Web Collector in general (e.g. preferred-data-port). Others are relevant for the whole product (e.g. user-agents). Instance configuration resides in the instance registry file:

products\i3fp\registry\instances\www\<server-name>\<instance_name>\settings.xml

Web Collector configuration resides in the registry file:

products\i3fp\registry\instances\www\<server-name>\settings.xml

Product level configuration resides in the registry file: products\i3fp\registry\products\indepth-web\focal-point.xml Web Collector behavior is set via the registry entry <web-collector>

Cluster configuration resides in the registry file:

products\i3fp\registry\clusters\www\<cluster-name>\settings.xml

Instance registry

Configuring the instance registry only affects the specific instance. Every element in the instance registry can also be specified in the server registry file, in which case it affects all the instances on that server.

To change instance registry

1. On the relevant Precise node (proxy), manually change the products\i3fp\registry\instances\www\<server-name>\<instance_name>\settings.xml file.
2. Save the file.
3. Run the update-main-registry CLI command on the same Precise node.
   • UNIX. /infra/bin/psin_cli.sh -action update-main-registry -i3-user admin -i3-clear-password admin -registry-path /registry/clusters/www/<server_name>/<instance_name>
   • Windows. infra\bin\psin_cli.bat -action update-main-registry -i3-user admin -i3-clear-password admin -registry-path /registry/clusters/www/<server_name>/<instance_name>

This will force a registry sync from the node's FocalPoint to the main FocalPoint.

Cluster registry

Configuring the cluster registry affects all instances of the specific cluster.

To change the cluster registry:

1. On the relevant Precise node (proxy), manually change the products\i3fp\registry\clusters\www\<cluster-name>\settings.xml file.
2. Save the file.
3. Run the update-main-registry CLI command on the same Precise node.
   • UNIX. ./infra/bin/psin_cli.sh -action update-main-registry -i3-user admin -i3-clear-password admin -registry-path /registry/clusters/www/<cluster_name>
   • Windows. infra\bin\psin_cli.bat -action update-main-registry -i3-user admin -i3-clear-password admin -registry-path /registry/clusters/www/<cluster_name>

This will force a registry sync from the node's FocalPoint to the main FocalPoint.

connection-params (in general section)

The following table describes the registry elements for the connection-params (in the general section).

Table 1 connection-params (in general section)

ssl (in connection-params, in general section)

The ssl element in the registry is a "container" element that contains the use-client-certificate, cipher-list, and log-file elements. It also contains another "container" element: client-certificate. This "container" element contains the path, password, and key-path elements.

The following table describes the registry elements that can be used for the ssl instance registry.

Table 2 ssl elements

user-authentication (in connection-params, in general section)

The following table describes the registry elements for the user-authentication (in connection-params, in general section).

Table 3 user-authentication (in connection-params, in general section)

Server-side

The following table describes the registry elements for the server-side .

Table 4 Registry elements for server-side

user-defined-transaction-name

By configuring the elements user-defined-transaction-name, you can change the collection method of the transactions. This is valid for Precise for Web and Precise TPM. The collection method can be represented by one of the following tags:

Table 5 Elements

When configuring a user defined transaction name, you will need to specify the display mode between the <display-mode> tags. Possible values are:

• prefix. This will place the value in the before the original transaction name.

• override. This will replace the original transaction name with the configure transaction name.

  When you configure a user defined transaction name, verify that it is a field with little variance (not many different values). For example, the cookie APP_VIEW is a good candidate to be used. In contrary to the SESSION_ID, which is a bad candidate, as it has a very large range of values. When you have a very large range of values, the Precise for Web schema tables grow very large.

To add a cookie - example

• If you have a cookie called USER_NAME in your application, you may add it to the user interface (as User Name), by adding the following UserDefined element:

<user-defined-transaction-name>
          <cookie-name>USER_NAME</cookie-name>
          <display-mode>prefix</display-mode>
</user-defined-transaction-name>

To add a dom element - example

• If you want to add the Title (DOM element) of your Web pages to the user interface (as My Title), you can add the following UserDefined element:

<user-defined-transaction-name>
          <dom-element>document.title</dom-element>
          <display-mode>prefix</display-mode>
</user-defined-transaction-name>

If the client-side agent is not installed on your Web server (only server-side is installed), you can not collect the Title DOM element.

user-defined-client-ip

By configuring the element user-defined-client-ip, you can change the way that client IP is collected by the server-side agent. You can instruct Precise for Web to collect the client IP from 3 different sources (instead of the HTTP request itself):

• Cookie
• Request header

• URL parameter

  You may want to change the way the client IP is collected when the Web server is behind some proxy, in which case the collected client IP is always the IP of the proxy.

apache-virtual-hosts

To separate Apache Virtual Hosts in different Precise applications, the Precise administrator needs to perform the following steps:

1. Create an Application in Precise for each Virtual Host. (For more information, see the Working with the Application Installer wizard section in the Precise Installation Guide.)
2. Place the Apache instance in the multiple instance view in each of the defined Precise applications.

3. Go to the instance registry and set the a registry entry for each of the Virtual Hosts using the following format:
   <virtual-host-settings>
        <vhost-i>
             <vhost-name>name</vhost-name>
             <precise-application-name>application_name</precise-application-name>
        </vhost-i>
        …
             <!-- map all unmapped Virtual Hosts to this env (if not defined the information will be discarded) -->
        <vhost-i>
             <vhost-name>default</vhost-name>
             <precise-application-name>application_name</precise-application-name>
        </vhost-i>
   <virtual-host-settings>

   In a case of an unmapped Virtual Host, transactions can either be displayed in the “default” application (“default” is set), or discarded if “default” is not set.

4. Restart the Web Collector on the monitored server by performing the following steps.
   1. Go to AdminPoint>Agents.
   2. Click Stop to stop all Web agents on the monitored server.
   3. Click Start to start all Web agents on the monitored server.

After performing these steps, you will see the unique information of each Virtual Host in each of the defined Precise applications.

The limitations of this feature are:

• Once the instance is configured as defined, each of the Virtual Hosts are linked to a specific application in Precise and the information cannot be shared in a multiple instance view.
• J2ee instances which are shared between two applications can cause unexpected results, and thus should be defined in two Virtual Host Precise applications.

Server registry

Configuring the server registry affects the Web collector and the instances on the server.

server-side

Table 6 client-side section

Table 7 verify section (inside web-collector)

Table 8 server-side section (inside verify, inside web-collector)

Table 9 client-side section (inside verify, inside web-collector)

The entries below are similar for 4 sections (with one exception*):

Table 10 summed section (inside server-side, inside output, inside web-collector) raw section (inside server-side, inside output, inside web-collector), summed section (inside client-side, inside output, inside web-collector), raw section (inside client -side, inside output, inside web-collector)

Table 11 server-side section (inside tac, inside smartlink, inside web-collector), client-side section (inside tac, inside smartlink, inside web-collector)

Table 12 server-side section (inside input, inside web-collector), client-side section (inside input, inside web-collector)

Table 13 statistics section (inside ivp, inside web-collector)

Table 14 processing section (inside ivp, inside web-collector)

Table 15 web-collector section

Table 16 summary section (inside web-collector)

Table 17 server-side section

Table 18 client-side section

Table 19 statistics section

Table 20 processing section (inside web-collector)

Table 21 server-side section (inside processing, inside web-collector)

Table 22 client-side section (inside processing, inside web-collector)

Table 23 network section (inside processing, inside web-collector)

Table 24 server-side section (inside filtering, inside web-collector)

Table 25 client-side section (inside filtering, inside web-collector)

FocalPoint registry

The following section describes the FocalPoint registry element.

user-agents

The user-agent element consists of a set of definitions of user agents. A user agent is a device that may access a Web server. A typical user agent is a browser like Microsoft Internet Explorer or Firefox. Other types of user agents are automatic HTTP traffic generators, like Precise Insight Inquire. The Precise for Web Collector agent, automatically collects the user agent of every request that it monitors. To extract a comprehensive user agent name and version from the user agent header of the request, the agent uses the definitions in the user-agents element. By default, the user-agent element contains a definition for most of the industry’s known Web servers, like Microsoft Internet Explorer, Firefox, Netscape, Mozilla as well as the integrative Precise Insight Inquire traffic generator. However, you can add any number of user agents to the list, or change the definition of an existing user agent to adjust it to customers private needs or conventions. For example, the definition for the Netscape browser is:

<user-agent id="Netscape" display-string="Netscape version">
     <version-search-string>Netscape</version-search-string>
     <search-string value="Netscape"/>
</user-agent>

The default user agents that the product supports out-of-the-box are:

• Precise Insight Inquire
• Microsoft Internet Explorer
• Firefox
• Opera
• Netscape
• Mozilla
• Konqueror
• iCab
• Safari

The following table describes the registry elements for the user-agent in the FocalPoint registry.

Table 26 Registry elements

Adding Web filter parameters

If you use an Apache, iPlanet, Sun ONE, WebSphere, Tomcat, Oracle Application Server, SAP, J2EE, or BEA WebLogic server, you can specify some Web filter settings that the Web server loads on startup. These parameters are the same for all Web servers. To add them, follow the instructions for the specific Web server. For more information, see Addable parameters.

To add parameters on an Apache server

1. Open the httpd.conf file.
2. After the LoadModule pssfilter_module line, add the parameter.

For example:

LoadModule pssfilter_module... PssFilterTrace 1

To add parameters on an iPlanet server

1. Open the magnus.conf files.
2. At the end of the Init fn=pss-init line, add the parameter.

For example:

Init fn=pss-init PssFilterTrace="1"

To add parameters on any J2EE server by editing the web.xml file

1. Open the web.xml file.
2. Add the parameters to the <filter> element in the following format:

<init-param>
<param-name>xxx</param-name>
<param-value>yyy</param-value>
</init-param>

For example:

<filter>
<filter-name>pssFilter</filter-name>
     <description></description>
     <filter-class>com.precise.ifweb.Collection.Filters.pssFilter
     .WLFilter</filter-class>
     <init-param>
          <param-name>PssFilterTrace</param-name>
         <param-value>1</param-value>
     </init-param>
</filter>

Addable parameters

The following table lists all parameters that you can add to the Web filters. This mechanism should only be used for the instance name and <i3_root>. Any other parameter should only be added after consultation with the Precise Enterprise Support Team.

Table 27 Addable Web filter parameters

The following table gives a comparison of the parameter and its equivalent registry element.

Table 28 Parameter and Registry element

Grouping consecutive URLs by pattern

The Activity tab of Precise for Web displays information on the URLs and pages visited. In some cases, the database tables that contain this information can easily swell and harm the performance of the user interface, for example when URLs are generated automatically.

To reduce the accumulation frequency of URLs, Precise for Web lets you group consecutive URLs by pattern by editing the data-patterns registry element. Each of the data-pattern elements (urls, pages, titles, domains, and user-defined-transaction-name) can be specified with methods. The available methods are prefix, suffix, prefix-by-key, and regex.

You can add as many methods and patterns to any of the sections (<urls>, <pages>, <titles>, <domains>, <user-defined-transaction-name>).

The following table describes the available methods.

Table 29 methods

The following code is an example of the element’s content for an URL element when all the grouping methods are activated:

<data-patterns>
     <urls>
          <execute>true</execute>
          <methods>
               <method1>
                    <name>prefix</name>
                    <patterns>
                         <pattern1>/redirectlogon.html</pattern1>
                    </patterns>
               </method1>
               <method2>
                    <name>suffix</name>
                    <patterns>
                         <pattern2>ads.com</pattern2>
                    </patterns>
               </method2>
               <method3>
                    <name>prefix-by-key</name>
                    <patterns>
                         <pattern3>:jsessionid=</pattern3>
                    </patterns>
               </method3>
               <method4>
                    <name>regex</name>
                    <patterns>
                         <pattern4 replace="$1">\d+: (.*)</pattern4>
                    <patterns/>
               </method4>
          </methods>
     </urls>
</data-patterns>

When URL pattern prefix grouping is activated, a percentage sign (%) is added at the end of a URL. For example, the URL /redirectlogon.html/121231245 is saved in the database as /redirectlogon.html%.

To group consecutive URLs by pattern

1. Open the relevant registry file (instance registry, server registry, or focal-point registry) and find the data-patterns element (If it does not exist, you can add it as appears in the server registry)
2. Edit the data-patterns element in the following way:
   • Set the required <execute> elements to true.
   • Choose the method (prefix, suffix, prefix-by-key, or regex) in the required element (urls, pages, titles, domains).
   • Define the URL patterns in the <pattern> elements. You can include as many <pattern> elements as required.
   • If you choose the regex method, use the replacement string. For example:
     <pattern replace=“$1”>\d+: (.*)</pattern>
3. Save and close the file.
4. Restart the Precise for Web server-side and dynamic instrumentation agents monitoring the relevant environment.

Temporarily stopping the maximum number of table rows test

If the database tables that contain the URLs and pages that are visited exceed the maximum number of rows, the installation verification procedure (IVP) issues an error message. To prevent this message from reappearing until the accumulation frequency of URLs has been lowered, you can temporarily stop the ‘maximum number of table rows’ test.

To temporarily stop the ‘maximum number of table rows’ test

1. Open the <i3_root>\products\www\ivp\resources\functions_ivp.xml file in an editor:
2. In the file, set the <max-rows-for-alert> element to 0.
3. Save and close the file.

Dynamic instrumentation

When you install a Web server agent, you are asked whether you would like to dynamically instrument Web pages. Also when you select an existing instance, you can edit it, so that the dynamic instrumentation can be applied. In both cases this results in an additional entry in the AdminPoint window. The new entry shows identical instance information for all but one column: the Agent column. In this column the agent is shown as Web Instrument agent. The Instrument.xml file handles the dynamic instrumentation configuration.

About the instrumentation configuration file (Instrument.xml)

If the instance is part of a cluster, the Instrument.xml file is located in the <FP server>\products\i3fp\registry\clusters\www\<name of cluster> directory.

If the instance is not part of a cluster, the Instrument.xml file is located in the <FP server>\products\i3fp\registry\instances\www\<monitored instance name>\<instance name>\<instance name> directory. If you make changes in the Instrument.xml file, then you will also have to make the changes in the proxy (or proxies). The recommended way to do so it you use the CLI command as describe before. See Instance registry.

Following is an example of the file structure that is explained in the section following the example:

<dynamic-inst>
          <enable>true</enable>
          <handle-js>true</handle-js>
          <prolog-string> <![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD
          XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/ xhtml1-transitional.dtd">]]>
          </prolog-string>
          <no-recompress>true</no-recompress>
          <accumulate-on-parsing>true</accumulate-on-parsing>
          <max-parsing-bytes>2048</max-parsing-bytes>
          <js-mime-type>text/javascript</js-mime-type>
          <instance-id>1234</instance-id>
          <strict-servlet-api>true</strict-servlet-api>
          <private-log>false</private-log>
          <i3-log>false</i3-log>
     <webgarden>
          <enable>false</enable>
          <sampling-interval>2000</sampling-interval>
     </webgarden>
     <user-agents>
               <user-agent name="debug">
                    <i3-log>false</i3-log>
                    <private-log>false</private-log>
                    <accumulation>default</accumulation>
                    <parsing>false</parsing>
                    <second-script>false</second-script>
                    <enable>true</enable>
               </user-agent>
               <user-agent name="MSIE">
                    <i3-log>false</i3-log>
                    <private-log>false</private-log>
                    <accumulation>default</accumulation>
                    <parsing>false</parsing>
                    <second-script>false</second-script>
                    <enable>true</enable>
               </user-agent>
               <user-agent name="Default">
                    <i3-log>false</i3-log>
                    <private-log>false</private-log>
                    <accumulation>default</accumulation>
                    <parsing>false</parsing>
                    <second-script>false</second-script>
                    <enable>true</enable>
               </user-agent>
     </user-agents>
     <include-ip>
          <range from="123.23.1.1" to="123.23.1.255" />
          <range from="125.2.1.1" to="125.2.1.255" />
     </include-ip>
     <url-exclude>
          <suffix>.gif</suffix>
          <suffix>.jpeg</suffix>
     </url-exclude>
     <url-include>
          <prefix>/products</prefix>
          <prefix>/petstore/accounts</prefix>
          <suffix>createData.dll</suffix>
     </url-include>
     <include-char-encoding>
          <char-enc>shift_jis</char-enc>
          <char-enc>jis</char-enc>
     </include-char-encoding>
     <req-header-exclude>
          <header name="content-type" value="application/x-www-form- urlencoded" />
     </req-header-exclude>
</dynamic-inst>

About the Instrument.xml tags

The following table contains the tags that can be encountered in the Instrument.xml file. "not applicable" means that the tag has no influence on that specifically chosen instance type.

Table 30 Instrument.xml tags

The tags that are marked with an asterisk (*) appear in the Frequently Asked Questions document.

About include and exclude tags

The following list describes the order in which the include and exclude tags are handled in the instrument.xml file:

• The optional tag "enable" can disable the whole instrumentation process for all HTTP responses.
• The "include-ip" section is checked first. If there is no "include-ip" section, all IPs can be instrumented.
• The "url-include" section is checked before the "url-exclude" section.

If one "url-include item is specified, this HTTP request must be instrumented. If no "url-include" section is specified, all URLs are included.

If one or more "url-exclude" item(s) is (are) specified, the HTTP request(s) must be skipped.

• If the filter recognizes a "content-type" that does not contain "text/html", the instrumentation process is skipped for that particular HTTP response.

IDERA |  Products | Purchase | Support |  Community |  Resources |  About Us  | Legal