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](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Observability-EKS-addon.html).
+ **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 (voir[Conditions préalables](#Application-Signals-DI-Prerequisites)), 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é.
1. **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 dans[Limites de capture](#Application-Signals-DI-Limits).
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 (voir[Limites de capture](#Application-Signals-DI-Limits)).
#### 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](https://awslabs.github.io/mcp/servers/cloudwatch-applicationsignals-mcp-server) 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_NAME`environnement) 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.