Page History

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

Anchor
AboutConfigForWebCollectors AboutConfigForWebCollectors

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.

Anchor
ConfigureRegistrySettings ConfigureRegistrySettings

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
NOTE    You can set instance configuration in the products\i3fp\registry\instances\www\<server-name>\settings.xml file if you want to set the same setting for all instances on the machine. Consider however that settings in the instance registry will override the settings in the server registry.
Web Collector configuration resides in the registry file:
products\i3fp\registry\instances\www\<server-name>\settings.xml
NOTE    You can set the configuration for all Web Collectors at once by modifying the file products\i3fp\registry\products\indepth-web\focal-point.xml Consider however that settings in the server registry will override the settings in the focal-point.xml file.
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.
How 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.
NOTE    All instances in the cluster need to be restarted via AdminPoint after changing the cluster registry.
How 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.
NOTE    Cluster registry changes override the FocalPoint registry changes.
connection-params (in general section)
The following table describes the registry elements for the connection-params (in the general section).
Table 9-1    connection-params (in general section)
Registry element    Description
site-name    Specifies the name of the Web application (context root). Only relevant for J2EE Web servers and only when the filter is not installed on the root Web application.
filter-connect-ext-cmd-line    Additional miscellaneous command line parameters for the psi_web_filter_connect utility which is used to send management URLs to the filter.
authorized-ips    Comma separated IPs list that specifies the IPs from which the Precise for Web agent management pages can be browsed. Other IPs that will try to access this status will be blocked. (127.0.0.1 is added by default).
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 9-2    ssl elements
Registry element    Child element    Description
use-client-certificate        Specifies the use of a client certificate when Precise for Web tries to connect using
Secure Socket Layer (SSL). Default value: false.
cipher-list        Specifies additional ciphers that OpenSSL uses on top of the default ciphers for SSL
version 2 and 3 and Transport Layer Security (TSL) version 1. For more information, see the following URL: http://www.openssl.org/docs/apps/ciphers.html#cipher_suite_names.
log-file        Specifies the file that OpenSSL logging is written to.
client-certificate        Specifies client certificate details, if the monitored Web server requires it. Container for path, password, and key-path elements.
    path    Specifies the full path of the client certificate.
    password    Specifies the password to be used to decrypt the certificate file. The password itself should be encrypted using the Encrypt command that is part of the Precise CLI Utility.
For more information, see the Precise CLI Utility Reference Guide.
    key-path    Specifies the path to the private key if it is different than the path to the certificate.
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 9-3    user-authentication (in connection-params, in general section)
Registry element    Description
user    Specifies the user name for authentication.
password    Specifies the user password for authentication. The password itself should be encrypted using the Encrypt command that is part of the Precise CLI Utility.
For more information, see the Precise CLI Utility Reference Guide.
domain    Specifies the domain name for authentication.
method    The authentication method.
One of the following methods should be used:
basic digest ntlm
Server-side
The following table describes the registry elements for the server-side .
Table 9-4    Registry elements for server-side
Registry element    Description
ext-list    Specifies the extensions used, such as .html, .jsp, and .asp. For example:
<ext-list>html,jsp,asp</ext-list>
Default values: html, swe, asp, aspx, htm, jsp, php, gbl, cfm, pl, php3, do, IScript_PT_NAV_PAGELET, I_Script_AppHP, IScript_UniHeader_Frame, IScript_PT_NAV_INFRAME, iscript_apphp, iscript_timeoutwarning
ext-list-separator    Specifies the separator of the extension list. Default value: , (a comma)
stat-extension    Specifies the URL of the statistics module. Add this registry element only if you know that the statistics URL differs from the default URL for the specific Web server type.
Default values:
Apache: server-status?auto iPlanet: .perf
WebLogic: weblogicstat
WebSphere: websphere_stats
filter-trace    Specifies whether filter logging is used. Default value: false
filter-session-cookie    Specifies the name of the session cookie used by the application. Define this value to improve client-side correlation in the following Web servers: WebLogic, WebSphere, Tomcat, Oracle AS, Sun One, IIS, Apache 2.x.
Default value: JSESSIONID
max-i4w-cookie-size    Specifies the maximum size of a Precise for Web cookie (in bytes). Default value: 2048
filter-ignore-files    A comma-separated list of files that the filter has to ignore. If a file contains any of these patterns, it is ignored. Only relevant for J2EE filters.
filter-use-encoding    Specifies the translation of URLs and URL parameters to unicode format. Set this parameter if
URLs or parameters may contain non-ASCII characters. Default value: false
filter-encoding-name    Specifies the name of the URL encoding mechanism. Set this parameter if the server handles
URLs that use neither UTF-8 nor local encoding, which are the default encoding types.
web-parameter-delimiters    A list of URL parameters delimiters. These delimiters are used to separate the parameters of a
URL from the URL itself. For example, the URL: “index.html?param1=abc” has 1 parameter
‘param1’. The parameters delimiter in this URL is ‘?’. Use this element if your application uses
non-standard delimiters (like ‘;’). To specify more than one delimiter, concatenate all delimiters into one string, for example: <parameter-delimiters>?;.</parameter-delimiters> sets 3 delimiters: ‘?’, ‘;’
& ‘.’ If more than 1 delimiter is used, the first one that is encountered in the URL is used. Default value: ? (question mark)
collect-post-parameters    If this registry element is set to true, the filter collects parameters that are passed in the request body (as opposed to parameters that are passed with the URL). For enabling the post-parameters collection on an IIS Web server, another action is needed (besides changing this flag) - For more information, see the Adding post-parameters collection for IIS6 and Adding post-parameters collection for IIS7 sections in the Installing Web Tier Collectors section of the Precise Installation Guide.
Default value: false (for Siebel this is set to “true” (automatically))
Note: This feature is not supported for Apache 1.3
Note: Only Form post-parameters are supported. This means:
Only submitted page forms of which the POST request contains the header Content-Type: application/x-www-form-urlencoded are supported. The post-parameters are passed as: key1=value1&key2=value2&...
Any other type of post-parameters are not monitored. For example - if the POST data is XML.
Note: In any case no more than 1500 characters of POST data will be collected.
apache-pid-file-path    Sets the path for apache .pid file (commonly: httpd.pid). Should be set only when the .pid file path is not specified in the configuration file or in any other case, when the statistics agent fails to resolve it.
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 9-5    Elements
Elements    Description
cookie-name    Collects the value of the specified cookie.
req-header-name    Collects the value of the specified request header.
parameter-name    Collects the value of the specified GET parameter (not relevant for POST parameters).
dom-element    Collects the value of the specified dom element. Applicable only if the client.-side agent is installed.
display-mode    The way the transaction name is displayed in Precise for Web and Precise TPM.

...

The following table describes the registry elements for the user-agent in the FocalPoint registry.
Table 9-26    Registry elements
Registry element    Description
user-agent    A user agent definition that Precise for Web uses to find and describe user agents.
user-agent.id    A string identifier for the user agent. This identifier is not the display name.
user-agent.display-string    The display string that is shown in the user interface for this user agent. You can use the
version token which is replaced with the detected user agent version.

Anchor
AddWebFilterParameters AddWebFilterParameters

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.
See “Addable parameters” on page 132.
NOTE    Modification of IIS Web filter parameters is not yet supported.
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 9-27    Addable Web filter parameters
Parameter    Description
PssInstanceName    Specifies the name of the filter’s instance.
PssInstanceID    The instance ID as specified in the infrastructure database.
PssI3Root    Specifies the path to the Precise installation directory.
PssReadConfFile    Specifies whether to read the configuration files on filter initialization. If this parameter is set to FALSE, parameters are taken from the Web server only.
Default: TRUE
PssRestartFilesPath    Specifies an alternate location for the pss_restart file. By default this file is located under the directories of the Web server itself (the exact location is web server type dependent). Set this to a different path if the file cannot be created at the default location.
PssInitLog    Specifies whether to write initialization log messages to standard output. In some cases the standard output is written to the Web server log.
Applies only to J2EE-based application servers (Sun ONE, WebSphere, Tomcat, Oracle Application Server, SAP J2EE, or BEA WebLogic)
The following table gives a comparison of the parameter and its equivalent registry element .
Table 9-28    Parameter and Registry element
Parameter    Registry element
PssFilterTrace    filter-trace
PssIgnoreFiles    filter-ignore-files
PssSessionCookieName    filter-session-cookie
PssMaxI4WCookieSize    max-i4w-cookie-size
PssCorrelationMode    web-disable-correlation
Note: The opposite of this registry element works as its equivalent parameter.
PssExtList    ext-list
PssExtListSeparator    ext-list-separator
pcs_shm_dir    general-pcs-shm-dir
PssURLEncodingName    filter-encoding-name
PssUseURLEncoding    filter-use-encoding

Anchor
GroupConsecutiveURLs GroupConsecutiveURLs

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>).
NOTE    The tags <methodN> and <patternN> should be numbered so that 'N' is replaced with a consecutive number.
NOTE    In URLs and Pages, pattern definitions only work on the path part. For example, in the URL /index.jsp?id=&eventid=, the path part is /index.jsp and the parameters part is id=&eventid=. To handle collection definitions (aka grouping) on the parameters part, refer to the Collector Settings section. In the above example, any pattern that is defined on the URL, ignores the parameters part (id=&eventid=).
The following table describes the available methods.
Table 9-29    methods
Method    Description
prefix    Take only the defined prefix.
For example: <pattern1>abraham</pattern1> - For URL 'abraham123.html' you will see
'abraham%'.
suffix    Take only the defined suffix.
For example: <pattern1>html</pattern1> - For URL 'abraham123.html' you will see '%html'.
prefix-by-key    Take text up to the defined key (not including that key).
For example: <pattern1>;jsessionid</pattern1> - For URL 'abraham123.html;jsessionid' you will see 'abraham123.html%' (if showReplaceChar="false", you will get 'abraham123.html').
regex    Use the given regular expression to change the given URL.
For example: <pattern1 replace="$1">service(.*)</pattern1> - For URL 'service123' you will get '123' (for more on regular expressions, consult your support representative).
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 regisrty, 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.

Anchor
TempStoppingTest TempStoppingTest

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.

Anchor
DynamicInstrumentation DynamicInstrumentation

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> 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” on page 116.
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 9-30    Instrument.xml tags
Tag    Description
dynamic-inst    The first tag of the dynamic instrumentation configuration file. J2EE: mandatory
ISAPI: mandatory
enable    Enables or disables the instrumentation filter globally. J2EE: optional
ISAPI: optional Values: true, false Default value: true
handle-js*    Enables or disables the JavaScript handling by the filter. J2EE: optional
ISAPI: optional Values: true, false Default value: true
strict-servlet-api (J2EE)    Forces compatibility with the J2EE servlets specifications. J2EE: optional
ISAPI: not applicable Values: true, false Default value: true
js-mime-type    Uses js-mime-type protocol. J2EE: optional
ISAPI: optional
Values: if possible to use dynamically obtained, otherwise use application/x-javascript
Default value: if possible use dynamically obtained, otherwise use application/x-javascript

...