使用 部署 AWS Cloud Development Kit (AWS CDK)

步驟 1：在您的帳戶中啟用 Application Signals

如果尚未在此帳戶中啟用 Application Signals，則必須授予 Application Signals 所需的許可，以探索您的服務。為此，請執行下列操作。您的帳戶只需執行一次此操作。

為您的應用程式啟用 Application Signals

1. 透過 https://console.aws.amazon.com/cloudwatch/ 開啟 CloudWatch 主控台。

2. 在導覽窗格中，選擇服務。

3. 選擇開始探索您的服務。

4. 選取核取方塊，然後選擇開始探索服務。

   第一次在您的帳戶中完成此步驟會建立 AWSServiceRoleForCloudWatchApplicationSignals 服務連結角色。此角色會授予 Application Signals 下列許可：

   • xray:GetServiceGraph

   • logs:StartQuery

   • logs:GetQueryResults

   • cloudwatch:GetMetricData

   • cloudwatch:ListMetrics

   • tag:GetResources

   如需有關此角色的詳細資訊，請參閱 CloudWatch Application Signals 的服務連結角色許可。

步驟 2：建立 IAM 角色

您必須建立 IAM 角色。如果您已建立此角色，您可能需要新增許可給該角色。

• ECS 任務角色 — 容器使用此角色來執行。許可應該是您的應用程式所需的任何項目，以及 CloudWatchAgentServerPolicy。

如需建立 IAM 角色的詳細資訊，請參閱建立 IAM 角色。

步驟 3：使用 中的 CloudWatch 代理程式檢測您的應用程式 AWS CDK

若要使用 啟用 Amazon ECS 的 Application Signals AWS CDK，請遵循下列步驟。本文件中的程式碼片段提供於 TypeScript。如需其他語言特定的替代方案，請參閱 cloudwatch-agent 支援的程式設計語言 AWS CDK

注意

本文件提供使用 的 Application Signals 設定程序概觀 AWS CDK，請參閱 步驟 4：使用 CloudWatch 代理程式檢測您的應用程式 以取得指定 MOUNT_VOLUME＞、＞、MOUNT_CONTAINER_PATH> INIT_CONTAINER_COMMAND和 值的語言特定設定指示 ENVIRONMENT_VARIABLES

使用 CloudWatch 代理程式檢測您的應用程式

1. 在您的應用程式任務定義中，指定繫結掛載。根據您的應用程式使用的語言取代 MOUNT_VOLUME。例如，在 Java opentelemetry-auto-instrumentation中使用 。在接下來的步驟中，該磁碟區將用於跨容器共用檔案。您將在此程序稍後使用此繫結掛載：

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

2. 接著，新增 CloudWatch 代理程式。有兩種可能的方法可以使用新增 CloudWatch 代理程式：附屬策略和協助程式策略。如需每種方法優缺點的相關資訊，請參閱使用自訂設定在 Amazon ECS 上啟用 Application Signals並選擇最適合您環境的方法。

   • Sidecar 策略 – 將名為 的新容器附加ecs-cwagent至應用程式的任務定義。將 $IMAGE 取代為 Amazon Elastic Container Registry 上最新 CloudWatch 容器映像的路徑。如需詳細資訊，請參閱 Amazon ECR 上的 cloudwatch-agent。

     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',
         }),
       }),
     });

   • 協助程式策略 – 在堆疊ecs-cwagent中建立新的名為 的服務。將 $TASK_ROLE_ARN 和 $EXECUTION_ROLE_ARN 替換為您在 中準備的 IAM 角色步驟 2：建立 IAM 角色。將 $IMAGE 取代為 Amazon Elastic Container Registry 上最新 CloudWatch 容器映像的路徑。如需詳細資訊，請參閱 Amazon ECR 上的 cloudwatch-agent。

     注意

     協助程式服務公開主機上的兩個連接埠，其中 4316 用作接收指標和追蹤的端點，2000 作為 CloudWatch 追蹤採樣器端點。此設定可讓代理程式從主機上執行的所有應用程式任務收集和傳輸遙測資料。請確定主機上的其他服務不會使用這些連接埠，以避免衝突。

     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. 將新的容器初始化附加到應用程式的任務定義。將 $IMAGE 取代為 AWS Distro for OpenTelemetry Amazon ECR 映像儲存庫中的最新映像。根據您的應用程式使用的語言取代 MOUNT_CONTAINER_PATH 和 INIT_CONTAINER_COMMAND。

   例如，在 Java 中使用 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. 根據應用程式使用的語言，將環境變數 ENVIRONMENT_VARIABLES 新增至應用程式容器。然後將磁碟區 MOUNT_VOLUME 掛載到應用程式容器中。

   注意

   如需指定 MOUNT_VOLUME＞、＞、MOUNT_CONTAINER_PATH> INIT_CONTAINER_COMMAND和 值的語言特定設定指示ENVIRONMENT_VARIABLES，請參閱 步驟 4：使用 CloudWatch 代理程式檢測您的應用程式。

   以下是範例：

   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
   });

使用 ESM 模組格式設定 Node.js 應用程式

我們提供 ESM 模組格式的 Node.js 應用程式有限支援。如需詳細資訊，請參閱 使用 ESM 的 Node.js 已知限制。

對於 ESM 模組格式，使用init容器注入 Node.js 檢測 SDK 來啟用 Application Signals 不適用。略過先前程序的步驟 1 和 3，然後改為執行下列動作。

使用 ESM 為 Node.js 應用程式啟用 Application Signals

1. 將相關的相依性安裝到您的 Node.js 應用程式以進行自動檢測：

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

2. 在先前程序中的步驟 4 中，移除磁碟區的掛載：

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

   並將環境變數設定為 NODE_OPTIONS --import @aws/aws-distro-opentelemetry-node-autoinstrumentation/register --experimental-loader=@opentelemetry/instrumentation/hook.mjs

步驟 4：部署更新的堆疊

在應用程式的主目錄中執行 cdk synth命令。若要在 AWS 帳戶中部署 服務，請在應用程式的主目錄中執行 cdk deploy命令。

如果您使用附屬策略，您會看到已建立一項服務：

• APPLICATION_SERVICE 是您應用程式的 服務。它包含以下三個容器：

  • init– 初始化 Application Signals 所需的容器。

  • ecs-cwagent– 執行 CloudWatch 代理程式的容器

  • my-app– 這是我們文件中的範例應用程式容器。在您實際的工作負載中，此特定容器可能不存在，或可能以您自己的服務容器取代。

如果您使用協助程式策略，您會看到建立的兩個服務：

• CWAgentDaemonService 是 CloudWatch 代理程式常駐程式服務。

• APPLICATION_SERVICE 是您應用程式的 服務。它包含下列兩個容器：

  • init– 初始化 Application Signals 所需的容器。

  • my-app– 這是我們文件中的範例應用程式容器。在您實際的工作負載中，此特定容器可能不存在，或可能以您自己的服務容器取代。