Instrumentierung für Ajax-Aufrufe konfigurieren

Sie können die ajax-Aufrufinstrumentierung in Application Performance Monitoring konfigurieren.

Damit Cross-Tier Tracing durchgeführt werden kann, fügt der APM-Browser-Agent mit Headern ähnlich "X-B3-*" einen Trace-Kontext zu ausgehenden Ajax-Aufrufen hinzu. Diese Header informieren einen potenziellen Server-Agent/Tracer über das Trace und den Span, der den Ajax-Aufruf ausgelöst hat. Dieser ermöglicht dann einen Bericht über den vollständigen Fluss vom Browser in die Backend-Server basierend auf dem propagierten Kontext.

Standardmäßig wird das oben genannte Verhalten für alle Ajax-Aufrufe angewendet, die dieselbe Domain gemeinsam verwenden und Ajax-Aufrufe an externe Domains ausschließen. Die Annahme besteht darin, dass die externen Domains nicht dieselbe APM-Überwachungsumgebung verwenden. In Fällen, in denen diese Logik nicht zutrifft, können Header bei Aufrufen von externen Domains aktiviert und/oder Header für einige Aufrufe derselben Domain deaktiviert werden.

Beispielkonfiguration:

apmrum.traceSupportingEndpoints =  [ 
    { headers: [ ], hostPattern: 'https://((identity)|(console)).*' },
    { headers: [ 'APM' ], hostPattern: 'https://my-rest-server.*' }
]

Die obige Konfiguration gibt an, dass für URLs, die mit "identity" oder "console" beginnen, die Header nicht manipuliert werden dürfen (leerer Kontext), aber für diejenigen, die mit "my-rest-server" beginnen, der APM-Browser-Agent daher idealerweise vorhanden ist, die Header mit apm-Kontext versehen werden sollten.

Hinweis

Die apmrum.traceSupportingEndpoints-Konfiguration ist von der Reihenfolge der Definition abhängig. Die Headerdefinition der ersten hostPattern, die mit der Ajax-URL übereinstimmt, wird verwendet. Wenn die erste Definition hostPattern: ".*" enthält, werden alle anderen Definitionen ignoriert. Die empfohlene Konfiguration besteht darin, konsistent entweder ein Präfix oder ein Suffix der ajax-URL zu verwenden, um die gewünschte Konfiguration zu erstellen.

CORS-Fehler, die vom APM-Browser-Agent verursacht wurden

Der Browser-Agent führt in einigen Fällen zu einem Fehler in einem Browser. Beispiel: Dies geschieht, wenn GET-Aufrufe mit B3-Headern versehen werden, die eine Preflight auslösen.

Der Server muss mit dem korrekten "Access-Control-Allow-Origin"-Header auf OPTIONS und dem tatsächlichen GET-Aufruf antworten. Außerdem muss der Server die relevanten kontextbezogenen Header als zulässig markieren, um Probleme mit ihnen zu vermeiden.

Informationen zum CORS-(Cross Origin Resource Sharing-)Protokoll finden Sie in https://fetch.spec.whatwg.org/#cors-protocol.

Integration von Browser-Agent mit Backend-Trace-Agents

Application Performance Monitoring kann den Browser-Agent mit Backend-Trace-Agents integrieren.

Der Browser-Agent zeichnet den Trace-Kontext auf und sendet ihn an Ajax-Aufrufe, um eine integrierte Ansicht der Browseraktivität und Backend-Aktivität zu erhalten. Dazu können verschiedene Headertypen für verschiedene Backend-Server-Agents verwendet werden. Solche benutzerdefinierten Header werden Ajax-Aufrufen hinzugefügt, sodass Preflight-Anforderungen für die Validierung von CORS (Cross Origin Resource Sharing) erforderlich sind. Informationen zum CORS-Protokoll finden Sie unter https://fetch.spec.whatwg.org/#cors-protocol.

Wenn der Server nicht für die Verarbeitung solcher Preflight-Aufrufe konfiguriert ist, verarbeitet der Browser keine Ajax-Aufrufe wie erwartet, und die Anwendung funktioniert möglicherweise nicht wie erwartet. Um verwandte Probleme zu vermeiden, prüft der APM-Browser-Agent Ajax-Aufrufe und fügt benutzerdefinierte Header nur Anforderungen hinzu, die eine Preflight-Anforderung oder Anforderungen an dieselbe Domain haben.

Domainnamen werden basierend auf der Domain der zweiten und der obersten Ebene verglichen. Beispiel: api.oracle.com gilt als dieselbe Domain wie apex.oracle.com.

Einzelheiten zur Integration von Browser-Agent mit Backend-Trace-Agents finden Sie in den folgenden Abschnitten:

Rest-Endpunkte mit Server-Agents konfigurieren

Wenn ein Server-Agent auf einem System installiert ist, auf das eine andere URL als die HTML zugegriffen wird, ist eine zusätzliche Konfiguration erforderlich. Diese Konfiguration informiert den Browser-Agent, dass das Hinzufügen des relevanten Traceheaders für diesen Server gewünscht wird, und Preflight-Anforderungen werden entsprechend verarbeitet.

Beispielkonfiguration mit APM Java Agent

Im Folgenden finden Sie eine Beispielkonfiguration, mit der die Standardlogik beim Erkennen derselben Domain deaktiviert wird. Sie kann jedoch das URL-Muster angeben, in dem der APM-Java-Agent mit https://regexThatMatchesServersThatHaveServerAgent.* installiert wird. Die APM-Java Agent-Kontextheader werden nur bei Ajax-Aufrufen verwendet, die an URLs vorgenommen werden, die diesem Muster entsprechen. Alle anderen URLs entsprechen dem Muster ".*" und werden nicht mit Anmerkungen versehen, da der Kontext leer ist.

document.apmrum.traceSupportingEndpoints =  [
    { headers: [ 'APM'], hostPattern: 'https://regexThatMatchesServersThatHaveServerAgent.*'},
    { headers: [ ], hostPattern: '.*'} // block headers for everything else
];

Beispielkonfiguration mit verschiedenen 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: []}, 
]

Header für Kontextpropagierung

In der folgenden Tabelle sind die verschiedenen Typen von Kontextpropagierungsheadern aufgeführt, die der APM-Browser-Agent unterstützt:

Name	Header für Kontextpropagierung	Beschreibung
API	X-B3-TraceId X-B3-SpanId X-B3-Sampled X-ORACLE-APM-BA-VERSION	APM Java Agent ist installiert, damit serverseitige Trace-Informationen kombiniert werden.
B3-Single	b3	Einzelner b3-Header mit kombinierten Traceinformationen im Wert.
B3-Multi	X-B3-TraceId X-B3-SpanId X-B3-Sampled	B3 Header mit Wert, die über separate Header verteilt sind.
W3C	Traceparent	Kombinierte Trace-Span-Informationen in einem einzelnen Header, wie von W3C angegeben.
UberId	Uber-Trace-ID	Der uberId-Header mit kombiniertem Tracekontext in einem einzelnen Wert.

Oracle Cloud Infrastructure-Dokumentation

Instrumentierung für Ajax-Aufrufe konfigurieren