Amazon EC2 で Application Signals を有効にする - Amazon CloudWatch
ステップ 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 に付与する必要があります。このためには、次の操作を行います。この操作はアカウントごとに 1 回のみ必要です。

特定のアプリケーション向けに Application Signals を有効にするには

  1. CloudWatch コンソール (https://console.aws.amazon.com/cloudwatch/) を開きます。

  2. ナビゲーションペインで [Services (サービス)] を選択します。

  3. [サービスの検出を開始] を選択します。

  4. チェックボックスを選択し、[サービスの検出を開始] を選択します。

    自分のアカウントでこのステップを初めて完了すると、[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 エージェントをインストールするには

  1. 最新バージョンの CloudWatch エージェントをインスタンスにダウンロードします。インスタンスに CloudWatch エージェントを既にインストールしていても、更新が必要となる場合があります。2023 年 11 月 30 日以降にリリースされたエージェントのバージョンのみ、CloudWatch Application Signals に対応しています。

    CloudWatch エージェントのダウンロードについては、「CloudWatch エージェントパッケージをダウンロードする」を参照してください。

  2. CloudWatch エージェントを起動する前に、その設定を行い、Application Signals を有効化できるようにします。次の例は、EC2 ホストのメトリクスとトレースの両方に対し Application Signals を有効にする CloudWatch エージェント設定を示しています。

    このファイルを Linux システムの /opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.json に配置することをお勧めします。

    {
  "traces": {
    "traces_collected": {
      "application_signals": {}
    }
  },
  "logs": {
    "metrics_collected": {
      "application_signals": {}
    }
  }
}

  3. IAM ポリシー CloudWatchAgentServerPolicy を Amazon EC2 インスタンスの IAM ロールにアタッチします。オンプレミスホストのアクセス許可については、「オンプレミスサーバーのアクセス許可」を参照してください。

    1. AWS Management Console にサインインして、IAM コンソール (https://console.aws.amazon.com/iam/) を開きます。

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

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

    4. CloudWatchAgentServerPolicy を検索します。必要に応じて検索ボックスを使用してください。次に、そのポリシーのチェックボックスをオンにして、[アクセス権限の追加] を選択します。

  4. 次のコマンドを入力して 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 認証を提供する必要があります。

オンプレミスホストのアクセス許可を設定するには

  1. オンプレミスホストにアクセス許可を付与するために使用する IAM ユーザーを作成します。

    1. IAM コンソール (https://console.aws.amazon.com/iam/) を開きます。

    2. [ユーザー]、[ユーザーの作成] の順に選択します。

    3. [ユーザー詳細] で、[ユーザー名] に新しい IAM ユーザーの名前を入力します。これは、ホストの認証に使用される AWS のサインイン名です。その後、[Next] (次へ) を選択します。

    4. [アクセス許可の設定] ページの [権限オプション] で、[ポリシーを直接アタッチする] を選択します。

    5. [アクセス許可ポリシー] リストから、CloudWatchAgentServerPolicy ポリシーを選択して、ユーザーに追加します。次いで、[次へ] を選択します。

    6. [確認と作成] ページで、ユーザー名に問題がなく、CloudWatchAgentServerPolicy ポリシーが [許可の概要] に含まれていることを確認します。

    7. [ユーザーの作成] を選択します。

  2. AWS アクセスキーとシークレットキーを作成して取得します。

    1. IAM コンソールのナビゲーションペインで、[ユーザー] を選択し、前のステップで作成したユーザーのユーザー名を選択します。

    2. ユーザーのページで、[セキュリティ認証情報] タブを選択します。次に、[アクセスキー] セクションで、[アクセスキーを作成] を選択します。

    3. [アクセスキーの作成ステップ 1] で、[コマンドラインインターフェイス (CLI)] を選択します。

    4. [アクセスキーの作成ステップ 2] で、必要に応じてタグを入力して [次へ] を選択します。

    5. [アクセスキーの作成ステップ 3] で、[.csv ファイルをダウンロード] を選択し、.csv ファイルに IAM ユーザーのアクセスキーとシークレットアクセスキーを含めて保存します。この情報は、次のステップで必要になります。

    6. [完了] をクリックします。

  3. 次のコマンドを入力して、オンプレミスホストで 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
Amazon EC2 インスタンスまたはオンプレミスホストで Application Signals を有効にする手順の一環として Java アプリケーションを計測可能にするには

  1. AWS Distro for OpenTelemetry Java 自動計測エージェントの最新バージョンをダウンロードします。このリンクを使用すると、最新バージョンをダウンロードできます。リリース済みバージョンをすべて確認するには、aws-otel-java-instrumentation のリリースを参照してください。

  2. Application Signals の利点を最適化するには、環境変数によって情報を追加した後にアプリケーションを起動します。この情報は、Application Signals のダッシュボードに表示されます。

    1. 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 メトリクスのディメンションに変換されます。

      • 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 のメトリクスが生成されます。

  3. 前のステップでリストアップした環境変数を使用して、アプリケーションを起動します。起動スクリプトの例を次に示します。

    注記

    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

  4. (オプション) ログ相関を有効にするには、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 が正しく動作するようにしてください。

Amazon EC2 インスタンスで Application Signals を有効にする手順内で、Python アプリケーションを計測可能にするには

  1. AWS Distro for OpenTelemetry Python 自動計測エージェントの最新バージョンをダウンロードします。次の コマンドを使用してインストールします。

    pip install aws-opentelemetry-distro

    リリース済みバージョンをすべて確認するには、「AWS Distro for OpenTelemetry Python instrumentation」を使用します。

  2. Application Signals の利点を最適化するには、環境変数によって情報を追加した後にアプリケーションを起動します。この情報は、Application Signals のダッシュボードに表示されます。

    1. 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 メトリクスのディメンションに変換されます。

    2. OTEL_EXPORTER_OTLP_PROTOCOL 変数には、テレメトリデータを HTTP 経由で次のステップに記載されている CloudWatch エージェントエンドポイントにエクスポートする http/protobuf を指定します。

    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 に設定すると、コンテナが X-Ray トレースと CloudWatch メトリクスを Application Signals に送信し始めます。

  3. 前のステップで説明した環境変数を使用してアプリケーションを起動します。起動スクリプトの例を次に示します。

    • $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」を参照してください。

    • Django アプリケーションには、OpenTelemetry Python ドキュメントで概説されている追加の必須設定があります。

      • --noreload フラグを使用すると、自動リロードを防ぐことができます。

      • Django アプリケーションの settings.py ファイルの場所に DJANGO_SETTINGS_MODULE 環境変数を設定します。これにより、OpenTelemetry がユーザーの Django 設定に正しくアクセスして統合できるようになります。

  4. (オプション) ログ相関を有効にするには、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 (Preview)
Amazon EC2 インスタンスまたはオンプレミスホストで Application Signals を有効にする手順の一環として .NET アプリケーションを計装するには

  1. AWS Distro for OpenTelemetry .NET 自動計装パッケージの最新バージョンをダウンロードします。最新バージョンは、aws-otel-dotnet-instrumentation Releases でダウンロードできます。

  2. 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"

  3. 前のステップでリストアップした環境変数を使用して、アプリケーションを起動します。

Node.js (Preview)
Amazon EC2 インスタンスで Application Signals を有効にする手順内で、Node.js アプリケーションを計測可能にするには

  1. Node.js 用の AWS Distro for OpenTelemetry JavaScript 自動計測エージェントの最新バージョンをダウンロードします。次の コマンドを使用してインストールします。

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

    リリース済みバージョンをすべて確認するには、「AWS Distro for OpenTelemetry JavaScript instrumentation」を使用します。

  2. Application Signals の利点を最適化するには、環境変数によって情報を追加した後にアプリケーションを起動します。この情報は、Application Signals のダッシュボードに表示されます。

    1. 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 メトリクスのディメンションに変換されます。

    2. OTEL_EXPORTER_OTLP_PROTOCOL 変数には、テレメトリデータを HTTP 経由で次のステップに記載されている CloudWatch エージェントエンドポイントにエクスポートする http/protobuf を指定します。

    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 に設定すると、コンテナが X-Ray トレースと CloudWatch メトリクスを Application Signals に送信し始めます。

  3. 前のステップで説明した環境変数を使用してアプリケーションを起動します。起動スクリプトの例を次に示します。

    • $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

  4. (オプション) ログ相関を有効にするには、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