Déployez à l'aide du AWS Cloud Development Kit (AWS CDK)

Étape 1 : activer Application Signals dans votre compte

Si vous n’avez pas encore activé Application Signals dans ce compte, vous devez accorder à Application Signals les autorisations nécessaires pour découvrir vos services. Pour ce faire, procédez comme suit. Cette opération ne doit être effectuée qu’une seule fois par compte.

Pour activer Application Signals pour vos applications

1. Ouvrez la CloudWatch console à l'adresse https://console.aws.amazon.com/cloudwatch/.

2. Dans le panneau de navigation, choisissez Services.

3. Choisissez Commencer à découvrir vos services.

4. Cochez la case et choisissez Commencer à découvrir les services.

   Si vous effectuez cette étape pour la première fois dans votre compte, le rôle AWSServiceRoleForCloudWatchApplicationSignalslié au service est créé. Ce rôle accorde à Application Signals les autorisations suivantes :

   • xray:GetServiceGraph

   • logs:StartQuery

   • logs:GetQueryResults

   • cloudwatch:GetMetricData

   • cloudwatch:ListMetrics

   • tag:GetResources

   Pour plus d’informations sur ce rôle, consultez Autorisations de rôle liées au service pour les signaux d'application CloudWatch .

Étape 2 : créer un rôle IAM

Vous devez créer un rôle IAM. Si vous avez déjà créé ce rôle, vous devrez peut-être y ajouter des autorisations.

• Rôle de tâche ECS : les conteneurs utilisent ce rôle pour s'exécuter. Les autorisations doivent également correspondre aux besoins de vos applications CloudWatchAgentServerPolicy.

Pour plus d'informations sur la création de rôles IAM, consultez Création de rôles IAM.

Étape 3 : Instrumenter votre application avec l' CloudWatch agent AWS CDK

Pour activer les signaux d'application pour Amazon ECS à l'aide de AWS CDK, suivez les étapes décrites ci-dessous. Les extraits de code contenus dans ce document sont fournis dans. TypeScript Pour d'autres alternatives spécifiques au langage, voir Langages de programmation pris en charge pour le cloudwatch-agent AWS CDK

Note

Ce document fournit une vue d'ensemble du processus de configuration des signaux d'application à l'aide de AWS CDK, voir Étape 4 : Instrumenter votre application avec l' CloudWatch agent les instructions de configuration spécifiques à la langue qui spécifient les valeurs pour MOUNT_VOLUME >, MOUNT_CONTAINER_PATH INIT_CONTAINER_COMMAND >, et ENVIRONMENT_VARIABLES

Pour instrumenter votre application avec l' CloudWatch agent

1. Dans la définition de la tâche de votre application, spécifiez un montage de liaison. Remplacez MOUNT_VOLUME en fonction de la langue utilisée par votre application. Par exemple, opentelemetry-auto-instrumentation utilisez-le en Java. Le volume sera utilisé pour partager des fichiers entre conteneurs au cours des prochaines étapes. Vous utiliserez ce montage de liaison plus loin dans cette procédure :

   const taskDefinition = new ecs.FargateTaskDefinition(this, 'MyTaskDefinition', {
     ...
     volumes: [{
       name: MOUNT_VOLUME,
     }]
    );
   
   

2. Ensuite, vous ajoutez l' CloudWatch agent. Il existe deux méthodes possibles pour utiliser l' CloudWatch agent d'ajout : la stratégie sidecar et la stratégie daemon. Pour plus d'informations sur les avantages et les inconvénients de chaque méthode, consultez Utilisation d’une configuration personnalisée pour activer Application Signals sur Amazon ECS et choisissez la méthode la mieux adaptée à votre environnement.

   • Stratégie sidecar : ajoutez un nouveau conteneur appelé ecs-cwagent à la définition de tâche de votre application. $IMAGERemplacez-le par le chemin d'accès à la dernière image de CloudWatch conteneur sur Amazon Elastic Container Registry. Pour plus d'informations, consultez cloudwatch-agent sur Amazon ECR.

     const cwAgentContainer = taskDefinition.addContainer('ecs-cwagent', {
       image: ecs.ContainerImage.fromRegistry("$IMAGE"),
       environment: {
         CW_CONFIG_CONTENT: '{"agent": {"debug": true}, "traces": {"traces_collected": {"application_signals": {"enabled": true}}}, "logs": {"metrics_collected": {"application_signals": {"enabled": true}}}}',
       },
       logging: new ecs.AwsLogDriver({
         streamPrefix: 'ecs',
         logGroup: new logs.LogGroup(this, 'CwAgentLogGroup', {
           logGroupName: '/ecs/ecs-cwagent',
         }),
       }),
     });

   • Stratégie Daemon — Créez un nouveau service appelé ecs-cwagent dans votre stack. Remplacez $TASK_ROLE_ARN et $EXECUTION_ROLE_ARN par les rôles IAM que vous avez préparés dansÉtape 2 : créer un rôle IAM. $IMAGERemplacez-le par le chemin d'accès à la dernière image de CloudWatch conteneur sur Amazon Elastic Container Registry. Pour plus d'informations, consultez cloudwatch-agent sur Amazon ECR.

     Note

     Le service daemon expose deux ports sur l'hôte, le 4316 étant utilisé comme point de terminaison pour la réception des métriques et des traces et le port 2000 comme point de terminaison de l' CloudWatch échantillonneur de traces. Cette configuration permet à l'agent de collecter et de transmettre des données de télémétrie provenant de toutes les tâches d'application exécutées sur l'hôte. Assurez-vous que ces ports ne sont pas utilisés par d'autres services sur l'hôte pour éviter les conflits.

     const cwAgentTaskDefinition = new ecs.Ec2TaskDefinition(this, 'CwAgentDaemonTaskDef', {
         taskRole: "$TASK_ROLE_ARN",
         executionRole: "$EXECUTION_ROLE_ARN",
     });
     
     // Add the CloudWatch agent container
     const cwAgentContainer = cwAgentTaskDefinition.addContainer('ecs-cwagent', {
         image: ecs.ContainerImage.fromRegistry("$IMAGE"),
         cpu: 128,
         memoryLimitMiB: 64,
         portMappings: [
             {
                 containerPort: 4316,
                 hostPort: 4316,
             },
             {
                 containerPort: 2000,
                 hostPort: 2000,
             },
         ],
         logging: new ecs.AwsLogDriver({
             streamPrefix: 'ecs',
             logGroup: new logs.LogGroup(this, 'CwAgentLogGroup', {
                 logGroupName: '/ecs/ecs-cwagent-daemon',
             }),
         }),
         environment: {
             CW_CONFIG_CONTENT: '{"agent": {"debug": true}, "traces": {"traces_collected": {"application_signals": {"enabled": true}}}, "logs": {"metrics_collected": {"application_signals": {"enabled": true}}}}',
         },
     });
     
     // Add the CloudWatch agent service running as a daemon
     const cwAgentService = new ecs.Ec2Service(this, 'CwAgentDaemonService', {
         cluster,
         taskDefinition: cwAgentTaskDefinition,
         daemon: true,
     });

3. Ajoutez un nouveau conteneur init à la définition de tâche de votre application. $IMAGERemplacez-la par la dernière image du référentiel d'images AWS Distro for OpenTelemetry Amazon ECR. Remplacez MOUNT_CONTAINER_PATH et INIT_CONTAINER_COMMAND selon la langue utilisée par votre application.

   Par exemple, en Java, utilisez INIT_CONTAINER_COMMAND=["cp", "/javaagent.jar", "/otel-auto-instrumentation/javaagent.jar"], MOUNT_CONTAINER_PATH='/otel-auto-instrumentation'

   const initContainer = taskDefinition.addContainer('init', {
       image: ecs.ContainerImage.fromRegistry("$IMAGE"),
       essential: false,
       command: INIT_CONTAINER_COMMAND
   });
   
   initContainer.addMountPoints({
       sourceVolume: MOUNT_VOLUME,
       containerPath: MOUNT_CONTAINER_PATH,
       readOnly: false
   });

4. Ajoutez les variables ENVIRONMENT_VARIABLES d'environnement au conteneur de votre application en fonction de la langue utilisée par votre application. Et montez le volume MOUNT_VOLUME dans le conteneur de l'application.

   Note

   Pour les instructions de configuration spécifiques à la langue qui spécifient les valeurs pour MOUNT_VOLUME >, MOUNT_CONTAINER_PATH >, INIT_CONTAINER_COMMAND > etENVIRONMENT_VARIABLES, voir. Étape 4 : Instrumenter votre application avec l' CloudWatch agent

   Voici un exemple :

   const appContainer = taskDefinition.addContainer('my-app', {
       ...
       environment: {
           ...
           ENVIRONMENT_VARIABLES
       },
   });
   
   appContainer.addMountPoints({
       sourceVolume: MOUNT_VOLUME,
       containerPath: MOUNT_CONTAINER_PATH,
       readOnly: false
   });
   
   appContainer.addContainerDependencies({
       container: initContainer,
       condition: ecs.ContainerDependencyCondition.SUCCESS
   });

Configuration d'une application Node.js au format du module ESM

Nous fournissons un support limité pour les applications Node.js au format de module ESM. Pour plus de détails, consultez Limitations connues concernant Node.js avec ESM.

Pour le format du module ESM, l'activation des signaux d'application en utilisant le init conteneur pour injecter le SDK d'instrumentation Node.js ne s'applique pas. Ignorez les étapes 1 et 3 de la procédure précédente et procédez plutôt comme suit.

Pour activer les signaux d'application pour une application Node.js avec ESM

1. Installez les dépendances pertinentes dans votre application Node.js pour l'autoinstrumentation :

   npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation
   npm install @opentelemetry/instrumentation@0.54.0

2. À l'étape 4 de la procédure précédente, retirez le montage du volume :

   appContainer.addMountPoints({
       sourceVolume: MOUNT_VOLUME,
       containerPath: MOUNT_CONTAINER_PATH,
       readOnly: false
   });

   Et définissez la variable NODE_OPTIONS environnementale comme étant --import @aws/aws-distro-opentelemetry-node-autoinstrumentation/register --experimental-loader=@opentelemetry/instrumentation/hook.mjs

Étape 4 : Déployer la pile mise à jour

Exécutez la cdk synth commande dans le répertoire principal de votre application. Pour déployer le service dans votre AWS compte, exécutez la cdk deploy commande dans le répertoire principal de votre application.

Si vous avez utilisé la stratégie du sidecar, vous verrez un service créé :

• APPLICATION_SERVICEest le service de votre application. Il comprend les trois conteneurs suivants :

  • init— Conteneur requis pour l'initialisation des signaux d'application.

  • ecs-cwagent— Un conteneur exécutant l' CloudWatch agent

  • my-app— Voici l'exemple de conteneur d'applications présenté dans notre documentation. Dans vos charges de travail réelles, ce conteneur spécifique n'existe peut-être pas ou peut être remplacé par vos propres conteneurs de services.

Si vous avez utilisé la stratégie daemon, vous verrez deux services créés :

• CWAgentDaemonServiceest le service CloudWatch agent daemon.

• APPLICATION_SERVICEest le service de votre application. Il comprend les deux conteneurs suivants :

  • init— Conteneur requis pour l'initialisation des signaux d'application.

  • my-app— Voici l'exemple de conteneur d'applications présenté dans notre documentation. Dans vos charges de travail réelles, ce conteneur spécifique n'existe peut-être pas ou peut être remplacé par vos propres conteneurs de services.