API de surveillance Android

Pour configurer la surveillance d' Instana s pour les applications Android, initialisez ` Instana ` dans votre Application classe onCreate(), immédiatement après super.onCreate():

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Instana.setup(
            this,
            InstanaConfig(
                key = "YOUR_APP_KEY",
                reportingURL = "YOUR_REPORTING_URL"
            )
        )
    }
}
 

Le tableau suivant présente les paramètres de configuration liés aux performances

Pour vérifier la configuration actuelle d' Instana, accédez à InstanaConfig l'instance :

val currentConfig = Instana.config
 

Chaque instance de l'agent « Instana » dispose d'un identifiant de session unique que vous pouvez utiliser à d'autres fins dans votre application.

Par défaut, les sessions d' HTTP s sont enregistrées automatiquement. Une fois Instana initialisé (après avoir installé le plug-in Android Instana et Instana Android SDK ), l'agent se charge du reste.

L'agent Android d' Instana intègre automatiquement du code permettant de surveiller les requêtes HTTP pour les clients pris en charge :

• OkHttp3
• HttpURLConnection
• Retrofit

La surveillance automatique de l' HTTP e peut être désactivée au profit d'une surveillance manuelle de l' HTTP e.

Vous pouvez également surveiller manuellement les sessions d' HTTP.

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 Instana.setView(String) . La vue est ensuite associée à toutes les balises surveillées jusqu'à ce que la vue change lorsque setView est à nouveau appelé.

N'utilisez pas de noms techniques ou génériques tels que la classe (par exemple, WebViewActivity) pour définir des vues. Utilisez des noms lisibles pour les vues, par exemple product detail page ou payment selection. En se concentrant sur l'expérience utilisateur, les membres de l'équipe qui n'ont pas une connaissance intime du codebase peuvent comprendre les connaissances fournies.

Des informations spécifiques à l'utilisateur peuvent, le cas échéant, être envoyées avec les données transmises à Instana. Ces informations peuvent ensuite être utilisées pour débloquer les fonctionnalités supplémentaires suivantes :

• Calcul du nombre d'utilisateurs affectés par des erreurs
• Filtrage des données pour des utilisateurs spécifiques
• Identification de l'utilisateur à l'origine d'une modification de vue ou d'une demande d' HTTP

Par défaut, Instana associe toute information permettant d'identifier un utilisateur aux balises. Veuillez tenir compte des lois applicables en matière de protection des données lorsque vous décidez d'envoyer des informations personnelles à Instana. Identifiez les utilisateurs à l'aide d'un ID utilisateur. Pour l' Instana e, cette action est une entité transparente 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.

Si vous gérez des utilisateurs anonymes et que vous 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 lorsque vous filtrez des données, mais ils sont un bon indicateur pour calculer les métriques d'utilisateur affectées ou uniques. Vous devez définir 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). Pour éviter de transmettre à Instana des données susceptibles de permettre l'accès, effectuez un hachage des identifiants de session.

Les données déjà transmises au serveur d' Instana s ne peuvent pas être mises à jour a posteriori. Vous devez donc appeler cette méthode ` API ` dès que possible lors du lancement de l'application.

Instana {
    void setUserId(@Nullable String)
    @Nullable String getUserId()
    void setUserName(@Nullable String)
    @Nullable String getUserName()
    void setUserEmail(@Nullable String)
    @Nullable String getUserEmail()
}
 

Des métadonnées facultatives peuvent être associées à toutes les données transmises à Instana. Vous pouvez utiliser ces 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.

Instana {
     val meta = MaxCapacityMap<String, String>(50)
}
 

Des URL peuvent être ignorées en fournissant des expressions régulières, en les ajoutant à la liste ignoreURLs. Ignorer toutes les demandes HTTP qui contiennent des données sensibles comme un mot de passe est un bon scénario d'utilisation de cette fonction.

Seules les URL surveillées automatiquement sont ignorées. Les URL surveillées manuellement ne sont pas ignorées.

Instana {
    val ignoreURLs = mutableListOf<Regex>()
}
 

Instana {
    List<Pattern> getIgnoreURLs()
}
 

Les événements personnalisés permettent de signaler à Instana les activités atypiques, les interactions importantes et les délais personnalisés. Ces rapports peuvent s'avérer particulièrement utiles pour analyser les erreurs non détectées (fil d'Ariane) et pour suivre davantage d'indicateurs de performance.

Instana {
    fun reportEvent(event: CustomEvent)
}
 

Grâce à la CustomEvent classe fournie par Instana, vous pouvez définir plusieurs paramètres, eventName (dans son constructeur) étant le seul obligatoire.

Vous pouvez indiquer explicitement à Instana si les services Play Google sont disponibles pour un utilisateur et une session spécifiques.

Instana {
    val googlePlayServicesMissing: Boolean?
}
 

Par défaut, Instana redirige directement vers LogCat. Vous pouvez diriger ces journaux en fournissant un objet qui implémente l'interface du consignateur:

interface Logger {
    fun log(level: Int, tag: String, message: String, error: Throwable?)
}

Instana {
    var logger: com.instana.android.Logger?
}
 

Par défaut, Instana génère des journaux de niveau INFO. Vous pouvez modifier cette valeur par défaut en définissant un niveau de journalisation parmi les niveaux android.util.Log communs (android.util.Log.INFO, android.util.Log.ERROR, ou d'autres niveaux):

Instana {
    var logLevel: Int
}
 

Vous pouvez activer la collecte et la transmission des données à tout moment, par exemple au démarrage de l'agent Instana ou pendant son exécution.

Cette fonction est particulièrement utile dans les scénarios où l'accord explicite de l'utilisateur est requis pour que la collecte des données puisse se poursuivre.

Instana {
    fun setCollectionEnabled(enabled: Boolean)
    fun isCollectionEnabled()
}
 

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 masquée est remplacée par <redacted>«. ».

La suppression des données sensibles s'effectue au sein de l'agent Instana avant que celui-ci ne transmette les informations au serveur Instana. Par conséquent, les secrets ne sont pas transmis aux serveurs d'arrière-plan d' Instana pour y être traités et ne peuvent donc pas être analysés dans l'interface utilisateur ni récupérés via 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 :

• key
• secret
• password

L'occultation est appliquée uniquement aux demandes surveillées automatiquement et à leurs journaux associés. Les demandes surveillées manuellement ne sont pas occultées.

Instana {
    val redactHTTPQuery = mutableListOf<Regex>()
}
 

Par défaut, l'agent Android collecte l' URL complète, qui comprend tous ses paramètres. Vous pouvez configurer l'agent de manière à ce qu'il ne collecte les paramètres que pour les URL correspondant à une liste spécifiée d'expressions régulières. Les paramètres des URL exclues ne sont pas suivis.

À partir de la liste d'expressions régulières fournie, l'agent Android suit les URL comme suit :

• Si l' URL e correspond à une entrée de la liste, l' URL e complète, y compris tous les paramètres, est récupérée.
• Si l'adresse URL ne correspond à aucune entrée de la liste, les paramètres de requête et les fragments de l'adresse URL ne sont pas transmis au backend Instana.
• Si la liste fournie est vide, le comportement par défaut est appliqué et l' URL e complète, avec ses paramètres, est enregistrée.

Instana {
    val queryTrackedDomainList = mutableListOf<Regex>()
}
 

Les scénarios suivants décrivent la situation dans laquelle l' URL e contient un secret ou un fragment masqué :

• Si l' URL e correspond à une entrée dans queryTrackedDomainList, l' URL e complet, avec le secret ou le fragment masqué, est envoyé au backend Instana.
• Si l' URL e ne correspond à aucune entrée du queryTrackedDomainList, tous les paramètres sont exclus avant l'envoi de l' URL e au backend Instana.

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 une demande et dans sa réponse, seule la valeur d'en-tête de la réponse est conservée.

Instana {
    val captureHeaders = mutableListOf<Regex>()
}
 

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. Ce renvoi ne fonctionne pas bien avec certains réseaux cellulaires. En activant la fonctionnalité « 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 balise consiste en une seule balise au lieu d'un lot (un maximum de 100 balises dans un lot). 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 000 et 3 600 000 millisecondes.

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é.

Pour capturer automatiquement les noms d'écran des interfaces utilisateur composables, vous pouvez ajouter la fonction d'extension addInstanaObserver() à l'objet NavHostController dans votre application composable. Cette fonction collecte les noms du chemin d'accès spécifié pour la navigation composable.