步骤 1：在账户中启用 Application Signals 步骤 2：下载并启动 CloudWatch 代理步骤 3：检测您的应用程序并将其启动

使用自定义设置在 Amazon EC2 和其他平台上启用 Application Signals

Application Signals 目前为预览版。如果您对此功能有任何反馈，可以通过 app-signals-feedback@amazon.com 联系我们。

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

以下步骤已在 Amazon EC2 实例上进行了测试，但预计也可以在支持 Amazon Distro for OpenTelemetry 的其他架构上运行。

要求

要获得对 Application Signals 的支持，您必须同时使用最新版本的 CloudWatch 代理和 Amazon Distro for OpenTelemetry 代理。
必须已在实例上安装 Amazon CLI。我们推荐 Amazon CLI 版本 2，但版本 1 应该也可以使用。有关安装 Amazon CLI 的更多信息，请参阅安装或更新 Amazon CLI 的最新版本。

重要

如果您已经在打算为 Application Signals 启用的应用程序中使用 OpenTelemetry，请在启用 Application Signals 之前参阅 OpenTelemetry 兼容性注意事项。

步骤 1：在账户中启用 Application Signals

如果您尚未在此账户中启用 Application Signals，则必须向 Application Signals 授予发现您的服务所需的权限。为此，请执行以下操作：您的账户只需执行一次该操作。

为您的应用程序启用 Application Signals

通过 https://console.aws.amazon.com/cloudwatch/ 打开 CloudWatch 控制台。
在导航窗格中，选择服务。
选择开始发现您的服务。
选中该复选框并选择开始发现服务。

首次在您的账户中完成此步骤会创建 AWSServiceRoleForCloudWatchApplicationSignals 服务相关角色。此角色授予 Application Signals 以下权限：
- xray:GetServiceGraph
- logs:StartQuery
- logs:GetQueryResults
- cloudwatch:GetMetricData
- cloudwatch:ListMetrics
- tag:GetResources
有关该角色的更多信息，请参阅 CloudWatch Application Signals 的服务相关角色权限。

步骤 2：下载并启动 CloudWatch 代理

作为在 Amazon EC2 实例上启用 Application Signals 的一部分安装 CloudWatch 代理

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

有关下载 CloudWatch 代理的信息，请参阅下载 CloudWatch 代理软件包。
启动 CloudWatch 代理之前，请将其配置为启用 Application Signals。以下示例是 CloudWatch 代理配置，该配置为 EC2 主机上的指标和跟踪启用 Application Signals。

您可以通过输入以下命令来创建该文件：
```
vim amazon-cloudwatch-agent.json
```
添加以下内容作为该文件的内容。
```
{
  "traces": {
    "traces_collected": {
      "app_signals": {}
    }
  },
  "logs": {
    "metrics_collected": {
      "app_signals": {}
    }
  }
}
```
将 CloudWatchAgentServerPolicy 和 AWSXrayWriteOnlyAccess IAM policy 附加到您的 Amazon EC2 实例的 IAM 角色。
1. 登录 Amazon Web Services Management Console，然后使用以下网址打开 IAM 控制台：https://console.aws.amazon.com/iam/。
2. 选择角色并查找您的 Amazon EC2 实例使用的角色。然后选择该角色的名称。
3. 在权限选项卡中，选择添加权限、附加策略。
4. 查找 CloudWatchAgentServerPolicy。如果需要，请使用搜索框。然后选择该策略对应的复选框，选择添加权限。
5. 查找 AWSXrayWriteOnlyAccess。如果需要，请使用搜索框。然后选择该策略对应的复选框，选择添加权限。
通过输入以下命令启动 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:$CONFIG_FILE_PATH
```

步骤 3：检测您的应用程序并将其启动

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

Java

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

下载最新版本的 Amazon Distro for OpenTelemetry Java 自动检测代理。您可以使用此链接下载最新版本。您可以在 aws-otel-java-instrumentation 版本上查看有关所有已发布版本的信息。
要优化 Application Signals 的优势，请在启动应用程序之前使用环境变量提供更多信息。此信息将显示在 Application Signals 控制面板中。
1. 对于 OTEL_RESOURCE_ATTRIBUTES 变量，将以下信息指定为键值对：
  - aws.hostedin.environment 设置应用程序运行所在的环境。这将作为应用程序的托管环境显示在 Application Signals 控制面板中。此属性键仅供 Application Signals 使用，并转换为 X-Ray 跟踪注释和 CloudWatch 指标维度。如果您不提供此键的值，将使用默认值 Generic。
  - service.name 设置服务的名称。这将作为应用程序的服务名称显示在 Application Signals 控制面板中。如果您不提供此键的值，将使用默认值 unknown_service。
2. 对于 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 变量，指定要将跟踪导出到的基本端点 URL。CloudWatch 代理将 4315 作为其 OLTP 端口公开。在 Amazon EC2 上，由于应用程序与本地 CloudWatch 代理通信，因此您应将此值设置为 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4315
3. 对于 OTEL_AWS_APP_SIGNALS_EXPORTER_ENDPOINT 变量，指定要将指标导出到的基本端点 URL。CloudWatch 代理将 4315 作为其 OLTP 端口公开。在 Amazon EC2 上，由于应用程序与本地 CloudWatch 代理通信，因此您应将此值设置为 OTEL_AWS_APP_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4315
4. 对于 JAVA_TOOL_OPTIONS 变量，指定存储 Amazon Distro for OpenTelemetry Java 自动检测代理的路径。
```
export JAVA_TOOL_OPTIONS=' -javaagent:$ADOT_AGENT_PATH'
```
  例如：
```
export ADOT_AGENT_PATH=./aws-opentelemetry-agent.jar
```
5. 对于 OTEL_METRICS_EXPORTER 变量，我们建议您将该值设置为 none。这将禁用其他指标导出程序，因此仅使用 Application Signals 导出程序。
6. 对于 OTEL_AWS_APP_SIGNALS_ENABLED 变量，通过将 OTEL_AWS_APP_SIGNALS_ENABLED 设置为 true 来启用 SpanMetricProcessor（SMP）。这会从跟踪中生成 Application Signals 指标。

使用上一步中讨论的环境变量启动应用程序。以下是启动脚本的示例。


JAVA_TOOL_OPTIONS=' -javaagent:$ADOT_AGENT_PATH' \
OTEL_METRICS_EXPORTER=none \
OTEL_AWS_APP_SIGNALS_ENABLED=true \
OTEL_AWS_APP_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4315 \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4315 \
OTEL_RESOURCE_ATTRIBUTES=aws.hostedin.environment=$YOUR_HOST_ENV,service.name=$YOUR_SVC_NAME \
java -jar $MY_JAVA_APP.jar

Python

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

下载最新版本的 Amazon Distro for OpenTelemetry Python 自动检测代理。通过运行以下命令安装它。
```
pip install aws-opentelemetry-distro
```
您可以在 Amazon Distro for OpenTelemetry Python instrumentation 上查看有关所有已发布版本的信息。
要优化 Application Signals 的优势，请在启动应用程序之前使用环境变量提供更多信息。此信息将显示在 Application Signals 控制面板中。
1. 对于 OTEL_RESOURCE_ATTRIBUTES 变量，将以下信息指定为键值对：
  - aws.hostedin.environment 设置应用程序运行所在的环境。这将作为应用程序的托管环境显示在 Application Signals 控制面板中。此属性键仅供 Application Signals 使用，并转换为 X-Ray 跟踪注释和 CloudWatch 指标维度。如果您不提供此键的值，将使用默认值 Generic。
  - service.name 设置服务的名称。这将作为应用程序的服务名称显示在 Application Signals 控制面板中。如果您不提供此键的值，将使用默认值 unknown_service。
2. 对于 OTEL_EXPORTER_OTLP_PROTOCOL 变量，指定 http/protobuf 以通过 HTTP 将遥测数据导出到以下步骤中列出的 CloudWatch 代理端点。
3. 对于 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 变量，指定要将跟踪导出到的基本端点 URL。CloudWatch 代理将 4316 作为其 HTTP 上的 OLTP 端口公开。在 Amazon EC2 上，由于应用程序与本地 CloudWatch 代理通信，因此您应将此值设置为 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces
4. 对于 OTEL_AWS_APP_SIGNALS_EXPORTER_ENDPOINT 变量，指定要将指标导出到的基本端点 URL。CloudWatch 代理将 4316 作为其 HTTP 上的 OLTP 端口公开。在 Amazon EC2 上，由于应用程序与本地 CloudWatch 代理通信，因此您应将此值设置为 OTEL_AWS_APP_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics
5. 对于 OTEL_METRICS_EXPORTER 变量，我们建议您将该值设置为 none。这将禁用其他指标导出程序，因此仅使用 Application Signals 导出程序。
6. 对于 OTEL_AWS_APP_SIGNALS_ENABLED 变量，通过将 OTEL_AWS_APP_SIGNALS_ENABLED 设置为 true 来启用 SpanMetricProcessor。这会从跟踪中生成 Application Signals 指标。
使用上一步中讨论的环境变量启动应用程序。以下是启动脚本的示例。
- 将 $HOST_ENV 替换为运行应用程序的主机环境。这将作为应用程序的托管环境在 Application Signals 控制面板中显示。
- 将 $SVC_NAME 替换为您的应用程序的名称。这将作为应用程序的名称在 Application Signals 控制面板中显示。
- 将 $PYTHON_APP 替换为您的应用程序的位置和名称。
```
OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORTER=none \
OTEL_AWS_APP_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_APP_SIGNALS_EXPORTER_ENDPOINT=http://localhost:4316/v1/metrics \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces \
OTEL_RESOURCE_ATTRIBUTES=aws.hostedin.environment=$HOST_ENV,service.name=$SVC_NAME \ 
opentelemetry-instrument python $PYTHON_APP.py
```
在为 Python 应用程序启用 Application Signals 之前，请注意以下注意事项。
- 在某些容器化应用程序中，缺少 PYTHONPATH 环境变量有时可能会导致应用程序无法启动。要解决此问题，请确保将 PYTHONPATH 环境变量设置为应用程序工作目录的位置。这是由于 OpenTelemetry 自动检测的已知问题造成的。有关此问题的更多信息，请参阅 Python autoinstrumentation setting of PYTHONPATH is not compliant（PYTHONPATH 的 Python 自动检测设置不兼容）。
- 对于 Django 应用程序，还有其他必需的配置，这些配置在 OpenTelemetry Python 文档中进行了概述。
  - 使用 --noreload 标志可防止自动重新加载。
  - 将 DJANGO_SETTINGS_MODULE 环境变量设置为 Django 应用程序 settings.py 文件的位置。这样可确保 OpenTelemetry 能够正确访问您的 Django 设置，并与之集成。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

使用自定义设置在 Amazon ECS 上启用 Application Signals

对 Application Signals 安装进行问题排查