JavaScript-Agent-API

In der folgenden Tabelle sind die Parameter aufgeführt:

Überwachungstasten können mit dem Befehl key gesetzt werden. Der Überwachungsschlüssel wird angezeigt, wenn Sie Websites in der Benutzeroberfläche von „ Instana “ konfigurieren.

ineum('key', trackingKey);
 

Beacons werden über HTTP GET und POST an die Berichts- URL gesendet, um die Überwachungsdaten an Instana zu übermitteln.

ineum('reportingUrl', reportingUrl);
 

In einigen Fällen kann es wünschenswert sein, einen JavaScript -Agenten an mehrere Back-Ends zu melden. Verwenden Sie in diesem Fall den Befehl reportingBackends , um den JavaScript -Agenten an mehrere Back-Ends zu melden.

ineum('reportingBackends', reportingBackends);
 

Instana kann Website-Messdaten nach logischen Seiten segmentieren. Dazu benötigt es einen Hinweis darauf, welche Seite der Benutzer gerade betrachtet. Dieser Seitenname kann mit dem Befehl page festgelegt werden. Setzen Sie den page so früh wie möglich. Sie können die page ändern, um Dokumentänderungen zu präsentieren (z. B. bei einseitigen Bewerbungen). Dadurch kann „ Instana “ nicht nur das Laden von Seiten, sondern auch Seitenwechsel erfassen.

ineum('page', pageName);
 

Seitenwechselereignisse werden immer dann erfasst, wenn der Seitenname über die Funktion ` API ` geändert wird – mit Ausnahme des ersten Aufrufs dieser Funktion ` 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 einen Mehrwert bieten, da window.title Produktnamen enthält.

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

Optional können benutzerspezifische Informationen zusammen 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 das Laden einer Seite oder einen Ajax-Aufruf ausgelöst hat.

Standardmäßig verknüpft Instana keine personenbezogenen Daten mit Beacons. Beachten Sie die jeweiligen Datenschutzgesetze, wenn Sie sich dafür entscheiden, dies zu tun. In „ Instana “ ist die Benutzer-ID ein transparenter string Wert, der ausschließlich zur Berechnung bestimmter Kennzahlen verwendet wird. Daher erfolgt die Identifizierung der Benutzer über eine Benutzer-ID. userName und userEmail kann zudem genutzt werden, um auf weitere Filter und eine übersichtliche Darstellung der Benutzerinformationen zuzugreifen.

Wenn diese Funktion „ API “ synchron während des Ladevorgangs der Seite aufgerufen wird, beispielsweise durch serverseitiges Einbinden der Informationen in das HTML-Dokument, wird sichergestellt, dass alle Beacons Benutzerinformationen enthalten, die Statistiken zu einzelnen oder betroffenen Benutzern korrekt sind und die Beacons bei der Analyse ordnungsgemäß 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. Mithilfe der Sitzungsverfolgung kann Instana insbesondere die Auswirkungen auf die Endnutzer ermitteln, wenn keine definierten Nutzerinformationen vorliegen.

Um Sitzungen zu verfolgen, verwendet der „ JavaScript “-Agent nach dem trackSessions Aufruf die Browser-URL localStorageAPI. Technisch gesehen ist eine Sitzung eine zufällige ID, die zusammen mit zwei Zeitstempeln in Browsern 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 Werte der Benutzeroberflächenkonfiguration, Einstellungen, Feature-Flags oder sonstige zusätzliche Kontextinformationen zu erfassen, die für die Analyse nützlich sein könnten.

ineum('meta', key, value);
 

Beim Laden der Seite kann eine Backend-Trace-ID definiert werden, um eine Korrelation zwischen Frontend und Backend 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 Frontend-Verarbeitung beim Laden von Seiten herzustellen. Sie ist für die Korrelation zwischen den XMLHttpRequest und fetch nicht erforderlich. Eine Trace-ID muss eine Hex-Zeichenkette mit 16 oder 32 Zeichen sein.

ineum('traceId', traceId);
 

Über diesen Link API können Sie mehrere reguläre Ausdrücke definieren. Bei mindestens einer Übereinstimmung erfolgt keine Datenübertragung an Instana. Die regulären Ausdrücke werden in den folgenden Szenarien ausgewertet:

• Überprüfung anhand der URLs der Dokumente (d. h. der in der Adressleiste window.location.href angezeigten URLs). Die gesamte Datenübertragung an Instana wird unterbunden, sobald einer der regulären Ausdrücke übereinstimmt.
• 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.
• Überprüfung der Ziel-URLs von Aufrufen unter HTTP, beispielsweise über 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. der URL, die in der Adressleiste des Browsers sichtbar ist (siehe secrets API ). Beachten Sie jedoch, dass die in den URLs von Dokumenten gespeicherten Geheimnisse fast allen Dritten bekannt sind. Wir haben eine spezielle Beispiel-App mit einer Beschreibung, die verdeutlicht, warum in Dokument-URLs gespeicherte Geheimnisse leicht an Dritte weitergegeben werden können. Weitere Einzelheiten finden Sie in dieser Beispielanwendung und -beschreibung. Sie können jedoch über diesen Link API die Erfassung aller Überwachungsdaten für diese URLs deaktivieren.

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

ineum('secrets', secrets);
 

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

Das Fragment der erfassten URLs kann sensible Informationen enthalten. Daher unterstützt der Agent „ JavaScript “ die Angabe von Mustern für Fragmentwerte, die auf der Grundlage des Pfads „ URL “ unkenntlich gemacht werden können. Diese Bearbeitung erfolgt über den „ JavaScript “-Agenten im Webbrowser. Dadurch wird verhindert, dass sensible Daten zur Verarbeitung an die Server von Instana gelangen. Vertrauliche Informationen bleiben für die Analyse in der Benutzeroberfläche oder den Abruf über das „ API “ unzugänglich.

ineum('fragment', fragment);
 

Wenn ein Teil Ihres „ URL “-Pfads mit einem Eintrag in der Liste übereinstimmt, wird der Wert des Fragments unkenntlich gemacht und nicht an das „ Instana “-Backend gesendet. Standardmäßig blendet „ Instana “ keine Fragmente von „ URL “ aus.

Instana Marker und Messwerte, die über das User-Timing- API erfasst werden, automatisch sammeln und in benutzerdefinierte Ereignisse umwandeln. Dies bedeutet, dass die User-Timing-API als herstellerneutrale Methode verwendet werden kann, um die reinen Timingdaten an Instana zu melden.

Mithilfe des User-Timing- API s können Sie mehrere reguläre Ausdrücke definieren, die, sobald mindestens einer davon zutrifft, dazu führen, dass keine spezifischen User-Timings erfasst werden. Standardmäßig werden die folgenden Bedingungen ignoriert:

• „User-Timings“ in React : die Markierungen und Messwerte, die mit dem ⚛️- oder ⛔-Emoji beginnen
• Die „user-timings“ von Angular : die Markierungen und Messungen, die mit Zone
• Markierungen und Maßnahmen, deren Namen mit start oder end beginnen

ineum('ignoreUserTimings', ignoreUserTimings);
 

Standardmäßig erfasst der „ JavaScript “-Agent den vollständigen Befehl „ URL “ einschließlich aller Parameter. Sie können den Agenten so konfigurieren, dass er nur Parameter für die URLs erfasst, die einer bestimmten Liste von regulären Ausdrücken entsprechen. Die Parameter der ausgeschlossenen URLs werden nicht erfasst.

Auf der Grundlage der bereitgestellten Liste regulärer Ausdrücke verfolgt der „ JavaScript “-Agent URLs wie folgt:

• Wenn der „ URL “ mit einem Eintrag in der Liste übereinstimmt, wird der gesamte „ URL “, der alle Parameter enthält, abgerufen.
• Wenn der „ URL “ mit keinem Eintrag in der Liste übereinstimmt, werden die Abfrageparameter und Fragmente der „ URL “ nicht an das „ Instana “-Backend gesendet.
• Ist die angegebene Liste leer, wird das Standardverhalten angewendet, und die gesamte „ URL “ mit ihren Parametern wird nachverfolgt.

ineum('queryTrackedDomainList',queryTrackedDomainList);
 

Die folgenden Szenarien erläutern die Situation, wenn die Datei „ URL “ ein Geheimnis oder ein Fragment enthält, das mithilfe von ineum('secrets', secrets) oder ineum('fragment', fragment)geschwärzt wurde:

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

Wenn ein Browser eine Anfrage an einen Remote-Server sendet und der Instana Agent den Remote-Server überwacht, kann die Antwort des Servers den HTTP Header „Server-Timing“ enthalten, um die Server-Timing-Informationen bereitzustellen. backendTraceId zum Instana -Agenten, der im Browser ausgeführt wird. Wenn auf dem Remote-Server „ OpenTelemetry “ aktiviert ist, kann der Header tracestate „ HTTP “ das enthalten backendTraceId.

tracestate und traceparent sind „ W3C-defined “-Header, die zur Korrelation verteilter Trace-IDs verwendet werden. Weitere Informationen zu den Trace-Headern von „ W3C “ finden Sie unter „Trace-Kontext-Ebene “.

Wenn Sie davon ausgehen, dass der Remote-Server „ OpenTelemetry “ verwenden und den Wert backendTraceId im tracestate Header bereitstellen kann, muss der „ Instana “-Agent im Browser „ enableW3CHeadersAPI “ auf „true“ setzen, um den backendTraceId Wert in den „ W3C “-Headern zu nutzen.

Sie können die Einstellung backendTraceId an drei verschiedenen Stellen vornehmen: über den Server-Timing Header, den tracestate Header und manuell über die Eingabe traceId von „ API “ im Browser. Die Reihenfolge dieser Ansätze ist wie folgt:

• Wenn diese enableW3CHeaders Option aktiviert ist, haben Sie zwei Möglichkeiten. Entnehmen Sie zunächst den tracestate Wert aus den Metadaten der traceparent aktuellen Seite und verwenden Sie ihn. Falls Sie nicht abrufen können tracestate, wird eine 16 Zeichen lange Zeichenfolge generiert und verwendet, die mit dem Trace-Kontext von „ W3C “ kompatibel ist.
• Wenn enableW3CHeaders deaktiviert ist, prüfen Sie zunächst, ob die Funktion traceId API aufgerufen wird. Wenn die traceId Methode ` API ` aufgerufen wird, verwende die ID als backendTraceId. Wenn die Funktion traceId ` API ` nicht aufgerufen wird, wird der Header `Server-Timing` der Antwort ` HTTP ` ausgewertet, um den Wert zu ermitteln backendTraceId.
• 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 erfassen, wartet der Agent „ JavaScript “, bis die folgenden Bedingungen erfüllt sind. Zum Beispiel die Verzögerung bei der ersten Eingabe und die kumulative Layoutverschiebung.

• 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 “ nach dem Laden der Seite – also nach dem Ende des Ereignisses „ onLoad “ – bis zu einer Sekunde.

ineum('maxMaitForPageLoadMetricsMillis', durationMillis);
 

Manchmal kann es sinnvoll sein, die ID des Seitenladens manuell abzurufen, beispielsweise wenn man eine benutzerdefinierte Korrelation durchführen möchte. Diese Funktion gibt undefined zurück, bis der JavaScript nicht geladen ist. Nach dem Laden des JavaScript wird immer derselbe string zurückgegeben.

ineum('getPageLoadId');
 

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

Benutzerdefinierte Ereignisse ermöglichen die Übermittlung von Informationen zu nicht standardmäßigen Aktivitäten, wichtigen Interaktionen und benutzerdefinierten Zeitpunkten an Instana. Dies kann besonders hilfreich sein, wenn es darum geht, nicht abgefangene Fehler (Breadcrumbs) zu analysieren und weitere Leistungskennzahlen zu erfassen.

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 Header, die anschließend 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 keine XMLHttpRequestan https://shop.example.com:443 senden, da es sich um zwei unterschiedliche Ursprünge handelt.

Um diese Sicherheitsbeschränkung zu umgehen, steht die Funktion „Cross-Origin Resource Sharing“ ( CORS ) zur Verfügung. 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.

Führen Sie die folgenden Schritte aus, um die Backend-Korrelation für „ Instana “ zu aktivieren:

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 (erkennbar an der OPTIONS Methode ` HTTP `) werden vom Browser ausgeführt, um zu überprüfen, ob Anfragen an den Server gesendet werden dürfen.

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

2. Teilen Sie dem Mitarbeiter von „ JavaScript “ mit, dass CORS korrekt konfiguriert ist und dass folgende Korrelations-Header gesetzt werden müssen:

   ineum('allowedOrigins', urls);
    

Die „ HTTP “-Header in den Anfrage- oder Antwortdaten von XMLHttpRequest oder fetch Anfragen können vom JavaScript -Agenten erfasst werden. Sie können die „ HTTP “-Header, die der „ JavaScript “-Agent erfassen soll, über den captureHeaders Befehl festlegen.

Innerhalb des Browsers beschränkt die Same-Origin-Policy den Zugriff auf angepasste Header. Ohne eine Konfiguration für den Austausch von Ressourcen zwischen verschiedenen Ursprüngen ( CORS ) kann der „ JavaScript “-Agent möglicherweise nicht alle „ HTTP “-Header erfassen. Informationen zur Aktivierung von „ CORS “ finden Sie unter „Cross-Origin Request Backend Correlation “. Bei „ CORS “ können vom „ JavaScript “-Agenten nur die Request- oder Response-Header erfasst werden, die die Bedingung „ CORS “ erfüllen, sowie diejenigen, die in „Access-Control-Expose-Headers“ definiert sind.