使用 AWS Distro for OpenTelemetry（ADOT）SDK 导出无收集器模式的追踪数据 - Amazon CloudWatch
先决条件为 Amazon EC2 设置 IAM 权限设置本地主机的 IAM 权限启用 ADOT SDK

使用 AWS Distro for OpenTelemetry（ADOT）SDK 导出无收集器模式的追踪数据

可以使用 ADOT SDK 以无收集器模式直接将追踪数据发送到 OTLP 端点（用于追踪数据）。

注意

默认情况下，当您启用 Transaction Search 时，Application Signals 将启用。AWS Distro for OpenTelemetry 不支持 Application Signals，必须将其禁用。

先决条件

请确保启用 Transaction Search，以向 X-ray OTLP 端点发送跨度。有关更多信息，请参阅开始使用 Transaction Search。

为 Amazon EC2 设置 IAM 权限

按照以下步骤将 AWSXrayWriteOnlyPolicy IAM 策略附加到 Amazon EC2 实例的 IAM 角色。

  1. 通过 https://console.aws.amazon.com/cloudwatch/ 打开 CloudWatch 控制台。

  2. 选择角色，查找并选择您的 Amazon EC2 实例使用的角色。

  3. 在权限选项卡下，依次选择添加权限、附加策略。

  4. 使用搜索框，搜索 AWSXrayWriteOnlyPolicy 策略。

  5. 选择 AWSXrayWriteOnlyPolicy 策略，然后选择添加权限。

设置本地主机的 IAM 权限

遵照以下步骤创建可用于向本地主机提供权限的 IAM 用户。

  1. 通过 https://console.aws.amazon.com/cloudwatch/ 打开 CloudWatch 控制台。

  2. 选择用户，然后选择创建用户。

  3. 依次选择用户、创建用户。

  4. 在用户详细信息下的用户名中，输入新 IAM 用户的名称。这是 AWS 的登录名，将用于对您的主机进行身份验证。

  5. 选择下一步。

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

  7. 从权限策略列表中，选择要添加到您的用户的 AWSXrayWriteOnlyPolicy 策略。

  8. 选择下一步。

  9. 在审核并创建页面上，确保您对用户名满意，并且 AWSXrayWriteOnlyPolicy 策略位于权限摘要下。

  10. 选择创建用户。

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

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

    2. 在用户的页面上，选择安全凭证选项卡。

    3. 在访问密钥部分，选择创建访问密钥。

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

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

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

    7. 选择完成。

  12. 通过输入以下命令，在本地主机中配置 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

启用 ADOT SDK

在 Java、Node.js、Python 和 .Net 上，可以将应用程序的追踪数据直接从 AWS Distro for OpenTelemetry（ADOT）SDK 发送到 OTLP 端点。

Java

  1. 下载最新版本的 AWS Distro for OpenTelemetry Java 自动检测代理。您可以使用此命令下载最新版本：

    curl -L -O https://github.com/aws-observability/aws-otel-java-instrumentation/releases/latest/download/aws-opentelemetry-agent.jar

    要查看所有已发布版本，请参阅 aws-otel-java-instrumentation 发布信息。

  2. 为了启用直接将跟踪信息发送到 X-Ray OTLP 跟踪端点的导出器并优化效益，请在启动应用程序之前使用环境变量提供其他信息。

  3. 对于 OTEL_RESOURCE_ATTRIBUTES 变量，将以下信息指定为键值对：

    （可选）service.name 设置服务的名称。这将作为应用程序的服务名称在 Application Signals 控制面板中显示。如果您不提供此键的值，则将使用默认值 UnknownService。

    （可选）deployment.environment 设置应用程序运行所在的环境。这将显示为应用程序的托管环境。如果您未指定此项，则使用以下默认值之一：

    • 如果这是属于自动扩缩组的实例，则将其设置为 ec2:name-of-Auto-Scaling-group

    • 如果这是不属于自动扩缩组的 Amazon EC2 实例，则将其设置为 ec2:default

    • 如果这是本地主机，则将其设置为 generic:default

    此环境变量仅供 Application Signals 使用，并转换为 X-Ray 跟踪注释和 CloudWatch 指标维度

  4. 对于 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 变量，指定 X-Ray OTLP 跟踪端点：https://xray.[AWSRegion].amazonaws.com/v1/traces。例如：

    export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://xray.us-west-2.amazonaws.com/v1/traces"

  5. 对于 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"

  6. 对于 OTEL_METRICS_EXPORTER 变量，建议将该值设置为 none。

  7. 对于 OTEL_LOGS_EXPORTER 变量，建议将该值设置为 none。

  8. 对于 OTEL_TRACES_EXPORTER 变量，必须为其设置 otlp 的值（这是可选操作，如果未设置此环境变量，则使用默认值）。

  9. 对于 OTEL_EXPORTER_OTLP_PROTOCOL 变量，必须将该值设置为 http/protobuf （这是可选操作，如果未设置此环境变量，则使用默认值）。X-Ray OTLP 端点目前仅支持 HTTP 协议。

  10. 您的应用程序现在应该使用 AWS Distro for OpenTelemetry Java 检测运行并将生成跨度。这些跨度存储在账户的 aws/spans CloudWatch LogsLogGroup 中。还可以在 CloudWatch 跟踪信息和指标控制台中查看与跨度相关的跟踪信息及指标。

  11. 使用您设置的环境变量启动应用程序。以下是启动脚本的示例。

    （注意：以下配置仅支持适用于 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_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://xray.us-east-1.amazonaws.com/v1/traces \
OTEL_RESOURCE_ATTRIBUTES="service.name=$YOUR_SVC_NAME" \
java -jar $MY_JAVA_APP.jar
Node.js

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

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

    要查看所有已发布版本的信息，请参阅 AWS Distro for OpenTelemetry JavaScript 检测资料。

  2. 为了启用导出器以直接将跟踪信息发送到 X-Ray OTLP 端点并优化效益，请在启动应用程序之前使用环境变量提供其他信息。

  3. 对于 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 指标维度。

  4. 对于 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 变量，指定 X-Ray OTLP 跟踪端点：https://xray.[AWSRegion].amazonaws.com/v1/traces。

    例如：

    export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://xray.us-west-2.amazonaws.com/v1/traces"

  5. 对于 OTEL_METRICS_EXPORTER 变量，建议将该值设置为 none。Application Signals 指标由 OTLP 端点生成。

  6. 对于 OTEL_LOGS_EXPORTER 变量，建议将该值设置为 none。

  7. 对于 OTEL_TRACES_EXPORTER 变量，必须为其设置 otlp 的值（这是可选操作，如果未设置此环境变量，则使用默认值）。

  8. 对于 OTEL_EXPORTER_OTLP_PROTOCOL 变量，必须将该值设置为 http/protobuf （这是可选操作，如果未设置此环境变量，则使用默认值）。X-Ray OTLP 端点目前仅支持 HTTP 协议。

  9. 您的应用程序现在应该使用 AWS Distro for OpenTelemetry Java 检测运行并将生成跨度。这些跨度存储在账户的 aws/spans CloudWatch LogsLogGroup 中。还可以在 CloudWatch 跟踪信息和指标控制台中查看与跨度相关的跟踪信息及指标。

  10. 使用您设置的环境变量启动应用程序。以下是启动脚本的示例。

    （注意：将 $SVC_NAME 替换为您的应用程序的名称。此值将显示为您的应用程序的名称。

    OTEL_METRICS_EXPORTER=none \
OTEL_LOGS_EXPORTER=none \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://xray.us-east-1.amazonaws.com/v1/traces \
OTEL_RESOURCE_ATTRIBUTES="service.name=$SVC_NAME" \
node —require '@aws/aws-distro-opentelemetry-node-autoinstrumentation/register' your-application.js
Python

  1. 下载最新版本的 AWS Distro for OpenTelemetry Python 自动检测代理。可以使用以下命令进行安装：

    pip install aws-opentelemetry-distro

  2. 为了启用导出器以直接将跟踪信息发送到 X-Ray OTLP 端点并优化效益，请在启动应用程序之前使用环境变量提供其他信息。

  3. 对于 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 指标维度。

  4. 对于 OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 变量，指定 X-Ray OTLP 跟踪端点：https://xray.[AWSRegion].amazonaws.com/v1/traces。

    例如：

    export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://xray.us-west-2.amazonaws.com/v1/traces"

  5. 对于 OTEL_METRICS_EXPORTER 变量，建议将该值设置为 none。Application Signals 指标由 OTLP 端点生成。

  6. 对于 OTEL_LOGS_EXPORTER 变量，建议将该值设置为 none。

  7. 对于 OTEL_TRACES_EXPORTER 变量，必须为其设置 otlp 的值（这是可选操作，如果未设置此环境变量，则使用默认值）。

  8. 对于 OTEL_EXPORTER_OTLP_PROTOCOL 变量，必须将该值设置为 http/protobuf （这是可选操作，如果未设置此环境变量，则使用默认值）。X-Ray OTLP 端点目前仅支持 HTTP 协议。

  9. 您的应用程序现在应该使用 AWS Distro for OpenTelemetry Java 检测运行并将生成跨度。这些跨度存储在账户的 aws/spans CloudWatch LogsLogGroup 中。还可以在 CloudWatch 跟踪信息和指标控制台中查看与跨度相关的跟踪信息及指标。

  10. 使用您设置的环境变量启动应用程序。以下是启动脚本的示例。

    （注意：将 $SVC_NAME 替换为您的应用程序名称，将 $PYTHON_APP 替换为应用程序的位置和名称。

    OTEL_METRICS_EXPORTER=none \ 
OTEL_LOGS_EXPORTER=none \ 
OTEL_PYTHON_DISTRO=aws_distro \
 OTEL_PYTHON_CONFIGURATOR=aws_configurator \ 
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://xray.us-east-1.amazonaws.com/v1/traces \
OTEL_RESOURCE_ATTRIBUTES="service.name=$SVC_NAME" \
opentelemetry-instrument python $MY_PYTHON_APP.py
.Net

为了启用直接将跟踪信息发送到 X-Ray OTLP 跟踪端点的导出器并优化效益，请在启动应用程序之前设置环境变量以提供其他信息。这些变量对于设置 .NET 检测也是必需的。

  1. 将 OTEL_RESOURCE_ATTRIBUTES 环境变量中的 dotnet-service-name 替换为您选择的服务名称。

  2. 设置 OTEL_TRACES_EXPORTER=none。

  3. 设置 OTEL_AWS_SIG_V4_ENABLED=true。

    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_TRACES_EXPORTER=none
export OTEL_AWS_SIG_V4_ENABLED=true

export OTEL_RESOURCE_ATTRIBUTES=service.name=dotnet-service-name
export OTEL_METRICS_EXPORTER=none
export OTEL_LOGS_EXPORTER=none
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://xray.us-east-1.amazonaws.com/v1/traces

    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_TRACES_EXPORTER=none
$env:OTEL_AWS_SIG_V4_ENABLED=true

$env:OTEL_RESOURCE_ATTRIBUTES=service.name=dotnet-service-name
$env:OTEL_METRICS_EXPORTER=none
$env:OTEL_LOGS_EXPORTER=none
$env:OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
$env:OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://xray.us-east-1.amazonaws.com/v1/traces

  4. 使用环境变量启动应用程序。

  5. （可选）或者，您可以使用提供的安装脚本来帮助安装和设置 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.shexport 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 存储库中找到 AWS Distro for OpenTelemetry .NET 自动检测包的 NuGet 包。请务必查看自述文件以获取说明。