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 クラスターのアプリケーションで有効にした後にそのアプリケーションを起動できない場合は、次の点を確認してください。
アプリケーションが別のモニタリングソリューションによって計測されていないかを確認します。Application Signals は、他の計測ソリューションと共存できない場合があります。
アプリケーションが Application Signals を使用するための互換性要件を満たしていることを確認します。詳細については、「サポートされているシステム」を参照してください。
アプリケーションで 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 アプリケーションを起動できない
OpenTelemetry 自動計測の既知の問題に、PYTHONPATH
環境変数が欠落していると場合によってはアプリケーションの起動に失敗するというものがあります。これを解決するには、PYTHONPATH
環境変数をアプリケーションの作業ディレクトリの場所に設定します。この問題の詳細については、「PPython autoinstrumentation setting of PYTHONPATH is not compliant with Python's module resolution behavior, breaking Django applications
Django アプリケーションには、OpenTelemetry Python ドキュメント
--noreload
フラグを使用すると、自動リロードを防ぐことができます。Django アプリケーションの
settings.py
ファイルの場所にDJANGO_SETTINGS_MODULE
環境変数を設定します。これにより、OpenTelemetry がユーザーの Django 設定に正しくアクセスして統合できるようになります。
WSGI サーバーを使用する Python アプリケーションに関する Application Signals データがない
Gunicorn や uWSGI などの WSGI サーバーを使用している場合は、ADOT Python 自動計測が機能するように追加で変更を加える必要があります。
注記
操作を続ける前に、最新バージョンの ADOT Python と Amazon CloudWatch Observability EKS アドオンを使用していることを確認してください。
WSGI サーバーで Application Signals を有効にするための追加の手順
フォークしたワーカープロセスに自動計測をインポートします。
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
OTEL_AWS_PYTHON_DEFER_TO_WORKERS_ENABLED
環境変数をtrue
に設定することで、メインプロセスをスキップしてワーカーに従うようにする 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 分ほど待った後に開始してください。
ADOT Java エージェントが、使用しているライブラリとフレームワークに対応していることを確認してください。詳細については、「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 分以内にデータが流れ始めるはずです。
サービスメトリクスまたは依存関係メトリクスに不明な値がある
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 を有効にする」を参照してください。UnknownRemoteOperation とは、送信先オペレーションの名前が不明であるという意味です。この状況になるのは、リモートコールがアクセスする送信先オペレーション名をシステムが抽出できない場合です。
解決策の 1 つに、リクエストを送信する関数の近くにカスタムスパンを作成し、指定された値で属性
aws.remote.operation
を追加するというものがあります。この他に、RemoteOperation
のメトリクス値をカスタマイズするように CloudWatch エージェントを設定するという方法もあります。CloudWatch エージェントでのカスタマイズの詳細については、「CloudWatch Application Signals を有効にする」を参照してください。
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
が表示されます。
起動時のプリロード - アプリケーションは、
loadDatafromDB
という名前のオペレーションを実行して、ウォームアップフェーズ中にデータベースからメタデータを読み取ります。loadDatafromDB
をサービスオペレーションとして観測するのではなく、InternalOperation
に分類します。バックグラウンドでの非同期実行 - アプリケーションは、イベントキューをサブスクライブし、更新があるたびにストリーミングデータを適宜処理します。トリガーされた各オペレーションは、サービスオペレーションとして
InternalOperation
になります。サービスレジストリからホスト情報を取得する - アプリケーションは、サービスレジストリと通信してサービス検出を行います。検出システムとのインタラクションは、すべて
InternalOperation
に分類されます。
.NET アプリケーションのログ記録を有効にするにはどうすればよいですか。
.NET アプリケーションのログ記録を有効にするには、以下の環境変数を設定します。これらの環境変数を設定する方法の詳細については、OpenTelemetry ドキュメントの「Troubleshooting .NET automatic instrumentation issues
OTEL_LOG_LEVEL
OTEL_DOTNET_AUTO_LOG_DIRECTORY
COREHOST_TRACE
COREHOST_TRACEFILE
.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 を使用する
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 }
必要なバージョンのエージェントまたは Amazon EKS アドオンへの更新
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 自動計測エージェントの両方を最新バージョンにアップグレードしてください。
以下のセクションの手順に従うと、サポートされているバージョンに容易に更新できます。
目次
Amazon CloudWatch Observability EKS アドオンの更新
Amazon CloudWatch Observability EKS アドオンを更新するには、AWS Management Consoleまたは AWS CLI を使用します。
コンソールを使用する
コンソールを使用してアドオンをアップグレードするには
https://console.aws.amazon.com/eks/home#/clusters
で Amazon EKS コンソールを開きます。 更新する Amazon EKS クラスターの名前を選択します。
[アドオン] タブを選択し、[Amazon CloudWatch Observability] を選択します。
[編集] を選択し、更新先のバージョンを選択して、[変更の保存] を選択します。
必ず
v1.7.0-eksbuild.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 を使用する
AWS CLI を使用してアドオンをアップグレードするには
以下のコマンドを入力して、最新バージョンを見つけます。
aws eks describe-addon-versions \ --addon-name amazon-cloudwatch-observability
以下のコマンドを入力して、アドオンを更新します。
$VERSION
をv1.7.0-eksbuild.1
以降のバージョンに置き換えます。$AWS_REGION
と$CLUSTER
をリージョンとクラスター名に置き換えます。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 を有効にする」で
$JSON_CONFIG
に使用する設定例を参照してください。以下のいずれかの 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 エージェントを更新する
サービスが Amazon EKS 以外のアーキテクチャで実行されている場合、最新の Application Signals 機能を使用するには、CloudWatch エージェントと ADOT 自動計測エージェントの両方をアップグレードする必要があります。
Amazon ECS の更新
Amazon ECS で実行されているサービスに応じてエージェントをアップグレードするには
新しいタスク定義リビジョンを作成します。詳細については、「Updating a task definition using the console」を参照してください。
ecs-cwagent
コンテナの$IMAGE
を、Amazon ECR の cloudwatch-agentにある最新のイメージタグに置き換えます。 修正バージョンにアップグレードする場合は、
1.300040.0
以降のバージョンを使用してください。init
コンテナの$IMAGE
を次の場所にある最新のイメージタグに置き換えます。Java の場合、aws-observability/adot-autoinstrumentation-java
を使用します。 修正バージョンにアップグレードする場合は、
1.32.2
以降のバージョンを使用してください。Python の場合、aws-observability/adot-autoinstrumentation-python
を使用します。 修正バージョンにアップグレードする場合は、
0.2.0
以降のバージョンを使用してください。-
NET, の場合、aws-observability/adot-autoinstrumentation-dotnet
を使用します。 修正バージョンにアップグレードする場合は、
1.3.2
以降のバージョンを使用してください。 -
Node.js の場合、aws-observability/adot-autoinstrumentation-node
を使用します。 修正バージョンにアップグレードする場合は、
0.3.0
以降のバージョンを使用してください。
「ステップ 4: CloudWatch エージェントを使用してアプリケーションを計測する」の手順に従って、アプリケーションコンテナの Application Signals 環境変数を更新します。
新しいタスク定義を使用してサービスをデプロイします。
Amazon EC2 または他のアーキテクチャでの更新
Amazon EC2 または他のアーキテクチャで実行されているサービスに応じてエージェントをアップグレードするには
「CloudWatch エージェントパッケージをダウンロードする」の手順に従って、CloudWatch エージェントを最新バージョンにアップデートします。必ずバージョン
1.300040.0
以降を選択してください。以下のいずれかの場所から、最新バージョンの AWS Distro for OpenTelemetry 自動計測エージェントをダウンロードします。
Java の場合、aws-otel-java-instrumentation
を使用します。 修正バージョンにアップグレードする場合は、必ず
1.32.2
以降を選択してください。Python の場合、aws-otel-python-instrumentation
を使用します。 修正バージョンにアップグレードする場合は、必ず
0.2.0
以降を選択してください。-
.NET の場合、aws-otel-dotnet-instrumentation
を使用します。 修正バージョンにアップグレードする場合は、必ず
1.3.2
以降を選択してください。 -
Node.js には、aws-otel-js-instrumentation
を使用します。 修正バージョンにアップグレードする場合は、必ず
0.3.0
以降を選択してください。
最新の Application Signals 環境変数をアプリケーションに適用し、アプリケーションを起動します。詳細については、「ステップ 3: 計測を設定しアプリケーションを起動する」を参照してください。