The Experience Manager Monitor is the core of the HVM framework. It is responsible for receiving and analyzing the raw performance data from thousands of browsers and generating meaningful metrics information and delivering those metrics to Operations Center.
All HVM components on the monitor are implemented with user-defined “HVM scripts” that define how data is collected and how collected data is reported to Operations Center. The scripting layer defines the “metrics” object that exposes the services and events needed by HVM scripts to perform these tasks.
The remainder of this section gives an overview of these components to help you understand how they fit together. Examples in the Script Reference section of this document, as well as the DemoMetrics configuration included in the Experience Manager Monitor installation, provide deeper insight.
Data Collection
When the monitor is ready to start processing HVM data, it fires the “metrics.onload” event. During its handling of this event, an HVM script should define a preprocessor object (see “metrics.createPreprocessor”) and one or more data-collector objects (see “metrics.creatSummaryCollector”), then deploy these objects using the “metrics.deploy” function. The configuration of these deployed objects determines how data is collected from the stream of events received from the instrumentation script running in end user browsers.
The preprocessor is composed of FieldFilter, FieldXForms (transformation rules), and rules for handling the received upload time. Using these value, the preprocessor scrubs each event record, normalizing data and filtering out any unwanted records. The monitor then uses the uploadTimeLimit value in the preprocessor to calculate the total response time for the event record.
Each event record that is not filtered out by the preprocessor is then evaluated be each deployed data collector. Data collectors collect information about the records received. In its smallest form, a data collector must define a name, an intervalDuration, and a function to which it delivers reports at the end of each interval. For example:
var collector = metrics.createSummaryCollector();
collector.name='example1';
collector.intervalDuration=60000;
collector.onreport=myReportHandler1;
As written, this example summary data collector calls myReportHandler1 once a minute (60000ms) and pass it a summary report, including the count and response time information (average, maximum and minimum values) for each event record received during that minute.
However, data collectors include several optional properties that allow for much richer data. For example, adding the following line to the example collector causes the collector to generate a separate report for each unique page title encountered during the reporting period:
collector.groupingFieldNames=[metrics.constants.FN_PAGE_TITLE];
Now, instead of generating a single report summarizing all the hits on an instrumented Web site, the data collector generates a separate report for each unique page title encountered during the interval. However, we might be using the HVM framework to collect information on more than one Web site, and those sites could have overlapping names. In that case, the groupingFieldNames property could be extended to include application name:
collector.groupingFieldNames=[metrics.constants.FN_APPLICATION_NAME,
metrics.constants.FN_PAGE_TITLE];
Now, assuming the instrumentation scripts on the two Web sites are configured with different application name values, the reports for those Web sites are properly segregated. Each unique combination of application name a page title produces a separate report.
In the examples above, groupingFieldNames were used to track metrics based on unique values sent from the instrumentation script. In some cases, the data from the instrumentation script does not provide the desired granularity. An example of this is a use case where data was tracked by browser type. The instrumentation script does not send browser type as one of the standard fields. It is however, possible to derive browser type from the user-agent field that is sent by the instrumentation script. To accomplish this, a set of FieldXForms in the preprocessor is needed to derive the browser type.
In the following snippet, FieldXform objects are created that identify Microsoft Internet Explorer and Mozilla Firefox browser types, the a collector is created to track hits by each of these types:
var iex = metrics.createFieldXform('IEX');
iex.fieldName=metrics.constants.FN_USER_AGENT;
iex.matchExpression='.*MSIE[^;]*.*';
iex.replaceExpression='Microsoft Internet Explorer';
iex.destFieldName='BrowserType';
var ffx = metrics.createFieldXform('FFX');
iex.fieldName=metrics.constants.FN_USER_AGENT;
iex.matchExpression='.*Firefox\S*.*';
iex.replaceExpression='Mozilla Firefox';
iex.destFieldName='BrowserType';
var preprocessor = metrics.createPreprocessor(3000, [iex,ffx],null);
var collector = metrics.createSummaryCollector();
collector.name='BrowseTypeCollector';
collector.intervalDuration=60000;
collector.onreport=myReportHandler2;
collector.groupingFieldNames=['BrowserType'];
metrics.start(preprocessor,[collector];
The HVM framework provides a broad, flexible set of tools to account for a variety of different Web site architectures. In the DemoMetrics example, provided with the Experience Manager Monitor installation, reports are generated by page, but in this case, Page Title is not assumed to be a valid way of distinguishing the page that was hit. In that case, the URL is passed through a FieldXform to determine the page that was hit, then a collector groups its reports based on those derived values.
Report Processing
At the end of each defined interval, a data collector calls their report handler functions and reports any activity it collected during that interval. If the data collector has grouping field names defined, then it delivers one report for each unique set of field values encountered during the interval.
The report handler extracts information from received reports and determines how the gathered information should be represented in the element tree. Handlers can be very straightforward and simply map the reports directly into elements. For example:
function myReportHandler1(reports)
{
for(var i=0; i < reports.length; i++)
{
var elem = metrics.createMetricsElement(reports[i], true);
metrics.sendMetricsElement(elem);
}
}
With very little script, this example captures virtually all of the data captured in the reports to Operations Center element. The element names reflect the name of the collector, as well as any grouping field values used to generate the report. The element properties reflect the current values collected, as well as details of the collector configuration, and the element is updated with series data containing the hit count and average, maximum, and minimum response times.
On the other hand, report handlers can be much more sophisticated. They can create and update any number of elements. It can add or update its own custom properties on those element, and it can store whatever series data is required with the element. There is no restriction as to how many elements can be created by a report handler, or how many report handlers can write to a given element. The only restriction is that for a given element, you might not write to the same series data name and time point more than once. So, for instance, in the report handler for the BrowserTypeCollector referenced above, we could just capture the percentage of hits on each browser and save that information as property and/or series data on an element that is also updated by another collector.
The report handler in DemoMetrics.js is much more sophisticated. It uses a number of page-specific configuration parameters to implement custom business rules. In that case, the condition of an element is driven by the percentage of hit within a predefined range to determine whether the page is performing at an appropriate level.
Configuration
An HVM implementation requires its own properties file and at least one script (.js) file. The name of the properties file is set in the “Metrics.properties” property in the monitor.properties file. For example, the default installation is configured as follows:
Metrics.properties=DemoMetrics.properties
The referenced properties file must identify the main script file of the HVM implementation and any configuration properties required by that script. It is recommended that HVM scripts not use the HVMetrics. prefix for its configuration properties. In a distributed data collection environment, it must also specify the HVM group properties (see Section 12.1.4, Grouping Monitors for distributed HVM data collection).
Errors in either the properties file or the HVM script file causes the monitor to halt.
