Application Signals を設定する

このセクションでは、CloudWatch Application Signals の設定について説明します。

トレースのサンプリングレート

デフォルトの場合、有効化後の Application Signals では、デフォルトのサンプリングレート設定 (reservoir=1/s と fixed_rate=5%) を使用して、一元化された X-Ray サンプリングを実行できるようになります。AWS Distro for OpenTelemetry (ADOT) SDK エージェントの環境変数は次のように設定されています。

サンプリング設定の変更方法については、以下を参照してください。

一元化された X-Ray サンプリングを無効にしてローカルサンプリングを使用する場合は、ADOT SDK Java エージェントに次の値を指定します。この例では、サンプリングレートが 5% に設定されます。

高度なサンプリング設定については、「OTEL_TRACES_SAMPLER」を参照してください。

ログ相関のトレースを有効にする

Application Signals でログ相関のトレースを有効にできます。これにより、トレース ID とスパン ID が関連するアプリケーションログに自動的に挿入されます。次に、Application Signals コンソールでトレースの詳細ページを開くと、現在のトレースに関連するログエントリがあれば、ページの下部に自動的に表示されます。

例えば、レイテンシーグラフにスパイクがあることに気付いたとします。グラフ上のそのポイントを選択すると、その時点の診断情報をロードできます。次に、関連するトレースを選択すると、詳細情報が表示されます。トレース情報を表示すると、下にスクロールしてそのトレースに関連付けられているログを参照できます。こうしたログを調べると、レイテンシーのスパイクを引き起こしている問題を突き止め、関連するパターンやエラーコードを明らかにできる可能性があります。

トレースログの相関を実現するために、Application Signals は以下を利用します。

いずれの計測も、OpenTelemetry コミュニティから提供されています。Application Signals は、これらを使用して、トレース ID やスパン ID などのトレースコンテキストをアプリケーションログに挿入します。これを有効にするには、自動計測を有効にするようにログ記録設定を手動で変更する必要があります。

アプリケーションが動作するアーキテクチャによっては、このセクションのステップに従うだけでなく、トレースログの相関を有効にする環境変数も設定する必要があります。

トレースログの相関を有効にした後

トレースログの相関の設定例

このセクションでは、いくつかの環境でトレースログの相関を設定する例を示します。

Spring Boot for Java

custom-app というフォルダに Spring Boot アプリケーションがあるとします。このアプリケーション設定は通常、custom-app/src/main/resources/application.yml という名前の YAML ファイルであり、次のようになります。

spring:
  application:
    name: custom-app
  config:
    import: optional:configserver:${CONFIG_SERVER_URL:http://localhost:8888/}
    
...   

トレースログの相関を有効にするには、次のログ記録設定を追加します。

spring:
  application:
    name: custom-app
  config:
    import: optional:configserver:${CONFIG_SERVER_URL:http://localhost:8888/}
    
...    

logging:
  pattern:
    level: trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p

Logback for Java

ログ記録設定 (logback.xml など) で、トレースコンテキスト trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p をエンコーダーの pattern に挿入します。例えば、以下の設定はトレースコンテキストの先頭にログメッセージを付加します。

<appender name="FILE" class="ch.qos.logback.core.FileAppender">
  <file>app.log</file>
  <append>true</append>
  <encoder> 
    <pattern>trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p - %m%n</pattern> 
  </encoder>
</appender>

Logback のエンコーダーの詳細については、Logback ドキュメントの「Encoders」を参照してください。

Log4j2 for Java

ログ記録設定 (log4j2.xml など) で、トレースコンテキスト trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p を PatternLayout に挿入します。例えば、以下の設定はトレースコンテキストの先頭にログメッセージを付加します。

<Appenders>
  <File name="FILE" fileName="app.log">
    <PatternLayout pattern="trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p - %m%n"/>
  </File>
</Appenders>

Log4j2 のパターンレイアウトの詳細については、Log4j2 ドキュメントの「Pattern Layout」を参照してください。

Log4j for Java

ログ記録設定 (log4j.xml など) で、トレースコンテキスト trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p を PatternLayout に挿入します。例えば、以下の設定はトレースコンテキストの先頭にログメッセージを付加します。

<appender name="FILE" class="org.apache.log4j.FileAppender">;
  <param name="File" value="app.log"/>;
  <param name="Append" value="true"/>;
  <layout class="org.apache.log4j.PatternLayout">;
    <param name="ConversionPattern" value="trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p - %m%n"/>;
  </layout>;
</appender>;

Log4j のパターンレイアウトの詳細については、Log4j ドキュメントの「Class Pattern Layout」を参照してください。

Python

アプリケーションの実行中に環境変数 OTEL_PYTHON_LOG_CORRELATION を true に設定します。詳細については、Python OpenTelemetry ドキュメントの「Enable trace context injection」を参照してください。

Node.js

Node.js 対応のロギングライブラリを使用できるように Node.js でトレースコンテキストの挿入を有効にする方法の詳細については、Node.js での Pino、Winston、Bunyan のいずれかの自動計測に NPM を使用する方法を解説したドキュメントを参照してください。

ログ相関のメトリクスを有効にする

CloudWatch Logs のロググループにアプリケーションログを発行する場合、Application Signals でアプリケーションログ相関のメトリクスを有効にできます。メトリクスログ相関では、Application Signals コンソールにメトリクスに関連付けられた関連するロググループが自動的に表示されます。

例えば、レイテンシーグラフにスパイクがあることに気付いたとします。グラフ上のポイントを選択すると、その時点の診断情報をロードできます。診断情報には、現在のサービスとメトリクスに関連付けられている関連するアプリケーションロググループが表示されます。次に、ボタンを選択して、それらのロググループに対して CloudWatch Logs Insights クエリを実行できます。アプリケーションログに含まれる情報によっては、レイテンシースパイクの原因を調査するのに役立つ場合があります。

アプリケーションが動作するアーキテクチャによっては、アプリケーションログ相関のメトリクスを有効にする環境変数も設定する必要がある場合があります。

高カーディナリティ操作の管理

Application Signals には、操作のカーディナリティを管理したり、コストを最適化するためにメトリクスのエクスポートを管理したりできる CloudWatch エージェントの設定が含まれています。デフォルトでは、あるサービスの個別操作の数がデフォルトのしきい値である 500 件を超えると、メトリクス制限機能が有効になります。構成設定を調整することで動作を調整できます。

メトリクス制限が有効かどうかを確認する

以下の方法を使用して、デフォルトのメトリクス制限が行われているかどうかを確認できます。行われている場合は、次のセクションのステップに従ってカーディナリティの制御の最適化を検討する必要があります。

カーディナリティコントロールの最適化

カーディナリティコントロールを最適化するには、以下を実行できます。

カスタムルールを作成して操作を集約する

高カーディナリティ操作は、コンテキストから抽出された不適切な一意の値が原因で発生することがあります。例えば、ユーザー ID やセッション ID をパスに含む HTTP/S リクエストを送信すると、何百もの個別の操作が発生する可能性があります。このような問題を解決するには、CloudWatch エージェントにカスタマイズルールを設定して、これらの操作を書き換えることをお勧めします。

PUT /api/customer/owners/123、PUT /api/customer/owners/456 などの個別の RemoteOperation 呼び出しで多数の異なるメトリクスの生成が急増している場合は、これらの操作を単一の RemoteOperation に統合することをおすすめします。1 つのアプローチは、PUT /api/customer/owners/ で始まるすべての RemoteOperation 呼び出しを統一された形式 (具体的には PUT /api/customer/owners/{ownerId}) に標準化することです。以下に示しているのはこのポリシーの例です。その他のカスタマイズルールについては、「CloudWatch Application Signals を有効にする」を参照してください。

{
   "logs":{
      "metrics_collected":{
         "application_signals":{
            "rules":[
               {
                  "selectors":[
                     {
                        "dimension":"RemoteOperation",
                        "match":"PUT /api/customer/owners/*"
                     }
                  ],
                  "replacements":[
                     {
                        "target_dimension":"RemoteOperation",
                        "value":"PUT /api/customer/owners/{ownerId}"
                     }
                  ],
                  "action":"replace"
               }
            ]
         }
      }
   }
}

また、カーディナリティの高いメトリクスが AllOtherRemoteOperations に集約されていて、具体的にどのようなメトリクスが含まれているのか不明瞭な場合もあります。CloudWatch エージェントは、ドロップされた操作を記録できます。ドロップされた操作を特定するには、次の例の設定を使用して、問題が再発するまでログ記録を有効にします。次に、CloudWatch エージェントログ (コンテナ stdout または EC2 ログファイルからアクセス可能) を調べ、キーワード drop metric data を検索します。

{
  "agent": {
    "config": {
      "agent": {
        "debug": true
      },
      "traces": {
        "traces_collected": {
          "application_signals": {
          }
        }
      },
      "logs": {
        "metrics_collected": {
          "application_signals": {
            "limiter": {
              "log_dropped_metrics": true
            }
          }
        }
      }
    }
  }
}

メトリクス制限ポリシーを作成する

デフォルトのメトリクス制限設定がサービスのカーディナリティに対応していない場合は、メトリクス制限設定をカスタマイズできます。これを行うには、CloudWatch エージェント設定ファイルの logs/metrics_collected/application_signals セクション内に limiter セクションを追加します。

次の例では、メトリクス制限のしきい値を 500 個の個別メトリクスから 100 個に引き下げています。

{
  "logs": {
    "metrics_collected": {
      "application_signals": {
        "limiter": {
          "drop_threshold": 100
        }
      }
    }
  }
}