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

在 Amazon EC2 上启用 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 的最新版本。

重要

如果您已经在打算为 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. 登录 AWS 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
```

本地服务器的权限

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

设置本地主机的权限

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

下载最新版本的 AWS 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 变量，指定存储 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 指标。

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

注意

以下配置仅支持适用于 Java 的 AWS 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

（可选）要启用跟踪日志关联，请在 OTEL_RESOURCE_ATTRIBUTES 中为应用程序的日志组设置其他环境变量 aws.log.group.names。这样，应用程序的跟踪和指标便可与这些特定日志组的相关日志条目相关联。对于此变量，将 $YOUR_APPLICATION_LOG_GROUP 替换为应用程序的日志组名称。如果您有多个日志组，则可以使用和号（&）分隔它们，如以下示例所示：aws.log.group.names=log-group-1&log-group-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="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 数据以获取有关使 Application Signals 起作用的信息。

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

下载最新版本的 AWS Distro for OpenTelemetry Python 自动检测代理。通过运行以下命令安装它。
```
pip install aws-opentelemetry-distro
```
您可以在 AWS 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_RESOURCE_ATTRIBUTES 中为应用程序的日志组设置其他环境变量 aws.log.group.names。这样，应用程序的跟踪和指标便可与这些特定日志组的相关日志条目相关联。对于此变量，将 $YOUR_APPLICATION_LOG_GROUP 替换为应用程序的日志组名称。如果您有多个日志组，则可以使用和号（&）分隔它们，如以下示例所示：aws.log.group.names=log-group-1&log-group-2。要启用指标与日志关联的功能，设置此当前环境变量已足够。有关更多信息，请参阅启用指标与日志关联。要启用跟踪与日志关联，您还需要更改应用程序中的日志记录配置。有关更多信息，请参阅启用跟踪与日志关联。

以下是帮助启用日志关联的启动脚本示例。
```
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 应用程序

下载最新版本适用于 OpenTelemetry 的 AWS Distro .NET 自动仪表化工具包。可以在 aws-otel-dotnet-instrumenting Release 上下载最新版本。

要启用 Application Signals，请在启动应用程序之前设置以下环境变量以提供更多信息。在启动 .NET 应用程序之前，为 .NET 仪表化设置启动钩子将需要这些变量。

以下是 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=aws-otel-integ-test
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=aws-otel-integ-test"
$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"

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

（可选）或者，您可以使用提供的安装脚本来帮助安装和设置 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"

您可以在官方 NuGet 存储库中找到 AWS Distro for OpenTelemetry .NET 自动检测包的 NuGet 包。请务必查看自述文件以获取说明。

Node.js

注意

要为使用 ESM 的 Node.js 应用程序启用 Application Signals，在开始这些步骤之前请参阅Setting up a Node.js application with the ESM module format。

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

下载适用于 Node.js 的最新版本的 AWS Distro for OpenTelemetry JavaScript 自动检测代理。通过运行以下命令安装它。
```
npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation
```
您可以在 AWS Distro for OpenTelemetry JavaScript 检测工具上查看有关所有已发布版本的信息。
要优化 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 控制面板中显示。


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

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

以下是帮助启用日志关联的启动脚本示例。
```
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
```

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

我们对采用 ESM 模块格式的 Node.js 应用程序提供有限的支持。有关详细信息，请参阅使用 ESM 的 Node.js 的已知限制。

为使用 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

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

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

文档惯例

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

在 Kubernetes 平台上启用 Application Signals