Application Signals のインストールでトラブルシューティングを行う

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

Application Signals Java レイヤーのコールドスタートパフォーマンス

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

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

詳細については、「Fast startup for Java agent」を参照してください。

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

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

Application Signals を有効にしたが、その後、アプリケーションを起動できない

Application Signals を Amazon EKS クラスターのアプリケーションで有効にした後にそのアプリケーションを起動できない場合は、次の点を確認してください。

この問題を軽減するには、アプリケーションデプロイマニフェストからアノテーション 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 アプリケーションを起動できない

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

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

WSGI サーバーを使用する Python アプリケーションに関する Application Signals データがない

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

Node.js アプリケーションが計測されていないか、または Application Signals テレメトリを生成していない

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

お使いのアプリケーションで ESM ではなく CJS を使用しているかどうかは、アプリケーションが ESM を有効にするための条件を満たしていないことを確認することで判断できます。

Application Signals ダッシュボードにアプリケーションデータがない

Application Signals のダッシュボードでメトリクスまたはトレースを確認できない場合は、次の原因が考えられます。こうした原因の調査は、最終更新の後、Application Signals によるデータの収集と表示が完了するまで 15 分ほど待った後に開始してください。

サービスメトリクスまたは依存関係メトリクスに不明な値がある

Application Signals ダッシュボードの依存関係名またはオペレーションに UnknownService、UnknownOperation、UnknownRemoteService、UnknownRemoteOperation が表示される場合は、不明なリモートサービスやリモートオペレーションに関するデータの発生とそれらのデプロイに一致が見られるかを確認してください。

Amazon CloudWatch Observability EKS アドオンの管理で生じた ConfigurationConflict への対処

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 の削除」で詳細を確認してください。

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

不要なメトリクスやトレースを除外したい

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

トレースサンプリングルールのカスタマイズについては、X-Ray ドキュメントの「Configure sampling rules」を参照してください。

InternalOperation とはどういう意味か

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

例えば、一般に次のような場合に InternalOperation が表示されます。

.NET アプリケーションのログ記録を有効にするにはどうすればよいですか。

.NET アプリケーションのログ記録を有効にするには、以下の環境変数を設定します。これらの環境変数を設定する方法の詳細については、OpenTelemetry ドキュメントの「Troubleshooting .NET automatic instrumentation issues」を参照してください。

.NET アプリケーションにおけるアセンブリバージョンの競合を解決するにはどうすればよいですか。

次のエラーが発生した場合は、OpenTelemetry ドキュメントの「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 を無効にできるか

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

コンテナログをフィルタリングしてから CloudWatch Logs にエクスポートしてもよいですか。

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

AWS Distro OpenTelemetry (ADOT) JavaScript Lambda Layer 使用時の TypeError の解決

Lambda 関数は、次の場合にエラー「TypeError - "Cannot redefine property: handler"」で失敗する可能性があります。

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 }

必要なバージョンのエージェントまたは Amazon EKS アドオンへの更新

2024 年 8 月 9 日以降、CloudWatch Application Signals では古いバージョンの Amazon CloudWatch Observability EKS アドオン、CloudWatch エージェント、および AWS Distro for OpenTelemetry 自動計測エージェントのサポートが終了します。

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

Amazon CloudWatch Observability EKS アドオンの更新

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

コンソールを使用する

AWS CLI を使用する

CloudWatch エージェントと ADOT エージェントを更新する

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

Amazon ECS の更新

Amazon EC2 または他のアーキテクチャでの更新

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

/aws/application-signals/data ロググループの EMF を無効にすると、Application Signals の機能に以下のような影響を与える可能性があります。

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

Application Signals が空のグラフまたはメトリクスを表示する場合、/aws/application-signals/data ロググループが完全な機能を復元するには、EMF を有効にする必要があります。詳細については、「PutAccountPolicy」を参照してください。