# 在 Amazon EC2 上启用应用程序
<a name="CloudWatch-Application-Signals-Enable-EC2Main"></a>

遵照本部分的自定义设置步骤，在 Amazon EC2 上启用 CloudWatch Application Signals。

对于在 Amazon EC2 上运行的应用程序，您可以自行安装并配置 CloudWatch 代理和 AWS Distro for OpenTelemetry。在这些启用了自定义 Application Signals 设置的架构上，Application Signals 不会自动发现您的服务的名称或运行这些服务的主机或集群。您必须在自定义设置期间指定这些名称，而您指定的名称就是显示在 Application Signals 控制面板上的名称。

本节中的说明适用于 Java、Python 和 .NET 应用程序。这些步骤已在 Amazon EC2 实例上进行了测试，但预计也可以在支持 AWS Distro for OpenTelemetry 的其他架构上运行。

**要求**
+ 要获得对 Application Signals 的支持，您必须同时使用最新版本的 CloudWatch 代理和 AWS Distro for OpenTelemetry 代理。
+ 必须已在实例上安装 AWS CLI。我们推荐 AWS CLI 版本 2，但版本 1 应该也可以使用。有关安装 AWS CLI 的更多信息，请参阅[安装或更新 AWS CLI 的最新版本](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。

**重要**  
如果您已经在打算为 Application Signals 启用的应用程序中使用 OpenTelemetry，请在启用 Application Signals 之前参阅 [支持的系统](CloudWatch-Application-Signals-supportmatrix.md)。

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

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

## 步骤 2：下载并启动 CloudWatch 代理
<a name="CloudWatch-Application-Signals-Enable-Other-agent"></a>

**作为在 Amazon EC2 实例或本地主机上启用 Application Signals 的一部分安装 CloudWatch 代理**

1. 将最新版本的 CloudWatch 代理下载到实例。如果实例已安装 CloudWatch 代理，您可能需要对其进行更新。只有在 2023 年 11 月 30 日或之后发布的代理版本支持 CloudWatch Application Signals。

1. 启动 CloudWatch 代理之前，请将其配置为启用 Application Signals。以下示例是 CloudWatch 代理配置，该配置为 EC2 主机上的指标和跟踪启用 Application Signals。

   建议您将此文件放在 Linux 系统中的 `/opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.json`。

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

1. 将 **CloudWatchAgentServerPolicy** IAM 策略附加到 Amazon EC2 实例的 IAM 角色。有关本地主机的权限，请参阅 [本地服务器的权限](#Enable-OnPremise-Permissions)。

   1. 登录 AWS 管理控制台，然后通过以下网址打开 IAM 控制台：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。

   1. 选择**角色**并查找您的 Amazon EC2 实例使用的角色。然后选择该角色的名称。

   1. 在**权限**选项卡中，选择**添加权限**、**附加策略**。

   1. 查找 **CloudWatchAgentServerPolicy**。如果需要，请使用搜索框。然后选择该策略对应的复选框，选择**添加权限**。

1. 通过输入以下命令启动 CloudWatch 代理。将 *agent-config-file-path* 替换为指向 CloudWatch 代理配置文件的路径，例如 `./amazon-cloudwatch-agent.json`。必须包含 `file:` 前缀，如图所示。

   ```
   export CONFIG_FILE_PATH=./amazon-cloudwatch-agent.json
   ```

   ```
   sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl \
   -a fetch-config \
   -m ec2 -s -c file:agent-config-file-path
   ```

### 本地服务器的权限
<a name="Enable-OnPremise-Permissions"></a>

对于本地主机，您需要为设备提供 AWS 授权。

**设置本地主机的权限**

1. 创建用于向本地主机提供权限的 IAM 用户：

   1. 通过 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 打开 IAM 控制台。

   1. 依次选择**用户**、**创建用户**。

   1. 在**用户详情**中，为**用户名**输入新 IAM 用户的名称。这是 AWS 的登录名，将用于对您的主机进行身份验证。然后选择**下一个**

   1. 在**设置权限**页面的**权限选项**下，选择**直接附加策略**。

   1. 从**权限策略**列表中，选择要添加到您的用户的 **CloudWatchAgentServerPolicy** 策略。然后选择**下一步**。

   1. 在**查看并创建**页面上，确保您对用户名满意，并且 **CloudWatchAgentServerPolicy** 策略位于**权限摘要**中。

   1. 选择 **Create user**。

1. 创建和检索您的 AWS 访问密钥和秘密密钥：

   1. 在 IAM 控制台的导航窗格中，选择**用户**，然后选择您在上一步中所创建用户的用户名。

   1.  在用户的页面上，选择**安全凭证**选项卡。然后，在**访问密钥**部分，选择**创建访问密钥**。

   1. 对于**创建访问密钥步骤 1**，选择**命令行界面 (CLI)**。

   1. 对于**创建访问密钥步骤 2**，（可选）输入标记，然后选择**下一步**。

   1. 对于**创建访问密钥步骤 3**，选择**下载.csv 文件**以保存包含您的 IAM 用户访问密钥和秘密访问密钥的 .csv 文件。您在后续步骤中需要此信息。

   1. 选择**完成**。

1. 通过输入以下命令，在本地主机中配置 AWS 凭证。将 *ACCESS\$1KEY\$1ID* 和 *SECRET\$1ACCESS\$1ID* 替换为您在上一步中下载的 .csv 文件中新生成的访问密钥和秘密访问密钥。

   ```
   $ aws configure
   AWS Access Key ID [None]: ACCESS_KEY_ID
   AWS Secret Access Key [None]: SECRET_ACCESS_ID
   Default region name [None]: MY_REGION
   Default output format [None]: json
   ```

## 步骤 3：检测您的应用程序并将其启动
<a name="CloudWatch-Application-Signals-Enable-Other-instrument"></a>

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

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

**检测 Java 应用程序，作为在 Amazon EC2 实例或本地主机上启用 Application Signals 的一部分流程**

1. 下载最新版本的 AWS Distro for OpenTelemetry Java 自动检测代理。您可以使用[此链接](https://github.com/aws-observability/aws-otel-java-instrumentation/releases/latest/download/aws-opentelemetry-agent.jar)下载最新版本。您可以在 [aws-otel-java-instrumentation 版本](https://github.com/aws-observability/aws-otel-java-instrumentation/releases)上查看有关所有已发布版本的信息。

1. 要优化 Application Signals 的优势，请在启动应用程序之前使用环境变量提供更多信息。此信息将显示在 Application Signals 控制面板中。

   1. 对于 `OTEL_RESOURCE_ATTRIBUTES` 变量，将以下信息指定为键值对：
     + （可选）`service.name` 设置服务的名称。这将作为应用程序的服务名称在 Application Signals 控制面板中显示。如果您不提供此键的值，将使用默认值 `UnknownService`。
     + （可选）`deployment.environment` 设置应用程序运行所在的环境。这将作为应用程序的**托管**环境显示在 Application Signals 控制面板中。如果您未指定此项，则使用以下默认值之一：
       + 如果这是属于自动扩缩组的实例，则将其设置为 `ec2:name-of-Auto-Scaling-group`
       + 如果这是不属于自动扩缩组的 Amazon EC2 实例，则将其设置为 `ec2:default` 
       + 如果这是本地主机，则将其设置为 `generic:default` 

       此环境变量仅供 Application Signals 使用，并转换为 X-Ray 跟踪注释和 CloudWatch 指标维度。
     + 对于 `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` 变量，指定要将跟踪导出到的基本端点 URL。CloudWatch 代理将 4316 作为其 OTLP 端口公开。在 Amazon EC2 上，由于应用程序与本地 CloudWatch 代理通信，因此您应将此值设置为 `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces`
     + 对于 `OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT` 变量，指定要将指标导出到的基本端点 URL。CloudWatch 代理将 4316 作为其 OTLP 端口公开。在 Amazon EC2 上，由于应用程序与本地 CloudWatch 代理通信，因此您应将此值设置为 `OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics`
     + 对于 `JAVA_TOOL_OPTIONS` 变量，指定存储 AWS Distro for OpenTelemetry Java 自动检测代理的路径。

       ```
       export JAVA_TOOL_OPTIONS=" -javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH"
       ```

       例如：

       ```
       export AWS_ADOT_JAVA_INSTRUMENTATION_PATH=./aws-opentelemetry-agent.jar
       ```
     + 对于 `OTEL_METRICS_EXPORTER` 变量，我们建议您将该值设置为 `none`。这将禁用其他指标导出程序，因此仅使用 Application Signals 导出程序。
     + 将 `OTEL_AWS_APPLICATION_SIGNALS_ENABLED` 设置为 `true`。这会从跟踪中生成 Application Signals 指标。

1. 使用上一步中列出的环境变量启动应用程序。以下是启动脚本的示例。
**注意**  
以下配置仅支持适用于 Java 的 AWS Distro for OpenTelemetry 自动检测代理版本 1.32.2 及更高版本。

   ```
   JAVA_TOOL_OPTIONS=" -javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH" \
   OTEL_METRICS_EXPORTER=none \
   OTEL_LOGS_EXPORTER=none \
   OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
   OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
   OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
   OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
   OTEL_RESOURCE_ATTRIBUTES="service.name=$YOUR_SVC_NAME" \
   java -jar $MY_JAVA_APP.jar
   ```

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)。

   以下是帮助启用日志关联的启动脚本示例。

   ```
   JAVA_TOOL_OPTIONS=" -javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH" \
   OTEL_METRICS_EXPORTER=none \
   OTEL_LOGS_EXPORT=none \
   OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
   OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
   OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
   OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
   OTEL_RESOURCE_ATTRIBUTES="aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,service.name=$YOUR_SVC_NAME" \
   java -jar $MY_JAVA_APP.jar
   ```

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

**注意**  
如果您在 Python 应用程序中使用 WSGI 服务器，则除了本节中的以下步骤之外，还可以参阅[使用 WSGI 服务器的 Python 应用程序没有 Application Signals 数据](CloudWatch-Application-Signals-Enable-Troubleshoot.md#Application-Signals-troubleshoot-Python-WSGI)以获取有关使 Application Signals 起作用的信息。

**检测 Python 应用程序，作为在 Amazon EC2 实例上启用 Application Signals 的一部分流程**

1. 下载最新版本的 AWS Distro for OpenTelemetry Python 自动检测代理。通过运行以下 命令安装它。

   ```
   pip install aws-opentelemetry-distro
   ```

   您可以在 [AWS Distro for OpenTelemetry Python instrumentation](https://github.com/aws-observability/aws-otel-python-instrumentation/releases) 上查看有关所有已发布版本的信息。

1. 要优化 Application Signals 的优势，请在启动应用程序之前使用环境变量提供更多信息。此信息将显示在 Application Signals 控制面板中。

   1. 对于 `OTEL_RESOURCE_ATTRIBUTES` 变量，将以下信息指定为键值对：
      + `service.name` 设置服务的名称。这将作为应用程序的服务名称显示在 Application Signals 控制面板中。如果您不提供此键的值，将使用默认值 `UnknownService`。
      + `deployment.environment` 设置应用程序运行所在的环境。这将作为应用程序的**托管**环境显示在 Application Signals 控制面板中。如果您未指定此项，则使用以下默认值之一：
        + 如果这是属于自动扩缩组的实例，则将其设置为 `ec2:name-of-Auto-Scaling-group`。
        + 如果这是不属于自动扩缩组的 Amazon EC2 实例，则将其设置为 `ec2:default` 
        + 如果这是本地主机，则将其设置为 `generic:default` 

         此属性键仅供 Application Signals 使用，并转换为 X-Ray 跟踪注释和 CloudWatch 指标维度。

   1. 对于 `OTEL_EXPORTER_OTLP_PROTOCOL` 变量，指定 `http/protobuf` 以通过 HTTP 将遥测数据导出到以下步骤中列出的 CloudWatch 代理端点。

   1. 对于 `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` 变量，指定要将跟踪导出到的基本端点 URL。CloudWatch 代理将 4316 作为其 HTTP 上的 OTLP 端口公开。在 Amazon EC2 上，由于应用程序与本地 CloudWatch 代理通信，因此您应将此值设置为 `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces`

   1. 对于 `OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT` 变量，指定要将指标导出到的基本端点 URL。CloudWatch 代理将 4316 作为其 HTTP 上的 OTLP 端口公开。在 Amazon EC2 上，由于应用程序与本地 CloudWatch 代理通信，因此您应将此值设置为 `OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics`

   1. 对于 `OTEL_METRICS_EXPORTER` 变量，我们建议您将该值设置为 `none`。这将禁用其他指标导出程序，因此仅使用 Application Signals 导出程序。

   1. 将 `OTEL_AWS_APPLICATION_SIGNALS_ENABLED` 变量设置为 `true` 以使您的容器开始向 Application Signals 发送 X-Ray 跟踪和 CloudWatch 指标。

1. 使用上一步中讨论的环境变量启动应用程序。以下是启动脚本的示例。
   + 将 `$SVC_NAME` 替换为您的应用程序的名称。这将作为应用程序的名称在 Application Signals 控制面板中显示。
   + 将 `$PYTHON_APP` 替换为您的应用程序的位置和名称。

   ```
   OTEL_METRICS_EXPORTER=none \
   OTEL_LOGS_EXPORTER=none \
   OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
   OTEL_PYTHON_DISTRO=aws_distro \
   OTEL_PYTHON_CONFIGURATOR=aws_configurator \
   OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
   OTEL_TRACES_SAMPLER=xray \
   OTEL_TRACES_SAMPLER_ARG="endpoint=http://localhost:2000" \
   OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
   OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
   OTEL_RESOURCE_ATTRIBUTES="service.name=$SVC_NAME" \
   opentelemetry-instrument python $MY_PYTHON_APP.py
   ```

   在为 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 设置，并与之集成。

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)。

   以下是帮助启用日志关联的启动脚本示例。

   ```
   OTEL_METRICS_EXPORTER=none \
   OTEL_LOGS_EXPORTER=none \
   OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
   OTEL_PYTHON_DISTRO=aws_distro \
   OTEL_PYTHON_CONFIGURATOR=aws_configurator \
   OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
   OTEL_TRACES_SAMPLER=xray \
   OTEL_TRACES_SAMPLER_ARG="endpoint=http://localhost:2000" \
   OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
   OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
   OTEL_RESOURCE_ATTRIBUTES="aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,service.name=$YOUR_SVC_NAME" \
   java -jar $MY_PYTHON_APP.jar
   ```

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

**在 Amazon EC2 实例或本地主机上启用 Application Signals 过程中仪表化 .NET 应用程序**

1. 下载最新版本适用于 OpenTelemetry 的 AWS Distro .NET 自动仪表化工具包。可以在 [aws-otel-dotnet-instrumenting Release](https://github.com/aws-observability/aws-otel-dotnet-instrumentation/releases) 上下载最新版本。

1. 要启用 Application Signals，请在启动应用程序之前设置以下环境变量以提供更多信息。在启动 .NET 应用程序之前，为 .NET 仪表化设置启动钩子将需要这些变量。将 `OTEL_RESOURCE_ATTRIBUTES` 环境变量中的 `dotnet-service-name` 替换为您选择的服务名称。
   + 以下是 Linux 的示例。

     ```
     export INSTALL_DIR=OpenTelemetryDistribution
     export CORECLR_ENABLE_PROFILING=1
     export CORECLR_PROFILER={918728DD-259F-4A6A-AC2B-B85E1B658318}
     export CORECLR_PROFILER_PATH=${INSTALL_DIR}/linux-x64/OpenTelemetry.AutoInstrumentation.Native.so
     export DOTNET_ADDITIONAL_DEPS=${INSTALL_DIR}/AdditionalDeps
     export DOTNET_SHARED_STORE=${INSTALL_DIR}/store
     export DOTNET_STARTUP_HOOKS=${INSTALL_DIR}/net/OpenTelemetry.AutoInstrumentation.StartupHook.dll
     export OTEL_DOTNET_AUTO_HOME=${INSTALL_DIR}
     
     export OTEL_DOTNET_AUTO_PLUGINS="AWS.Distro.OpenTelemetry.AutoInstrumentation.Plugin, AWS.Distro.OpenTelemetry.AutoInstrumentation"
     
     export OTEL_RESOURCE_ATTRIBUTES=service.name=dotnet-service-name
     export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
     export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4316
     export OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://127.0.0.1:4316/v1/metrics
     export OTEL_METRICS_EXPORTER=none
     export OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true
     export OTEL_TRACES_SAMPLER=xray
     export OTEL_TRACES_SAMPLER_ARG=http://127.0.0.1:2000
     ```
   + 以下示例适用于 Windows Server。

     ```
     $env:INSTALL_DIR = "OpenTelemetryDistribution"
     $env:CORECLR_ENABLE_PROFILING = 1
     $env:CORECLR_PROFILER = "{918728DD-259F-4A6A-AC2B-B85E1B658318}"
     $env:CORECLR_PROFILER_PATH = Join-Path $env:INSTALL_DIR "win-x64/OpenTelemetry.AutoInstrumentation.Native.dll"
     $env:DOTNET_ADDITIONAL_DEPS = Join-Path $env:INSTALL_DIR "AdditionalDeps"
     $env:DOTNET_SHARED_STORE = Join-Path $env:INSTALL_DIR "store"
     $env:DOTNET_STARTUP_HOOKS = Join-Path $env:INSTALL_DIR "net/OpenTelemetry.AutoInstrumentation.StartupHook.dll"
     $env:OTEL_DOTNET_AUTO_HOME = $env:INSTALL_DIR
     
     $env:OTEL_DOTNET_AUTO_PLUGINS = "AWS.Distro.OpenTelemetry.AutoInstrumentation.Plugin, AWS.Distro.OpenTelemetry.AutoInstrumentation"
     
     $env:OTEL_RESOURCE_ATTRIBUTES = "service.name=dotnet-service-name"
     $env:OTEL_EXPORTER_OTLP_PROTOCOL = "http/protobuf"
     $env:OTEL_EXPORTER_OTLP_ENDPOINT = "http://127.0.0.1:4316"
     $env:OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT = "http://127.0.0.1:4316/v1/metrics"
     $env:OTEL_METRICS_EXPORTER = "none"
     $env:OTEL_AWS_APPLICATION_SIGNALS_ENABLED = "true"
     $env:OTEL_TRACES_SAMPLER = "xray"
     $env:OTEL_TRACES_SAMPLER_ARG = "http://127.0.0.1:2000"
     ```

1. 使用上一步中列出的环境变量启动应用程序。

   （可选）或者，您可以使用提供的安装脚本来帮助安装和设置 AWS Distro for OpenTelemetry .NET 自动检测包。

   对于 Linux，请从 GitHub 发布页面下载并安装 Bash 安装脚本：

   ```
   # Download and Install
   curl -L -O https://github.com/aws-observability/aws-otel-dotnet-instrumentation/releases/latest/download/aws-otel-dotnet-install.sh
   chmod +x ./aws-otel-dotnet-install.sh
   ./aws-otel-dotnet-install.sh
   
   # Instrument
   . $HOME/.otel-dotnet-auto/instrument.sh
   export OTEL_RESOURCE_ATTRIBUTES=service.name=dotnet-service-name
   ```

   对于 Windows Server，请从 GitHub 发布页面下载并安装 PowerShell 安装脚本：

   ```
   # Download and Install
   $module_url = "https://github.com/aws-observability/aws-otel-dotnet-instrumentation/releases/latest/download/AWS.Otel.DotNet.Auto.psm1"
   $download_path = Join-Path $env:temp "AWS.Otel.DotNet.Auto.psm1"
   Invoke-WebRequest -Uri $module_url -OutFile $download_path
   Import-Module $download_path
   Install-OpenTelemetryCore
   
   # Instrument
   Import-Module $download_path
   Register-OpenTelemetryForCurrentSession -OTelServiceName "dotnet-service-name"
   Register-OpenTelemetryForIIS
   ```

   您可以在[官方 NuGet 存储库](https://www.nuget.org/packages/AWS.Distro.OpenTelemetry.AutoInstrumentation)中找到 AWS Distro for OpenTelemetry .NET 自动检测包的 NuGet 包。请务必查看[自述文件](https://github.com/aws-observability/aws-otel-dotnet-instrumentation/blob/main/src/AWS.Distro.OpenTelemetry.AutoInstrumentation/nuget-readme.md)以获取说明。

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

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

**检测 Node.js 应用程序，作为在 Amazon EC2 实例上启用 Application Signals 的一部分流程**

1. 下载适用于 Node.js 的最新版本的 AWS Distro for OpenTelemetry JavaScript 自动检测代理。通过运行以下 命令安装它。

   ```
   npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation
   ```

   您可以在 [AWS Distro for OpenTelemetry JavaScript 检测工具](https://github.com/aws-observability/aws-otel-js-instrumentation/releases)上查看有关所有已发布版本的信息。

1. 要优化 Application Signals 的优势，请在启动应用程序之前使用环境变量提供更多信息。此信息将显示在 Application Signals 控制面板中。

   1. 对于 `OTEL_RESOURCE_ATTRIBUTES` 变量，将以下信息指定为键值对：
      + `service.name` 设置服务的名称。这将作为应用程序的服务名称显示在 Application Signals 控制面板中。如果您不提供此键的值，将使用默认值 `UnknownService`。
      + `deployment.environment` 设置应用程序运行所在的环境。这将作为应用程序的**托管**环境显示在 Application Signals 控制面板中。如果您未指定此项，则使用以下默认值之一：
        + 如果这是属于自动扩缩组的实例，则将其设置为 `ec2:name-of-Auto-Scaling-group`。
        + 如果这是不属于自动扩缩组的 Amazon EC2 实例，则将其设置为 `ec2:default` 
        + 如果这是本地主机，则将其设置为 `generic:default` 

         此属性键仅供 Application Signals 使用，并转换为 X-Ray 跟踪注释和 CloudWatch 指标维度。

   1. 对于 `OTEL_EXPORTER_OTLP_PROTOCOL` 变量，指定 `http/protobuf` 以通过 HTTP 将遥测数据导出到以下步骤中列出的 CloudWatch 代理端点。

   1. 对于 `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` 变量，指定要将跟踪导出到的基本端点 URL。CloudWatch 代理将 4316 作为其 HTTP 上的 OTLP 端口公开。在 Amazon EC2 上，由于应用程序与本地 CloudWatch 代理通信，因此您应将此值设置为 `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces`

   1. 对于 `OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT` 变量，指定要将指标导出到的基本端点 URL。CloudWatch 代理将 4316 作为其 HTTP 上的 OTLP 端口公开。在 Amazon EC2 上，由于应用程序与本地 CloudWatch 代理通信，因此您应将此值设置为 `OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics`

   1. 对于 `OTEL_METRICS_EXPORTER` 变量，我们建议您将该值设置为 `none`。这将禁用其他指标导出程序，因此仅使用 Application Signals 导出程序。

   1. 将 `OTEL_AWS_APPLICATION_SIGNALS_ENABLED` 变量设置为 `true` 以使您的容器开始向 Application Signals 发送 X-Ray 跟踪和 CloudWatch 指标。

1. 使用上一步中讨论的环境变量启动应用程序。以下是启动脚本的示例。
   + 将 `$SVC_NAME` 替换为您的应用程序的名称。这将作为应用程序的名称在 Application Signals 控制面板中显示。

   ```
   OTEL_METRICS_EXPORTER=none \
   OTEL_LOGS_EXPORTER=none \
   OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
   OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
   OTEL_TRACES_SAMPLER=xray \
   OTEL_TRACES_SAMPLER_ARG="endpoint=http://localhost:2000" \
   OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
   OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
   OTEL_RESOURCE_ATTRIBUTES="service.name=$SVC_NAME" \
   node --require '@aws/aws-distro-opentelemetry-node-autoinstrumentation/register' your-application.js
   ```

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)。

   以下是帮助启用日志关联的启动脚本示例。

   ```
   export OTEL_METRICS_EXPORTER=none \
   export OTEL_LOGS_EXPORTER=none \
   export OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true \
   export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
   export OTEL_TRACES_SAMPLER=xray \
   export OTEL_TRACES_SAMPLER_ARG=endpoint=http://localhost:2000 \
   export OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
   export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
   export OTEL_RESOURCE_ATTRIBUTES="aws.log.group.names=$YOUR_APPLICATION_LOG_GROUP,service.name=$SVC_NAME" \
   node --require '@aws/aws-distro-opentelemetry-node-autoinstrumentation/register' your-application.js
   ```<a name="EC2-NodeJs-ESM"></a>

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

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

为使用 ESM 的 Node.js 应用程序启用 Application Signals，您需要修改之前程序中的步骤。

首先，为您的 Node.js 应用程序安装 `@opentelemetry/instrumentation`：

```
npm install @opentelemetry/instrumentation@0.54.0
```

然后，在之前程序的步骤 3 和 4 中，将节点选项从：

```
--require '@aws/aws-distro-opentelemetry-node-autoinstrumentation/register'
```

更改为以下内容：

```
--import @aws/aws-distro-opentelemetry-node-autoinstrumentation/register --experimental-loader=@opentelemetry/instrumentation/hook.mjs
```

------

## 使用模型上下文协议（MCP）服务器在 Amazon EC2 上启用 Application Signals
<a name="CloudWatch-Application-Signals-EC2-MCP"></a>

您可以使用 CloudWatch Application Signals 模型上下文协议（MCP）服务器，通过对话式人工智能交互，在 Amazon EC2 实例上启用 Application Signals。这为设置 Application Signals 监控提供了自然语言界面。

MCP 服务器通过理解您的需求并生成相应的配置来自动执行启用过程。您只需简单描述要启用的功能，无需手动执行设置步骤。

### 先决条件
<a name="CloudWatch-Application-Signals-EC2-MCP-Prerequisites"></a>

在使用 MCP 服务器启用 Application Signals 之前，请确保满足以下条件：
+ 支持 MCP 的开发环境（例如 Kiro、Claude Desktop、带有 MCP 扩展的 VSCode 或其他与 MCP 兼容的工具）
+ 已在 IDE 中配置 CloudWatch Application Signals MCP 服务器。有关详细的设置说明，请参阅 [CloudWatch Application Signals MCP 服务器文档](https://awslabs.github.io/mcp/servers/cloudwatch-applicationsignals-mcp-server)。

### 使用 MCP 服务器
<a name="CloudWatch-Application-Signals-EC2-MCP-Usage"></a>

在 IDE 中配置好 CloudWatch Application Signals MCP 服务器后，即可使用自然语言提示来请求启用指导。尽管编码助手可以从项目结构中推断出上下文，但在提示中提供具体细节有助于确保获得更准确、更相关的指导。包含一些信息，例如应用程序语言、实例详细信息以及基础设施和应用程序代码的绝对路径等等。

**最佳实践提示（具体且完整）：**

```
"Enable Application Signals for my Python service running on EC2.
My app code is in /home/ec2-user/flask-api and IaC is in /home/ec2-user/flask-api/terraform"

"I want to add observability to my Java application on EC2.
The application code is at /opt/apps/checkout-service and
the infrastructure code is at /opt/apps/checkout-service/cloudformation"

"Help me instrument my Node.js application on EC2 with Application Signals.
Application directory: /home/ubuntu/payment-api
Terraform code: /home/ubuntu/payment-api/terraform"
```

**效果较差的提示：**

```
"Enable monitoring for my app"
→ Missing: platform, language, paths

"Enable Application Signals. My code is in ./src and IaC is in ./infrastructure"
→ Problem: Relative paths instead of absolute paths

"Enable Application Signals for my EC2 service at /home/user/myapp"
→ Missing: programming language
```

**快速模板：**

```
"Enable Application Signals for my [LANGUAGE] service on EC2.
App code: [ABSOLUTE_PATH_TO_APP]
IaC code: [ABSOLUTE_PATH_TO_IAC]"
```

### 使用 MCP 服务器的优势
<a name="CloudWatch-Application-Signals-EC2-MCP-Benefits"></a>

使用 CloudWatch Application Signals MCP 服务器具有以下优势：
+ **自然语言界面：**无需记住命令或配置语法，即可描述要启用的功能
+ **上下文感知指导**：MCP 服务器了解特定环境并提供量身定制的建议
+ **减少错误：**自动生成配置可最大限度地减少手动输入错误
+ **更快设置：**更快地将想法过渡到实施
+ **学习工具：**查看生成的配置，了解 Application Signals 的工作原理

### 其他资源
<a name="CloudWatch-Application-Signals-EC2-MCP-MoreInfo"></a>

有关配置和使用 CloudWatch Application Signals MCP 服务器的更多信息，请参阅 [MCP 服务器文档](https://awslabs.github.io/mcp/servers/cloudwatch-applicationsignals-mcp-server)。

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

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