AWS Distro for OpenTelemetry (ADOT) SDK を使用したコレクターレストレースのエクスポート - Amazon CloudWatch
前提条件Amazon EC2 の IAM アクセス許可の設定オンプレミスホストの IAM アクセス許可の設定ADOT SDK の有効化

AWS Distro for OpenTelemetry (ADOT) SDK を使用したコレクターレストレースのエクスポート

ADOT SDK を使用してコレクターレスに移行し、トレースを OTLP エンドポイント (トレース用) に直接送信できます。

注記

デフォルトでは、トランザクション検索を有効にすると Application Signals が有効になります。Application Signals は AWS Distro for OpenTelemetry ではサポートされていないため、無効にする必要があります。

前提条件

トランザクション検索が有効になっていて、X-Ray OTLP エンドポイントにスパンを送信できることを確認します。詳細については、「トランザクション検索の開始方法」を参照してください。

Amazon EC2 の IAM アクセス許可の設定

Amazon EC2 インスタンスの IAM ロールに AWSXrayWriteOnlyPolicy IAM ポリシーをアタッチするには、次の手順に従います。

  1. CloudWatch コンソールの https://console.aws.amazon.com/cloudwatch/ を開いてください。

  2. [ロール] を選択し、Amazon EC2 インスタンスに使用しているロールを検索します。

  3. [アクセス権限] タブで、[許可を追加]、[ポリシーをアタッチ] の順に選択します。

  4. 検索ボックスを使って、AWSXrayWriteOnlyPolicy ポリシーを検索します。

  5. AWSXrayWriteOnlyPolicy ポリシーを選択し、[許可を追加] を選択します。

オンプレミスホストの IAM アクセス許可の設定

オンプレミスホストにアクセス許可を付与するために使用する IAM ユーザーを作成するには、次の手順に従います。

  1. CloudWatch コンソールの https://console.aws.amazon.com/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 ファイルをダウンロード] を選択し、.csv ファイルに IAM ユーザーのアクセスキーとシークレットアクセスキーを含めて保存します。この情報は、次のステップで必要になります。

    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 を使用します。これは、アプリケーションの [ホスト元] 環境として表示されます。これを指定しない場合、次のいずれかのデフォルトが使用されます。

    • これが Auto Scaling グループに含まれるインスタンスである場合は、ec2:name-of-Auto-Scaling-group に設定されます。

    • Auto Scaling グループに含まれていない 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 ダッシュボードに表示されます。この変数を指定しない場合、次のいずれかのデフォルトが使用されます。

    • これが Auto Scaling グループに含まれるインスタンスである場合は、ec2:name-of-Auto-Scaling-group に設定されます。

    • Auto Scaling グループに含まれていない 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 ダッシュボードに表示されます。これを指定しない場合、次のいずれかのデフォルトが使用されます。

    • これが Auto Scaling グループに含まれるインスタンスである場合は、ec2:name-of-Auto-Scaling-group に設定されます。

    • Auto Scaling グループに含まれていない 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

    AWS Distro for OpenTelemetry .NET 自動計測パッケージの NuGet パッケージは、公式 NuGet リポジトリにあります。手順については、「README ファイル」を確認してください。