Chat now with support
Chat with Support

Foglight APM for Real User Experience 5.9.9 - Administration and Configuration Guide

Getting started Configuring traffic capture
Managing Sniffers Managing Archivers Managing capture groups Managing sessionizing policies Managing monitored ports Managing monitored IP addresses Managing monitored subnets Managing identifiers for virtual addressing schemes Managing private keys Managing web services and SOAP operations
Configuring traffic analysis Configuring analyzers Capturing traffic outside the network Configuring advanced options Integrating Foglight APM with other products Maintaining and troubleshooting Appendix: Building regular expressions in Foglight Appendix: Traffic analysis processing
Understanding the traffic analysis workflow Stage 1: Run hit analysis Stage 2: Run sequence analysis Stage 3: Finalize stopped sequences Stage 4: Finalize the session Example of interdependent analyzers Online-Only Topics
Removing items from a table Defining extraction expressions Adding, copying, and editing archivers Testing archivers Configuring archiver database shard settings Adding, copying, and editing sniffers Testing sniffers Adding and editing capture groups Testing capture groups Adding and copying sessionizing policies Editing sessionizing policies Selecting session identifiers from a discovery list Adding and editing session identifier variables Organizing session identifiers Selecting user name variables from a discovery list Adding and editing username rules Selecting URL prefixes from a discovery list Adding or adding URL prefixes Selecting ports from a discovery list Adding or editing monitored ports Selecting IP addresses from a discovery list Adding or editing monitored IP addresses Looking up host names for all monitored IP addresses Associating private keys with IP addresses Selecting subnets from a discovery list Adding and editing monitored subnets Adding identifiers Editing identifiers Finding IP addresses in HTTP headers Configuring a custom HTTP header using Microsoft IIS Manager Adding and editing local private keys Adding and editing HSM private keys Exporting keys using Microsoft Management Console Adding or editing web services Importing WSDL files to define web services Managing custom fields and metrics Adding, copying, and editing custom fields Removing custom fields Editing custom metrics Removing custom metrics Managing sensitive data Adding, copying, and editing sensitive hit detail policies Adding, copying, and editing sensitive content expression policies Modifying members of pivot categories Selecting aliases from a discovery list Adding, copying, and editing domain rules Adding, copying, and editing large hit details Adding, copying, and editing URL classifiers Reviewing rules for browser category, browser, and operating system hit details Adding user-defined user agent rules Adding and editing additional parsed response types Adding and editing captured request body types Adding, copying, and editing scripts Removing scripts Referencing configuration objects in a script Testing regular expressions Syntax for test data Adding simple hit analyzers using the Setup Wizard Adding simple sequence analyzers using the Setup Wizard Adding analyzers Copying analyzers Editing analyzers Adding and editing conditions Creating a simple Boolean expression Creating a complex Boolean expression Disabling standard metrics generated by a hit analyzer Adding custom metrics Editing custom metrics Selecting pivot categories Breaking out metrics into dynamically-named topology objects Publishing metric timeslices for the Geographical Perspectives dashboard Changing SLA thresholds Adding custom field updates Editing custom field updates Adding scripts to an analyzer Editing scripts Creating new scripts on the fly Adding hit storage restrictions Editing hit storage restrictions Adding sequence events Editing sequence events Adding static page elements Editing static page elements Viewing resource files defined by static page elements Adding and editing subnet filters Exporting configurations Exporting encrypted configurations Restoring a previous configuration Importing saved configurations Importing hit analysis configurations from Foglight Experience Viewer Using the Import Configuration Wizard

Define output variables

Script output variables can be referenced in conditions, custom field updates, and metric updates. Decide how many output variables your script requires and the type of value you want to assign to each output variable. The value of an output variable can be a String, Integer, Long, Double, or Boolean value. You do not need to set the data type explicitly, but you should decide now on what values you want to expose after the script runs.
Groovy often defaults to BigDecimal and BigInteger when it encounters numeric literals. In Foglight APM, BigDecimal values are automatically converted to Double, and BigInteger is converted to Integer.

Decide when to execute the script

A script executes once in the selected context, such as once in the current hit or once in a session. Your choice of API affects which execute options are available, as shown in the following table.
 
Table 50. Deciding when to execute a script
Traffic Analysis API
Once Per Hit
Once Per Session
Once Per Sequence
HitAnalysis
—
SessionAnalysis
—
SequenceAnalysis
PostSequenceAnalysis
When a script executes the first time in the selected context (hit/session/sequence), it caches the value of any generated output variables. If other analyzers match the same hit/session/sequence and require the value of the script’s output variables, they use the cached values; the script cannot execute again in the same hit/session/sequence. Of course, if the hit analyzer never matches a hit, the script's output variable is not required and therefore the script is not executed and the value for the output variable remains undefined (null).
For example, let’s say you create a HitAnalysis script with one output variable that is configured to run Once Per Hit. A hit analyzer requires the script’s output variable to update a custom field. When the analyzer’s conditions match a hit, the script executes exactly one time and caches the value of its output variable. When a second analyzer matches the same hit, it can use the cached value, but cannot rerun the script.
 
* 
IMPORTANT: For scripts with multiple output variables, any output variables whose values are not set when the script executes the first (and only) time remain set to null.
If your script contains multiple output variables that are referenced either by the same analyzer or multiple analyzers, you cannot control the order in which the script’s output variables are referenced. Any of the references can cause the script to run. In this case, you need to write your script to generate values for all output variables every time the script runs.

Decide how many uncaught failures are allowed

An uncaught failure is an uncaught exception that prevents the script from running to completion. Decide whether you want to prevent the script from running after a certain number of uncaught failures. To ignore script failures and continue to use the script, you can leave the default value of zero.

Creating scripts

Now that you know your script requirements, you can begin coding your script. While you can code your script directly in the Edit Script dialog box, if you intend to create a long or complex script, you may be more comfortable drafting the script in your favorite text editor first. You can copy the draft script to the Edit Script dialog box for syntax verification and sample data testing.
You can create scripts from the Traffic Analysis > Advanced Options dashboard or from any dashboard that offers a Scripts view. From the Advanced Options dashboard, when you click Add in the Scripts view, the Script - Add dashboard appears. From all other locations, when you click Add, you can choose to use an existing script or create a new one. If you create a new one, the Script - Add dialog box appears.You specify the analysis API, execute policy, uncaught failure policy, and output variables that you decided upon when determining your script requirements. For more information, see Determining requirements and Adding, copying, and editing scripts.
Let’s look at an example script. The following image shows the options required for a script that transforms data. The HitAnalysis API is used for access to hit details and the script executes once per hit. Two output variables are declared: productTotal and bigOrder. For more information, see Defining scripts.
Figure 72. Script—Add dialog box
In this dashboard, the Script Body box is display only. To add the body of the script, click Edit Script. From the Edit Script dialog box you can type your script and validate the syntax.
 
* 
NOTE: Foglight APM scripts are based on the Groovy scripting language. For a list of scripting resources, see Before you begin.
Before reviewing the script for TransformData, you should be aware that all scripts have access to a default binding containing the following two variables:
•
api—an instance of the API that you selected in the Type box, such as HitAnalysis. The api variable provides access to traffic analysis data as well as to other key functionality such as regular expressions.
•
results—a collection used to store the values for the output variables (defined in the Output Variables pane). Data generated by the script is put into the results collection through an assignment statement, such as results.outputVariable = someValue.
The following image shows the TransformData script. Behind the scenes, api is automatically bound to the HitAnalysis API because Hit Analysis was selected in the Type box.
Figure 73. Edit Script dialog box
The script starts by getting the cookie associated with the hit. If the cookie has no value, the script exits silently through the use of a return statement. Next, the script defines a pattern to match in the cookie and then uses the API’s buildMatcher() method to do the work of matching the pattern in the current cookie. If no match is found, the script exits silently. Otherwise, it sets the value of productTotal to the value found in the cookie. If that value exceeds $1,000, the bigOrder variable is set to true. Both values are stored in the default results collection.
This was a fairly straightforward example. Your scripts can be as simple or as complex as required to meet your needs. When coding your own script, you can:
•
Reference any of the traffic analysis details (such as hit details and session details) exposed by the API you selected. For a complete list, click the links in the Data Requirements table.
 
* 
NOTE: Hit details are not available following a session or sequence timeout. If your script can be executed immediately following a timeout, the script needs to be programmed so that either it does not require hit details or it can handle the case where hit details are null.
•
Call any of the methods in your chosen API. For a complete list of classes and methods in the APIs, see the corresponding list of interfaces in the API Javadoc.
•
Generate and cache values for the script’s output variables using the results collection. The values can be used by analyzers in match conditions, custom fields, and metrics.
•
Use return statements to exit silently whenever a script cannot access data or meet some other precondition it needs to proceed. When a script quits, any unset output variables continue to be undefined (null) values. Exiting a script through a return statement does not count as an uncaught failure.
•
Reference traffic analysis configuration objects, such as hit analyzers and custom fields. Because configuration object names are not necessarily unique, you need to use the object’s UUID. You can look up the UUID by clicking Lookup Object UUID. For more information, see Referencing configuration objects in a script.
•
Add regular expressions to your script to do things like match a pattern. You can create and test regular expressions in the Extraction Rule tool by clicking Regular Expression Tester. For more information, see Testing regular expressions.
•
Check your syntax while you work by clicking Check Syntax. The Syntax Messages box displays errors or warnings regarding basic syntactical errors. Security violations or references to undefined classes or methods are not detected or reported.
Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating