API Flutter Monitoring

Découvrez comment utiliser l' API de surveillance d' Flutter pour surveiller et instrumenter vos applications Flutter à l'aide d' Instana. Cette documentation fournit des informations en temps réel sur la surveillance et les performances des applications mobiles multiplateformes.

Flutter versions de l'agent

Pour obtenir des informations détaillées sur la version, les fonctionnalités et les corrections apportées à l'agent « Flutter », consultez le fichier du journal des modifications sur GitHub.

API de l'agent Instana Flutter

La section suivante décrit l'utilisation de l'agent Instana Flutter. Vous pouvez utiliser l'agent Instana Flutter avec les méthodes InstanaAgent de classe décrites ci-dessous :

Configuration

Pour éviter que certaines actions ne soient pas enregistrées, initialisez ` Instana ` dans la initState() classe d'état de l'application dès que possible à l'aide de la commande suivante :

static Future<void> setup({@required String key, @required String reportingUrl}) async
 

Options de configuration

Le tableau suivant répertorie les paramètres :

Paramètre Description
key (String) La clé de configuration de surveillance de Instana.
reportingURL (String) L' URL, qui pointe vers l'instance Instana à laquelle les données de surveillance sont envoyées.
options (SetupOptions, facultatif) Options de configuration (telles que collectionEnabled).

Exemple

@override
void initState() {
  super.initState();
  setupInstana();
}
Future<void> setupInstana() async {
    await InstanaAgent.setup(key: 'Your-Instana-Key', reportingUrl: 'Your-Instana-Reporting-URL', null);

    // Alternatively with configuration options
    var options = SetupOptions();
    options.collectionEnabled = false;
    await InstanaAgent.setup(key: 'Your-Instana-Key', reportingUrl: 'Your-Instana-Reporting-URL', options: options);
}
 

Versions prises en charge de Dart et d' Flutter

Actuellement, toutes les versions du SDK Dart 2.12.0 ou ultérieures, ainsi que toutes les versions de Flutter 1.20.0 ou ultérieures, sont prises en charge.

Activer ou désactiver la collecte

Vous pouvez activer la collecte de données à tout moment pendant l'exécution. Si vous appelez la méthode Instana.setup ` API ` sans activer la collecte de données, et que vous activez ensuite la collecte de données, cela déclenche le démarrage différé de la collecte de données (par exemple, après le consentement de l'utilisateur).

Propriété Description Type
setCollectionEnabled Indicateur permettant d'activer ou de désactiver la collecte de données. Booléen

Traitement des erreurs

Toutes les interfaces de l'agent « Instana » (Android-agent et iOSAgent ) renvoient une valeur asynchrone Future. Les erreurs sont encapsulées dans une exception de typePlatformException.

Il est conseillé de suivre les techniques courantes de gestion des erreurs pour Futures et de consigner les erreurs possibles.

Exemple :

InstanaAgent.setup(key: 'KEY', reportingUrl: 'REPORTING_URL')
    .catchError((e) =>
            log("Captured PlatformException during Instana setup: $e")
        );
 

De même, dans les fonctions asynchrones:

try {
  var result = await InstanaAgent.setup(key: 'KEY', reportingUrl: 'REPORTING_URL');
} catch (e) {
  log("Captured PlatformException during Instana setup: $e");
}
 

Identificateur de session

Chaque instance d' Instana (Android-agent et iOSAgent ) dispose d'un identifiant de session unique que vous pouvez utiliser à d'autres fins dans votre application.

static Future<String> getSessionID() async
 

Surveillance HTTP manuelle

HTTP Les sessions doivent être enregistrées manuellement à l'aide de l' Flutter. Pour plus d'informations, voir la documentation spécifique à chaque plateforme.

static Future<Marker> startCapture({@required String url, @required String method, String viewName}) async
 

Options de configuration

Le tableau suivant répertorie les paramètres :

Paramètre Description
url (URL) URL à capturer.
method (String) Méthode HTTP de la demande.
viewName (String, facultatif) Nom facultatif de la vue visible associée à cette demande.

Exemple

final url = 'http://www.example.com/album'
var marker = await InstanaAgent.startCapture(url: url, method: 'GET', viewName: 'Album');
 

Définir les détails de la réponse

Une fois la réponse générée, vous pouvez définir la taille de la réponse et le code d'état de réponse HTTP dans le fichier Marker.

Définition de la taille de la réponse

marker.responseSizeHeader = 50; // Size of the HTTP header
marker.responseSizeBody = 1000; // Size of the http body
marker.responseSizeBodyDecoded = 2400; // // Size of the decoded http body
 

Définir un code d'état de réponse « HTTP »

marker.responseStatusCode = 200; // The http status code
 

Définir les en-têtes de réponse

Remarque : les en-têtes indiqués ici sont filtrés par Instana en fonction de vos setCaptureHeaders paramètres.
marker.responseHeaders = response.headers;
 

Définir l'ID de traçage du backend d' Instana

Instana L'ID de traçage du backend est l'identifiant permettant de créer une trace du backend pour la requête et la réponse de l' HTTP. Cet identifiant est fourni dans le champ d'en-tête « HTTPserver-timing ». Par exemple, server-timing: intid;desc=be01a91da80e33.

marker.backendTracingID = 'be01a91da80e33'; // the backend tracing id
 

Pour extraire l'ID de traçage dorsal d'une réponse, utilisez la classe d'auxiliaire BackendTracingIDParser comme indiqué:

var Map<String,String> headers = getResponseHeaders(); // You need to get this map from your `response` object
var backendTracingID = BackendTracingIDParser.fromHeadersMap(headers);
 

Définir un message d'erreur

En cas d'échec d'une requête de type « HTTP », vous pouvez définir un message d'erreur de votre choix.

marker.errorMessage = 'Download of album failed'; // the backend tracing id
 

Fin de la capture HTTP

Après avoir défini les détails de la réponse, vous devez appeler finish sur le Marker pour finaliser la capture, comme indiqué dans la commande suivante:

marker.finish();
 

Annulation de la capture HTTP

Vous pouvez également annuler le Marker en attente à l'aide de la commande suivante:

marker.cancel();
 

Vues

Instana peut segmenter les informations d'application mobile par vues logiques. Pour ce faire, définissez le nom de la vue via la méthode InstanaAgent.setView(String) . La vue est ensuite associée à toutes les balises surveillées jusqu'à ce que la vue change lorsque vous appelez à nouveau setView .

L'utilisation de noms lisibles pour définir des vues, telles que product detail page ou payment selection , au lieu de noms techniques ou génériques, tels que la classe (par exemple, WebViewActivity), permet aux membres de l'équipe qui n'ont pas une connaissance approfondie du codebase de comprendre les informations fournies.

Remarque: InstanaAgent.setView(String) doit être appelé lorsqu'un écran est présenté à l'utilisateur, plutôt que lorsqu'un écran est créé (comme dans un fragment, qui peut être créé une seule fois mais affiché plusieurs fois). La définition d'un nom de vue permet à Instana de suivre les transitions entre les pages, en plus des chargements de pages.
static Future<void> setView(String name) async
 

Options de configuration

Le tableau suivant répertorie les paramètres :

Paramètre Description
name (String) Nom de la vue.

Exemple

await InstanaAgent.setView('Webview: FitBit authorization');
 

Identification des utilisateurs

Des informations spécifiques à l'utilisateur peuvent, le cas échéant, être envoyées avec les données transmises à Instana. Les informations peuvent ensuite être utilisées pour déverrouiller d'autres fonctions, telles que:

  • Calculer le nombre d'utilisateurs affectés par des erreurs
  • Filtrer les données pour des utilisateurs spécifiques
  • Voir quel utilisateur a déclenché une modification de la vue ou une demande d' HTTP

Par défaut, Instana n'associe aucune information permettant d'identifier l'utilisateur aux balises.

Important: Prenez en compte les lois de protection des données respectives si vous choisissez d'associer des informations d'identification d'utilisateur à des balises.

Identifiez les utilisateurs à l'aide d'un ID utilisateur pour qu'ils restent uniques. Dans « Instana », l'identifiant utilisateur est un paramètre transparent String qui sert uniquement à calculer certains indicateurs. userName et userEmail peuvent également être utilisés pour avoir accès à plus de filtres et à une présentation plus agréable des informations utilisateur.

Dans les cas où vous traitez des utilisateurs anonymes et n'avez donc pas accès à des ID utilisateur, vous pouvez également utiliser des ID de session. Les ID de session ne sont pas aussi utiles que les ID utilisateur pour filtrer les données, mais ils constituent un bon indicateur pour calculer les métriques utilisateur uniques ou affectées. Définissez un nom d'utilisateur, tel que Anonymous , pour établir une distinction claire entre les utilisateurs authentifiés et les utilisateurs non authentifiés. Les ID session peuvent être des données sensibles (en fonction de l'infrastructure ou de la plateforme utilisée). Envisagez de hacher les identifiants de session afin d'éviter de transmettre à Instana des données susceptibles de permettre l'accès.

Important : les données déjà transmises au serveur d' Instana s ne peuvent pas être mises à jour a posteriori. Pour cette raison, il est important d'appeler les API suivantes dès que possible dans le processus de lancement de l'application.
static Future<void> setUserID(String userID) async
static Future<void> setUserName(String name) async
static Future<void> setUserEmail(String email) async
 

Champs d'identification de l'utilisateur

Le tableau suivant répertorie les paramètres :

Paramètre Description
id (String) Identificateur de l'utilisateur.
email (String) Adresse électronique de l'utilisateur.
name (String) Nom de l'utilisateur.

Exemple

@override
void initState() {
  super.initState();

  await InstanaAgent.setup(key: 'Your-Instana-Key', reportingUrl: 'Your-Instana-Reporting-URL');
  await InstanaAgent.setUserID('1234567890');
  await InstanaAgent.setUserName('John Appleseed');
  await InstanaAgent.setUserEmail('john@appleseed.com');
}
 

Métadonnées

Une clé aléatoire peut, si vous le souhaitez, être associée à toutes les données transmises à Instana. Envisagez d'utiliser les métadonnées pour suivre les valeurs de configuration de l'interface utilisateur, les paramètres, les indicateurs de fonction et tout contexte supplémentaire pouvant être utile pour l'analyse.

Remarque : « Instana » prend actuellement en charge jusqu'à 50 paires clé-valeur.
static Future<void> setMeta({@required String key, @required String value}) async
 

Paramètres

Le tableau suivant répertorie les paramètres :

Paramètre Description
value (String) value de la paire clé-valeur que vous souhaitez ajouter en tant que métadonnées.
key (String) key de la paire clé-valeur que vous souhaitez ajouter en tant que métadonnées.

Exemple

await InstanaAgent.setMeta(key: 'exampleKey', value: 'Some Value');
 

Signalement de évènements personnalisés

Les événements personnalisés permettent de signaler à Instana les activités atypiques, les interactions importantes et les délais personnalisés. La génération de rapports sur ces événements peut être utile lorsque vous analysez des erreurs non interceptées (éléments de navigation) et que vous effectuez le suivi d'un plus grand nombre d'attributs de performance.

static Future<void> reportEvent({@required String name, EventOptions options}) async
 

Paramètres

Le tableau suivant répertorie les paramètres :

Paramètre Description
name (String) Définit le type d'événement survenant dans votre application qui peut entraîner l'envoi d'une balise personnalisée.
options (EventOptions, facultatif) Horodatage, en millisecondes, depuis Epoch indiquant l'heure de démarrage de l'évènement. La valeur now() - duration est spécifiée si l'horodatage n'est pas défini.

EventOptions

Le tableau suivant répertorie l' EventOptions:

Paramètre Description
startTime (int) Horodatage, en millisecondes, depuis Epoch indiquant l'heure de démarrage de l'évènement. La valeur now() - duration est spécifiée si l'horodatage n'est pas défini.
duration (int) Durée de l'évènement, exprimée en millisecondes. La valeur par défaut est zéro.
viewName (String) Vous pouvez transmettre une chaîne pour regrouper la demande dans une vue. Si vous l'envoyez explicitement, viewName est ignoré. Vous pouvez également ne pas indiquer le paramètre viewName pour utiliser le nom de la vue en cours que vous avez défini dans setView(String).
meta (Map<String, String>) Un objet de type « JavaScript » contenant des valeurs sous forme de chaînes de caractères, qui peut être utilisé pour envoyer des métadonnées à Instana uniquement pour cet événement particulier. Contrairement à l'utilisation de l'API de métadonnées, ces métadonnées ne sont pas incluses dans les balises suivantes.
backendTracingID (String) Identificateur permettant de créer une trace back-end pour l'évènement.
customMetric (double) Données de métrique personnalisées avec une précision jusqu'à 4 décimales. N'incluez pas d'informations sensibles dans cette mesure.

Exemple

await InstanaAgent.reportEvent(
      name: 'advancedCustomEvent',
      options: EventOptions()
        ..viewName = 'customViewName'
        ..startTime = DateTime.now().millisecondsSinceEpoch
        ..duration = 3 * 1000
        ..meta = {
          'customKey1': 'customValue1',
          'customKey2': 'customValue2'
        }
        ..customMetric: 123.4567);
 

Capturer les en-têtes d' HTTP

Si vous le souhaitez, l'agent « Instana » peut enregistrer les en-têtes « HTTP » de chaque requête ou réponse suivie.

Une liste de modèles d'expression régulière peut être définie pour déterminer les en-têtes qui sont capturés.

Si le même nom d'en-tête est présent à la fois dans la demande et dans sa réponse, seule la valeur d'en-tête de la réponse est conservée.

static Future<void> setCaptureHeaders({@required List<String> regex}) async
 

Exemple

InstanaAgent.setCaptureHeaders(regex: [
      'x-ratelimit-limit',
      'x-ratelimit-remaining',
      'x-ratelimit-reset'
    ]);
 

Masquer les paramètres de requête d' URL

Les paramètres de requête dans les URL collectées peuvent contenir des données sensibles. Par conséquent, l'agent « Instana » prend en charge la définition de modèles d'expressions régulières pour les clés de paramètres de requête dont les valeurs doivent être masquées. Toute valeur à occulter est remplacée par la chaîne <redacted>. La masquage des données est effectué au sein de l'agent Instana avant que celui-ci n'envoie ses rapports au serveur Instana. Par conséquent, les secrets ne sont pas transmis au backend d' Instana pour y être traités et ne sont donc pas disponibles pour analyse dans l'interface utilisateur de Instana, ni accessibles via l'API Instana API.

Par défaut, l'agent « Instana » est configuré avec une liste de trois expressions régulières permettant de masquer automatiquement les valeurs des paramètres de requête pour les clés « password », « key » et « secret ».

static Future<void> redactHTTPQuery({@required List<String> regex}) async
 

Exemple

InstanaAgent.redactHTTPQuery(regex: [
      'user',
      'id',
      'key'
    ]);
 

Surveillance native d' HTTP

Bien que la surveillance d' HTTP s soit désactivée par défaut, vous pouvez enregistrer les appels d' HTTP s effectués au sein de la plateforme iOS (en Swift ou en Objective- C ) et de la plateforme Android (en Kotlin ou en Java ).

Exemple

@override
void initState() {
  super.initState();
  setupInstana();
}
Future<void> setupInstana() async {
  var options = SetupOptions(captureNativeHttp: true);
  await InstanaAgent.setup(key: 'Your-Instana-Key', reportingUrl: 'Your-Instana-Reporting-URL', options: options);
  if (!ret) {
    // Error handling here
    if (kDebugMode) {
      print("InstanaAgent setup failed");
    }
  }
}
 

Surveillance HTTP automatique

HTTP Les sessions créées en langage Dart peuvent être enregistrées automatiquement. Définissez votre propriété HttpOverrides.global comme illustré dans l'exemple suivant:

Exemple

@override
void main() {
  HttpOverrides.global = InstanaHttpOverrides();
  runApp(const MyApp());
}
 

Si vous disposez déjà de votre propre version de la classe HttpOverrides à d'autres fins, fusionnez la fonction de classe InstanaHttpOverrides avec votre classe et gérez vous-même la classe combinée. La combinaison de plusieurs classes HttpOverrides entraîne une erreur. Vous pouvez également analyser la classe InstanaHttpOverrides et créer votre classe HttpOverrides similaire à la classe InstanaHttpOverrides au lieu d'utiliser la fonction InstanaHttpOverrides() .

Mode d'envoi lent (obsolète depuis la version 3.1.5 )

La fonction de mode d'envoi lent est désactivée par défaut. Si nécessaire, vous pouvez activer cette fonction.

Par défaut, si l'envoi d'une balise échoue, l'agent Instana tente de la renvoyer jusqu'à ce que l'envoi aboutisse. Le renvoi de la balise ne fonctionne pas bien avec certains réseaux cellulaires. En activant la fonction « Mode d'envoi lent », l'intervalle d'envoi des balises est défini sur la valeur temporelle attribuée au slowSendIntervalMillis paramètre. Chaque envoi de balises ne comprend qu'une seule balise, et non un lot (un lot pouvant contenir jusqu'à 100 balises). L'agent « Instana » reste en mode d'envoi lent jusqu'à ce qu'une balise ait été envoyée avec succès.

La plage de temps valide pour slowSendIntervalMillis est comprise entre 2 et 3 600 secondes.

Exemple

@override
void initState() {
  super.initState();
  setupInstana();
}
Future<void> setupInstana() async {
  var options = SetupOptions();
  options.slowSendInterval = 60.0;
  await InstanaAgent.setup(key: 'Your-Instana-Key', reportingUrl: 'Your-Instana-Reporting-URL', options: options);
  if (!ret) {
    // Error handling here
    if (kDebugMode) {
      print("InstanaAgent setup failed");
    }
  }
}
 

Identifiant de session utilisateur

Par défaut, la session utilisateur est suivie et l'ID est un identificateur unique universel (UUID) généré de manière aléatoire. Cet ID reste inchangé lors de l'installation de l'application. Vous pouvez configurer la durée de validité de l'identifiant de session utilisateur à l'aide du usiRefreshTimeIntervalInHrs paramètre.

Les valeurs de paramètre suivantes indiquent le statut de l'ID de session utilisateur:

  • Nombre négatif: cette valeur indique que l'ID de session utilisateur n'expire jamais. La valeur par défaut est -1.

  • Nombre positif: cette valeur signifie que l'ID de session utilisateur est actualisé après l'heure définie, c'est-à-dire qu'un nouvel identificateur unique universel est généré et utilisé.

  • Zéro: Cette valeur indiquée par 0.0 signifie que l'ID de session utilisateur est désactivé.

Exemple

@override
void initState() {
  super.initState();
  setupInstana();
}
Future<void> setupInstana() async {
  var options = SetupOptions();
  options.usiRefreshTimeIntervalInHrs = 24.0;
  await InstanaAgent.setup(key: 'Your-Instana-Key', reportingUrl: 'Your-Instana-Reporting-URL', options: options);
  if (!ret) {
    // Error handling here
    if (kDebugMode) {
      print("InstanaAgent setup failed");
    }
  }
}
 

Saisie automatique des pseudonymes (version préliminaire publique)

Vous pouvez récupérer automatiquement les noms d'écran en fournissant des observateurs ou go-routers en les transmettant à Instana, en fonction de la stratégie de navigation de votre application.

Si l'interface utilisateur de base de votre application est construite avecMaterialApp,CupertinoApp, ou tout widget de base similaire comprenantnavigatorObservers , alors vous pouvez ajouterInstanaScreenNameObserver() à la liste des observateurs pour capturer automatiquement les noms d'écran, ce qui lance le suivi de navigation et collecte les noms d'écran à partir des chemins spécifiés.

InstanaScreenNameObserver()prend en charge trois paramètres pour capturer des noms d'écran avancés. Lorsque vous fournissez lebuildContext paramètre, les noms d'écran sont collectés à partir du widget, du titre du widget ou de l'enfant du widget si le nom de l'itinéraire n'est pas spécifié. Vous pouvez personnaliser davantage votreScreenNameExtractor pour capturer automatiquement les noms d'écran etRouteFilter , qui collecte par défaut les noms dePageRoute .

Si la navigation de base de votre application est gérée par go_router, vous pouvez transmettre l'objet routeur à Instana à l'aide de InstanaGoRouteObserver(yourRouterObject). Instana puis récupère les noms d'écran à partir de la navigation.

Exemple

MaterialApp(
    navigatorObservers: [
      InstanaScreenNameObserver(), /*Providing instana observer here*/
    ],
    title: "Title",
    theme: new ThemeData(
      ...,
      ...
    ),
    initialRoute: '/',
    routes: {
      // When navigating to the "/" route, build the FirstScreen widget.
      '/': (context) => FirstScreen(
            ...,
          ),
      // When navigating to the "/second" route, build the SecondScreen widget.
      '/second': (context) => const SecondScreen(),
  })
 

Paramètres

Le tableau suivant répertorie les paramètres :

Paramètre Description
buildContext (BuildContext, facultatif) Fournit le contexte de construction à partir du widget racine.
screenNameExtractor (ScreenNameExtractor, facultatif) Fournit unScreenNameExtractor objet, qui renvoie une chaîne en appliquant le mécanisme d'extraction. La valeur par défaut est tirée duRouteSettings nom.
routeFilter (RouteFilter, facultatif) Par défaut, seulementPageRoutes sont suivis. Vous pouvez dispenser des cours basés surRouteFilter si besoin.

Balises de limitation de débit

Ce paramètre vous permet de définir le nombre maximal de balises pouvant être envoyées au cours d'un intervalle de temps donné. Le tableau suivant répertorie les options disponibles et les limites de balise correspondantes. Par défaut, DEFAULT_LIMITS est sélectionné.

Limites disponibles Comptes
DEFAULT_LIMITS - 500 balises toutes les 5 minutes - 20 balises toutes les 10 secondes
MID_LIMITS - 1 000 balises toutes les 5 minutes - 40 balises toutes les 10 secondes
MAX_LIMITS - 2 500 balises toutes les 5 minutes - 100 balises toutes les 10 secondes

Exemple

@override
void initState() {
  super.initState();
  setupInstana();
}
Future<void> setupInstana() async {
  var options = SetupOptions();

  options.rateLimits = RateLimits.MAX_LIMITS;

  await InstanaAgent.setup(key: 'Your-Instana-Key', reportingUrl: 'Your-Instana-Reporting-URL', options: options);

}
 

Corrélation côté serveur avec w3cHeaders

Lorsque l'option enableW3CHeaders ( Boolean , facultative) est activée, l'agent Flutter inclut les traceparent en-têtes tracestate et dans tous les appels API surveillés. Ces en-têtes permettent la corrélation au niveau du backend, même si celui-ci n'est pas équipé de l'agent d' Instana. Dans ce cas, vous devez utiliser un outil de surveillance compatible (tel que OpenTelemetry ) pour exporter les détails des traces du backend vers le backend Instana. Si cette option est désactivée, la corrélation avec le backend n'est possible que si ce dernier est également surveillé par l'agent d' Instana. La valeur par défaut est false.

Exemple

@override
void initState() {
  super.initState();
  setupInstana();
}
Future<void> setupInstana() async {
  var options = SetupOptions();

  options.enableW3CHeaders = true;

  await InstanaAgent.setup(key: 'Your-Instana-Key', reportingUrl: 'Your-Instana-Reporting-URL', options: options);

}