# Application Signals のインストールでトラブルシューティングを行う
<a name="CloudWatch-Application-Signals-Enable-Troubleshoot"></a>

このセクションでは、CloudWatch Application Signals のトラブルシューティングに役立つヒントを紹介します。

**Topics**
+ [

## Application Signals を使用して Amazon EKS の OpenTelemetry 設定の競合に対処する
](#Application-Signals-troubleshoot-eks-applications)
+ [

## Application Signals Java レイヤーのコールドスタートパフォーマンス
](#Application-Signals-troubleshoot-cold-start-performance)
+ [

## Application Signals を有効にしたが、その後、アプリケーションを起動できない
](#Application-Signals-troubleshoot-starting)
+ [

## Application Signals を有効にしたが、その後、Python アプリケーションを起動できない
](#Application-Signals-troubleshoot-starting-Python)
+ [

## WSGI サーバーを使用する Python アプリケーションに関する Application Signals データがない
](#Application-Signals-troubleshoot-Python-WSGI)
+ [

## Node.js アプリケーションが計測されていないか、または Application Signals テレメトリを生成していない
](#Application-Signals-troubleshoot-telemetry-nodejs)
+ [

## .NET アプリケーションが計測されていない、または中断して AWS SDK を呼び出す
](#Application-Signals-troubleshoot-sdk-calls)
+ [

## Application Signals ダッシュボードにアプリケーションデータがない
](#Application-Signals-troubleshoot-missingdata)
+ [

## サービスメトリクスまたは依存関係メトリクスに不明な値がある
](#Application-Signals-troubleshoot-unknown-values)
+ [

## Amazon CloudWatch Observability EKS アドオンの管理で生じた ConfigurationConflict への対処
](#Application-Signals-troubleshoot-conflict)
+ [

## 不要なメトリクスやトレースを除外したい
](#Application-Signals-troubleshoot-cardinality)
+ [

## `InternalOperation` とはどういう意味か
](#Application-Signals-troubleshoot-InternalOperation)
+ [

## .NET アプリケーションのログ記録を有効にするにはどうすればよいですか。
](#Application-Signals-troubleshoot-dotnet-logging)
+ [

## .NET アプリケーションにおけるアセンブリバージョンの競合を解決するにはどうすればよいですか。
](#Application-Signals-troubleshoot-dotnet-conflicts)
+ [

## FluentBit を無効にできるか
](#Application-Signals-troubleshoot-FluentBit)
+ [

## コンテナログをフィルタリングしてから CloudWatch Logs にエクスポートしてもよいですか。
](#Application-Signals-troubleshoot-filter-logs)
+ [

## AWS Distro OpenTelemetry (ADOT) JavaScript Lambda Layer 使用時の TypeError の解決
](#lambda-execution)
+ [

## AWS Distro OpenTelemetry (ADOT) JavaScript Lambda Layer でレスポンスストリーミング Lambda ハンドラーを使用するときの TypeError
](#lambda-execution-streaming)
+ [

## 必要なバージョンのエージェントまたは Amazon EKS アドオンへの更新
](#CloudWatch-Application-Signals-Agent-Versions)
+ [

## Application Signals の埋め込みメトリクス形式 (EMF) が無効になっている
](#emf-appsignals)

## Application Signals を使用して Amazon EKS の OpenTelemetry 設定の競合に対処する
<a name="Application-Signals-troubleshoot-eks-applications"></a>

Amazon EKS でのアプリケーションパフォーマンスモニタリング (APM) に OpenTelemetry (OTel) を使用し、CloudWatch エンドポイント以外のカスタム OTLP エクスポーターエンドポイントを設定すると、CloudWatch Observability アドオンバージョン 5.0.0 以降をインストールまたはアップグレードした後に、次の動作が発生することがあります。
+ 既存の OTel テレメトリの中断 – CloudWatch Observability アドオンは、アプリケーションでハードコーディングした OTLP エクスポーターエンドポイントを上書きすることがあります。この上書きは、コンテナ環境変数または `envFrom` ConfigMap を介して設定されたエンドポイントには影響しません。上書きされると、メトリクスとトレースが意図した送信先に到達しない可能性があります。既存の APM 設定を、V5.0.0 以降にアップグレードした後でも維持するには、「[Application Signals のオプトアウト](install-CloudWatch-Observability-EKS-addon.md#Opting-out-App-Signals)」を参照してください。
+ 以前に CloudWatch Observability アドオンを使用して Application Signals を有効にし、カスタム OTLP エンドポイントを設定している場合、Application Signals が機能しないことがあります。これを解決するには、カスタム OTLP エンドポイントを削除するか、バージョン 5.0.0 以降をインストールまたはアップグレードするときに環境変数 `OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true` を設定します。

## Application Signals Java レイヤーのコールドスタートパフォーマンス
<a name="Application-Signals-troubleshoot-cold-start-performance"></a>

Application Signals Layer を Java Lambda 関数に追加すると、スタートアップのレイテンシー (コールドスタート時間) が増加します。以下のヒントは、時間的制約のある関数のレイテンシーを低減するのに役立ちます。

**Java エージェントの高速スタートアップ ** – Application Signals Java Lambda Layer には、デフォルトで無効になっている高速起動機能が含まれていますが、OTEL\$1JAVA\$1AGENT\$1FAST\$1STARTUP\$1ENABLED 変数を true に設定することで有効にできます。この機能を有効にすると、階層型コンパイルレベル 1 C1 コンパイラを使用して、コールドスタートを高速化するためにすばやく最適化されたネイティブコードを生成するように JVM が設定されます。C1 コンパイラは長期的な最適化を犠牲にして速度を優先しますが、C2 コンパイラは時間の経過とともにデータをプロファイリングすることで、全体的なパフォーマンスを向上させます。

詳細については、「[Fast startup for Java agent](https://github.com/open-telemetry/opentelemetry-lambda/blob/main/java/README.md#fast-startup-for-java-agent)」を参照してください。

**プロビジョニングされた同時実行によるコールドスタート時間を短縮** – AWS Lambda でプロビジョニングされた同時実行では、指定された数の関数インスタンスを初期化し、リクエストに即座に応答できるようにして、事前に割り当てます。これにより、実行時に関数環境を初期化する必要がなくなるため、コールドスタート時間が短縮され、特にレイテンシーの影響を受けやすいワークロードでは、パフォーマンスが高速で一貫性が増します。詳細については、「[関数に対するプロビジョニングされた同時実行数の設定](https://docs.aws.amazon.com/lambda/latest/dg/provisioned-concurrency.html)」を参照してください。

**Lambda SnapStart を使用して起動パフォーマンスを最適化**する – AWS Lambda SnapStart は、関数の初期化フェーズ後に実行環境の事前初期化されたスナップショットを作成して、Lambda 関数の起動パフォーマンスを最適化する機能です。このスナップショットは、新しいインスタンスを起動する際に再利用され、関数呼び出し時の初期化プロセスをスキップすることで、コールドスタート時間を大幅に短縮できます。詳細については、「[Lambda SnapStart による起動パフォーマンスの向上](https://docs.aws.amazon.com/lambda/latest/dg/snapstart.html)」(Lambda SnapStart を使用したスタートアップパフォーマンスの向上) を参照してください。

## Application Signals を有効にしたが、その後、アプリケーションを起動できない
<a name="Application-Signals-troubleshoot-starting"></a>

Application Signals を Amazon EKS クラスターのアプリケーションで有効にした後にそのアプリケーションを起動できない場合は、次の点を確認してください。
+ アプリケーションが別のモニタリングソリューションによって計測されていないかを確認します。Application Signals は、他の計測ソリューションと共存できない場合があります。
+ アプリケーションが Application Signals を使用するための互換性要件を満たしていることを確認します。詳細については、「[サポートされているシステム](CloudWatch-Application-Signals-supportmatrix.md)」を参照してください。
+ アプリケーションで AWS Distro for OpenTelemetery Java または Python エージェントや CloudWatch エージェントイメージなどの Application Signals アーティファクトを取得できなかった場合は、ネットワークの問題である可能性があります。

この問題を軽減するには、アプリケーションデプロイマニフェストからアノテーション `instrumentation.opentelemetry.io/inject-java: "true"` または `instrumentation.opentelemetry.io/inject-python: "true"` を削除し、アプリケーションを再デプロイします。その後、アプリケーションが動作するかどうかを確認します。

**既知の問題**

Java SDK リリース v1.32.5 のランタイムメトリクスコレクションは、JBoss Wildfly を使用するアプリケーションで動作しないことが知られています。この問題は Amazon CloudWatch Observability EKS アドオンに及び、`2.3.0-eksbuild.1` から `2.5.0-eksbuild.1` までのバージョンに影響します。

影響を受けた場合、バージョンをダウングレードするか、アプリケーションに `OTEL_AWS_APPLICATION_SIGNALS_RUNTIME_ENABLED=false` 環境変数を追加してランタイムメトリクス収集を無効にします。

## Application Signals を有効にしたが、その後、Python アプリケーションを起動できない
<a name="Application-Signals-troubleshoot-starting-Python"></a>

OpenTelemetry 自動計測の既知の問題に、`PYTHONPATH` 環境変数が欠落していると場合によってはアプリケーションの起動に失敗するというものがあります。これを解決するには、`PYTHONPATH` 環境変数をアプリケーションの作業ディレクトリの場所に設定します。この問題の詳細については、「[PPython autoinstrumentation setting of PYTHONPATH is not compliant with Python's module resolution behavior, breaking Django applications](https://github.com/open-telemetry/opentelemetry-operator/issues/2302)」を参照してください。

Django アプリケーションには、[OpenTelemetry Python ドキュメント](https://opentelemetry-python.readthedocs.io/en/latest/examples/django/README.html)で概説されている追加の必須設定があります。
+ `--noreload` フラグを使用すると、自動リロードを防ぐことができます。
+ Django アプリケーションの `settings.py` ファイルの場所に `DJANGO_SETTINGS_MODULE` 環境変数を設定します。これにより、OpenTelemetry がユーザーの Django 設定に正しくアクセスして統合できるようになります。

## WSGI サーバーを使用する Python アプリケーションに関する Application Signals データがない
<a name="Application-Signals-troubleshoot-Python-WSGI"></a>

Gunicorn や uWSGI などの WSGI サーバーを使用している場合は、ADOT Python 自動計測が機能するように追加で変更を加える必要があります。

**注記**  
操作を続ける前に、最新バージョンの ADOT Python と Amazon CloudWatch Observability EKS アドオンを使用していることを確認してください。

**WSGI サーバーで Application Signals を有効にするための追加の手順**

1. フォークしたワーカープロセスに自動計測をインポートします。

   Gunicorn の場合、`post_fork` フックを使用します。

   ```
   # gunicorn.conf.py
   def post_fork(server, worker):
       from opentelemetry.instrumentation.auto_instrumentation import sitecustomize
   ```

   uWSGI の場合、`import` ディレクティブを使用します。

   ```
   #  uwsgi.ini
   [uwsgi]
   ; required for the instrumentation of worker processes
   enable-threads = true
   lazy-apps = true
   import = opentelemetry.instrumentation.auto_instrumentation.sitecustomize
   ```

1.  `OTEL_AWS_PYTHON_DEFER_TO_WORKERS_ENABLED` 環境変数を `true` に設定することで、メインプロセスをスキップしてワーカーに従うようにする ADOT Python 自動計測の設定を有効にします。

## Node.js アプリケーションが計測されていないか、または Application Signals テレメトリを生成していない
<a name="Application-Signals-troubleshoot-telemetry-nodejs"></a>

Node.js で Application Signals を有効にするには、Node.js アプリケーションで必ず CommonJS (CJS) モジュール形式を使用する必要があります。AWS Distro for OpenTelemetry の Node.js は、ESM モジュール形式をサポートしていません。OpenTelemetry JavaScript による ESM のサポートはまだ実験段階であり、現在も作業を継続しているためです。

アプリケーションで ESM ではなく CJS を使用しているかどうかは、アプリケーションが [ESM を有効にするための条件](https://nodejs.org/api/esm.html#enabling)を満たしていないことを確認することで判断できます。

## .NET アプリケーションが計測されていない、または中断して AWS SDK を呼び出す
<a name="Application-Signals-troubleshoot-sdk-calls"></a>

AWS Distro for Open Telemetry (ADOT) SDK for .NET は AWS SDK for .NET V4 をサポートしていません。Application Signals を完全にサポートするには、AWS SDK .NET V3 を使用します。

## Application Signals ダッシュボードにアプリケーションデータがない
<a name="Application-Signals-troubleshoot-missingdata"></a>

Application Signals のダッシュボードでメトリクスまたはトレースを確認できない場合は、次の原因が考えられます。こうした原因の調査は、最終更新の後、Application Signals によるデータの収集と表示が完了するまで 15 分ほど待った後に開始してください。
+ ADOT Java エージェントが、使用しているライブラリとフレームワークに対応していることを確認してください。詳細については、「[Libraries / Frameworks](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md#libraries--frameworks)」を参照してください。
+ CloudWatch エージェントが実行中であることを確認します。最初に、CloudWatch エージェントポッドのステータスを確認し、いずれのポッドも `Running` のステータスであることを確認します。

  ```
  kubectl -n amazon-cloudwatch get pods.
  ```

  CloudWatch エージェント設定ファイルに次の記述を追加してデバッグログを有効にし、エージェントを再起動します。

  ```
  "agent": {
  
    "region": "${REGION}",
    "debug": true
  },
  ```

  その後、CloudWatch エージェントポッドでエラーが発生していないか確認します。
+ CloudWatch エージェントの設定に問題がないか確認します。CloudWatch エージェント設定ファイルに次の記述があり、その記述を追加した後にエージェントを再起動したことを確認します。

  ```
  "agent": {
    "region": "${REGION}",
    "debug": true
  },
  ```

  その後、OpenTelemetry のデバッグログに次のようなエラーメッセージがないか確認します: `ERROR io.opentelemetry.exporter.internal.grpc.OkHttpGrpcExporter - Failed to export ...`。こうしたメッセージは、問題を示している可能性があります。

  それでも問題が解決しない場合は、`kubectl describe pod` コマンドでポッドを記述し、ダンプの後、`OTEL_` で始まる名前の環境変数を確認します。
+ OpenTelemetry Python デバッグログを有効にするには、環境変数 `OTEL_PYTHON_LOG_LEVEL` を `debug` に設定して、アプリケーションを再デプロイします。
+ CloudWatch エージェントからデータをエクスポートするためのアクセス権限の付与が間違っていないかや、十分であるかを確認します。CloudWatch エージェントのログに `Access Denied` のメッセージが見られる場合は、その点が問題の可能性があります。例えば、CloudWatch エージェントのインストール時に適用したアクセス権限が後で変更されたり削除されたりしたかもしれません。
+ テレメトリデータの生成中に AWS Distro for OpenTelemetry (ADOT) の問題が生じていないかを確認します。

  計測のアノテーションである `instrumentation.opentelemetry.io/inject-java` と ` sidecar.opentelemetry.io/inject-java` のそれぞれがアプリケーションのデプロイメントに適用され、値が `true` に設定されていることを確認してください。これらが適切でない場合、ADOT アドオンを正しくインストールしていても、アプリケーションポッドは計測されません。

  次に、`init` コンテナがアプリケーションに適用され、`Ready` 状態が `True` であることを確認します。`init` コンテナが Ready でない場合は、ステータスを確認してその理由を特定してください。

  問題が解決しない場合は、環境変数 `OTEL_JAVAAGENT_DEBUG` を true に設定し、アプリケーションを再デプロイして、OpenTelemetry Java SDK でデバッグログ記録を有効にします。`ERROR io.telemetry` で始まるメッセージを検索します。
+ メトリクスまたはスパンエクスポーターの処理でデータの一部が送信されなかった可能性があります。原因を特定するには、アプリケーションログで「`Failed to export...`」が含まれるメッセージを確認してください。
+ CloudWatch エージェントによってメトリクスまたはスパンが Application Signals に送信される際に、同エージェントがスロットリングされた可能性があります。スロットリングを示すメッセージを CloudWatch エージェントのログで確認してください。
+ サービス検出設定が有効になっていることを確認します。この操作は、リージョンごとに 1 回のみ必要です。

  これを確認するには、CloudWatch コンソールで、**[Application Signals]**、**[サービス]** の順に選択します。ステップ 1 が **[完了]** とマークされていない場合は、**[サービスの検出を開始]** を選択します。5 分以内にデータが流れ始めるはずです。

## サービスメトリクスまたは依存関係メトリクスに不明な値がある
<a name="Application-Signals-troubleshoot-unknown-values"></a>

Application Signals ダッシュボードの依存関係名またはオペレーションに **UnknownService**、**UnknownOperation**、**UnknownRemoteService**、**UnknownRemoteOperation** が表示される場合は、不明なリモートサービスやリモートオペレーションに関するデータの発生とそれらのデプロイに一致が見られるかを確認してください。
+ **UnknownService** とは、計測されたアプリケーションの名前が不明であるという意味です。`OTEL_SERVICE_NAME` 環境変数が未定義で、`service.name` が `OTEL_RESOURCE_ATTRIBUTES` に指定されていない場合、サービス名は `UnknownService` に設定されます。これを修正するには、`OTEL_SERVICE_NAME` または `OTEL_RESOURCE_ATTRIBUTES` でサービス名を指定します。
+ **UnknownOperation** とは、呼び出されたオペレーションの名前が不明であるという意味です。この状況になるのは、リモートコールを呼び出すオペレーション名を Application Signals が検出できないか、抽出されたオペレーション名に高いカーディナリティ値が含まれている場合です。
+ **UnknownRemoteService** とは、送信先サービスの名前が不明であるという意味です。この状況になるのは、リモートコールがアクセスする送信先サービス名をシステムが抽出できない場合です。

  解決策の 1 つに、リクエストを送信する関数の近くにカスタムスパンを作成し、指定された値で属性 `aws.remote.service` を追加するというものがあります。この他に、`RemoteService` のメトリクス値をカスタマイズするように CloudWatch エージェントを設定するという方法もあります。CloudWatch エージェントでのカスタマイズの詳細については、「[CloudWatch Application Signals を有効にする](CloudWatch-Agent-Application_Signals.md)」を参照してください。
+ **UnknownRemoteOperation** とは、送信先オペレーションの名前が不明であるという意味です。この状況になるのは、リモートコールがアクセスする送信先オペレーション名をシステムが抽出できない場合です。

  解決策の 1 つに、リクエストを送信する関数の近くにカスタムスパンを作成し、指定された値で属性 `aws.remote.operation` を追加するというものがあります。この他に、`RemoteOperation` のメトリクス値をカスタマイズするように CloudWatch エージェントを設定するという方法もあります。CloudWatch エージェントでのカスタマイズの詳細については、「[CloudWatch Application Signals を有効にする](CloudWatch-Agent-Application_Signals.md)」を参照してください。

## Amazon CloudWatch Observability EKS アドオンの管理で生じた ConfigurationConflict への対処
<a name="Application-Signals-troubleshoot-conflict"></a>

Amazon CloudWatch Observability EKS アドオンのインストールまたは更新時に、タイプが `ConfigurationConflict` の `Health Issue` によって生じたエラー (`Conflicts found when trying to apply. Will not continue due to resolve conflicts mode` で始まる) が見られたとします。これはおそらく、CloudWatch エージェントとその関連コンポーネント (ServiceAccount、ClusterRole、ClusterRoleBinding など) がクラスターにインストールされていることが原因と考えられます。このアドオンによって CloudWatch エージェントとその関連コンポーネントがインストールされるときに内容の変更が検出されると、デフォルトではインストールまたは更新が失敗します。これによって、クラスター上にあるリソースの状態が上書きされることを防いでいます。

Amazon CloudWatch Observability EKS アドオンへのオンボード時にこのエラーが発生した場合は、クラスターにインストール済みの CloudWatch エージェントセットアップを削除した後に EKS アドオンをインストールすると良いでしょう。カスタムエージェント設定など、元の CloudWatch エージェントセットアップへのカスタマイズを必ずバックアップし、Amazon CloudWatch Observability EKS アドオンを次回インストールまたは更新するときにそれらのカスタマイズを適用してください。Container Insights へのオンボーディングを目的に CloudWatch エージェントをインストール済みである場合は、「[Container Insights の CloudWatch エージェントと Fluent Bit の削除](ContainerInsights-delete-agent.md)」で詳細を確認してください。

その他に、アドオンでサポートされている設定オプションで `OVERWRITE` を指定して競合を解決することも可能です。このオプションを使用すると、クラスター上の競合を上書きしてアドオンのインストールまたは更新を継続できます。Amazon EKS コンソールを使用する場合、アドオンの作成または更新時に **[オプションの構成設定]** を選択すると、**[競合の解決方法]** が表示されます。AWS CLI を使用する場合は、コマンドに `--resolve-conflicts OVERWRITE` を指定することで、アドオンを作成または更新できます。

## 不要なメトリクスやトレースを除外したい
<a name="Application-Signals-troubleshoot-cardinality"></a>

Application Signals が収集しているトレースやメトリクスの中に不要なものがある場合は、「[高カーディナリティ操作の管理](Application-Signals-Cardinality.md)」を参照して、カスタムルールでカーディナリティを低くするように CloudWatch エージェントを設定する方法について確認してください。

トレースサンプリングルールのカスタマイズについては、X-Ray ドキュメントの「[Configure sampling rules](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console)」を参照してください。

## `InternalOperation` とはどういう意味か
<a name="Application-Signals-troubleshoot-InternalOperation"></a>

`InternalOperation` は、外部呼び出しではなくアプリケーションによって内部でトリガーされるオペレーションです。`InternalOperation` が表示されるのは、想定内の正常な動作です。

例えば、一般に次のような場合に `InternalOperation` が表示されます。
+ **起動時のプリロード** - アプリケーションは、`loadDatafromDB` という名前のオペレーションを実行して、ウォームアップフェーズ中にデータベースからメタデータを読み取ります。`loadDatafromDB` をサービスオペレーションとして観測するのではなく、`InternalOperation` に分類します。
+ **バックグラウンドでの非同期実行** - アプリケーションは、イベントキューをサブスクライブし、更新があるたびにストリーミングデータを適宜処理します。トリガーされた各オペレーションは、サービスオペレーションとして `InternalOperation` になります。
+ **サービスレジストリからホスト情報を取得する** - アプリケーションは、サービスレジストリと通信してサービス検出を行います。検出システムとのインタラクションは、すべて `InternalOperation` に分類されます。

## .NET アプリケーションのログ記録を有効にするにはどうすればよいですか。
<a name="Application-Signals-troubleshoot-dotnet-logging"></a>

.NET アプリケーションのログ記録を有効にするには、以下の環境変数を設定します。これらの環境変数を設定する方法の詳細については、OpenTelemetry ドキュメントの「[Troubleshooting .NET automatic instrumentation issues](https://opentelemetry.io/docs/zero-code/net/troubleshooting/#general-steps)」を参照してください。
+ `OTEL_LOG_LEVEL`
+ `OTEL_DOTNET_AUTO_LOG_DIRECTORY`
+ `COREHOST_TRACE`
+ `COREHOST_TRACEFILE`

## .NET アプリケーションにおけるアセンブリバージョンの競合を解決するにはどうすればよいですか。
<a name="Application-Signals-troubleshoot-dotnet-conflicts"></a>

次のエラーが発生した場合は、OpenTelemetry ドキュメントの「[Assembly version conflicts](https://opentelemetry.io/docs/zero-code/net/troubleshooting/#assembly-version-conflicts)」を参照して、解決手順を確認してください。

```
Unhandled exception. System.IO.FileNotFoundException: Could not load file or assembly 'Microsoft.Extensions.DependencyInjection.Abstractions, Version=7.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60'. The system cannot find the file specified.

File name: 'Microsoft.Extensions.DependencyInjection.Abstractions, Version=7.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60'
   at Microsoft.AspNetCore.Builder.WebApplicationBuilder..ctor(WebApplicationOptions options, Action`1 configureDefaults)
   at Microsoft.AspNetCore.Builder.WebApplication.CreateBuilder(String[] args)
   at Program.<Main>$(String[] args) in /Blog.Core/Blog.Core.Api/Program.cs:line 26
```

## FluentBit を無効にできるか
<a name="Application-Signals-troubleshoot-FluentBit"></a>

Amazon CloudWatch Observability EKS アドオンを設定することで、FluentBit を無効にできます。詳細については、「[(オプション) その他の設定](install-CloudWatch-Observability-EKS-addon.md#install-CloudWatch-Observability-EKS-addon-configuration)」を参照してください。

## コンテナログをフィルタリングしてから CloudWatch Logs にエクスポートしてもよいですか。
<a name="Application-Signals-troubleshoot-filter-logs"></a>

いいえ。コンテナログのフィルタリングはまだサポートされていません。

## AWS Distro OpenTelemetry (ADOT) JavaScript Lambda Layer 使用時の TypeError の解決
<a name="lambda-execution"></a>

Lambda 関数は、次の場合にエラー「`TypeError - "Cannot redefine property: handler"`」で失敗する可能性があります。
+ ADOT JavaScript Lambda Layer を使用する 
+ `esbuild` を使用して TypeScript をコンパイルする
+ `export` キーワードを使用してハンドラーをエクスポートする

ADOT JavaScript Lambda Layer は、実行時にハンドラーを変更する必要があります。`export` キーワードを (直接または AWS CDK を介して) `esbuild` と共に使用すると、`esbuild` によってハンドラーがイミュータブルになり、これらの変更が防止されます。

`export` キーワードの代わりに `module.exports` を使用してハンドラー関数をエクスポートします。

```
// Before
export const handler = (event) => {
  // Handler Code
}
```

```
// After
const handler = async (event) => {
  // Handler Code
}
module.exports = { handler }
```

## AWS Distro OpenTelemetry (ADOT) JavaScript Lambda Layer でレスポンスストリーミング Lambda ハンドラーを使用するときの TypeError
<a name="lambda-execution-streaming"></a>

Lambda 関数は、次の場合にエラー「`TypeError - "responseStream.write is not a function"`」で失敗する可能性があります。
+ AWS Lambda Instrumentation が有効になっている ADOT JavaScript Lambda Layer を使用する (デフォルトで有効) 
+ Node.js マネージドランタイムでのレスポンスストリーミング機能の使用。例えば、関数ハンドラーが次のような場合です。

  ```
  * export const handler = awslambda.streamifyResponse(...)
  ```

ADOT JavaScript Lambda Layer の AWS Lambda Instrumentation は現在、Node.js マネージドランタイムのレスポンスストリーミングをサポートしていないため、この TypeError を回避するには無効にする必要があります。

## 必要なバージョンのエージェントまたは Amazon EKS アドオンへの更新
<a name="CloudWatch-Application-Signals-Agent-Versions"></a>

2024 年 8 月 9 日以降、CloudWatch Application Signals では古いバージョンの Amazon CloudWatch Observability EKS アドオン、CloudWatch エージェント、および AWS Distro for OpenTelemetry 自動計測エージェントのサポートが終了します。
+ Amazon CloudWatch Observability EKS アドオンでは、`v1.7.0-eksbuild.1` より前のバージョンがサポートされなくなります。
+ CloudWatch エージェントでは、`1.300040.0` より前のバージョンがサポートされなくなります。
+ AWS Distro for OpenTelemetry 自動計測エージェントの場合:
  + Java では、`1.32.2` より前のバージョンはサポートされていません。
  + Python では、`0.2.0` より前のバージョンはサポートされていません。
  + NET, では、`1.3.2` より前のバージョンはサポートされていません。
  + Node.js では、`0.3.0` より前のバージョンはサポートされていません。

**重要**  
エージェントの最新バージョンには、Application Signals メトリクススキーマへの更新が含まれています。こうした更新には下位互換性がないため、互換性のないバージョンを使用するとデータの問題が発生する可能性があります。最新バージョンの機能にシームレスに移行できるようにするには、以下の操作を行います。  
Amazon EKS でアプリケーションを実行している場合は、Amazon CloudWatch Observability アドオンを更新した後で、計測されたすべてのアプリケーションを再起動してください。
それ以外のプラットフォームでアプリケーションを実行している場合は、CloudWatch エージェントと AWS OpenTelemetry 自動計測エージェント**の両方**を最新バージョンにアップグレードしてください。

以下のセクションの手順に従うと、サポートされているバージョンに容易に更新できます。

**Contents**
+ [

### Amazon CloudWatch Observability EKS アドオンの更新
](#Application-Signals-Upgrade-Addon)
  + [

#### コンソールを使用する
](#Upgrade-Addon-Console)
  + [

#### AWS CLI の使用
](#Upgrade-Addon-CLI)
+ [

### CloudWatch エージェントと ADOT エージェントを更新する
](#Application-Signals-Upgrade-Agents)
  + [

#### Amazon ECS の更新
](#Upgrade-Agents-ECS)
  + [

#### Amazon EC2 または他のアーキテクチャでの更新
](#Upgrade-Addon-EC2)

### Amazon CloudWatch Observability EKS アドオンの更新
<a name="Application-Signals-Upgrade-Addon"></a>

Amazon CloudWatch Observability EKS アドオンを更新するには、AWS マネジメントコンソールまたは AWS CLI を使用します。

#### コンソールを使用する
<a name="Upgrade-Addon-Console"></a>

**コンソールを使用してアドオンをアップグレードするには**

1. [https://console.aws.amazon.com/eks/home\$1/clusters](https://console.aws.amazon.com/eks/home#/clusters) で Amazon EKS コンソールを開きます。

1. 更新する Amazon EKS クラスターの名前を選択します。

1. **[アドオン]** タブを選択し、**[Amazon CloudWatch Observability]** を選択します。

1. **[編集]** を選択し、更新先のバージョンを選択して、**[変更の保存]** を選択します。

   必ず `v1.7.0-eksbuild.1` 以降を選択してください。

1. 以下のいずれかの AWS CLI コマンドを入力して、サービスを再起動します。

   ```
     # Restart a deployment
     kubectl rollout restart deployment/name
     # Restart a daemonset
     kubectl rollout restart daemonset/name
     # Restart a statefulset
     kubectl rollout restart statefulset/name
   ```

#### AWS CLI の使用
<a name="Upgrade-Addon-CLI"></a>

**AWS CLI を使用してアドオンをアップグレードするには**

1. 以下のコマンドを入力して、最新バージョンを見つけます。

   ```
   aws eks describe-addon-versions \
   --addon-name amazon-cloudwatch-observability
   ```

1. 以下のコマンドを入力して、アドオンを更新します。*\$1VERSION* を `v1.7.0-eksbuild.1` 以降のバージョンに置き換えます。*\$1AWS\$1REGION* と *\$1CLUSTER* をリージョンとクラスター名に置き換えます。

   ```
   aws eks update-addon \
   --region $AWS_REGION \
   --cluster-name $CLUSTER \
   --addon-name amazon-cloudwatch-observability \
   --addon-version $VERSION \
   # required only if the advanced configuration is used.
   --configuration-values $JSON_CONFIG
   ```
**注記**  
アドオンにカスタム設定を使用する場合は、「[CloudWatch Application Signals を有効にする](CloudWatch-Agent-Application_Signals.md)」で *\$1JSON\$1CONFIG* に使用する設定例を参照してください。

1. 以下のいずれかの AWS CLI コマンドを入力して、サービスを再起動します。

   ```
     # Restart a deployment
     kubectl rollout restart deployment/name
     # Restart a daemonset
     kubectl rollout restart daemonset/name
     # Restart a statefulset
     kubectl rollout restart statefulset/name
   ```

### CloudWatch エージェントと ADOT エージェントを更新する
<a name="Application-Signals-Upgrade-Agents"></a>

サービスが Amazon EKS 以外のアーキテクチャで実行されている場合、最新の Application Signals 機能を使用するには、CloudWatch エージェントと ADOT 自動計測エージェントの両方をアップグレードする必要があります。

#### Amazon ECS の更新
<a name="Upgrade-Agents-ECS"></a>

**Amazon ECS で実行されているサービスに応じてエージェントをアップグレードするには**

1. 新しいタスク定義リビジョンを作成します。詳細については、「[Updating a task definition using the console](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/update-task-definition-console-v2)」を参照してください。

1. `ecs-cwagent` コンテナの `$IMAGE` を、Amazon ECR の [cloudwatch-agent](https://gallery.ecr.aws/cloudwatch-agent/cloudwatch-agent) にある最新のイメージタグに置き換えます。

   修正バージョンにアップグレードする場合は、`1.300040.0` 以降のバージョンを使用してください。

1. `init` コンテナの `$IMAGE` を次の場所にある最新のイメージタグに置き換えます。
   + Java の場合、[aws-observability/adot-autoinstrumentation-java](https://gallery.ecr.aws/aws-observability/adot-autoinstrumentation-java) を使用します。

     修正バージョンにアップグレードする場合は、`1.32.2` 以降のバージョンを使用してください。
   + Python の場合、[aws-observability/adot-autoinstrumentation-python](https://gallery.ecr.aws/aws-observability/adot-autoinstrumentation-python) を使用します。

     修正バージョンにアップグレードする場合は、`0.2.0` 以降のバージョンを使用してください。
   + NET, の場合、[aws-observability/adot-autoinstrumentation-dotnet](https://gallery.ecr.aws/aws-observability/adot-autoinstrumentation-dotnet) を使用します。

     修正バージョンにアップグレードする場合は、`1.3.2` 以降のバージョンを使用してください。
   + Node.js の場合、[aws-observability/adot-autoinstrumentation-node](https://gallery.ecr.aws/aws-observability/adot-autoinstrumentation-node) を使用します。

     修正バージョンにアップグレードする場合は、`0.3.0` 以降のバージョンを使用してください。

1. 「[ステップ 4: CloudWatch エージェントを使用してアプリケーションを計測する](CloudWatch-Application-Signals-ECS-Sidecar.md#CloudWatch-Application-Signals-Enable-ECS-Instrument)」の手順に従って、アプリケーションコンテナの Application Signals 環境変数を更新します。

1. 新しいタスク定義を使用してサービスをデプロイします。

#### Amazon EC2 または他のアーキテクチャでの更新
<a name="Upgrade-Addon-EC2"></a>

**Amazon EC2 または他のアーキテクチャで実行されているサービスに応じてエージェントをアップグレードするには**

1. CloudWatch エージェントのバージョンとして `1.300040.0` 以降を選択してください。

1. 以下のいずれかの場所から、最新バージョンの AWS Distro for OpenTelemetry 自動計測エージェントをダウンロードします。
   + Java の場合、[aws-otel-java-instrumentation ](https://gallery.ecr.aws/aws-observability/adot-autoinstrumentation-java)を使用します。

     修正バージョンにアップグレードする場合は、必ず `1.32.2` 以降を選択してください。
   + Python の場合、[aws-otel-python-instrumentation ](https://github.com/aws-observability/aws-otel-python-instrumentation/releases)を使用します。

     修正バージョンにアップグレードする場合は、必ず `0.2.0` 以降を選択してください。
   + .NET の場合、[aws-otel-dotnet-instrumentation ](https://github.com/aws-observability/aws-otel-dotnet-instrumentation/releases)を使用します。

     修正バージョンにアップグレードする場合は、必ず `1.3.2` 以降を選択してください。
   + Node.js には、[aws-otel-js-instrumentation ](https://github.com/aws-observability/aws-otel-js-instrumentation/releases)を使用します。

     修正バージョンにアップグレードする場合は、必ず `0.3.0` 以降を選択してください。

1. 最新の Application Signals 環境変数をアプリケーションに適用し、アプリケーションを起動します。詳細については、「[ステップ 3: 計測を設定しアプリケーションを起動する](CloudWatch-Application-Signals-Enable-EC2Main.md#CloudWatch-Application-Signals-Enable-Other-instrument)」を参照してください。

## Application Signals の埋め込みメトリクス形式 (EMF) が無効になっている
<a name="emf-appsignals"></a>

`/aws/application-signals/data` ロググループの EMF を無効にすると、Application Signals の機能に以下のような影響を与える可能性があります。
+ Application Signals のメトリクスとグラフが表示されない
+ Application Signals の機能が低下する

**Application Signals を復元するにはどうすればよいですか?**

Application Signals が空のグラフまたはメトリクスを表示する場合、`/aws/application-signals/data` ロググループが完全な機能を復元するには、EMF を有効にする必要があります。詳細については、「[PutAccountPolicy](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutAccountPolicy.html#API_PutAccountPolicy_RequestSyntax)」を参照してください。