Configure Attributes for Real User Monitoring

Attributes defined in the APM browser agent are added to the spans that the browser agent uploads to the APM service.

The custom text attributes from APM browser agent are represented as dimensions in Trace Explorer, and they can also be used to define metric groups. The custom numeric attributes from APM browser agent are represented as metrics in Trace Explorer. The numeric attributes can be aggregated and used in alerts in Monitoring service. For details about dimensions in Trace Explorer, see About Trace and Span Attributes.

Review the following sections about attributes configuration:

Configure Custom Attributes

The custom attributes can be added most easily though udfAttributes property of the apmrum object.

Every time the browser agent code creates a span, this data is looked up and used to populate the span with the desired attributes. The definition can be a string, number or function (that returns a string or number).

When a function is used, that function will be executed each time the span is created, and the value for the attribute is needed. Attention to detail is required when using functions to avoid negative impact on performance.

Note

A new attribute will be activated automatically only after the fifth occurrence, and only if auto-activate is enabled. Otherwise, it can be activated manually using the Span Attributes page.

Simple Configuration Example

The following code is a basic example that can be used to add some custom fields:

window.apmrum.udfAttributes = [
    { name: 'mySiteId', value: "TheWebSiteId" },
    { name: 'resultsOnPage', value: 123 },

     // calling a user-supplied javascript function to calculate shopping cart totals
    { name: 'shoppingCart', value: () => { productsInBasket(); } }
];

The above sample configuration shows how a string value can be assigned.

The attribute/dimension ‘mySiteId’ will be created in the UI with the value ‘TheWebSiteId’. This can be useful if the html template allows to assign different values for it, or different deployments are using this.
The attribute ‘resultsOnPage’ will create the metric with this name in the UI. The benefit of a numeric value is that it can be summed and average can be calculated for it, as well as other numeric functions.

It is important to note that something like a productNumber should not be provided as a number, but it should be used as a string, to allow selection of specific products as well as grouping by the product. For example, when the productid or productNumber is available in javascript as a numeric field, it needs to be converted into a string to ensure Application Performance Monitoring handles it correctly.

Complex Configuration Example

The following example shows more complex construction with intermittent property on apmrum object to exchange data:

window.apmrum.udfAttributes = [
    { name: 'myDynamicSiteId', value: () => window.apmrum.tmpSiteId },
    { name: 'curProductNumber', value: '123456' },
];

// on other locations in the code:
window.apmrum.tmpSiteId = 'siteA';

 // on some other locations in the code
window.apmrum.tmpSiteId = 'siteB';

The clearest implementation is to have the attributes generated on one spot. If a particular value is known or set as some state during specific calls, these can be assigned to a property in apmrum object that starts with ‘tmp’ in the name. This value can be picked up in the udfAttributes to report the value. When the value is ‘undefined’, the property will not be sent.

Limitations

The data provided is limited to ensure that reporting on it makes sense. The main goal is to ensure that arbitrary data doesn’t get pushed accidentally.

Name	Limit	Description
attrNameLenMax	50	Maximum number of characters for a name (enforced by adding dots to name if provided name is too long)
attrValueLenMax	500	Maximum number of characters in value (enforce by adding dots to value if provided value is too long)
attrMax	50	Maximum number of flex fields allowed

Configure User Name Attribute

You have to set the apmrum.username attribute to enable the filtering of Real User Monitoring data by user name.

Before you proceed, you must do the following:

Identify the original source of the user name. This depends on the monitored application and the authentication mechanism used.
Embed scripting in the application pages (or the application landing page). Assign the user name value to the apmrum.username variable. This makes the user name available for reporting.

The original source of the user name depends on the monitored application and the authentication mechanism used. Here are a few examples of how user names can be collected in different environments:

get username from Windows in Internet Explorer:

var WinNetwork = new ActiveXObject("WScript.Network");
window.apmrum || (apmrum = {} );
apmrum.username =  WinNetwork.UserName

get username logic from PHP code:

window.apmrum || (apmrum = {} );
apmrum.username = '<?php echo $username; ?>';

get username from the page:
You can use this if the page is using DOM, and the page contains something like: <div id="welcomeMsg">Welcome <user> (last visit <mm–dd-yyyy>)</div>.
```
var Loginname = document.getElementById("welcomeMsg").innerHTML ;   
var end = Loginname.indexOf("("); 
var nameOnly = Loginname.substring(8, end);
window.apmrum || (apmrum = {} );
apmrum.username = nameOnly;
```

Note

If you are using Oracle applications, see Configure Application Performance Monitoring for Packaged Applications for details on how to capture the username attribute when configuring automatic injection in APM Agent depending on the specific Oracle application.

Configure Custom Attributes in Legacy Environments

If you migrated from Oracle Management Cloud Application Performance Monitoring product to Oracle Cloud Infrastructure (OCI) Application Performance Monitoring service, you can use the same properties in OCI configuration as shown in this section.

The values for these attributes provide a closer perspective of application performance on the user’s site. These attributes are displayed as dimensions in the Application Performance Monitoring user interface, which can be used for filtering data. To add the attributes, include the following JavaScript code in the pages you want to monitor:

apmrum.udfAttribute1 = function()
{
    // return desired value of attribute 1
    return "Attribute value 1"; 
};
apmrum.udfAttribute2 = function()
{
    // return desired value of attribute 2
    return "Attribute value 2"; 
};

By default, attribute1 will be populated with the top level directory of the URL and attribute2..9 will remain empty and can be configured by you. In Application Performance Monitoring you can configure up to nine attributes.

For example, in the URL https://www.sample.com/calendar/render, attribute1 will be populated with the string calendar.

The document title of the application page and the text visible to the user can be helpful in reporting, but they may contain person identifiable information (PII) that is not allowed to be captured by default. If you want to capture those values, you can use the trackScreenText setting which requires to be set explicitly to true value using the following: window.apmrum.trackScreenText=true.

The page title can be redefined by setting the apmrum.udfAttributeDt attribute. In context reporting, the data in attribute1 is most generic, udfAttributeDt is more specific (page level) and apmrum.udfAttribute2 is assumed to point to/describe roughly the area on a screen that is active during an AJAX call or the area that is clicked.

The element naming logic can be redefined by configuring the getElmLabelFn attribute. This function receives the ‘Element’ (event target) that was clicked/activated by the user as an argument. By using the getElmLabelFn attribute, you have more control over the reported information and it reduces the risk of accidentally exposing PII.

Here's an example:

apmrum.trackScreenText=true;
apmrum.udfAttributeDt = function()
{     
    // return desired value of page title
    return "New Page Title";
};
apmrum.getElmLabelFn = function(e)
{
    // return desired value for element
    return "elm: "+e.tagName+"["+e.id+"]"; 
}

Oracle Cloud Infrastructure Documentation