L’instrumentation dynamique vous permet d’instrumenter vos systèmes de production en cours d’exécution sans aucun redémarrage et n’importe où dans le code de votre application, y compris les bibliothèques tierces. Vous pouvez ajouter ou modifier des données de télémétrie pour vos logs, métriques et spans, ainsi que les tags correspondants, depuis l’interface utilisateur de Datadog. L’instrumentation dynamique sollicite peu de ressources et n’a aucun effet secondaire sur votre système.
L’autorisation Dynamic Instrumentation Read Configuration (debugger_read) est requise pour accéder à la page Dynamic Instrumentation.
L’autorisation Dynamic Instrumentation Write Configuration (debugger_write) est requise pour créer ou modifier des instrumentations.
L’autorisation Dynamic Instrumentation Capture Variables (debugger_capture_variables) est requise pour utiliser l’option Capture method parameters and local variables.
Pour en savoir plus sur les rôles et découvrir comment les attribuer aux utilisateurs, consultez la section Contrôle d’accès à base de rôles.
Créer un index de logs
L’instrumentation dynamique crée des « logs dynamiques » qui sont envoyés à Datadog et affichés dans la même interface que vos logs d’application standard.
Si vous utilisez des filtres d’exclusion, assurez-vous que les logs de l’instrumentation dynamique ne sont pas filtrés :
Créez un index de logs et configurez-le selon la rétention souhaitée et sans aucun échantillonnage.
Définissez le filtre sur le tag source:dd_debugger. Tous les logs de l’instrumentation dynamique utilisent cette source.
Assurez-vous que le nouvel index a la priorité sur les autres index basés sur ce tag, car la première correspondance l’emporte.
Pour obtenir des instructions plus détaillées, sélectionnez votre runtime ci-dessous :
Limites
Lʼinstrumentation dynamique n’est pas encore compatible avec Azure App Services ni les environnements sans serveur.
Seules les applications créées avec Python, Java, et .NET sont prises en charge.
Explorer l’instrumentation dynamique
L’instrumentation dynamique peut vous aider à comprendre ce que fait votre application lors de son exécution. En ajoutant une sonde d’instrumentation dynamique, vous pouvez exporter des données supplémentaires de votre application sans modification du code ni redéploiement.
Utiliser des sondes
Une sonde vous permet de recueillir des données depuis des points spécifiques de votre code sans interrompre l’exécution du programme.
Grâce aux sondes, vous pouvez accroître vos capacités d’observabilité en ajoutant des logs, des métriques et des spans dynamiques à une application en cours d’exécution sans modification du code, déploiement, ni redémarrage d’un service. Vous pouvez ainsi collecter immédiatement des données sans perturber l’expérience des utilisateurs ni effectuer de longs déploiements.
D’un point de vue développement, une sonde peut également être vue comme un point d’arrêt « non interruptif ». En debugging conventionnel, un point d’arrêt est un point du programme où l’exécution s’arrête, ce qui permet au développeur d’examiner l’état du programme en ce point. Toutefois, dans les environnements de production physiques, il n’est pas pratique ni même possible d’arrêter l’exécution du programme. Les sondes comblent cette lacune en vous permettant d’examiner l’état des variables dans les environnements de production de façon non intrusive.
Créer une sonde
La configuration initiale est la même pour tous les types de sondes :
Cliquez sur Create Probe en haut à droite, ou affichez le menu contextuel d’un service en cliquant sur les trois points et sélectionnez Add a probe for this service.
Si ces informations ne sont pas déjà renseignées, choisissez le service, le runtime, l’environnement et la version.
Dans le code source, indiquez où vous souhaitez définir la sonde en sélectionnant soit une classe et une méthode, soit un fichier source et une ligne. Si vous avez configuré l’intégration du code source pour votre service, la saisie automatique vous propose des fichiers à sélectionner et affiche le code associé afin de vous permettre de choisir la ligne.
Vous trouverez ci-dessous les instructions de création propres à chaque type de sonde.
Vous pouvez également créer une sonde depuis les autres contextes suivants :
Profiling
Dans le flamegraph d’un profileur, vous pouvez créer une sonde pour une méthode en sélectionnant Instrument this frame with a probe dans le menu contextuel d’un frame.
Suivi des erreurs
Dans une stack trace, placez le pointeur de la souris sur un stack frame et cliquez sur Instrument. Les données du contexte du problème sont alors renseignées automatiquement dans le formulaire de création de la sonde.
Créer des sondes log
Une sonde log génère un log lorsqu’elle s’exécute.
Définissez un modèle de message de log. Vous pouvez utiliser le langage d’expression de l’instrumentation dynamique pour faire référence à des valeurs à partir du contexte d’exécution.
Si vous le souhaitez, activez l’enregistrement de données supplémentaires par la sonde. (Bêta)
Si vous le souhaitez, définissez une condition à l’aide du langage d’expression de l’instrumentation dynamique. Le log est généré lorsque l’expression renvoie la valeur true.
Par défaut, les sondes log sont activées sur toutes les instances du service correspondant à l’environnement et à la version spécifiés. Elles sont limitées à 5 000 exécutions par seconde sur chaque instance de votre service.
Vous devez définir un modèle de message de log pour chaque sonde log. Les modèles prennent en charge l’intégration d’expressions entre accolades. Par exemple : L'utilisateur {user.id} a acheté {count(products)} produits.
Vous pouvez également définir une condition pour une sonde log à l’aide du langage d’expression. L’expression doit renvoyer une valeur booléenne. La sonde s’exécute si l’expression renvoie la valeur true, et n’enregistre ou ne génère aucune donnée si l’expression renvoie la valeur false.
Bêta : si vous activez l’option Capture method parameters and local variables pour la sonde log, l’ensemble du contexte d’exécution est ajouté à l’événement de log :
Les arguments de méthode, les variables locales et les champs, avec les limites par défaut suivantes :
Suivi des références sur trois niveaux (configurable dans l’interface utilisateur).
Les 100 premiers éléments pour les collections.
Les 255 premiers caractères pour les valeurs des chaînes.
20 champs à l’intérieur des objets. Les champs statiques ne sont pas recueillis.
Stack trace de l’appel.
Exceptions interceptées et non interceptées.
Les sondes pour lesquelles ce paramètre est activé sont limitées à une exécution par seconde.
Avertissement : les données enregistrées peuvent contenir des informations sensibles, notamment des données personnelles, des mots de passe et des secrets, comme des clés AWS.
Pour que ces informations soient correctement censurées :
L'instrumentation dynamique de Datadog fait appel à plusieurs techniques pour censurer les informations sensibles. Pour en savoir plus sur les mécanismes par défaut ou pour découvrir comment les étendre pour répondre à vos besoins, consultez la section relative au nettoyage des données sensibles.
Désactivez l'option Capture method parameters and local variables et sélectionnez explicitement les variables à inclure dans le modèle de message de log. Cela permet de s'assurer que les sondes log ne contiennent que les données relatives aux variables spécifiquement identifiées, ce qui réduit le risque de fuite indésirable de données sensibles.
Si vous êtes l'administrateur de votre compte Datadog et souhaitez empêcher les autres utilisateurs d'utiliser l'option Capture method parameters and local variables, vous pouvez révoquer leur autorisation Dynamic Instrumentation Capture Variables (debugger_capture_variables).
Si vous devez enregistrer ces données, mais que vous souhaitez limiter le risque associé au fait qu'elles soient accessibles dans Datadog, vous pouvez limiter les utilisateurs de votre organisation autorisés à consulter les données enregistrées en définissant une requête de restriction sur source:dd_debugger.
Créer des sondes métrique
Une sonde métrique génère une métrique lorsqu’elle s’exécute.
Donnez un nom à la métrique, qui aura comme préfixe dynamic.instrumentation.metric.probe..
Sélectionnez le type de métrique (count, gauge ou histogram).
Choisissez la valeur de la métrique en utilisant le langage d’expression de l’instrumentation dynamique. Vous pouvez utiliser n’importe quelle valeur numérique issue du contexte d’exécution, comme un paramètre de méthode, une variable locale, un champ de classe ou une expression produisant une valeur numérique. Cette étape est facultative pour les métriques count, et si vous l’ignorez, chaque invocation incrémente le total de un.
Les sondes métrique sont automatiquement activées sur toutes les instances du service correspondant à l’environnement et à la version configurés. Leur fréquence d’exécution n’est pas limitée et elles s’exécutent à chaque invocation de la méthode ou de la ligne.
Les sondes métrique d’instrumentation dynamique prennent en charge les types de métriques suivants :
Count : compte le nombre d’exécutions d’une méthode ou d’une ligne donnée. Cette métrique peut être combinée à des expressions de métrique pour incrémenter le total à l’aide de la valeur d’une variable.
Gauge : génère une métrique gauge en fonction de la dernière valeur d’une variable. Cette métrique nécessite une expression de métrique.
Histogram : génère une distribution statistique d’une variable. Cette métrique nécessite une expression de métrique.
Créer des sondes span
Une sonde span génère une span lorsqu’une méthode est exécutée.
Une sonde tag de span ajoute une valeur de tag à une span existante. Vous pouvez ajouter un tag à la span active ou à la span d’entrée de service. Gardez à l’esprit que les spans internes ne sont pas indexées par défaut et qu’il est donc possible que vous ne puissiez pas les rechercher dans APM.
Si vous le souhaitez, définissez une condition à l’aide du langage d’expression de l’instrumentation dynamique. Le tag ne sera ajouté que si l’expression renvoie la valeur true.
Si vous le souhaitez, ajoutez d’autres tags en définissant pour chacun d’eux un nom, une expression et une condition facultative.
