# 使用挎斗策略进行部署
<a name="CloudWatch-Application-Signals-ECS-Sidecar"></a>

## 步骤 1：在账户中启用 Application Signals
<a name="CloudWatch-Application-Signals-ECS-Grant"></a>

必须先在账户中启用 Application Signals。如果还没有，请参阅[在账户中启用 Application Signals](CloudWatch-Application-Signals-Enable.md)。

## 步骤 2：创建 IAM 角色
<a name="CloudWatch-Application-Signals-Enable-ECS-IAM"></a>

您必须创建一个 IAM 角色。如果您已创建此角色，则可能需要向其添加权限。
+ **ECS 任务角色 –** 容器使用此角色运行。权限应是您的应用程序所需的任何权限，以及 **CloudWatchAgentServerPolicy**。

有关创建 IAM 角色的更多信息，请参阅[创建 IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html)。

## 步骤 3：准备 CloudWatch 代理配置
<a name="CloudWatch-Application-Signals-Enable-ECS-PrepareAgent"></a>

首先，在启用 Application Signals 的情况下准备代理配置。为此，请创建一个名为 `/tmp/ecs-cwagent.json` 的本地文件。

```
{
  "traces": {
    "traces_collected": {
      "application_signals": {}
    }
  },
  "logs": {
    "metrics_collected": {
      "application_signals": {}
    }
  }
}
```

然后，将此配置上传到 SSM 参数仓库中。要执行此操作，请输入以下命令。在该文件中，将 *\$1REGION* 替换为您的实际区域名称。

```
aws ssm put-parameter \
--name "ecs-cwagent" \
--type "String" \
--value "`cat /tmp/ecs-cwagent.json`" \
--region "$REGION"
```

## 步骤 4：使用 CloudWatch 代理检测您的应用程序
<a name="CloudWatch-Application-Signals-Enable-ECS-Instrument"></a>

下一步是为 CloudWatch Application Signals 检测您的应用程序。

------
#### [ Java ]

**使用 CloudWatch 代理检测您在 Amazon ECS 上的应用程序**

1. 首先，指定绑定挂载。在接下来的步骤中，该卷将用于跨容器共享文件。您将在此过程的稍后部分使用此绑定挂载。

   ```
   "volumes": [
     {
       "name": "opentelemetry-auto-instrumentation"
     }
   ]
   ```

1. 添加 CloudWatch 代理 sidecar 定义。为此，请在应用程序的任务定义中追加一个名为 `ecs-cwagent` 的新容器。将 *\$1REGION* 替换为您的实际区域名称。将 *\$1IMAGE* 替换为 Amazon Elastic Container Registry 上最新 CloudWatch 容器映像的路径。有关更多信息，请参阅 Amazon ECR 上的 [cloudwatch-agent](https://gallery.ecr.aws/cloudwatch-agent/cloudwatch-agent)。

   如果要改为启用使用进程守护程序策略的 CloudWatch 代理，请参阅 [使用进程守护程序策略进行部署](CloudWatch-Application-Signals-ECS-Daemon.md) 中的说明。

   ```
   {
     "name": "ecs-cwagent",
     "image": "$IMAGE",
     "essential": true,
     "secrets": [
       {
         "name": "CW_CONFIG_CONTENT",
         "valueFrom": "ecs-cwagent"
       }
     ],
     "logConfiguration": {
       "logDriver": "awslogs",
       "options": {
         "awslogs-create-group": "true",
         "awslogs-group": "/ecs/ecs-cwagent",
         "awslogs-region": "$REGION",
         "awslogs-stream-prefix": "ecs"
       }
     }
   }
   ```

1. 在应用程序的任务定义中添加一个新容器 `init`。将 *\$1IMAGE* 替换为 [AWS Distro for OpenTelemetry Amazon ECR 映像存储库](https://gallery.ecr.aws/aws-observability/adot-autoinstrumentation-java)中的最新映像。

   ```
   {
     "name": "init",
     "image": "$IMAGE",
     "essential": false,
     "command": [
       "cp",
       "/javaagent.jar",
       "/otel-auto-instrumentation/javaagent.jar"
     ],
     "mountPoints": [
       {
         "sourceVolume": "opentelemetry-auto-instrumentation",
         "containerPath": "/otel-auto-instrumentation",
         "readOnly": false
       }
     ]
   }
   ```

1. 在 `init` 容器上添加依赖项，以确保此容器在应用程序容器启动之前完成。

   ```
   "dependsOn": [
     {
       "containerName": "init",
       "condition": "SUCCESS"
     }
   ]
   ```

1. 将以下环境变量添加到您的应用程序容器中。您必须使用适用于 OpenTelemetry 的 AWS Distro [Java 自动仪表化代理](https://opentelemetry.io/docs/zero-code/java/agent/)版本 1.32.2 或更高版本。    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-ECS-Sidecar.html)

1. 挂载您在此过程的步骤 1 中定义的卷 `opentelemetry-auto-instrumentation`。如果您不需要启用与指标和跟踪的日志关联，请使用以下 Java 应用程序示例。如果要启用日志关联，请改为参阅下一步。

   ```
   {
     "name": "my-app",
      ...
     "environment": [
       {
         "name": "OTEL_RESOURCE_ATTRIBUTES",
         "value": "service.name=$SVC_NAME"
       },
       {
         "name": "OTEL_LOGS_EXPORTER",
         "value": "none"
       },
       {
         "name": "OTEL_METRICS_EXPORTER",
         "value": "none"
       },
       {
         "name": "OTEL_EXPORTER_OTLP_PROTOCOL",
         "value": "http/protobuf"
       },
       {
         "name": "OTEL_AWS_APPLICATION_SIGNALS_ENABLED",
         "value": "true"
       },
       {
         "name": "JAVA_TOOL_OPTIONS",
         "value": " -javaagent:/otel-auto-instrumentation/javaagent.jar"
       },
       {
         "name": "OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT",
         "value": "http://localhost:4316/v1/metrics"
       },
       {
         "name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
         "value": "http://localhost:4316/v1/traces"
       },
       {
         "name": "OTEL_TRACES_SAMPLER",
         "value": "xray"
       },
       {
         "name": "OTEL_PROPAGATORS",
         "value": "tracecontext,baggage,b3,xray"
       }
     ],
     "dependsOn": [
       {
         "containerName": "init",
         "condition": "SUCCESS"
       }
     ],
     "mountPoints": [
       {
         "sourceVolume": "opentelemetry-auto-instrumentation",
         "containerPath": "/otel-auto-instrumentation",
         "readOnly": false
       }
     ]
   }
   ```

------
#### [ Python ]

在为 Python 应用程序启用 Application Signals 之前，请注意以下注意事项。
+ 在某些容器化应用程序中，缺少 `PYTHONPATH` 环境变量有时可能会导致应用程序无法启动。要解决此问题，请确保将 `PYTHONPATH` 环境变量设置为应用程序工作目录的位置。这是由于 OpenTelemetry 自动检测的已知问题造成的。有关此问题的更多信息，请参阅 [Python autoinstrumentation setting of PYTHONPATH is not compliant](https://github.com/open-telemetry/opentelemetry-operator/issues/2302)（PYTHONPATH 的 Python 自动检测设置不兼容）。
+ 对于 Django 应用程序，还有其他必需的配置，这些配置在 [OpenTelemetry Python 文档](https://opentelemetry-python.readthedocs.io/en/latest/examples/django/README.html)中进行了概述。
  + 使用 `--noreload` 标志可防止自动重新加载。
  + 将 `DJANGO_SETTINGS_MODULE` 环境变量设置为 Django 应用程序 `settings.py` 文件的位置。这样可确保 OpenTelemetry 能够正确访问您的 Django 设置，并与之集成。
+ 如果您在 Python 应用程序中使用 WSGI 服务器，则除了本节中的以下步骤之外，还可以参阅[使用 WSGI 服务器的 Python 应用程序没有 Application Signals 数据](CloudWatch-Application-Signals-Enable-Troubleshoot.md#Application-Signals-troubleshoot-Python-WSGI)以获取有关使 Application Signals 起作用的信息。

**使用 CloudWatch 代理检测您在 Amazon ECS 上的 Python 应用程序**

1. 首先，指定绑定挂载。在接下来的步骤中，该卷将用于跨容器共享文件。您将在此过程的稍后部分使用此绑定挂载。

   ```
   "volumes": [
     {
       "name": "opentelemetry-auto-instrumentation-python"
     }
   ]
   ```

1. 添加 CloudWatch 代理 sidecar 定义。为此，请在应用程序的任务定义中追加一个名为 `ecs-cwagent` 的新容器。将 *\$1REGION* 替换为您的实际区域名称。将 *\$1IMAGE* 替换为 Amazon Elastic Container Registry 上最新 CloudWatch 容器映像的路径。有关更多信息，请参阅 Amazon ECR 上的 [cloudwatch-agent](https://gallery.ecr.aws/cloudwatch-agent/cloudwatch-agent)。

   如果要改为启用使用进程守护程序策略的 CloudWatch 代理，请参阅 [使用进程守护程序策略进行部署](CloudWatch-Application-Signals-ECS-Daemon.md) 中的说明。

   ```
   {
     "name": "ecs-cwagent",
     "image": "$IMAGE",
     "essential": true,
     "secrets": [
       {
         "name": "CW_CONFIG_CONTENT",
         "valueFrom": "ecs-cwagent"
       }
     ],
     "logConfiguration": {
       "logDriver": "awslogs",
       "options": {
         "awslogs-create-group": "true",
         "awslogs-group": "/ecs/ecs-cwagent",
         "awslogs-region": "$REGION",
         "awslogs-stream-prefix": "ecs"
       }
     }
   }
   ```

1. 在应用程序的任务定义中添加一个新容器 `init`。将 *\$1IMAGE* 替换为 [AWS Distro for OpenTelemetry Amazon ECR 映像存储库](https://gallery.ecr.aws/aws-observability/adot-autoinstrumentation-python)中的最新映像。

   ```
   {
       "name": "init",
       "image": "$IMAGE",
       "essential": false,
       "command": [
           "cp",
           "-a",
           "/autoinstrumentation/.",
           "/otel-auto-instrumentation-python"
       ],
       "mountPoints": [
           {
               "sourceVolume": "opentelemetry-auto-instrumentation-python",
               "containerPath": "/otel-auto-instrumentation-python",
               "readOnly": false
           }
       ]
   }
   ```

1. 在 `init` 容器上添加依赖项，以确保此容器在应用程序容器启动之前完成。

   ```
   "dependsOn": [
     {
       "containerName": "init",
       "condition": "SUCCESS"
     }
   ]
   ```

1. 将以下环境变量添加到您的应用程序容器中。    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-ECS-Sidecar.html)

1. 挂载您在此过程的步骤 1 中定义的卷 `opentelemetry-auto-instrumentation-python`。如果您不需要启用与指标和跟踪的日志关联，请使用以下 Python 应用程序示例。如果要启用日志关联，请改为参阅下一步。

   ```
   {
     "name": "my-app",
     ...
     "environment": [
       {
         "name": "PYTHONPATH",
         "value": "/otel-auto-instrumentation-python/opentelemetry/instrumentation/auto_instrumentation:$APP_PATH:/otel-auto-instrumentation-python"
       },
       {
         "name": "OTEL_EXPORTER_OTLP_PROTOCOL",
         "value": "http/protobuf"
       },
       {
         "name": "OTEL_TRACES_SAMPLER",
         "value": "xray"
       },
       {
         "name": "OTEL_TRACES_SAMPLER_ARG",
         "value": "endpoint=http://localhost:2000"
       },
       {
         "name": "OTEL_LOGS_EXPORTER",
         "value": "none"
       },
       {
         "name": "OTEL_PYTHON_DISTRO",
         "value": "aws_distro"
       },
       {
         "name": "OTEL_PYTHON_CONFIGURATOR",
         "value": "aws_configurator"
       },
       {
         "name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
         "value": "http://localhost:4316/v1/traces"
       },
       {
         "name": "OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT",
         "value": "http://localhost:4316/v1/metrics"
       },
       {
         "name": "OTEL_METRICS_EXPORTER",
         "value": "none"
       },
       {
         "name": "OTEL_AWS_APPLICATION_SIGNALS_ENABLED",
         "value": "true"
       },
       {
         "name": "OTEL_RESOURCE_ATTRIBUTES",
         "value": "service.name=$SVC_NAME"
       },
       {
         "name": "DJANGO_SETTINGS_MODULE",
         "value": "$PATH_TO_SETTINGS.settings"
       }
     ],
     "mountPoints": [
       {
         "sourceVolume": "opentelemetry-auto-instrumentation-python",
         "containerPath": "/otel-auto-instrumentation-python",
         "readOnly": false
       }
     ]
   }
   ```

1. （可选）要启用日志关联，请在挂载卷之前执行以下操作。在`OTEL_RESOURCE_ATTRIBUTES` 中，为应用程序的日志组设置其他环境变量 `aws.log.group.names`。这样，应用程序的跟踪和指标便可与这些特定日志组的相关日志条目相关联。对于此变量，将 *\$1YOUR\$1APPLICATION\$1LOG\$1GROUP* 替换为应用程序的日志组名称。如果您有多个日志组，则可以使用和号（`&`）分隔它们，如以下示例所示：`aws.log.group.names=log-group-1&log-group-2`。要启用指标与日志关联的功能，设置此当前环境变量已足够。有关更多信息，请参阅 [启用指标与日志关联](Application-Signals-MetricLogCorrelation.md)。要启用跟踪与日志关联，您还需要更改应用程序中的日志记录配置。有关更多信息，请参阅 [启用跟踪与日志关联](Application-Signals-TraceLogCorrelation.md)。

   示例如下：要启用日志关联，请在挂载您于此过程的步骤 1 中定义的卷 `opentelemetry-auto-instrumentation-python` 时使用此示例。

   ```
   {
     "name": "my-app",
     ...
     "environment": [
       {
         "name": "PYTHONPATH",
         "value": "/otel-auto-instrumentation-python/opentelemetry/instrumentation/auto_instrumentation:$APP_PATH:/otel-auto-instrumentation-python"
       },
       {
         "name": "OTEL_EXPORTER_OTLP_PROTOCOL",
         "value": "http/protobuf"
       },
       {
         "name": "OTEL_TRACES_SAMPLER",
         "value": "xray"
       },
       {
         "name": "OTEL_TRACES_SAMPLER_ARG",
         "value": "endpoint=http://localhost:2000"
       },
       {
         "name": "OTEL_LOGS_EXPORTER",
         "value": "none"
       },
       {
         "name": "OTEL_PYTHON_DISTRO",
         "value": "aws_distro"
       },
       {
         "name": "OTEL_PYTHON_CONFIGURATOR",
         "value": "aws_configurator"
       },
       {
         "name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
         "value": "http://localhost:4316/v1/traces"
       },
       {
         "name": "OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT",
         "value": "http://localhost:4316/v1/metrics"
       },
       {
         "name": "OTEL_METRICS_EXPORTER",
         "value": "none"
       },
       {
         "name": "OTEL_AWS_APPLICATION_SIGNALS_ENABLED",
         "value": "true"
       },
       {
         "name": "OTEL_RESOURCE_ATTRIBUTES",
         "value": "aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,service.name=$SVC_NAME"
       },
       {
         "name": "DJANGO_SETTINGS_MODULE",
         "value": "$PATH_TO_SETTINGS.settings"
       }
     ],
     "mountPoints": [
       {
         "sourceVolume": "opentelemetry-auto-instrumentation-python",
         "containerPath": "/otel-auto-instrumentation-python",
         "readOnly": false
       }
     ]
   }
   ```

------
#### [ .NET ]

**使用 CloudWatch 代理检测您在 Amazon ECS 上的应用程序**

1. 首先，指定绑定挂载。在接下来的步骤中，该卷将用于跨容器共享文件。您将在此过程的稍后部分使用此绑定挂载。

   ```
   "volumes": [
     {
       "name": "opentelemetry-auto-instrumentation"
     }
   ]
   ```

1. 添加 CloudWatch 代理 sidecar 定义。为此，请在应用程序的任务定义中追加一个名为 `ecs-cwagent` 的新容器。将 *\$1REGION* 替换为您的实际区域名称。将 *\$1IMAGE* 替换为 Amazon Elastic Container Registry 上最新 CloudWatch 容器映像的路径。有关更多信息，请参阅 Amazon ECR 上的 [cloudwatch-agent](https://gallery.ecr.aws/cloudwatch-agent/cloudwatch-agent)。

   如果要改为启用使用进程守护程序策略的 CloudWatch 代理，请参阅 [使用进程守护程序策略进行部署](CloudWatch-Application-Signals-ECS-Daemon.md) 中的说明。

   ```
   {
     "name": "ecs-cwagent",
     "image": "$IMAGE",
     "essential": true,
     "secrets": [
       {
         "name": "CW_CONFIG_CONTENT",
         "valueFrom": "ecs-cwagent"
       }
     ],
     "logConfiguration": {
       "logDriver": "awslogs",
       "options": {
         "awslogs-create-group": "true",
         "awslogs-group": "/ecs/ecs-cwagent",
         "awslogs-region": "$REGION",
         "awslogs-stream-prefix": "ecs"
       }
     }
   }
   ```

1. 在应用程序的任务定义中添加一个新容器 `init`。将 *\$1IMAGE* 替换为 [AWS Distro for OpenTelemetry Amazon ECR 映像存储库](https://gallery.ecr.aws/aws-observability/adot-autoinstrumentation-dotnet)中的最新映像。

   对于 Linux 容器实例，请使用以下代码。

   ```
   {
     "name": "init",
     "image": "$IMAGE",
     "essential": false,
     "command": [
         "cp",
         "-a",
         "autoinstrumentation/.",
         "/otel-auto-instrumentation"
     ],
     "mountPoints": [
         {
             "sourceVolume": "opentelemetry-auto-instrumentation",
             "containerPath": "/otel-auto-instrumentation",
             "readOnly": false
         }
     ]
   }
   ```

   对于 Windows Server 容器实例，请使用以下代码。

   ```
   {
     "name": "init",
     "image": "$IMAGE",
     "essential": false,
     "command": [
         "CMD",
         "/c",
         "xcopy",
         "/e",
         "C:\\autoinstrumentation\\*",
         "C:\\otel-auto-instrumentation",
         "&&",
         "icacls",
         "C:\\otel-auto-instrumentation",
         "/grant",
         "*S-1-1-0:R",
         "/T"
     ],
     "mountPoints": [
         {
             "sourceVolume": "opentelemetry-auto-instrumentation",
             "containerPath": "C:\\otel-auto-instrumentation",
             "readOnly": false
         }
     ]
   }
   ```

1. 在 `init` 容器上添加依赖项，以确保此容器在应用程序容器启动之前完成。

   ```
   "dependsOn": [
       {
           "containerName": "init",
           "condition": "SUCCESS"
       }
   ]
   ```

1. 将以下环境变量添加到您的应用程序容器中。您必须使用适用于 OpenTelemetry 的 AWS Distro [.NET 自动仪表化代理](https://opentelemetry.io/docs/zero-code/net/)版本 1.1.0 或更高版本。    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-ECS-Sidecar.html)

1. 挂载您在此过程的步骤 1 中定义的卷 `opentelemetry-auto-instrumentation`。对于 Linux，请使用以下代码。

   ```
   {
       "name": "my-app",
      ...
       "environment": [
           {
              "name": "OTEL_RESOURCE_ATTRIBUTES",
              "value": "service.name=$SVC_NAME"
          },
           {
               "name": "CORECLR_ENABLE_PROFILING",
               "value": "1"
           },
           {
               "name": "CORECLR_PROFILER",
               "value": "{918728DD-259F-4A6A-AC2B-B85E1B658318}"
           },
           {
               "name": "CORECLR_PROFILER_PATH",
               "value": "/otel-auto-instrumentation/linux-x64/OpenTelemetry.AutoInstrumentation.Native.so"
           },
           {
               "name": "DOTNET_ADDITIONAL_DEPS",
               "value": "/otel-auto-instrumentation/AdditionalDeps"
           },
           {
               "name": "DOTNET_SHARED_STORE",
               "value": "/otel-auto-instrumentation/store"
           },
           {
               "name": "DOTNET_STARTUP_HOOKS",
               "value": "/otel-auto-instrumentation/net/OpenTelemetry.AutoInstrumentation.StartupHook.dll"
           },
           {
               "name": "OTEL_DOTNET_AUTO_HOME",
               "value": "/otel-auto-instrumentation"
           },
           {
               "name": "OTEL_DOTNET_AUTO_PLUGINS",
               "value": "AWS.Distro.OpenTelemetry.AutoInstrumentation.Plugin, AWS.Distro.OpenTelemetry.AutoInstrumentation"
           },
           {
               "name": "OTEL_RESOURCE_ATTRIBUTES",
               "value": "aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,service.name=aws-dotnet-service-name"
           },
           {
               "name": "OTEL_LOGS_EXPORTER",
               "value": "none"
           },
           {
               "name": "OTEL_METRICS_EXPORTER",
               "value": "none"
           },
           {
               "name": "OTEL_EXPORTER_OTLP_PROTOCOL",
               "value": "http/protobuf"
           },
           {
               "name": "OTEL_AWS_APPLICATION_SIGNALS_ENABLED",
               "value": "true"
           },
           {
               "name": "OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT",
               "value": "http://localhost:4316/v1/metrics"
           },
           {
               "name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
               "value": "http://localhost:4316/v1/traces"
           },
           {
               "name": "OTEL_EXPORTER_OTLP_ENDPOINT",
               "value": "http://localhost:4316"
           },
           {
              "name": "OTEL_TRACES_SAMPLER",
              "value": "xray"
          },
          {
              "name": "OTEL_TRACES_SAMPLER_ARG",
              "value": "endpoint=http://localhost:2000"
          },
           {
               "name": "OTEL_PROPAGATORS",
               "value": "tracecontext,baggage,b3,xray"
           }
       ],
       "dependsOn": [
       {
         "containerName": "init",
         "condition": "SUCCESS"
       }
     ],
       "mountPoints": [
           {
               "sourceVolume": "opentelemetry-auto-instrumentation",
               "containerPath": "/otel-auto-instrumentation",
               "readOnly": false
           }
       ]
   }
   ```

   对于 Windows Server，使用以下代码。

   ```
   {
       "name": "my-app",
      ...
       "environment": [
          {
              "name": "OTEL_RESOURCE_ATTRIBUTES",
              "value": "service.name=$SVC_NAME"
          },
           {
               "name": "CORECLR_ENABLE_PROFILING",
               "value": "1"
           },
           {
               "name": "CORECLR_PROFILER",
               "value": "{918728DD-259F-4A6A-AC2B-B85E1B658318}"
           },
           {
               "name": "CORECLR_PROFILER_PATH",
               "value": "C:\\otel-auto-instrumentation\\win-x64\\OpenTelemetry.AutoInstrumentation.Native.dll"
           },
           {
               "name": "DOTNET_ADDITIONAL_DEPS",
               "value": "C:\\otel-auto-instrumentation\\AdditionalDeps"
           },
           {
               "name": "DOTNET_SHARED_STORE",
               "value": "C:\\otel-auto-instrumentation\\store"
           },
           {
               "name": "DOTNET_STARTUP_HOOKS",
               "value": "C:\\otel-auto-instrumentation\\net\\OpenTelemetry.AutoInstrumentation.StartupHook.dll"
           },
           {
               "name": "OTEL_DOTNET_AUTO_HOME",
               "value": "C:\\otel-auto-instrumentation"
           },
           {
               "name": "OTEL_DOTNET_AUTO_PLUGINS",
               "value": "AWS.Distro.OpenTelemetry.AutoInstrumentation.Plugin, AWS.Distro.OpenTelemetry.AutoInstrumentation"
           },
           {
               "name": "OTEL_RESOURCE_ATTRIBUTES",
               "value": "aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,service.name=dotnet-service-name"
           },
           {
               "name": "OTEL_LOGS_EXPORTER",
               "value": "none"
           },
           {
               "name": "OTEL_METRICS_EXPORTER",
               "value": "none"
           },
           {
               "name": "OTEL_EXPORTER_OTLP_PROTOCOL",
               "value": "http/protobuf"
           },
           {
               "name": "OTEL_AWS_APPLICATION_SIGNALS_ENABLED",
               "value": "true"
           },
           {
               "name": "OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT",
               "value": "http://localhost:4316/v1/metrics"
           },
           {
               "name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
               "value": "http://localhost:4316/v1/traces"
           },
           {
               "name": "OTEL_EXPORTER_OTLP_ENDPOINT",
               "value": "http://localhost:4316"
           },
           {
              "name": "OTEL_TRACES_SAMPLER",
              "value": "xray"
          },
          {
              "name": "OTEL_TRACES_SAMPLER_ARG",
              "value": "endpoint=http://localhost:2000"
          },
           {
               "name": "OTEL_PROPAGATORS",
               "value": "tracecontext,baggage,b3,xray"
           }
       ],
       "mountPoints": [
           {
               "sourceVolume": "opentelemetry-auto-instrumentation",
               "containerPath": "C:\\otel-auto-instrumentation",
               "readOnly": false
           }
       ],
       "dependsOn": [
           {
               "containerName": "init",
               "condition": "SUCCESS"
           }
      ]
   }
   ```

------
#### [ Node.js ]

**注意**  
要为使用 ESM 的 Node.js 应用程序启用 Application Signals，在开始这些步骤之前请参阅[Setting up a Node.js application with the ESM module format](#ECS-NodeJs-ESM)。

**使用 CloudWatch 代理检测您在 Amazon ECS 上的应用程序**

1. 首先，指定绑定挂载。在接下来的步骤中，该卷将用于跨容器共享文件。您将在此过程的稍后部分使用此绑定挂载。

   ```
   "volumes": [
     {
       "name": "opentelemetry-auto-instrumentation-node"
     }
   ]
   ```

1. 添加 CloudWatch 代理 sidecar 定义。为此，请在应用程序的任务定义中追加一个名为 `ecs-cwagent` 的新容器。将 *\$1REGION* 替换为您的实际区域名称。将 *\$1IMAGE* 替换为 Amazon Elastic Container Registry 上最新 CloudWatch 容器映像的路径。有关更多信息，请参阅 Amazon ECR 上的 [cloudwatch-agent](https://gallery.ecr.aws/cloudwatch-agent/cloudwatch-agent)。

   如果要改为启用使用进程守护程序策略的 CloudWatch 代理，请参阅 [使用进程守护程序策略进行部署](CloudWatch-Application-Signals-ECS-Daemon.md) 中的说明。

   ```
   {
     "name": "ecs-cwagent",
     "image": "$IMAGE",
     "essential": true,
     "secrets": [
       {
         "name": "CW_CONFIG_CONTENT",
         "valueFrom": "ecs-cwagent"
       }
     ],
     "logConfiguration": {
       "logDriver": "awslogs",
       "options": {
         "awslogs-create-group": "true",
         "awslogs-group": "/ecs/ecs-cwagent",
         "awslogs-region": "$REGION",
         "awslogs-stream-prefix": "ecs"
       }
     }
   }
   ```

1. 在应用程序的任务定义中添加一个新容器 `init`。将 *\$1IMAGE* 替换为 [AWS Distro for OpenTelemetry Amazon ECR 映像存储库](https://gallery.ecr.aws/aws-observability/adot-autoinstrumentation-node)中的最新映像。

   ```
   {
     "name": "init",
     "image": "$IMAGE",
     "essential": false,
     "command": [
       "cp",
       "-a",
       "/autoinstrumentation/.",
       "/otel-auto-instrumentation-node"
     ],
     "mountPoints": [
       {
         "sourceVolume": "opentelemetry-auto-instrumentation-node",
         "containerPath": "/otel-auto-instrumentation-node",
         "readOnly": false
       }
     ],
   }
   ```

1. 在 `init` 容器上添加依赖项，以确保此容器在应用程序容器启动之前完成。

   ```
   "dependsOn": [
     {
       "containerName": "init",
       "condition": "SUCCESS"
     }
   ]
   ```

1. 将以下环境变量添加到您的应用程序容器中。    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-ECS-Sidecar.html)

1. 挂载您在此过程的步骤 1 中定义的卷 `opentelemetry-auto-instrumentation`。如果您不需要启用与指标和跟踪的日志关联，请使用以下 Node.js 应用程序示例。如果要启用日志关联，请改为参阅下一步。

   对于应用程序容器，在 `init` 容器上添加依赖项，以确保容器在应用程序容器启动之前完成。

   ```
   {
     "name": "my-app",
      ...
     "environment": [
       {
         "name": "OTEL_RESOURCE_ATTRIBUTES",
         "value": "service.name=$SVC_NAME"
       },
       {
         "name": "OTEL_LOGS_EXPORTER",
         "value": "none"
       },
       {
         "name": "OTEL_METRICS_EXPORTER",
         "value": "none"
       },
       {
         "name": "OTEL_EXPORTER_OTLP_PROTOCOL",
         "value": "http/protobuf"
       },
       {
         "name": "OTEL_AWS_APPLICATION_SIGNALS_ENABLED",
         "value": "true"
       },
       {
         "name": "OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT",
         "value": "http://localhost:4316/v1/metrics"
       },
       {
         "name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
         "value": "http://localhost:4316/v1/traces"
       },
       {
         "name": "OTEL_TRACES_SAMPLER",
         "value": "xray"
       },
       {
         "name": "OTEL_TRACES_SAMPLER_ARG",
         "value": "endpoint=http://localhost:2000"
       },
       {
         "name": "NODE_OPTIONS",
         "value": "--require /otel-auto-instrumentation-node/autoinstrumentation.js"
       }
       ],
     "mountPoints": [
       {
         "sourceVolume": "opentelemetry-auto-instrumentation-node",
         "containerPath": "/otel-auto-instrumentation-node",
         "readOnly": false
       }
     ],
     "dependsOn": [
       {
         "containerName": "init",
         "condition": "SUCCESS"
       }
     ]
   }
   ```

1. （可选）要启用日志关联，请在挂载卷之前执行以下操作。在`OTEL_RESOURCE_ATTRIBUTES` 中，为应用程序的日志组设置其他环境变量 `aws.log.group.names`。这样，应用程序的跟踪和指标便可与这些特定日志组的相关日志条目相关联。对于此变量，将 *\$1YOUR\$1APPLICATION\$1LOG\$1GROUP* 替换为应用程序的日志组名称。如果您有多个日志组，则可以使用和号（`&`）分隔它们，如以下示例所示：`aws.log.group.names=log-group-1&log-group-2`。要启用指标与日志关联的功能，设置此当前环境变量已足够。有关更多信息，请参阅 [启用指标与日志关联](Application-Signals-MetricLogCorrelation.md)。要启用跟踪与日志关联，您还需要更改应用程序中的日志记录配置。有关更多信息，请参阅 [启用跟踪与日志关联](Application-Signals-TraceLogCorrelation.md)。

   示例如下：使用此示例可在您挂载于此过程的步骤 1 中定义的卷 `opentelemetry-auto-instrumentation` 时启用日志关联。

   ```
   {
     "name": "my-app",
      ...
     "environment": [
       {
         "name": "OTEL_RESOURCE_ATTRIBUTES",
         "value": "aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,service.name=$SVC_NAME"
       },
       {
         "name": "OTEL_LOGS_EXPORTER",
         "value": "none"
       },
       {
         "name": "OTEL_METRICS_EXPORTER",
         "value": "none"
       },
       {
         "name": "OTEL_EXPORTER_OTLP_PROTOCOL",
         "value": "http/protobuf"
       },
       {
         "name": "OTEL_AWS_APPLICATION_SIGNALS_ENABLED",
         "value": "true"
       },
       {
         "name": "OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT",
         "value": "http://localhost:4316/v1/metrics"
       },
       {
         "name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
         "value": "http://localhost:4316/v1/traces"
       },
       {
         "name": "OTEL_TRACES_SAMPLER",
         "value": "xray"
       },
       {
         "name": "OTEL_TRACES_SAMPLER_ARG",
         "value": "endpoint=http://localhost:2000"
       },
       {
         "name": "NODE_OPTIONS",
         "value": "--require /otel-auto-instrumentation-node/autoinstrumentation.js"
       }
       ],
     "mountPoints": [
       {
         "sourceVolume": "opentelemetry-auto-instrumentation-node",
         "containerPath": "/otel-auto-instrumentation-node",
         "readOnly": false
       }
     ],
     "dependsOn": [
       {
         "containerName": "init",
         "condition": "SUCCESS"
       }
     ]
   }
   ```<a name="ECS-NodeJs-ESM"></a>

**设置采用 ESM 模块格式的 Node.js 应用程序**

我们对采用 ESM 模块格式的 Node.js 应用程序提供有限的支持。有关更多信息，请参阅 [使用 ESM 的 Node.js 的已知限制](CloudWatch-Application-Signals-supportmatrix.md#ESM-limitations)。

对于 ESM 模块格式，使用 `init` 容器注入 Node.js 检测 SDK 不适用。要为使用 ESM 的 Node.js 应用程序启用 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
   ```

1. 在之前程序的步骤 5 和 6 中，删除卷 `opentelemetry-auto-instrumentation-node` 的挂载：

   ```
    "mountPoints": [
       {
           "sourceVolume": "opentelemetry-auto-instrumentation-node",
           "containerPath": "/otel-auto-instrumentation-node",
           "readOnly": false
       }
    ]
   ```

   请将节点替换为以下内容。

   ```
   {
       "name": "NODE_OPTIONS",
       "value": "--import @aws/aws-distro-opentelemetry-node-autoinstrumentation/register --experimental-loader=@opentelemetry/instrumentation/hook.mjs"
   }
   ```

------

## 步骤 5：部署应用程序
<a name="CloudWatch-Application-Signals-Enable-ECS-Deploy"></a>

创建任务定义的新修订版并将其部署到您的应用程序集群。您应该在新创建的任务中看到三个容器：
+ `init` – Application Signals 初始化所必需的容器。
+ `ecs-cwagent` – 运行 CloudWatch 代理的容器
+ `my-app` – 这是我们文档中的示例应用程序容器。在实际工作负载中，此特定的容器可能不存在，或者可能被您自己的服务容器所取代。

## （可选）第 6 步：监控应用程序运行状况
<a name="CloudWatch-Application-Signals-Monitor-sidecar"></a>

在 Amazon ECS 上启用应用程序后，便可监控应用程序的运行状况。有关更多信息，请参阅 [使用 Application Signals 监控应用程序的运行状况](Services.md)。