React Native-Überwachungs-API
Erfahren Sie, wie Sie die React Native API nutzen können, um Ihre React Native-Anwendungen mit Instana zu überwachen und zu instrumentieren. Dies ermöglicht Echtzeitbeobachtung und Leistungseinblicke für hybride mobile Anwendungen.
React Native Agent-Versionen
Um Updates, Erweiterungen und Änderungen für den React Native-Agenten zu entdecken, sehen Sie sich die Changelog-Datei auf GitHub:
React Native-Agenten-API von Instana
Sie können den Instana React Native Agent über die Methoden der Klasse Instana verwenden, die hier erklärt werden.
Der React Native Agent unterstützt TypeScript Projekte ab der Version 2.0.6.
Einrichtung
Initialisieren Sie Instana in Ihrer Klasse App componentDidMount() :
export default class App extends Component {
componentDidMount() {
Instana.setup(YOUR_INSTANA_APP_KEY, YOUR_INSTANA_REPORTING_URL, null);
// Alternatively with configuration options
Instana.setup(YOUR_INSTANA_APP_KEY, YOUR_INSTANA_REPORTING_URL, {'collectionEnabled': false});
}
}
Der folgende Code ist eine TypeScript Definition:
setup(your_instana_app_key: string, your_instana_app_reportingUrl: string, options?: Object): void;
setup(your_instana_app_key: string, your_instana_app_reportingUrl: string, {collectionEnabled: boolean}): void;
Setup-Parameter
In der folgenden Tabelle sind die Einrichtungsparameter aufgeführt:
| Parameter | Beschreibung |
|---|---|
key (String) |
Instana-Überwachungskonfigurationsschlüssel |
reportingURL (String) |
Die URL, die auf die Instana-Instanz zeigt, an die die Überwachungsdaten gesendet werden sollen |
Sitzungs-ID
Jede Instana-Agentinstanz hat einen eindeutigen Sitzungsbezeichner, den Sie für andere Zwecke in Ihrer Anwendung verwenden können.
static getSessionID()
Der folgende Code ist eine TypeScript Definition:
getSessionID(): Promise<string>;
Parameter zur Sitzungskennung
Gibt Folgendes zurück: Promise(String)
Beispiel für einen Sitzungsidentifikator
var sessionID = await Instana.getSessionID();
Automatische HTTP-Überwachung
Der Instana-Agent bietet eine automatische Überwachung der HTTP -Anfragen.
Ansichten
Instana kann Mobile-App-Einsichten in logische Ansichten segmentieren. Sie können den Namen der Ansicht mit Hilfe der Methode Instana.setView(String) festlegen. Die Ansicht wird dann mit allen überwachten Baken verknüpft, bis die Ansicht durch einen erneuten Aufruf von setView geändert wird.
Verwenden Sie keine technischen oder generischen Namen wie Class (z. B. WebViewActivity), um Ansichten zu definieren. Verwenden Sie stattdessen lesbare Namen für die Ansichten (z. B. product detail page oder payment selection). Durch die Fokussierung auf die Nutzererfahrungen können auch Teammitglieder, die keine intime Kenntnis der Codebasis haben, die gewonnenen Erkenntnisse verstehen.
Instana.setView(String) wird aufgerufen, wenn dem Benutzer ein Bildschirm präsentiert wird, und nicht, wenn ein Bildschirm erstellt wird (wie bei einem Fragment, das einmal erstellt, aber mehrmals angezeigt werden kann). Wenn Sie den Ansichtsnamen festlegen, kann Instana zusätzlich zum Laden von Seiten auch Seitenübergänge verfolgen.static setView(String name)
Der folgende Code ist eine TypeScript Definition:
setView(name: string): void;
Ansichten Parameter
In der folgenden Tabelle sind die Parameter der Ansichten aufgeführt:
| Parameter | Beschreibung |
|---|---|
name (String) |
Der Name der Ansicht. |
Beispiel für Ansichten
Instana.setView('Webview: FitBit authorization');
Benutzer identifizieren
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
- Daten für bestimmte Benutzer filtern
- Sehen Sie, welcher Benutzer eine Ansichtsänderung oder eine HTTP Anfrage initiiert hat
Instana verknüpft standardmäßig keine benutzeridentifizierbaren Informationen mit Beacons. Sie müssen die jeweiligen Datenschutzgesetze kennen. Identifizieren Sie Benutzer durch eine Benutzer-ID. Für Instana ist es eine transparente String , die nur zur Berechnung bestimmter Metriken verwendet wird. userName und userEmail können auch verwendet werden, um Zugang zu mehr Filtern und einer besseren Darstellung der Benutzerinformationen zu haben.
In Fällen, in denen Sie mit anonymen Benutzern arbeiten und daher keinen Zugang zu Benutzer-IDs haben, können Sie alternativ Sitzungs-IDs verwenden. Sitzungs-IDs sind nicht so hilfreich wie Benutzer-IDs, wenn Sie Daten filtern, aber sie sind ein guter Indikator für die Berechnung von Metriken für betroffene oder eindeutige Benutzer. Legen Sie einen Benutzernamen wie Anonymous fest, um eine klare Unterscheidung zwischen authentifizierten und nicht authentifizierten Benutzern zu haben. Sitzungs-IDs können sensible Daten sein (je nach verwendetem Framework oder Plattform). Erwägen Sie das Hashing von Sitzungs-IDs, um die Übertragung von Daten an Instana zu vermeiden, die Zugriff gewähren können.
Bereits an den Server von Instana übermittelte Daten können nicht mehr rückwirkend aktualisiert werden. Aus diesem Grund ist es wichtig, diese API so früh wie möglich im Startprozess der App aufzurufen.
static setUserID(String ID)
static setUserName(String email)
static setUserEmail(String name)
Der folgende Code ist eine TypeScript Definition:
setUserID(id: string): void;
setUserName(name: string): void;
setUserEmail(email: string): void;
Benutzerparameter
In der folgenden Tabelle sind die Benutzerparameter aufgeführt:
| Parameter | Beschreibung |
|---|---|
ID (String) |
Eine Kennung für den Benutzer. |
email (String) |
Die E-Mail-Adresse des Benutzers. |
name (String) |
Der Name des Benutzers. |
Benutzerbeispiel
export default class App extends Component {
componentDidMount() {
Instana.setup(YOUR_INSTANA_APP_KEY, YOUR_INSTANA_REPORTING_URL);
Instana.setUserID('1234567890');
Instana.setUserEmail('instana@example.com');
Instana.setUserName('instana react-native agent demo');
}
}
Metadaten
An alle Daten, die an Instana übermittelt werden, können beliebige Metadaten angehängt werden. Sie können damit UI-Konfigurationswerte, Einstellungen, Funktionsflags und jeden zusätzlichen Kontext verfolgen, der für die Analyse nützlich sein könnte.
static setMeta(String key, String value)
Der folgende Code ist eine TypeScript Definition:
setMeta(key: string, value: string): void;
Metadaten-Parameter
In der folgenden Tabelle sind die Metadatenparameter aufgeführt:
| Parameter | Beschreibung |
|---|---|
value (String) |
Der Wert (value) des Schlüsselwertpaares, das Sie als Metadaten hinzufügen möchten. |
key (String) |
Der Wert (key) des Schlüsselwertpaares, das Sie als Metadaten hinzufügen möchten. |
Beispiel für Metadaten
export default class App extends Component {
componentDidMount() {
Instana.setMeta('randomKey1', 'randomValue1');
Instana.setMeta('randomKey2', 'randomValue2');
}
}
Angepasste Ereignisse melden
Benutzerdefinierte Ereignisse ermöglichen die Berichterstattung über nicht standardmäßige Aktivitäten, wichtige Interaktionen und benutzerdefinierte Zeitpunkte an Instana. Es kann besonders hilfreich sein, wenn Sie nicht abgefangene Fehler (Breadcrumbs) analysieren und weitere Leistungsmetriken verfolgen wollen.
static reportEvent(String eventName, {
startTime: Number startTime,
duration: Number duration,
viewName: String viewName,
backendTraceId: String backendTraceId,
meta: Map meta
})
Der folgende Code ist eine TypeScript Definition:
reportEvent(eventName: string, options?: {
startTime?: number;
duration?: number;
viewName?: string;
meta?: Map<string, string>;
backendTracingId?: string;
customMetric?: number;
}): void;
Parameter für benutzerdefinierte Ereignisse
In der folgenden Tabelle sind die Parameter für benutzerdefinierte Ereignisse aufgeführt:
| Parameter | Beschreibung |
|---|---|
eventName (String) |
Legt fest, welche Art von Ereignis, das in Ihrer Anwendung eintritt, zur Übertragung eines benutzerdefinierten Beacons führen soll |
startTime (Numberoptional) |
Eine Zeitmarke in Millisekunden seit der Epoche, die angibt, zu welchem Zeitpunkt das Ereignis begonnen hat. Wechselt zurück zu now() - duration , wenn nicht definiert. |
duration (Numberoptional) |
Die Dauer in Millisekunden, wie lange das Ereignis dauerte. Der Standardwert ist null. |
viewName (Stringoptional) |
Eine Zeichenkette, die Sie übergeben können, um die Anfrage in einer Ansicht zu gruppieren. Wenn Sie explizit nil senden, wird viewName ignoriert. Alternativ können Sie auch den Parameter viewName weglassen, um den aktuellen Namen der Ansicht zu verwenden, den Sie unter setView(String name) festgelegt haben.) |
backendTracingId (Stringoptional) |
Kennung zur Erstellung eines Backend-Trace für dieses Ereignis |
meta (objectoptional) |
Ein JavaScript Objekt mit String-Werten, die verwendet werden können, um Metadaten nur für dieses einzelne Ereignis an Instana zu senden. Im Gegensatz zur Verwendung der Metadaten-API werden diese Metadaten nicht in nachfolgende Beaconnachrichten einbezogen. |
customMetric (doubleoptional) |
Benutzerdefinierte metrische Daten mit einer Genauigkeit von bis zu 4 Dezimalstellen. Nehmen Sie keine sensiblen Informationen in diese Metrik auf. |
Beispiel für benutzerdefinierte Ereignisse
Instana.reportEvent('myCustomEvent', {
startTime: Date.now() - 500,
duration: 300,
viewName: 'overridenViewName',
backendTracingId: '31ab91fc1092',
meta: {
state: 'running'
},
customMetric: 123.4567
});
URLs aus der Überwachung ausschließen
URLs können ignoriert werden, indem man reguläre Ausdrücke angibt oder sie der Liste ignoreURLs hinzufügt. Diese Funktion ist nützlich, wenn Sie alle HTTP Anfragen ignorieren möchten, die sensible Daten wie z. B. ein Kennwort enthalten.
Der Agent muss jede Zeichenkette, die Sie der Methode setIgnoreURLsByRegex übergeben, in einen nativen Regex-Ausdruck für jede unterstützte Plattform umwandeln. Sie können Ablehnungen von Zusagen verfolgen, die Sie über jedes Problem informieren, auf das der Agent gestoßen ist, während Sie Ihre Eingaben interpretiert haben.
static setIgnoreURLsByRegex([]String regexArray)
Der folgende Code ist eine TypeScript Definition:
setIgnoreURLsByRegex(regexArray: Array<string>): Promise<any>;
URL Parameter ausschließen
In der folgenden Tabelle sind die auszuschließenden Parameter aufgeführt URL :
| Parameter | Beschreibung |
|---|---|
regexArray |
Ein Array von String-Objekten, der das Regex enthält, das mit den URLs übereinstimmt, die Sie ignorieren möchten. |
Rückgabe: Promise(Boolean). Bei Ablehnung enthält die Ausnahme eine Liste aller Parameter, die nicht in native Regex konvertiert werden konnten.
Beispiel ausschließen URL
export default class App extends Component {
componentDidMount() {
setIgnoreURLsByRegex();
async function setIgnoreURLsByRegex() {
try {
await Instana.setIgnoreURLsByRegex(["http:\/\/localhost:8081.*", "/.*([&?])password=.*/i"]);
} catch (e) {
console.warn(e);
}
}
}
}
Das Beispiel ignoriert alle Abfragen an den Metro-Bundler und alle URLs, die ein Kennwort in der Abfrage enthalten.
Redact URL Abfrageparameter
Abfrageparameter in den gesammelten URLs können sensible Daten enthalten. Daher unterstützt der Instana-Agent die Angabe von Regex-Mustern für Abfrageparameterschlüssel, deren Werte geschwärzt werden müssen. Jeder Wert, der unkenntlich gemacht werden muss, wird durch die Zeichenfolge <redacted> ersetzt. Die Redigierung erfolgt innerhalb des Instana-Agenten, bevor der Agent an den Instana-Server berichtet. Daher erreichen die Geheimnisse nicht die Instana-Server zur Verarbeitung und stehen nicht für die Analyse in der Instana-Benutzeroberfläche oder den Abruf über die Instana-API zur Verfügung.
Standardmäßig ist der Instana-Agent mit einer Liste von drei Regex-Mustern konfiguriert, um Abfrageparameterwerte für die Schlüssel "password", "key" und "secret" automatisch zu redigieren.
static setRedactHTTPQueryByRegex([]String regexArray)
Der folgende Code ist eine TypeScript Definition:
setRedactHTTPQueryByRegex(regexArray: Array<string>): Promise<any>;
Redact URL Abfrageparameter
In der folgenden Tabelle sind die Abfrageparameter von Redact URL aufgeführt:
| Parameter | Beschreibung |
|---|---|
regex ([NSRegularExpression]) |
Ein Array von String , das den Schlüsseln für die Werte entspricht, die Sie schwärzen möchten. |
Redact URL Abfragebeispiel
export default class App extends Component {
componentDidMount() {
setRedactHTTPQueryByRegex();
async function setRedactHTTPQueryByRegex() {
try {
await Instana.setRedactHTTPQueryByRegex(["pass(word|wort)"]);
} catch (e) {
console.warn(e);
}
}
}
}
In diesem Beispiel werden die Werte für die HTTP Parameterschlüssel "password" oder "passwort" redacted.
Die erfassten URL https://example.com/accounts/?password=123&passwort=459 werden gesammelt und als https://example.com/accounts/?password=<redacted>&passwort=<redacted> angezeigt.
/account/<account id>/status) oder Matrixparameter (/account;accountId=<account id>/status) als Geheimnisse zu behandeln.Erfassen von HTTP Kopfzeilen
Optional kann der Instana-Agent die HTTP -Header jeder verfolgten Anfrage und Antwort erfassen.
Es kann eine Liste von Regex-Mustern definiert werden, um zu bestimmen, welche Kopfzeilen erfasst werden sollen.
Wenn derselbe Kopfzeilenname sowohl in einer Anfrage als auch in ihrer Antwort vorhanden ist, wird nur der Kopfzeilenwert der Antwort berücksichtigt.
static setCaptureHeadersByRegex([]String regexArray)
Der folgende Code ist eine TypeScript Definition:
setCaptureHeadersByRegex(regexArray: Array<string>): Promise<any>;
Beispiel für Capture HTTP headers
export default class App extends Component {
componentDidMount() {
setCaptureHeadersByRegex();
async function setCaptureHeadersByRegex() {
try {
await Instana.setCaptureHeadersByRegex(["cache-control", "etag"]);
} catch (e) {
console.warn(e);
}
}
}
}
Langsamer Sendebetrieb
Wenn das Senden eines Beacons fehlschlägt, versucht der Instana-Agent standardmäßig, das Beacon erneut zu senden, bis das Beacon erfolgreich gesendet wurde. Allerdings funktioniert dieses Verhalten bei einigen Mobilfunknetzen nicht gut. Wenn Sie die Funktion "Langsames Senden" aktivieren, können Sie das Sendeintervall der Bake auf den Zeitwert ändern, der dem Parameter slowSendInterval parameter zugeordnet ist. Jede Sendung besteht aus nur einer Bake anstelle eines Stapels (maximal 100 Baken in einem Stapel). Der Instana-Agent bleibt im langsamen Sendemodus, bis ein Beacon erfolgreich gesendet wurde.
Der gültige Zeitbereich für den Parameter slowSendInterval parameter beträgt 2-3600 Sekunden.
Der folgende Code ist eine TypeScript Definition:
setup(key: string, reportingUrl: string, {slowSendInterval: number}): void;
Beispiel für einen langsamen Sendemodus
export default class App extends Component {
componentDidMount() {
var options = {}
options.slowSendInterval = 120.0;
Instana.setup('<your key>', '<your reporting url>', options);
}
}
ID der Benutzersitzung
Standardmäßig wird die Benutzersitzung nachverfolgt und ein Universally Unique Identifier (UUID) nach dem Zufallsprinzip erzeugt. Diese ID bleibt unverändert, solange die App installiert ist. Sie können die Verfallszeit der Benutzersitzungsnummer mit dem usiRefreshTimeIntervalInHrs parameter.
Die folgenden Parameterwerte geben den Status der Benutzersitzungsnummer an:
Negative Zahl: Dieser Wert zeigt an, dass die Benutzersitzungs-ID niemals abläuft. Der Standardwert ist -1.
Positive Zahl: Dieser Wert bedeutet, dass die Benutzersitzungs-ID nach der eingestellten Zeit aufgefrischt wird. Es wird eine neue UUID erzeugt und verwendet.
Null: Dieser mit 0.0 bezeichnete Wert bedeutet, dass die Benutzersitzungsnummer deaktiviert ist.
Der folgende Code ist eine TypeScript Definition:
setup(key: string, reportingUrl: string, {usiRefreshTimeIntervalInHrs: number}): void;
Beispiel einer Benutzersitzungs-ID
export default class App extends Component {
componentDidMount() {
var options = {}
options.usiRefreshTimeIntervalInHrs = 24.0;
Instana.setup('<your key>', '<your reporting url>', options);
}
}
Begrenzte Anzahl von Baken
Mit diesem Parameter können Sie die Grenzwerte für die Anzahl der Beacons, die innerhalb eines bestimmten Zeitintervalls gesendet werden können, anpassen. In der folgenden Tabelle sind die verfügbaren Optionen und die entsprechenden Grenzwerte für Baken aufgeführt. Standardmäßig ist 0 (DEFAULT_LIMITS) ausgewählt.
| Verfügbare Grenzwerte | Option 'counts' |
|---|---|
0 (DEFAULT_LIMITS) |
- 500 Baken pro 5 Minuten - 20 Baken pro 10 Sekunden |
1 (MID_LIMITS) |
- 1000 Baken pro 5 Minuten - 40 Baken pro 10 Sekunden |
2 (MAX_LIMITS) |
- 2500 Baken pro 5 Minuten - 100 Baken pro 10 Sekunden |
Beispiel
class App extends Component {
componentDidMount() {
let options = {};
options.suspendReporting = Instana.androidSuspendReport.LOW_BATTERY_OR_CELLULAR_CONNECTION;
options.rateLimits = 2;
Instana.setup('<your key>', '<your reporting url>', options);
}
}
Backend-Korrelation mit W3CHeaders
Wenn die enableW3CHeaders ( Boolean , optional) aktiviert ist, schließt der react-native Agent die Header traceparent und tracestate in alle überwachten API-Aufrufe ein. Diese Header ermöglichen eine Backend-Korrelation, selbst wenn das Backend nicht mit dem Instana-Agenten instrumentiert ist. In solchen Fällen müssen Sie ein kompatibles Überwachungstool (z. B. OpenTelemetry ) für den Export von Backend-Trace-Details in das Instana-Backend verwenden. Wenn diese Option deaktiviert ist, ist eine Backend-Korrelation nur möglich, wenn das Backend auch vom Instana-Agenten überwacht wird. Der Standardwert ist false.
Beispiel
class App extends Component {
componentDidMount() {
let options = {};
options.enableW3CHeaders = true;
Instana.setup('<your key>', '<your reporting url>', options);
}
}