View a markdown version of this page

Déboguer des applications avec une instrumentation dynamique - Amazon CloudWatch
ConceptsLangues prises en chargeConditions préalablesAjoutez une instrumentation dynamique à votre applicationStockage de donnéesAfficher et gérer les configurationsComprendre le statutLimites de capture

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Déboguer des applications avec une instrumentation dynamique

Avec Dynamic Instrumentation, vous pouvez capturer l'état d'exécution d'une application en ligne sans redémarrer ni redéployer. L'état d'exécution inclut les valeurs variables, les arguments de méthode, les valeurs de retour et les traces de pile. Vous définissez des configurations d'instrumentation qui spécifient l'endroit du code dans lequel les données doivent être capturées, et l'agent en cours d'exécution instrumente l'application au moment de l'exécution.

Concepts

Point d'arrêt

Instrumentation temporaire qui expire automatiquement. L'expiration par défaut est de 24 heures, configurable de 5 minutes à 24 heures. Utilisez des points d'arrêt pour le débogage et l'investigation.

Sonde

Instrumentation permanente qui persiste jusqu'à sa suppression explicite. Utilisez des sondes pour une observabilité continue.

Instantané

Capture instantanée de l'état du programme, y compris les variables locales, les arguments, la valeur de retour, les exceptions et la trace de pile. Dynamic Instrumentation émet des instantanés sous forme d'enregistrements de journal dans Logs. CloudWatch

Location

Emplacement du code où l'instrumentation est appliquée. Les champs obligatoires varient selon la langue.

Langues prises en charge

  • Java

  • Python

  • JavaScript ou TypeScript

Conditions préalables

Pour utiliser Dynamic Instrumentation, mettez à jour vos composants d'instrumentation vers la dernière version en fonction de votre type de déploiement :

  • Clients Amazon EKS : mettez à jour le module complémentaire Amazon CloudWatch Observability EKS vers la dernière version. Le module complémentaire inclut le SDK et CloudWatch l'agent ADOT. Pour plus d'informations, voir Installer le module complémentaire CloudWatch Observability EKS.

  • Tous les autres clients : mettez à jour les deux composants suivants :

    • Le SDK d'instrumentation AWS Distro for OpenTelemetry (ADOT) pour votre langage (Java, Python ou). Node.js

    • L' CloudWatch agent vers la dernière version.

Les conditions suivantes doivent également être remplies :

  • CloudWatch Les signaux d'application doivent être activés pour votre application.

  • Définissez la variable d'environnement OTEL_AWS_DYNAMIC_INSTRUMENTATION_ENABLED=true sur votre application.

  • Définissez la variable d'environnement OTEL_SERVICE_NAME sur le nom de votre service.

  • Définissez la variable d’environnement OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=my_deployment_env_name. Pour les utilisateurs existants d'Application Signals, la valeur doit correspondre au nom de l'environnement de votre service tel qu'il apparaît dans la console Application Signals.

  • L' CloudWatch agent doit être exécuté avec la configuration Application Signals.

  • L'instrumentation dynamique n'est pas prise en charge dans les environnements Lambda.

Ajoutez une instrumentation dynamique à votre application

Après avoir instrumenté votre application (voirConditions préalables), vous créez une configuration d'instrumentation qui indique dans quelle partie du code vous souhaitez introduire la télémétrie dynamique. Chaque configuration définit deux choses :

  1. Où dans le code à surveiller : emplacement du code où le point d'arrêt ou la sonde est appliqué.

  2. Quelles données capturer : état d'exécution capturé lors de l'exécution du point d'arrêt ou de la sonde.

Note

Par défaut, Dynamic Instrumentation ne capture que des données limitées. Pour optimiser la valeur de cette fonctionnalité, envisagez d'étendre la configuration de capture à l'aide des options décrites dansLimites de capture.

Vous pouvez créer des configurations à l'aide de la AWS CLI ou du SDK, ou à l'aide du serveur MCP (Model Context Protocol) avec un assistant de codage AI dans votre IDE.

Création de configurations à l'aide de la CLI ou du SDK

Utilisez la AWS CLI ou le AWS SDK pour créer des configurations d'instrumentation par programmation.

Spécifiez l'emplacement du code

L'emplacement définit l'endroit où l'instrumentation est appliquée dans votre code. Les champs obligatoires varient selon la langue :

Language Champs obligatoires Champs facultatifs
Java CodeUnit(paquet)ClassName,MethodName, FilePath LineNumber
Python CodeUnit(module)MethodName, FilePath LineNumber, ClassName
JavaScript ou TypeScript FilePath, LineNumber Aucune. Seuls les points d'arrêt au niveau de la ligne sont pris en charge. Les sondes et les points d'arrêt au niveau des fonctions ne sont pas pris en charge. TypeScript est pris en charge lorsque vous fournissez des cartes sources.

Configurer les données à capturer

La configuration de capture contrôle l'état d'exécution qui est collecté lorsque l'instrumentation se déclenche. Options disponibles :

  • CaptureArguments— Liste des noms d'arguments de méthode à capturer.

  • CaptureReturn— Capture la valeur de retour (booléen).

  • CaptureStackTrace— Capture la trace de la pile (booléen).

  • CaptureLocals— Liste des noms de variables locales à capturer.

  • CaptureLimits— Contrôlez la profondeur et la taille de capture (voirLimites de capture).

Paramètres de configuration

Paramètres clés lors de la création d'une configuration :

  • instrumentation-type— BREAKPOINT ou PROBE

  • service— Le nom du service tel qu'indiqué par Application Signals

  • environment— Le nom de l'environnement

  • signal-type — SNAPSHOT

  • location— Champs de localisation du code (voir ci-dessus)

  • capture-configuration— Options de capture (voir ci-dessus)

Exemple

L'exemple suivant crée un point d'arrêt sur une méthode Java :

aws application-signals create-instrumentation-configuration \
    --instrumentation-type BREAKPOINT \
    --service "my-service" \
    --environment "production" \
    --signal-type SNAPSHOT \
    --location '{
        "CodeLocation": {
            "Language": "Java",
            "CodeUnit": "com.example.service",
            "ClassName": "OrderController",
            "MethodName": "processOrder",
            "FilePath": "OrderController.java"
        }
    }' \
    --capture-configuration '{
        "CodeCapture": {
            "CaptureArguments": ["orderId", "user"],
            "CaptureReturn": true,
            "CaptureStackTrace": true,
            "CaptureLimits": {
                "MaxHits": 100,
                "MaxStringLength": 255,
                "MaxCollectionWidth": 20,
                "MaxObjectDepth": 3,
                "MaxFieldsPerObject": 20,
                "MaxStackFrames": 20
            }
        }
    }'

Création de configurations à l'aide du serveur MCP

L'approche recommandée pour utiliser l'instrumentation dynamique consiste à utiliser le serveur CloudWatch Application Signals MCP (Model Context Protocol). Le MCP permet aux assistants et agents de codage AI de votre IDE de créer, gérer et interroger des configurations d'instrumentation dynamique directement depuis votre environnement de développement.

À l'aide du MCP, votre assistant IA peut :

  • Créez des points d'arrêt et des sondes à des emplacements de code spécifiques sans quitter votre éditeur.

  • Interrogez les instantanés capturés pour inspecter les valeurs des variables d'exécution et les chemins d'appel.

  • Corrélez automatiquement les données des instantanés avec le code sur lequel vous travaillez pour suggérer des correctifs.

  • Gérez le cycle de vie des configurations d'instrumentation (affichage de l'état, suppression des points d'arrêt expirés).

Pour les instructions de configuration et d'utilisation, consultez le serveur Application Signals MCP sur le GitHub site Web.

Stockage de données

Lorsqu'un point d'arrêt ou une sonde se déclenche, Dynamic Instrumentation crée un groupe de CloudWatch journaux dans Logs avec le préfixe /aws/application-signals/service-name (où service-name est la valeur de votre variable d'OTEL_SERVICE_NAMEenvironnement) et écrit les instantanés capturés sous forme d'enregistrements de journal dans ce groupe de journaux.

Si le groupe de journaux n'existe pas déjà, Dynamic Instrumentation le crée automatiquement lors de la première émission d'un instantané. L'ingestion et le stockage des journaux vous sont facturés aux tarifs standard CloudWatch des journaux.

Afficher et gérer les configurations

Dans la CloudWatch console, accédez à la page détaillée du service et choisissez l'onglet Instrumentation.

  • Basculez entre Breakpoints et Probes pour afficher les configurations par type.

  • Consultez les détails de configuration, notamment la description, la configuration de capture, l'emplacement, l'ARN et le délai d'expiration.

  • Afficher l'historique des statuts pour suivre les transitions : Prêt à activer vers Error/Disabled.

  • Supprimez les configurations qui ne sont plus nécessaires.

Comprendre le statut

Chaque configuration d'instrumentation possède un statut qui indique son état actuel.

Statut Description
PRÊT L'agent a reçu la configuration.
ACTIF L'agent a appliqué l'instrumentation à l'application en cours d'exécution.
ERROR L'instrumentation ne s'appliquait pas. Consultez la cause de l'erreur pour plus de détails.
DISABLED L'instrumentation a expiré ou vous l'avez retirée.

Lorsqu'un instrument entre dans l'état d'erreur, les causes suivantes peuvent être signalées :

Cause de l'erreur Description
FICHIER_INTROUVABLE Le chemin de fichier spécifié n'existe pas dans l'application.
MÉTHODE NON TROUVÉE La méthode spécifiée n'existe pas dans la classe ou le module cible.
LIGNE NON EXÉCUTABLE Le numéro de ligne spécifié ne correspond pas à une instruction exécutable.
MÉTHODES_SURCHARGÉES Plusieurs méthodes correspondent au nom spécifié. Fournissez des informations de localisation supplémentaires pour identifier la bonne méthode.
INADÉQUATION DE LA LANGUE Les champs de localisation ne correspondent pas à la langue de l'application en cours d'exécution.
ERREUR_D'EXÉCUTION Une erreur inattendue s'est produite lors de l'application de l'instrumentation.

Limites de capture

Les limites de capture contrôlent la taille et la profondeur des données capturées. Configurez ces valeurs dans le capture-limits champ de configuration de capture.

Limite Par défaut Range Description
maximum StringLength 255 1 à 255 Nombre maximum de caractères capturés par valeur de chaîne.
maximum CollectionWidth 20 1-20 Nombre maximum d'éléments capturés par collection ou tableau.
maximum ObjectDepth 3 1 à 5 Profondeur maximale pour la traversée d'objets imbriqués.
maximum FieldsPerObject 20 1-20 Nombre maximum de champs capturés par objet.
maximum StackFrames 20 1-20 Nombre maximal d'images empilées capturées.
Nombre maximum de visites 100 1 à 1 000 Nombre maximum de captures avant la désactivation automatique. Points d'arrêt uniquement.

Le débit de chaque point d'instrumentation est limité à 5 captures par seconde.