iOS API
L' Instana iOS API est un ensemble de fonctions permettant d'instrumenter du code personnalisé dans vos applications iOS afin de collecter des données et de les envoyer au backend Instana.
iOS versions de l'agent
Pour consulter l'historique détaillé des versions et les mises à jour spécifiques à chaque version de l'agent « iOS », consultez le fichier «Changelog» sur GitHub.
API de l'agent Instana iOS
Vous pouvez lancer l'agent Instana iOS à l'aide des méthodes Instana de classe.
Configuration de l'agent « Instana » iOS
Initialisez l'agent Instana iOS dès le début didFinishLaunchingWithOptions en appelant la fonction de configuration. Ne retardez pas le lancement d' Instana. Veillez à lancer la configuration dès que l'application s'ouvre. Vous pouvez activer ou désactiver le délai de l' Instana e à l'aide du Instana.collectionEnabled drapeau.
static func setup(key: String, reportingURL: URL)
Paramètres de configuration
Le tableau suivant présente les paramètres de configuration :
| Paramètre | Description |
|---|---|
key ( String ) |
Clé de configuration de la surveillance Instana. |
reportingURL ( URL ) |
L' URL, qui pointe vers l'instance Instana à laquelle les données de surveillance sont envoyées. |
httpCaptureConfig ( HTTPCaptureConfig , facultatif) |
Par défaut, les requêtes et les réponses d' HTTP s sont automatiquement enregistrées. Pour désactiver la surveillance automatique, définissez ce paramètre sur manual ou utilisez les deux modes conjointement avec la configuration de capture automaticAndManual de la commande « HTTP ». Pour désactiver la surveillance des sessions d' HTTP, vous pouvez passer none. |
collectionEnabled ( Bool , facultatif) |
Par défaut, la collecte de données est activée avec la configuration. Pour configurer l' Instana, mais ignorer toute collecte de données, définissez ce paramètre sur false dans la configuration. Ce paramètre est utile pour les scénarios dans lesquels l'accord de l'utilisateur est requis pour que l'agent puisse collecter des données. La valeur par défaut est true. |
enableCrashReporting ( Bool , facultatif) |
Par défaut, la fonction de signalement des plantages est désactivée dans la configuration. La fonctionnalité de signalement des plantages peut être activée ultérieurement à l'aide de cette propriété, ce qui permet aux applications de commencer à collecter des données sur les plantages d' Instana. Cette propriété est particulièrement utile pour les scénarios dans lesquels l'accord explicite de l'utilisateur est requis pour que l'agent puisse collecter des données de panne. La valeur par défaut est false. |
slowSendInterval ( Double , facultatif) |
Cette fonction est obsolète. Ce paramètre active le mode d'envoi lent en cas d'échec de l'envoi de la balise; pour ce faire, il faut saisir un nombre entier positif en secondes (compris entre 2 et 3 600). La valeur par défaut est |
usiRefreshTimeIntervalInHrs ( Double , facultatif) |
Ce paramètre définit la fréquence usi de rafraîchissement de la userSessionIdentifier. Vous devez fournir la valeur en heures. La valeur par défaut est « -1.0 », ce qui signifie que l'identifiant de session de l'utilisateur n'est jamais actualisé. Les valeurs de paramètre suivantes indiquent l'état du usi: - Nombre négatif : cette valeur indique que le usi conserve son comportement par défaut et ne s'actualise jamais. - Nombre positif : cette valeur indique que le usi s'actualise aux intervalles de temps spécifiés. - Zéro : cette valeur indique que le usi n'est pas envoyé au backend Instana et que l'identifiant est donc désactivé. |
autoCaptureScreenNames ( Bool , facultatif) |
(version préliminaire publique) Ce paramètre permet la saisie automatique des noms d'écran lorsqu'il est défini sur true. Les contrôleurs de vue dont UIViewController la classe est la superclasse, que ce soit directement ou indirectement, peuvent être capturés automatiquement. Dans UIKit, les contrôleurs de vue dont le accessibilityLabel paramètre ou navigationItem.title est défini sont automatiquement capturés. Le nom de la vue est défini comme suit : ( accessibilityLabel ou navigationItem.title) @( ViewControllerClassName ). Si aucun des deux n'est défini, le nom de la vue est @( ViewControllerClassName ). Pour l' SwiftUI,, la vue avec navigationTitle le paramètre est automatiquement enregistrée; dans le cas contraire, elle est ignorée. La valeur par défaut est false. |
debugAllScreenNames ( Bool , facultatif) |
(aperçu public) Ce paramètre débogue autoCaptureScreenNames. Lorsque debugAllScreenNames est défini sur true et que autoCaptureScreenNames est également défini sur true, tous les contrôleurs de vue sont capturés. Lorsque autoCaptureScreenNames est défini sur false, debugAllScreenNames est ignoré. Le debugAllScreenNames paramètre doit être défini sur false dans l'environnement de production. La valeur par défaut est false. |
queryTrackedDomainList ( regex , facultatif) |
Par défaut, l'agent « iOS » collecte l' URL complète, qui comprend tous ses paramètres. Grâce à cette configuration, vous pouvez paramétrer 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. En fonction de la liste d'expressions régulières fournie, l'agent iOS effectue le suivi des URL comme suit : - Si l' URL correspond à une entrée de la liste, l' URL e complète, y compris tous les paramètres, est collectée. - Si l' URL e ne correspond à aucune entrée de la liste, les paramètres de requête et les fragments de l' URL e ne sont pas envoyés au backend Instana. - Si la liste fournie est vide, le comportement par défaut s'applique et l' URL e complète, avec ses paramètres, est suivie. |
rateLimits ( RateLimits , facultatif) |
Ce paramètre vous permet de personnaliser les limites relatives au nombre de balises pouvant être envoyées au cours d'un intervalle de temps donné. Trois options sont disponibles : DEFAULT_LIMITS, MID_LIMITS et MAX_LIMITS. Par défaut, l'option DEFAULT_LIMITS est sélectionnée. 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 |
dropBeaconReporting ( Bool , facultatif) |
Ce paramètre active la signalisation des balises perdues. Lorsque le nombre de balises atteint les limites de débit, les nouvelles balises sont ignorées au lieu d'être envoyées au serveur Instana. Si ce paramètre est défini sur true, les balises perdues sont suivies en interne et le rapport sur les balises est envoyé au backend Instana lorsque le nombre de balises ne dépasse plus la limite de débit. La valeur par défaut est false. |
trustDeviceTiming ( Boolean , facultatif) |
Lorsque cette option est activée, chaque balise contient un indicateur qui demande au serveur Instana de considérer comme fiable l'horodatage de création de la balise. Par défaut, si une balise est reçue plus de 30 minutes après sa création, le serveur remplace l'heure de création par l'heure de réception. La valeur par défaut de ce paramètre est « false ». |
enableW3CHeaders ( Boolean , facultatif) |
Lorsque cette option est activée, l'agent d' iOS inclut les traceparent en-têtes tracestate et dans les appels vers API faisant l'objet d'une surveillance. 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 est possible lorsque l'agent d' Instana s surveille également le backend. Par défaut, le paramètre a la valeur false. |
perfConfig ( InstanaPerformanceConfig , facultatif) |
Ce paramètre permet de configurer la surveillance des performances de l'application. Pour les paramètres de configuration des performances, voir le tableau 2. |
timeoutInterval (Double, facultatif) |
Ce paramètre définit le délai d'expiration pour l'appel réseau de vidage des balises. La valeur par défaut est « 120.0 », ce qui correspond à 2 minutes. La valeur minimale de ce paramètre est 60.0. |
Paramètres de configuration des performances
Le tableau suivant présente les paramètres de configuration liés aux performances
| Paramètre | Description |
|---|---|
enableAppStartTimeReport ( Bool , facultatif) |
Ce paramètre permet de générer des rapports sur les heures de démarrage des applications, telles que l'heure du démarrage à froid et l'heure du démarrage à chaud. * Temps de démarrage à froid : Temps nécessaire au démarrage d’une iOS app lorsqu’elle est lancée à partir de zéro, et non en arrière-plan. La mesure commence après l'initialisation de la bibliothèque dynamique et se termine lorsque l'interface utilisateur de l'application devient interactive. * Temps de démarrage à chaud : temps nécessaire pour lancer l'application qui n'a pas été complètement fermée et qui s'exécute en arrière-plan. Les temps de démarrage se mesurent en millisecondes. La valeur par défaut est true. |
enableAnrReport ( Bool , facultatif) |
Ce paramètre permet de signaler les cas où l'application ne répond pas (application not respond). La valeur par défaut est false. |
anrThreshold ( Double , facultatif) |
Ce paramètre définit le délai, en secondes, au terme duquel l'application est considérée comme ne répondant plus (application not respond). Ce paramètre ne s'applique que si enableAnrReport est défini sur true. La valeur par défaut est 3.0. |
enableLowMemoryReport ( Bool , facultatif) |
Ce paramètre active l'affichage des notifications en cas de mémoire insuffisante. La valeur par défaut est false. |
Exemple
import InstanaAgent
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
Instana.setup(key: "<Your Instana Key>", reportingURL: URL(string: "<Your Instana URL>")!)
....
return true
}
L'exemple suivant illustre la configuration manuelle de la capture d' HTTP s. Pour modifier les paramètres par défaut, exécutez les commandes suivantes:
let options = InstanaSetupOptions(httpCaptureConfig: .manual)
Instana.setup(key: <Your Key>, reportingURL: <Your Instana URL>, options: options)
Configuration actuelle
L'objet de classe Instana contient les propriétés suivantes pour extraire la configuration en cours:
| Propriété | Description |
|---|---|
key (String, facultatif) |
Clé de configuration de la surveillance Instana. |
reportingURL (URL, facultatif) |
L' URL, qui pointe vers l'instance Instana à laquelle les données de surveillance sont envoyées. |
Exemple
let key = Instana.key
let url = Instana.reportingURL
Identificateur de session
Chaque instance de l'agent « Instana » dispose d'un identifiant de session unique que vous pouvez utiliser à d'autres fins dans votre application.
| Propriété | Description |
|---|---|
sessionID (String, facultatif) |
Identificateur de la session en cours. Cet ID session est créé lors du processus de configuration. |
Exemple
let sessionID = Instana.sessionID
Surveillance HTTP automatique
Par défaut, les sessions d' HTTP s sont enregistrées automatiquement. L'agent Instana iOS utilise le protocole NSURLProtocol de la Fondation pour surveiller les demandes et les réponses. Pour observer tous les NSURLSession automatiquement avec NSURLProtocol, il est nécessaire de procéder à des permuter certaines méthodes dans NSURLSession . Pour désactiver la surveillance automatique des sessions d' HTTP, vous devez enregistrer manuellement chaque requête et chaque réponse.
Surveillance HTTP manuelle
Pour enregistrer manuellement des sessions d' HTTP, vous devez configurer Instana à l'aide de httpCaptureConfig: .manual et utiliser les fonctions correspondantes. Vous pouvez capturer manuellement les requêtes et les réponses d' HTTP en utilisant URLRequest ou URL.
Surveillance HTTP automatique et manuelle
Pour enregistrer automatiquement ou manuellement les sessions d' HTTP, vous devez configurer Instana à l'aide du httpCaptureConfig: .automaticAndManual. Vous pouvez utiliser l'instrumentation automatique ou capturer manuellement les requêtes et les réponses d' HTTP.
Démarrage de la capture (URLRequest)
La fonction permettant de lancer la capture d' HTTP s pour URLRequest et le nom de la vue (facultatif). Un objet HTTPMarker est renvoyé. Cet objet est nécessaire pour définir les résultats de la réponse de l' HTTP.
static func startCapture(_ request: URLRequest?, viewName: String? = nil) -> HTTPMarker
Paramètres de configuration
Le tableau suivant présente les paramètres de configuration :
| Paramètre | Description |
|---|---|
request (URLRequest) |
URLRequest pour la capture |
viewName (String, facultatif) |
Nom de la vue visible associée à cette demande. |
Renvoie : un objet de type « HTTP » contenant les résultats de la réponse à la requête HTTP (code d'état HTTP, tailles, erreur).
Démarrage de la capture (URL)
Cette fonction lance la capture d' HTTP s pour la méthode URL, HTTP, ainsi que le nom de la vue (facultatif). Un objet HTTPMarker est renvoyé. Vous aurez besoin de cet objet ultérieurement pour définir les résultats de la réponse de l' HTTP.
static func startCapture(url: URL, method: String, viewName: String? = nil) -> HTTPMarker
Paramètres de configuration
Le tableau suivant présente les paramètres de configuration :
| Paramètre | Description |
|---|---|
url (URL) |
L' URL e à capturer |
method (String) |
La méthode « HTTP » de la requête |
viewName (String, facultatif) |
Nom de la vue visible associée à cette demande |
Renvoie : un objet de type « HTTP » contenant les résultats de la réponse à la requête HTTP (code d'état HTTP, tailles, erreur).
Définition de la taille de la réponse HTTP
Appelez cette méthode sur HTTPMarker lorsque la taille de la réponse est déterminée.
func set(responseSize: Instana.Types.HTTPSize)
Paramètres de configuration
Le tableau suivant présente les paramètres de configuration :
| Paramètre | Description |
|---|---|
responseSize (HTTPSize) |
L'objet httpSize qui contient headerBytes, bodyByteset bodyBytesAfterDecoding. |
HTTPMarker après avoir appelé finish ou cancel.Taille de la réponse HTTP
Vous pouvez créer HTTPMarker.Size avec l'initialiseur suivant:
init(response: URLResponse, transactionMetrics: [URLSessionTaskTransactionMetrics]?)
Paramètres de configuration
Le tableau suivant présente les paramètres de configuration :
| Paramètre | Description |
|---|---|
response (URLResponse) |
L'objet URLResponse |
transactionMetrics ([URLSessionTaskTransactionMetrics], facultatif) |
Tableau facultatif avec URLSessionTaskTransactionMetrics |
Vous pouvez également créer l'objet HTTPMarker.Size en transmettant la valeur de taille directement en tant que paramètre:
HTTPMarker.Size(header: Instana.Types.Bytes, body: Instana.Types.Bytes, bodyAfterDecoding: Instana.Types.Bytes)
Fin de la capture (URLResponse)
Appelez finish on HTTPMarker une fois la demande terminée avec URLResponse et un Errorfacultatif.
func finish(response: URLResponse?, error: Error?)
Fin de la capture (HTTPCaptureResult)
Vous pouvez également nous HTTPCaptureResult pour terminer la capture.
let size = HTTPMarker.Size(header: 123, body: 1024, bodyAfterDecoding: 2048)
let result = HTTPCaptureResult(statusCode: statusCode, backendTracingID: "Instana-backend-tracing-id", responseSize: size, error: error)
marker.finish(result: result)
Annulation de la capture
Appelez cette méthode sur HTTPMarker si la demande est annulée avant l'achèvement. L'état est défini sur "Echec en interne" avec le statut NSURLErrorCancelled lorsque vous appelez cancel.
func cancel()
Exemple de fin surveillance HTTP manuelle (URLResponse)
let marker = Instana.startCapture(request, viewName: "User: Details")
URLSession.shared.dataTask(with: request) { data, response, error in
marker.finish(response: response, error: error)
}.resume()
Vous pouvez également définir manuellement la taille de la réponse de l' HTTP, URLSessionDelegate comme indiqué dans l'exemple suivant (avant d'appeler finish ou cancel) :
func urlSession(_ session: URLSession, task: URLSessionTask, didFinishCollecting metrics: URLSessionTaskMetrics) {
guard let response = task.response else { return }
marker.set(responseSize: HTTPMarker.Size(response: response, transactionMetrics: metrics.transactionMetrics))
}
Exemple de fin de surveillance HTTP manuelle (URL)
let url = URL(string: "https://www.example.com/user/123/details")!
let marker = Instana.startCapture(url: url, method: "GET", viewName: "Home")
YourNetworkManager(url: url, method: "GET") { (statusCode, error) in
let size = HTTPMarker.Size(header: 123, body: 1024, bodyAfterDecoding: 2048) // optionally
let backendTracingID = "Instana-backend-tracing-id" // optionally
let result = HTTPCaptureResult(statusCode: statusCode, backendTracingID: backendTracingID, responseSize: size, error: error)
marker.finish(result: result)
}.resume()
Vues
Instana peut segmenter les métriques d'application par vues logiques. Pour ce faire, vous devez ajouter un conseil sur la vue que l'utilisateur est en train de consulter. Ce nom de vue peut être défini à l'aide desetView(name: String). Le nom de la vue est associé à toutes les balises surveillées jusqu'à ce que vous appeliez à nouveau setView avec un autre nom. N'utilisez pas de noms techniques ou génériques tels que la classe (c'est-à-dire WebViewController) pour définir des vues. Utilisez des noms lisibles pour les vues. Par exemple, product detail page ou payment selection. Il en résulte moins de pages avec une relation directe avec le code existant. Envisagez de définir le nom de la vue dans viewDidAppear. La définition d'un nom de vue permet à Instana de suivre les transitions entre les pages, en plus des chargements de pages.
Le nom de la vue est mis à jour automatiquement lorsque votre application change d'état (par exemple, d'actif à inactif ou en arrière-plan). Le nom de la vue est Inactive lorsque votre application est inactive (lorsqu'elle reçoit un SMS). Elle est définie sur Background une fois que votre application a quitté l'avant-plan.
static func setView(name: String)
Paramètres de configuration
Le tableau suivant présente les paramètres de configuration :
| Paramètre | Description |
|---|---|
name (String) |
Nom de la vue |
Exemple
override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
Instana.setView(name: "User: Details")
}
Pour obtenir le nom de la vue en cours, vous pouvez utiliser la variable de classe viewName. La valeur du nom de vue peut être Inactive ou Background en fonction de l'état de l'application.
| Propriété | Description |
|---|---|
viewName (String, facultatif) |
Le nom de la vue en cours est défini via setView(name:). |
Exemple
let viewName = Instana.viewName
Identification des utilisateurs
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é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
- Identifier l'utilisateur à l'origine d'une modification de vue ou d'une demande d' HTTP
Par défaut, Instana n'associe aucune information permettant d'identifier l'utilisateur aux balises. Vous devez vérifier les lois de protection des données respectives avant d'associer des informations identifiant l'utilisateur à des balises. Identifiez les utilisateurs avec un ID utilisateur. Dans le cas d' Instana s, il s'agit d'un élément String transparent utilisé uniquement pour calculer certains indicateurs. Vous pouvez également utiliser userName et userEmail pour accéder à d'autres filtres afin de présenter 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 pour filtrer les données, mais ils sont de bons indicateurs pour calculer les métriques d'utilisateur affectées ou uniques. Envisagez de définir un nom d'utilisateur tel que Anonymous pour distinguer clairement les utilisateurs authentifiés des 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.
Les données déjà transmises à Instana ne peuvent pas être mises à jour rétroactivement. Appelez cette fonction ` API ` immédiatement lors du lancement de l'application.
static func setUser(id: String, email: String?, name: String?)
Paramètres de configuration
Le tableau suivant présente les paramètres de configuration :
| Paramètre | Description |
|---|---|
id (String) |
Identificateur de l'utilisateur |
email (String, facultatif) |
Adresse de courrier électronique de l'utilisateur |
name (String, facultatif) |
Nom de l'utilisateur |
Vous pouvez transmettre nil pour les valeurs que vous ne souhaitez pas définir.
Exemple
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
Instana.setup(key: InstanaKey, reportingURL: InstanaURL)
Instana.setUser(id: someID, email: "email@example.com", name: "John")
return true
}
Vous pouvez également définir les propriétés de l'utilisateur individuellement.
ID utilisateur
Définissez l'ID utilisateur:
static func setUser(id: String)
Paramètres de configuration
Le tableau suivant présente les paramètres de configuration :
| Paramètre | Description |
|---|---|
id (String) |
Identificateur de l'utilisateur |
Adresse électronique de l'utilisateur
Définissez l'adresse électronique de l'utilisateur:
static func setUser(email: String)
Paramètres de configuration
Le tableau suivant présente les paramètres de configuration :
| Paramètre | Description |
|---|---|
email (String) |
Adresse de courrier électronique de l'utilisateur |
Nom d'utilisateur
Définissez le nom d'utilisateur:
static func setUser(name: String)
Paramètres
Le tableau suivant présente les paramètres :
| Paramètre | Description |
|---|---|
name (String) |
Nom de l'utilisateur |
Métadonnées
Les informations de métadonnées sont jointes aux données transmises. Envisagez d'utiliser des métadonnées pour suivre les valeurs de configuration de l'interface utilisateur, les paramètres, l'indicateur de fonction ou tout contexte supplémentaire pouvant être utile pour l'analyse. Veillez à définir les métadonnées lors du lancement de l'application afin d'attribuer la clé ou les valeurs à toutes les données transmises.
static func setMeta(value: String, key: String)
Paramètres
Le tableau suivant présente les paramètres :
| Paramètre | Description |
|---|---|
value (String) |
Le value de la paire clé-valeur que vous souhaitez ajouter en tant que métadonnées |
key (String) |
Le key de la paire clé-valeur que vous souhaitez ajouter en tant que métadonnées |
Exemple
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
Instana.setup(key: InstanaKey, reportingURL: InstanaURL)
Instana.setMeta(value: "ReactNative", key: "Platform")
Instana.setMeta(value: "DEBUG", key: "Environment")
return true
}
Exclusion de URLSession de la surveillance
Vous pouvez exclure un élément personnalisé URLSession de la surveillance effectuée par l'agent Instana iOS.
static func ignore(_ session: URLSession)
Paramètres de configuration
Le tableau suivant présente les paramètres de configuration :
| Paramètre | Description |
|---|---|
session (URLSession) |
URLSession à exclure de la surveillance |
Exemple
let session = URLSession(configuration: .default)
Instana.ignore(session)
Exclusion d'URL de la surveillance
Vous pouvez exclure les URL qui correspondent aux expressions régulières afin d'empêcher leur transmission à Instana. Un bon exemple d'utilisation de cette fonction serait d'exclure toutes les requêtes HTTP contenant des données sensibles, comme un mot de passe.
static func setIgnoreURLs(matching regex: [NSRegularExpression])
Paramètres de configuration
Le tableau suivant présente les paramètres de configuration :
| Paramètre | Description |
|---|---|
regex ([NSRegularExpression]) |
Un tableau d'objets NSRegularExpression correspondant aux URL que vous souhaitez ignorer |
Exemple
let regex = try! NSRegularExpression(pattern: "/.*(&|\?)password=.*/i")
Instana.setIgnoreURLs(matching: [regex])
Dans cet exemple, toutes les URL contenant un mot de passe dans la requête sont ignorées.
Vous pouvez également ignorer les URL complètes similaires à l'exemple suivant:
Instana.setIgnore(urls: [URL(string: "https://www.example.com")!])
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. Il peut être particulièrement utile d'analyser les erreurs qui ne sont pas détectées (éléments de navigation) et d'effectuer le suivi d'un plus grand nombre d'attributs de performance.
static func reportEvent(name: String, timestamp: Instana.Types.Milliseconds? = nil, duration: Instana.Types.Milliseconds? = nil, backendTracingID: String? = nil, error: Error? = nil, meta: [String: String]? = nil, viewName: String? = Instana.viewName)
Paramètres de configuration
Le tableau suivant présente les paramètres de configuration :
| Paramètre | Description |
|---|---|
name (String) |
Définit le type d'événements qui se sont produits dans votre application et qui se traduit par la transmission d'une balise personnalisée. |
timestamp (Int64, facultatif) |
Horodatage en millisecondes du démarrage de l'événement. Si vous ne fournissez pas d'horodatage, l'heure en cours est utilisée comme horodatage. Si vous ne fournissez pas d'horodatage mais que vous définissez une durée, l'horodatage est calculé en soustrayant la durée de l'heure en cours. (horodatage = durée-heure en cours) |
duration (Int64, facultatif) |
Durée de l'évènement, exprimée en millisecondes. La valeur par défaut est zéro. |
backendTracingID (String, facultatif) |
Identificateur permettant de créer une trace back-end pour l'évènement. |
error (Error, facultatif) |
Objet d'erreur pour fournir plus de contexte. |
meta ([String: String], facultatif) |
Données de type « clé-valeur », qui peuvent être utilisées pour envoyer des métadonnées à Instana uniquement pour cet événement particulier. |
viewName (String, facultatif) |
Vous pouvez transmettre une chaîne pour regrouper la demande dans une vue. Si l'envoi est nul, viewName est ignoré. Vous pouvez également ne pas indiquer le paramètre viewName pour utiliser le nom de vue en cours que vous avez défini dans setView(name: String). |
customMetric (Double, facultatif) |
Données de métrique personnalisées avec une précision jusqu'à 4 décimales. La valeur par défaut sert Double.nan à indiquer que ` customMetric ` n'est pas défini par l'appelant. N'incluez pas d'informations sensibles dans cette mesure. |
Exemples
Instana.reportEvent(name: "Event-Name")
Instana.reportEvent(name: "Event-Name", viewName: "User: Details")
Instana.reportEvent(name: "Event-Name", timestamp: 1590149955086, duration: 124842, backendTracingID: "some-id", error: NSError(domain: "Some", code: -1, userInfo: nil), meta: ["Key": "Value"], viewName: "User: Details")
Instana.reportEvent(name: "Event-Name", customMetric: 1234.567)
Activer ou désactiver la collecte
Vous pouvez activer la collecte de données à tout moment pendant l'exécution. Il active le démarrage différé de la collecte de données (par exemple, après le consentement de l'utilisateur).
| Propriété | Description |
|---|---|
collectionEnabled (Bool) |
Indicateur d'activation ou de désactivation de la collecte de données |
Exemple
Instana.collectionEnabled = true
Activer la journalisation
L'agent iOS Instana dispose d'une fonction de consignation à des fins de débogage. Ajoutez la variable d'environnement INSTANA_DEBUG_LOGLEVEL dans Xcode. En tant que valeur, vous devez transmettre l'une des valeurs suivantes comme niveau de journalisation:
- 0 = Informations de débogage, avertissements et erreurs
- 1 = Avertissements et erreurs
- 2 = > Erreurs uniquement
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 iOS 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 occultée est remplacée par <redacted>. La suppression des données confidentielles est effectuée au sein de l'agent Instana avant que les données ne soient transmises à Instana. Par conséquent, les données confidentielles ne sont pas transmises à Instana pour y être traitées. Les secrets ne peuvent pas être analysés dans l'interface utilisateur ni récupérés à l'aide de Instana API.
Par défaut, l'agent Instana iOS 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 ». L'occultation est appliquée uniquement aux demandes surveillées automatiquement et à leurs journaux associés. Les demandes surveillées manuellement ne sont pas expurgées.
static func redactHTTPQuery(matching regex: [NSRegularExpression])
Paramètres de configuration
Le tableau suivant présente les paramètres de configuration :
| Paramètre | Description |
|---|---|
regex ([NSRegularExpression]) |
Un tableau d'objets NSRegularExpression correspondant aux clés des valeurs que vous souhaitez occulter. |
Exemple
let regex = try! NSRegularExpression(pattern: #"pass(word|wort)"#)
Instana.redactHTTPQuery(matching: [regex])
Dans cet exemple, les valeurs des clés « password » ou « passwort » du paramètre « HTTP » ont été masquées. L' URL ion https://example.com/accounts/?password=123&passwort=459 capturée est collectée et affichée sous la forme https://example.com/accounts/?password=<redacted>&passwort=<redacted>.
/account/<account id>/status) ou des paramètres matriciels (/account;accountId=<account id>/status) en tant que secrets.Capturer les champs d'en-tête d' HTTP
HTTP Les en-têtes de requête et de réponse peuvent être capturés par l'agent iOS. Vous pouvez utiliser des expressions régulières pour définir les clés des champs d'en-tête « HTTP » que l'agent iOS doit capturer.
public static func setCaptureHeaders(matching regex: [NSRegularExpression])
Paramètres de configuration
Le tableau suivant présente les paramètres de configuration :
| Paramètre | Description |
|---|---|
regex ([NSRegularExpression]) |
Un tableau contenant les NSRegularExpression objets correspondant aux clés des en-têtes de requête et de réponse HTTP s que vous souhaitez capturer. |
Exemple
let regex = try! NSRegularExpression(pattern: #"X-Key"#, options: [.caseInsensitive])
Instana.setCaptureHeaders(matching: [regex])
Cet exemple présente les champs d'en-tête « HTTP » avec la clé X-Key ou X-KEY.
Mode d'envoi lent (obsolète depuis la version 1.10.0 )
Facultatif: vous pouvez activer la fonction de mode d'envoi lent.
Par défaut, si l'envoi d'une balise échoue, l'agent Instana tente de la renvoyer jusqu'à ce que l'envoi aboutisse. Cela 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 slowSendInterval paramètre. Chaque tentative d'envoi se compose d'une seule balise au lieu d'un lot (un maximum de 100 balises dans un lot). Instana L'agent reste en mode d'envoi lent jusqu'à ce qu'une balise ait été envoyée avec succès.
La plage de valeurs valides pour slowSendInterval est comprise entre 2 et 3 600 secondes.
Exemple
import InstanaAgent
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
let options = InstanaSetupOptions(slowSendInterval: 60.0)
if !Instana.setup(key: InstanaKey, reportingURL: InstanaURL, options: options) {
// Error handling here
}
....
return true
}
Identifiant de session utilisateur
Par défaut, la session utilisateur est suivie. 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 : par défaut, l'identifiant de session de l'utilisateur est configuré pour ne jamais expirer. La valeur par défaut de ce paramètre est « -1 ».
- Nombre positif: 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: l'ID de session utilisateur est désactivé. Cette valeur est indiquée par 0.0.
Exemple
import InstanaAgent
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
let options = InstanaSetupOptions(usiRefreshTimeIntervalInHrs: 24.0)
if !Instana.setup(key: InstanaKey, reportingURL: InstanaURL, options: options) {
// Error handling here
}
....
return true
}
Fichier de déclaration de confidentialité
Le fichier manifeste de confidentialité est pris en charge depuis iOSAgent version 1.8.0. Aucune configuration supplémentaire n'est nécessaire pour utiliser cette fonction si l'application est conforme aux exigences d'Apple.