Configure Attributes for Real User Monitoring
You can configure Application Performance Monitoring to enable better classification of different end user activities by adding additional attributes.
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.
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.
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
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 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
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.
- 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.
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;
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+"]";
}