Deploy the APM Browser Agent With Your Application

You can deploy the APM browser agent by inserting a JavaScript in all your application pages and allow Application Performance Monitoring to report on real user experience.

Note

The details of where and how to insert the JavaScript are specific to the monitored application.

When the APM Java agent is used, it can also be configured to inject the browser agent script automatically. This includes the packaged application specific script if applicable.

To insert the JavaScript:

  1. Edit the HTML source of monitored application pages.
    Note

    • For packaged web applications, there is typically a page template used for all pages belonging to the web application.

      Make sure to include the packaged application specific script as well, if applicable. For details, see Deploy the APM Browser Agent With Packaged Applications.

    • The configuration can be stored in either the window.apmrum or document.apmrum object.

      Make sure to use the same object consistently to avoid confusing configurations. Lazy loading is used for the object properties and updates are applied dynamically.

  2. Specify values for the following properties and insert the script after the closing </head> tag. Ensure that you do not add the code within another <script> tag:
    • window.apmrum.serviceName: Specify a name for the service. If you do not specify the service name, the default service name, APM Browser, is assigned. It's recommended that you specify a service name to be able to filter by service and monitor the corresponding spans.
    • window.apmrum.webApplication: Specify a name for the web application, which can be used to classify functional areas of deployment. If no value for webApplication is specified, the default value "Default WebApp" will be used.
    • window.apmrum.ociDataUploadEndpoint: Specify the Data Upload Endpoint which determines the data center and domain to which RUM data will be uploaded. The Data Upload Endpoint value can be obtained doing the following:
      • Go to the OCI Console, navigate to Observability & Management > Application Performance Management > Administration and select the desired domain.
      • Click Copy next to Data Upload Endpoint to copy the value into your clipboard and use it to set the value of window.apmrum.ociDataUploadEndpoint.
    • window.apmrum.OracleAPMPublicDataKey: Specify the public dataKey that is generated when the APM domain is created. The public dataKey can be obtained doing the following:
      • Go to the OCI Console, navigate to Observability & Management > Application Performance Management > Administration and select the desired Compartment and Domain.
      • Click on Data Keys under Resources. If no data key exists then click on Generate Data Key and select Public Data Key.
      • Click on Copy which it's next to a data key of type 'Public' to retrieve the value to be used to populate the value of window.apmrum.OracleAPMPublicDataKey.

    To optimize performance for users of the monitored application, the location of a JavaScript library has to be specified, and you must ensure that the JavaScript library is accessible in your network.

    JavaScript Example

    The script looks like the following:

    <script>
    window.apmrum = (window.apmrum || {}); 
    window.apmrum.serviceName='<APM Browser>';
    window.apmrum.webApplication='<Web App Name>';
    window.apmrum.ociDataUploadEndpoint='<ociDataUploadEndpoint>';
    window.apmrum.OracleAPMPublicDataKey='<APM_Public_Datakey>';
    </script>
    <script async crossorigin="anonymous" src="<ociDataUploadEndpoint>/static/jslib/apmrum.min.js"></script>
    Where:
    • <APM Browser> is the service name value that you specify for your APM Browser agent. If you don't set a value, the default service name APM Browser is assigned.
    • <Web App Name> is the web application name value.
    • <ociDataUploadEndpoint> is the Data Upload Endpoint value. It can be obtained from the APM Administration page. See Obtain Data Upload Endpoint and Data Keys.
    • <APM Public Datakey> is the APM Public Datakey value that can be obtained from the Administration menu in the APM main page.

    For example, if the Data Upload Endpoint value is aaaac5d2kke6waaaaaaaaaaala.apm-agt.us-ashburn-1.oci.oraclecloud.com and the APM Public Datakey value is IMWJ5UN2C6YOLQSUZ5Q7IGN3QACF4AZD, the script will look like the following:

    <script>
    window.apmrum = (window.apmrum || {});
    window.apmrum.serviceName='Apm Browser1';
    window.apmrum.webApplication='Webapp';
    window.apmrum.ociDataUploadEndpoint='https://aaaac5d2kke6waaaaaaaaaaala.apm-agt.us-ashburn-1.oci.oraclecloud.com';
    window.apmrum.OracleAPMPublicDataKey='IMWJ5UN2C6YOLQSUZ5Q7IGN3QACF4AZD';
    </script>
    <script async crossorigin="anonymous" src="https://aaaac5d2kke6waaaaaaaaaaala.apm-agt.us-ashburn-1.oci.oraclecloud.com/static/jslib/apmrum.min.js"></script>

    Using the reference to <ociDataUploadEndpoint>/static/jslib/apmrum.min.js in your instrumentation ensures that APM monitoring always takes advantage of the latest version available of the APM Browser Agent.

    For more information on public DataKey and DataUploadEndpoint, see Obtain Data Upload Endpoint and Data Keys.

    If you have a packaged application, follow the additional step: Deploy the APM Browser Agent With Packaged Applications.

Deploy the APM Browser Agent With Packaged Applications

When monitoring packaged applications, it is possible to use a specific script that helps capturing the characteristics of that packaged application. This can be used to reduce the need of manual configuration to capture package application specifics.

You can use a specific set of javascript code when using one of the following supported packaged application:
  • Oracle E-Business Suite.
  • PeopleSoft.
  • Siebel.
  • Oracle Business Intelligence Enterprise Edition (OBIEE).
  • Visual Builder Studio.

The script tracks the characteristics of the specific packaged application, recognizes the specific areas in the url/DOM and uses them to enrich the spans with additional attributes.

To deploy the browser agent with a packaged application, do the following:
  1. Confirm that you completed the step to add the apmrum.min.js library to the script as described in Deploy the APM Browser Agent With Your Application.

  2. Add the specific packaged application library to the script.
    <script crossorigin="anonymous" src="<ociDataUploadEndpoint>/static/jslib/<libraryName>"></script>

    Where:

    • <ociDataUploadEndpoint> is the Data Upload Endpoint value. For details, see Obtain Data Upload Endpoint and Data Keys.
    • <libraryName> is the library name for the specific packaged application. For details, see below table:
      Packaged Application <libraryName> Example Atributes System Rules Name
      Oracle E-Business Suite apmrum.ebs.base.min.js EbsFunctionId,EbsOAFunc,EbsClassName,EbsRegionCode,EbsAkRegionCode EBS Suite
      PeopleSoft apmrum.psft.fluidui.min.js portalName, portalPortalNodePart,portalObjName -
      Siebel apmrum.sbl.openui.min.js ActiveView,ActiveApplet,ActiveBusObj,ActiveBusComp,WebApplicationName -
      OBIEE apmrum.obiee.base.min.js UserName(hash) -
      Visual Builder Studio apmrum.vbs.base.min.js ActionOutcome,EventName,EventType,ContainerParentId,ContainerParentType,AppUiId,Username(hash) -
      For example, if you are using Oracle E-Business Suite applications (the library name is apmrum.ebs.base.min.js) and the APM Data Upload Endpoint value is aaaac5d2kke6waaaaaaaaaaala.apm-agt.us-ashburn-1.oci.oraclecloud.com, the script looks like the following:
      <script crossorigin="anonymous" src="aaaac5d2kke6waaaaaaaaaaala.apm-agt.us-ashburn-1.oci.oraclecloud.com/static/jslib/apmrum.ebs.base.min.js"></script>