Configure Ajax Calls Instrumentation
You can configure ajax calls instrumentation in Application Performance Monitoring.
To allow for cross tier tracing to take place, the APM browser agent adds a trace context using headers similar to 'X-B3-*' to outgoing ajax calls. These headers inform a potential server agent/tracer of the trace and span that triggered the ajax call which then allows to report on the complete flow from browser into the backend servers based on the propagated context.
By default, the above behavior is applied for all ajax calls that share the same domain and exclude ajax calls to external domains. The assumption is that the external domains do not share the same APM monitoring environment. In cases where this logic does not apply, it is possible to enable headers on calls to external domain and/or disable header to some of the call to the same domain.
apmrum.traceSupportingEndpoints = [
{ headers: [ ], hostPattern: 'https://((identity)|(console)).*' },
{ headers: [ 'APM' ], hostPattern: 'https://my-rest-server.*' }
]The above configuration indicates that for urls that start with
'identity' or 'console', the headers should not be
manipulated (empty context), but for the ones that start with
'my-rest-server', the APM browser agent is present therefore
ideally, the headers should be annotated with apm context.
The apmrum.traceSupportingEndpoints configuration is sensitive to
the order of the definition. The headers definition of the first
hostPattern that matches the ajax url is used. If the first
definition has hostPattern: ".*", then all other definitions are
ignored. The recommended configuration is to use consistently either a prefix or
suffix of the ajax url, to create the desired configuration.
CORS failures caused by the APM Browser Agent
The browser agent in some cases causes the requests to fail in a browser. For
example, this happens when GET calls are annotated with
B3 headers, which triggers a pre-flight.
The server needs to respond with a correct ``Access-Control-Allow-Origin`` header to
OPTIONS and actual GET call. In addition, the
server needs to mark the relevant context-related headers as allowed to avoid issues
with them.
For information about CORS (Cross Origin Resource Sharing) protocol, see https://fetch.spec.whatwg.org/#cors-protocol.
Integration of Browser Agent with Backend Trace Agents
Application Performance Monitoring can integrate the browser agent with backend trace agents.
The browser agent records and pushes the trace context to ajax calls for an integrated view of browser activity and backend activity. This can be done using different types of headers for different types of backend server agents. Such custom headers will be added to ajax calls which results in the need for preflight requests for CORS (Cross Origin Resource Sharing) validation is required. For information about CORS protocol, see https://fetch.spec.whatwg.org/#cors-protocol.
When the server is not configured to handle such preflight calls, then the browser will not handle ajax calls as expected and the application may not work as expected. To avoid related issues, the APM browser agent checks ajax calls and adds custom headers only to requests that have a preflight request or requests that go to the same domain.
Domain names are compared based on the second level and top level domain. For
example, api.oracle.com will be considered the same domain as
apex.oracle.com.
Configure Rest Endpoints with Server Agents
When a server agent is installed on a system that is accessed with a different url than the html, some additional configuration is needed. This configuration will inform the browser agent that adding the relevant trace header is desired for that server, and preflight requests will be handled adequately.
Sample Configuration with APM Java Agent
See below a sample configuration that disables the default logic on
recognizing same domain, but it allows to specify the url pattern where the APM Java
Agent is installed using
https://regexThatMatchesServersThatHaveServerAgent.*. The APM
Java Agent context headers will only be used on ajax calls made to urls that match
this pattern. All other urls match the '.*' pattern and will not be annotated since
the context there is empty.
document.apmrum.traceSupportingEndpoints = [
{ headers: [ 'APM'], hostPattern: 'https://regexThatMatchesServersThatHaveServerAgent.*'},
{ headers: [ ], hostPattern: '.*'} // block headers for everything else
];Sample Configuration with Different Agents
/* sample configuration for an app running on
* sample.oracle.com, by default 'APM' headers
* are added for ajax-calls to data.oracle.com
* (same domain) so no configuration needed in
* that scenario.
*/
document.apmrum.traceSupportingEndpoints = [
/* apm server agent running on api.oracledata.com servers */
{ hostPattern: 'https://api.oracledata.com', headers: [ 'APM']},
/* oracle functions uses B3 header for integration */
{ hostPattern: 'https://functions.oraclecloud.com', headers: [ 'B3-Multi']},
/* more complex configuration withregexp host and multiple header types combined */
{ hostPattern: 'https://*.extern.*.com', headers: ['W3C', 'B3-Multi']},
/* server has no agent therefore don't send headers */
{ hostPattern: 'https://info.oracle.com', headers: []},
]Context Propagation Headers
The following table shows the different types of context propagation headers that the APM browser agent supports:
| Name | Context Propagation Headers | Description |
|---|---|---|
| APM |
X-B3-TraceId X-B3-SpanId X-B3-Sampled X-ORACLE-APM-BA-VERSION |
APM Java Agent installed to have server side trace information combined. |
| B3-Single | b3 | Single b3 header with trace information combined in value. |
| B3-Multi |
X-B3-TraceId X-B3-SpanId X-B3-Sampled |
B3 headers with value spread over separate headers. |
| W3C | traceparent | Combined trace-span info in single header as specified by W3C. |
| UberId | Uber-Trace-Id | The uberId header with combined trace context in single value. |