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

在 Amazon EC2 上启用 Application Signals

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

本节中的说明适用于 Java 应用程序和 Python 应用程序。这些步骤已在 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 控制台。
在导航窗格中，选择服务。
选择开始发现您的服务。
选中该复选框并选择开始发现您的服务。

首次在您的账户中完成此步骤时，Application Signals 会创建 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。

建议您将此文件放在 Linux 系统中的 /opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.json。
```
{
  "traces": {
    "traces_collected": {
      "application_signals": {}
    }
  },
  "logs": {
    "metrics_collected": {
      "application_signals": {}
    }
  }
}
```
将 CloudWatchAgentServerPolicy IAM 策略附加到 Amazon EC2 实例的 IAM 角色。有关本地主机的权限，请参阅本地服务器的权限。
1. 登录 Amazon Web Services Management Console，然后通过以下网址打开 IAM 控制台：https://console.aws.amazon.com/iam/。
2. 选择角色并查找您的 Amazon EC2 实例使用的角色。然后选择该角色的名称。
3. 在权限选项卡中，选择添加权限、附加策略。
4. 查找 CloudWatchAgentServerPolicy。如果需要，请使用搜索框。然后选择该策略对应的复选框，选择添加权限。
通过输入以下命令启动 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
```

本地服务器的权限

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

设置本地主机的权限

创建用于向本地主机提供权限的 IAM 用户：
1. 通过 https://console.aws.amazon.com/iam/ 打开 IAM 控制台。
2. 依次选择用户、创建用户。
3. 在用户详情中，为用户名输入新 IAM 用户的名称。这是 Amazon 的登录名，将用于对您的主机进行身份验证。然后选择下一个
4. 在设置权限页面的权限选项下，选择直接附加策略。
5. 从权限策略列表中，选择要添加到您的用户的 CloudWatchAgentServerPolicy 策略。然后选择下一步。
6. 在查看并创建页面上，确保您对用户名满意，并且 CloudWatchAgentServerPolicy 策略位于权限摘要中。
7. 选择 Create user。
创建和检索您的 Amazon 访问密钥和秘密密钥：
1. 在 IAM 控制台的导航窗格中，选择用户，然后选择您在上一步中所创建用户的用户名。
2. 在用户的页面上，选择安全凭证选项卡。然后，在访问密钥部分，选择创建访问密钥。
3. 对于创建访问密钥步骤 1，选择命令行界面 (CLI)。
4. 对于创建访问密钥步骤 2，（可选）输入标记，然后选择下一步。
5. 对于创建访问密钥步骤 3，选择下载.csv 文件以保存包含您的 IAM 用户访问密钥和秘密访问密钥的 .csv 文件。您在后续步骤中需要此信息。
6. 选择完成。
通过输入以下命令，在本地主机中配置 Amazon 凭证。将 ACCESS_KEY_ID 和 SECRET_ACCESS_ID 替换为您在上一步中下载的 .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：检测您的应用程序并将其启动

下一步是为 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 变量，将以下信息指定为键值对：
  - （可选）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 变量，指定存储 Amazon 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 指标。

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

注意

以下配置仅支持适用于 Java 的 Amazon Distro for OpenTelemetry 自动检测代理版本 1.32.2 及更高版本。


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=service.name=$YOUR_SVC_NAME \
java -jar $MY_JAVA_APP.jar

（可选）要启用跟踪日志关联，请将其他环境变量 aws.log.group.names 设置为应用程序日志的日志组名称。然后，应用程序的跟踪便可与该特定日志组的相关日志条目相关联。要启用跟踪日志关联，您还需要更改应用程序中的日志记录配置。有关更多信息，请参阅启用跟踪日志关联。

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


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 应用程序，作为在 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 变量，将以下信息指定为键值对：
  - 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 指标维度。
2. 对于 OTEL_EXPORTER_OTLP_PROTOCOL 变量，指定 http/protobuf 以通过 HTTP 将遥测数据导出到以下步骤中列出的 CloudWatch 代理端点。
3. 对于 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 变量，指定要将跟踪导出到的基本端点 URL。CloudWatch 代理将 4316 作为其 HTTP 上的 OTLP 端口公开。在 Amazon EC2 上，由于应用程序与本地 CloudWatch 代理通信，因此您应将此值设置为 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4316/v1/traces
4. 对于 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
5. 对于 OTEL_METRICS_EXPORTER 变量，我们建议您将该值设置为 none。这将禁用其他指标导出程序，因此仅使用 Application Signals 导出程序。
6. 将 OTEL_AWS_APPLICATION_SIGNALS_ENABLED 变量设置为 true 以使您的容器开始向 Application Signals 发送 X-Ray 跟踪和 CloudWatch 指标。
使用上一步中讨论的环境变量启动应用程序。以下是启动脚本的示例。
- 将 $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（PYTHONPATH 的 Python 自动检测设置不兼容）。
- 对于 Django 应用程序，还有其他必需的配置，这些配置在 OpenTelemetry Python 文档中进行了概述。
  - 使用 --noreload 标志可防止自动重新加载。
  - 将 DJANGO_SETTINGS_MODULE 环境变量设置为 Django 应用程序 settings.py 文件的位置。这样可确保 OpenTelemetry 能够正确访问您的 Django 设置，并与之集成。

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


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,aws.hostedin.environment=$YOUR_HOST_ENV,service.name=$YOUR_SVC_NAME \ 
java -jar $MY_PYTHON_APP.jar

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

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

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

在 Kubernetes 平台上启用 Application Signals