JavaScript-Agent-API

In der folgenden Tabelle sind die Parameter aufgeführt:

Überwachungsschlüssel können über den Befehl key eingestellt werden. Der Überwachungsschlüssel ist sichtbar, wenn Sie Websites in der Instana-Benutzeroberfläche konfigurieren.

ineum('key', trackingKey);
 

Beacons werden über HTTP GET und POST an das Reporting URL übertragen, um die Überwachungsdaten an Instana zu liefern.

ineum('reportingUrl', reportingUrl);
 

In einigen Fällen kann es wünschenswert sein, dass ein JavaScript Agent an mehrere Backends berichtet. In diesem Fall verwenden Sie den Befehl reportingBackends , damit der Agent JavaScript an mehrere Backends berichtet.

ineum('reportingBackends', reportingBackends);
 

Instana kann Website-Messdaten nach logischen Seiten segmentieren. Dazu benötigt es einen Hinweis auf die Seite, die der Nutzer gerade anschaut. Dieser Seitenname kann mit dem Befehl page festgelegt werden. Stellen Sie die page so früh wie möglich ein. Sie können die page ändern, um Änderungen am Dokument darzustellen (z. B. bei einseitigen Anwendungen). Dies ermöglicht es Instana, zusätzlich zum Laden der Seite auch die Seitenübergänge zu verfolgen.

ineum('page', pageName);
 

Seitenübergangsereignisse werden immer dann aufgezeichnet, wenn der Seitenname über die API geändert wird - mit Ausnahme des ersten Aufrufs dieser API während der Ladephase der Seite.

Um Seiten zu definieren, verwenden Sie logische Namen wie product detail page oder payment selection anstelle von window.title oder window.href. Die Verwendung von product detail page oder payment selection führt zu weniger Seiten, die einen direkten Bezug zum bestehenden Code haben. Die Verwendung von window.title oder window.href hingegen führt zu zahlreichen nachverfolgten Seiten, die in den meisten Fällen von Nutzen sind, da window.title Produktnamen enthält.

Instana bietet Beispielprojekte, die zeigen, wie man sinnvolle Seitennamen für verschiedene Frameworks und Bibliotheken sammelt. Stellen Sie eine Pull- oder Support-Anfrage für ein fehlendes Framework oder eine Bibliothek.

Benutzerspezifische Informationen können optional mit den an Instana übermittelten Daten gesendet werden. Diese Informationen können dann verwendet werden, um weitere Funktionen freizuschalten, wie z. B.:

• Berechnen Sie die Anzahl der von Fehlern betroffenen Benutzer
• So filtern Sie Daten für bestimmte Benutzer
• Um zu sehen, welcher Benutzer einen Seitenaufbau oder Ajax-Aufruf initiiert hat.

Instana verknüpft standardmäßig keine benutzeridentifizierbaren Informationen mit Beacons. Beachten Sie die jeweiligen Datenschutzgesetze, wenn Sie sich dafür entscheiden, dies zu tun. In Instana ist die Benutzer-ID eine transparente string , die nur zur Berechnung bestimmter Metriken verwendet wird. Daher erfolgt die Identifizierung der Benutzer über eine Benutzer-ID. userName und userEmail können auch verwendet werden, um Zugang zu mehr Filtern und einer effektiven Präsentation von Benutzerinformationen zu haben.

Der synchrone Aufruf dieser API beim Laden der Seite, z. B. durch Rendering der Informationen in das HTML-Dokument auf der Serverseite, trägt dazu bei, dass alle Beacons Nutzerinformationen tragen, die eindeutigen oder betroffenen Nutzerstatistiken korrekt sind und die Beacons bei der Analyse korrekt gefiltert und gruppiert werden.

ineum('user', userId, userName, userEmail);
 

Die Sitzungsverfolgung kann genutzt werden, um Einblicke in die Aktivitäten der Endnutzer beim Laden von Seiten zu gewinnen. Die Sitzungsverfolgung ermöglicht es Instana, die Auswirkungen auf den Endbenutzer zu bestimmen, wenn keine definierten Benutzerinformationen vorliegen.

Um Sitzungen zu verfolgen, verwendet der Agent JavaScript die localStorage browser-API, nachdem er den Aufruf trackSessions getätigt hat. Technisch gesehen ist eine Sitzung eine zufällige ID, die zusammen mit zwei Zeitstempeln im Browser localStorage unter dem Schlüssel in-session gespeichert wird.

Die Verantwortung für die Einhaltung der Datenschutzbestimmungen liegt beim Aufrufenden dieser API.

Metadaten können verwendet werden, um Seitenaufbau und Ajax-Aufrufe zu annotieren. Verwenden Sie Metadaten, um die UI-Konfigurationswerte, Einstellungen, Funktionsflags oder jeden zusätzlichen Kontext zu verfolgen, der für die Analyse nützlich sein könnte.

ineum('meta', key, value);
 

Als Teil des Seitenladens kann eine Backend-Trace-ID definiert werden, um eine Korrelation zwischen Front-End und Back-End zu ermöglichen. Weitere Informationen finden Sie unter Backend-Korrelation. Die Definition der Backend-Trace-ID ist erforderlich, um eine Korrelation zwischen der Backend- und der Front-End-Verarbeitung von Seitenladungen herzustellen. Sie ist für die Korrelation zwischen den Anfragen XMLHttpRequest oder fetch nicht erforderlich. Eine Trace-ID muss eine Hex-Zeichenkette mit 16 oder 32 Zeichen sein.

ineum('traceId', traceId);
 

Mit Hilfe dieser API können Sie mehrere reguläre Ausdrücke definieren. Bei mindestens einer Übereinstimmung kommt es nicht zu einer Datenübertragung an Instana. Die regulären Ausdrücke werden in den folgenden Szenarien ausgewertet:

• Auswertung gegen die URLs der Dokumente (die in der Adressleiste sichtbaren URLs, d.h. window.location.href). Alle Datenübertragungen an Instana werden deaktiviert, wenn einer der regulären Ausdrücke zutrifft.
• Auswertung anhand der URLs von Ressourcen, z. B. der URLs von JavaScript und CSS-Dateien. Es werden keine Informationen über Ressourcen, die einem der regulären Ausdrücke entsprechen, an Instana übermittelt.
• Auswertung gegen die Ziel-URLs der HTTP -Aufrufe, zum Beispiel durch XMLHttpRequest und fetch. Es werden keine Informationen über HTTP Aufrufe, die einem der regulären Ausdrücke entsprechen, an Instana übermittelt.

ineum('ignoreUrls', ignoreUrls);
 

Instana unterstützt auch das Entfernen von Geheimnissen aus Dokument-URLs, d.h. aus der URL, die in der Adressleiste des Browsers sichtbar ist (siehe die API für Geheimnisse ). Beachten Sie jedoch, dass die in den URLs von Dokumenten gespeicherten Geheimnisse fast allen Dritten bekannt sind. Wir haben eine spezielle Beispielanwendung mit einer Beschreibung, die zeigt, warum Geheimnisse, die in Dokument-URLs gespeichert sind, anfällig dafür sind, an Dritte weitergegeben zu werden. Weitere Einzelheiten finden Sie in dieser Beispielanwendung und -beschreibung. Sie können jedoch die Erfassung aller Überwachungsdaten für diese URLs über diese API ignorieren.

Abfrageparameter in gesammelten URLs können sensible Daten enthalten. Daher unterstützt der Agent JavaScript die Angabe von Mustern für Abfrageparameterschlüssel, deren Werte geschwärzt werden. Das Redigieren erfolgt innerhalb des JavaScript -Agenten, d. h. innerhalb des Webbrowsers. Daher gelangen die Geheimnisse nicht zur Verarbeitung auf die Instana-Server und stehen nicht für die Analyse in der Benutzeroberfläche zur Verfügung oder werden über die API abgerufen.

ineum('secrets', secrets);
 

Wenn ein Abfrageparameter mit einem Eintrag aus der Liste übereinstimmt, wird der Wert unkenntlich gemacht und nicht an das Instana-Backend gesendet. Wenn keine ineum('secrets') definiert ist, verwendet Instana standardmäßig [/key/i, /secret/i, /password/i] als passende Regel.

Die Fragmente der gesammelten URLs könnten sensible Informationen enthalten. Daher unterstützt der Agent JavaScript die Angabe von Mustern für Fragmentwerte, die auf der Grundlage des Pfads URL geschwärzt werden können. Diese Schwärzung erfolgt innerhalb des JavaScript Agenten im Webbrowser. Dadurch wird verhindert, dass sensible Informationen die Instana-Server zur Verarbeitung erreichen. Sensible Informationen bleiben für die Analyse in der Benutzeroberfläche oder den Abruf über die API unzugänglich.

ineum('fragment', fragment);
 

Wenn ein Segment Ihres URL Pfads mit einem Eintrag in der Liste übereinstimmt, wird der Fragmentwert geschwärzt und nicht an das Instana-Backend gesendet. Standardmäßig werden in Instana die Fragmente von URL nicht bearbeitet.

Instana sammelt automatisch Markierungen und Maßnahmen, die über die User-Timing-API vorgenommen werden, und verwandelt sie in benutzerdefinierte Ereignisse. Dies bedeutet, dass die User-Timing-API als herstellerneutrale Methode verwendet werden kann, um die reinen Timingdaten an Instana zu melden.

Mithilfe der User-Timing-API können Sie mehrere reguläre Ausdrücke definieren, die, wenn mindestens einer übereinstimmt, nicht zu einer Sammlung bestimmter User-Timings führen. Standardmäßig werden die folgenden Bedingungen ignoriert:

• React's User-Timings: die Zeichen und Takte, die mit dem ⚛️ oder ⛔ Emoji beginnen
• Angulars User-Timings: die Marken und Maße, die mit Zone
• Marken und Maßnahmen, deren Namen entweder mit start oder end

ineum('ignoreUserTimings', ignoreUserTimings);
 

Standardmäßig sammelt der Agent JavaScript die vollständige URL, die alle Parameter enthält. Sie können den Agenten so konfigurieren, dass er nur Parameter für die URLs sammelt, die einer bestimmten Liste regulärer Ausdrücke entsprechen. Die Parameter der ausgeschlossenen URLs werden nicht verfolgt.

Auf der Grundlage der angegebenen Liste regulärer Ausdrücke verfolgt der Agent JavaScript URLs wie folgt:

• Wenn die URL mit einem Eintrag der Liste übereinstimmt, wird die gesamte URL, die alle Parameter enthält, gesammelt.
• Wenn die URL nicht mit einem Eintrag der Liste übereinstimmt, werden Abfrageparameter und Fragmente der URL nicht an das Instana-Backend gesendet.
• Wenn die angegebene Liste leer ist, wird das Standardverhalten angewandt, und die vollständige URL mit ihren Parametern wird verfolgt.

ineum('queryTrackedDomainList',queryTrackedDomainList);
 

Die folgenden Szenarien erläutern die Bedingung, wenn URL ein Geheimnis oder ein Fragment enthält, das mit Hilfe von ineum('secrets', secrets) oder ineum('fragment', fragment) geschwärzt wurde:

• Wenn URL mit einem Eintrag in queryTrackedDomainList übereinstimmt, wird das gesamte URL mit dem geschwärzten Geheimnis oder Fragment an das Instana-Backend gesendet.
• Wenn URL nicht mit einem Eintrag in queryTrackedDomainList übereinstimmt, werden alle Parameter ausgeschlossen, bevor URL an das Instana-Backend gesendet wird.

Wenn ein Browser eine Anfrage an einen entfernten Server sendet und der Instana-Agent den entfernten Server überwacht, dann kann die Antwort des Servers den HTTP Header Server-Timing enthalten, um dem Instana-Agenten, der im Browser läuft, die backendTraceId zur Verfügung zu stellen. Wenn OpenTelemetry im Remote Server aktiviert ist, kann der tracestate HTTP Header den backendTraceId enthalten.

tracestate und traceparent sind W3C-defined Kopfzeilen, die für die Korrelation von verteilten Trace-IDs verwendet werden. Weitere Informationen über W3C Trace-Header finden Sie unter Trace-Kontextebene.

Wenn Sie davon ausgehen, dass der Remote-Server OpenTelemetry verwenden kann und den backendTraceId im tracestate -Header bereitstellt, muss der Instana-Agent im Browser die enableW3CHeaders -API auf true setzen, um den backendTraceId -Wert in den W3C -Headern zu verwenden.

Sie können die backendTraceId an drei verschiedenen Stellen einstellen: über die Kopfzeile Server-Timing , die Kopfzeile tracestate und manuell über die API traceId im Browser. Die Reihenfolge dieser Ansätze ist wie folgt:

• Wenn enableW3CHeaders aktiviert ist, haben Sie zwei Möglichkeiten. Extrahieren Sie zunächst den Wert tracestate aus den Metadaten der aktuellen Seite traceparent und verwenden Sie ihn. Wenn Sie tracestate nicht abrufen können, wird eine 16 Zeichen lange Zeichenkette generiert und verwendet, die mit W3C trace context kompatibel ist.
• Wenn enableW3CHeaders deaktiviert ist, überprüfen Sie zunächst, ob die API traceId aufgerufen wird. Wenn die API traceId aufgerufen wird, dann verwenden Sie die ID als backendTraceId. Wenn die traceId API nicht aufgerufen wird, wird der HTTP Header Server-Timing geparst, um die backendTraceId zu erhalten.
• Wenn keiner der oben genannten Werte verfügbar ist, können Sie Beacons nicht mit Backend-Traces verknüpfen.

ineum('enableW3CHeaders',true);
 

Um zusätzliche Metriken zu sammeln, wartet der Agent JavaScript, bis die folgenden Bedingungen erfüllt sind. Zum Beispiel die erste Eingangsverzögerung und die kumulative Layout-Verschiebung.

• Alle Metriken sind verfügbar
• Die Seite wird entladen (z.B. Registerkarte wird geschlossen)
• Bis eine maximale Wartezeit verstrichen ist

Sie können diese API verwenden, um die maximale Wartezeit zu rekonfigurieren. Standardmäßig wartet Instana bis zu einer Sekunde, nachdem das Laden der Seite beendet ist, d.h. das Ereignis onLoad endet.

ineum('maxMaitForPageLoadMetricsMillis', durationMillis);
 

Manchmal kann es nützlich sein, die ID der geladenen Seite manuell zu erhalten, z. B. wenn man eine benutzerdefinierte Korrelation durchführen möchte. Diese Funktion gibt undefined zurück, solange der Agent JavaScript nicht geladen ist. Nachdem der Agent JavaScript geladen wurde, gibt er immer die gleiche string zurück.

ineum('getPageLoadId');
 

Weitere Informationen zu globalen benutzerdefinierten Ereignissen finden Sie auf der Seite Ereignisse.

Benutzerdefinierte Ereignisse ermöglichen die Berichterstattung über nicht standardmäßige Aktivitäten, wichtige Interaktionen und benutzerdefinierte Zeitpunkte an Instana. Dies kann insbesondere bei der Analyse nicht abgefangener Fehler (Breadcrumbs) und bei der Verfolgung weiterer Leistungsmetriken hilfreich sein.

ineum('reportEvent', eventName, {
  duration: duration,
  timestamp: timestamp,
  backendTraceId: backendTraceId,
  error: error,
  componentStack: componentStack,
  meta: meta,
  customMetric: customMetric
});
 

Die Back-End-Korrelation von Instana funktioniert, indem angepasste Header für Anforderungen des Typs XMLHttpRequest/fetch festgelegt werden. Der Agent JavaScript setzt diese Kopfzeilen, die dann vom Server gelesen werden. Innerhalb des Browsers beschränkt die Same-Origin-Policy die Übertragung von angepassten Headern. Genauer gesagt können benutzerdefinierte Kopfzeilen nur für Anfragen gleichen Ursprungs oder für Anfragen an andere Ursprünge, die die Übertragung benutzerdefinierter Kopfzeilen erlauben, festgelegt werden. So kann beispielsweise eine Website, die von https://example.com:443 bedient wird, standardmäßig nicht von XMLHttpRequestauf https://shop.example.com:443 verweisen, da es sich um zwei unterschiedliche Ursprünge handelt.

Um diese Sicherheitsbeschränkung zu umgehen, gibt es das Cross-Origin Resource Sharing (CORS). Mit CORS kann der Cross-Origin-Ressourcenzugriff für Ursprünge ermöglicht werden. Wenn Sie in Ihrer Anwendung bereits über Cross-Origin-Ressourcenzugriff verfügen, verwenden Sie wahrscheinlich bereits einige CORS-Header.

Um die Instana-Backend-Korrelation zu aktivieren, führen Sie die folgenden Schritte aus:

1. Ermöglichen Sie Cross-Origin-Anforderungen für die Korrelation-Header von Instana durch serverseitige Antwort mit den folgenden Headern.

   Hinweis: Ihr Server muss sowohl bei Preflight-Anfragen als auch bei regulären Anfragen mit diesen Headern antworten. Preflight-Anfragen (identifizierbar über die Methode OPTIONS HTTP ) werden vom Browser ausgeführt, um zu überprüfen, ob Anfragen an den Server gestellt werden können.

   Access-Control-Allow-Origin: https://your-origin.example.com
   Access-Control-Allow-Headers: X-INSTANA-T, X-INSTANA-S, X-INSTANA-L
   
    

2. Informieren Sie den JavaScript -Agenten, dass CORS korrekt konfiguriert ist und dass er diese Korrelations-Header setzen muss:

   ineum('allowedOrigins', urls);
    

Die HTTP Anfrage- oder Antwort-Header von XMLHttpRequest oder fetch Anfragen können vom JavaScript Agenten erfasst werden. Sie können die HTTP Kopfzeilen, die der Agent JavaScript erfassen soll, mit dem Befehl captureHeaders definieren.

Innerhalb des Browsers schränkt die Same-Origin-Policy den Zugriff auf benutzerdefinierte Kopfzeilen ein. Ohne CORS-Konfiguration ( Cross-Origin Resource Sharing ) ist der Agent JavaScript möglicherweise nicht in der Lage, alle HTTP -Header zu erfassen. Um CORS zu aktivieren, siehe Cross-Origin Request Backend Correlation. Mit CORS können nur die CORS-konformen Anfrage- oder Antwort-Header und die in Access-Control-Expose-Headers definierten Header vom JavaScript -Agenten erfasst werden.