Transaction Filters

Transaction filters measure the performance of web applications.

Filter Types

The agent supports two different types of filters.

• HTTP Filters
• Internet Explorer Filters (IE Filters)

The syntax for the filter definitions has the same structure for the two types of filters.

HTTP Filters

HTTP filters are filters that are monitored directly on the packets collected on the monitored network interface (NIC).

The filter specification is applied to requests sent to the specified <host;port>. Responses are not filtered.

As filtration is applied at the network layer, HTTP filters can only be applied to clear-text requests. This means that request made using SSL (Secure Socket Layer) or other types of encryption can't be monitored with this type of filter.

Internet Explorer Filters

Internet Explorer (IE) filters are useful for measuring page load times. They are applied to requests made from Internet Explorer only. This type of filter is particularly useful when requests are made using the HTTPS protocol (HTTP over SSL) in which case the HTTP fails to extract any useful information because all the TCP packets that carry the HTTP conversation have been encrypted, thus making the request unreadable on the network capture layer.

Filter Syntax

A transaction filter is configured by adding configuration lines to the agent configuration.

Host = www.dr.dk
Tag1.Id = URL:
Tag1.RegExp1 = URL,\{.*\}

A simple filter example which will generate tags like URL:page.htm for each URL visited on http://www.dr.dk.

A transaction filter definition must contain at least one Host specification, but multiple host specifications are allowed. A filter contains of one or more Tags, and each tag contains an ID and one or more regular expressions. The definition for a transaction tag may also contain a session specification.

Regular expressions match the specified data source, and may extract parts of the matched expressions. The extracted parts are the concatenated with the tagid to form the tag.

Regular expression examples:

Tag1.RegExp1 = URL,{.*}
   Tag1.RegExp2 = Method,GET
   Tag2.RegExp1 = URL,{.*}.jpg
   Tag5.RegExp1 = doShow,true

The regular expression source (ExpSource) defines which part of the request should be used when matching the regular expression.

The regular expression really defines two different things:

• The criteria for a match
• Which part of the regular expression source should be extracted

The part (or parts) that should be extracted are enclosed in curly brackets ({}).

Here is an overview of the syntax used for specifying regular expressions:

Transaction Name Construction

When a request fulfills the regular expressions in a filter, a transaction name is constructed by concatenating the Tag Identifier (for exampleTag1.Id) with the information extracted by the regular expressions, for example:

Tag1.Id = URI:
Tag1.RegExp1 = Method,{.*}
Tag1.RegExp2 = URL,{.*}

The first regular expression (Tag1.RegExp1) will extract the value of the http _Method{_}, that is _GET 'POST{_}. The second regular expression Tag1(.RegExp2) will extract the entire URL of the requests. The Id and the extracted parts are concatenated and generates names like :

• URI:GET/images/image.gif
• URI:GET/index.html

Multiple Tags and Multiple Regular Expressions

When the PerformanceGuard agent examines a request to determine if it belongs to a filter, it will go through the tags in the filter one by one:

1. For each tag the agent tests if the regular expressions for the tag match.
2. If all regular expressions match the criteria, the agent constructs a tag ID and assigns that tag ID to the connection.
3. If a regular expression for a tag doesn't match, the agent considers the next tag defined for the filter until a match is found or there are no more tags left to examine.

A connection keeps its tag ID until it's closed, or a request that generates a different tag ID is encountered on the connection. This means that it may be necessary to construct dummy tags in order to un-assign a connection.

Transaction Configuration in a Proxies Setting

When communication to HTTP servers is proxied the HTTP transaction filter needs to be constructed in a special way to generate tags.

• The address and port of the proxy needs to be specified in the Host configuration line.
• A new line needs to be added to the RegExp section of the Tag specification. Matching the host URI of the HTTP server with the Host HTTP header field.

Host = myproxy.here.net:8088
Tag1.Id = Google-PNG-
Tag1.RegExp1 = Host, .*google.com
Tag1.RegExp2 = URL, {.*}\.png

The filter creates tags for all png images retrieved from Google, through the proxy myproxy.here.net on port 8088

Sessions

In addition to normal single-packet transactions it's possible to construct tags that retain information in an HTTP session from request to request. You do this by specifying special session parameters on the tag:

Example

Sample configuration:

Host = possystem.company.com
Logging = true
Tag1.Id = TeamNet-
Tag1.SessionId = cookie, .*SSO_ID\={[^;]*}.*
Tag1.SessionImutable = false
Tag1.SessionContext = p_app, {.*}
Tag1.SessionDefaultContext = <>

In the sample, logging is enabled. The text "TeamNet-" is prepended to all generated tags: As there are no regular expressions all packets to the host will match the tag, and a tag will be generated. The session ID is the SSO_ID cookie entry (generated by the serving web-server). The session context is determined by the p_app varaiable. The text "<>" is inserted if no session context has been found for the session yet.

Examples of generated tags:

TeamNet-<>

TeamNet-shop

TeamNet-workshop 

TeamNet-finance 

Debug Transaction Filters

To make it easier to debug transactions filters it's possible to enable logging of the

Edit the Configuration Locally on the Agent

When you create transaction filters, it's often a good idea to avoid the delay that can occur between the time that a change is made in a transaction definition in the PerformanceGuard web interface and the time that the new configuration arrives at the agent. To avoid the delay you can edit transaction filters directly on an agent.

Consider if you want data from a locally modified agent to be transmitted to the backend server. To avoid such data being sent to the backend server, you can configure the agent so that it doesn't communicate with the backend server: In the agent user interface, select Config > Send Reports and make sure that the >> in front of Send Reports isn't present when you apply any modified configurations.

When you edit the configuration locally on an agent, you must use a slightly different syntax for the transaction configuration lines than when using the PerformanceGuard web interface.

Note that all transaction filter configuration lines start with Filter.HTTP.Demo. The Filter.HTTP prefix is used to direct the configuration lines to the HTTP transaction filter engine. Demo is the name of the filter being constructed. Note that there is no specific line that creates the named filter, the filter is implicitly created by the first line that sets an attribute for it.

Apply the Modified Configuration

When you have edited the agent configuration locally, the new configuration must be applied to the agent. To do this, select Actions > Reconfigure in the agent user interface. After a few seconds the agent will display the status view. This is the same view that you can obtain by selecting View > Status.

If you want to revert to the configuration supplied by the PerformanceGuard backend server, select Actions > Reset Configuration. This causes the agent to contact the PerformanceGuard backend server and tell the backend server that it has an unknown configuration (configuration ID is set to zero). When that's the case, the PerformanceGuard backend server will send a new configuration to the agent, and the agent will reconfigure itself. When you are using local modifications on an agent in a production environment, you should always remember to reset the configuration when you are done.

Check the Integrity of the Configuration

If there are errors when parsing the tag configuration, the agent will log error messages. To view such error messages in the agent user interface, select View > Errors. To view them in the PerformanceGuard web interface; select ADMINISTRATION > Status > Errors.

Debug Request Packets Using the Agent

It can be tricky to create a transaction filter that selects the packets that correspond to specific application transactions. In order to make this task easier you can use the agent to look at the HTTP requests that a client sends to a web server.

To capture the request packets:

1. Specify Logging = true for the filter
2. Make sure that you create a registry key TagDebugDir with the value set to the folder where you want the log file to be created.

A log file will be created for each filter that has logging enabled. The log files will contain all the Regular Expression sources that were extracted from the request, and also any tags generated by running the filter on the request.

Debugging Internet Explorer Tag Filters

When you are developing tag filters for use with the internet explorer agent, you can use the method that's used for editing HTTP filters. When the filter is specified, however, you need to specify "IE" instead of "HTTP" for the filter type:Example - IE https Filter definition with SSL port:

Filter.IE.MPS_Front.Host = www.mpower-shipper.com:443

Filter.IE.MPS_Front.Tag1.id=MPS_FrontPage 

Filter.IE.MPS_Front.Tag1.RegExp1 = URL,/MPS/Controller 

Filter.IE.MPS_Front.Tag1.RegExp2 = do_displayMainPage,true

When you define IE filters for use with https sites, you must include the SSL port in the host attribute of the filter

The Internet Explorer Agent will assign the port number 443 to the host when an https URI is used to access the resource.

Note that you need to apply the modified configuration by selecting Actions > Reconfigure in the agent user interface, in the same way that you apply locally modified HTTP transaction filter modifications. The Internet Explorer Agent will load the new configuration after the next web page is loaded.

When the Internet Explorer Agent has reloaded the transaction definitions, you can check that they have been parsed correctly by looking at the interface of the IE Agent itself

1. To check the matches generated by the IE Agent enable the Internet Explorer Agent console window by selecting Dialog Enable on the about:ieagent:settings page.
2. In the window that appears, click Matches and get a list of generated tags in the upper left part of the window.
3. In the lower part of the window you can verify the events that have been intercepted by the Internet Explorer Agent. This is useful when you create filters for https-based applications, because URIs of https requests are encrypted inside Internet Explorer, and this means that they are not visible in network packet traces.