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

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 を有効にするための追加の手順
  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
  2. 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_LEVELdebug に設定して、アプリケーションを再デプロイします。

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

  • UnknownService とは、計測されたアプリケーションの名前が不明であるという意味です。OTEL_SERVICE_NAME 環境変数が未定義で、service.nameOTEL_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 アドオンのインストールまたは更新時に、タイプが ConfigurationConflictHealth 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 を使用します。

コンソールを使用する

コンソールを使用してアドオンをアップグレードするには
  1. https://console.aws.amazon.com/eks/home#/clusters で Amazon EKS コンソールを開きます。

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

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

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

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

  5. 以下のいずれかの 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 を使用してアドオンをアップグレードするには
  1. 以下のコマンドを入力して、最新バージョンを見つけます。

    aws eks describe-addon-versions \ --addon-name amazon-cloudwatch-observability
  2. 以下のコマンドを入力して、アドオンを更新します。$VERSIONv1.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 に使用する設定例を参照してください。

  3. 以下のいずれかの 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 で実行されているサービスに応じてエージェントをアップグレードするには
  1. 新しいタスク定義リビジョンを作成します。詳細については、「Updating a task definition using the console」を参照してください。

  2. ecs-cwagent コンテナの $IMAGE を、Amazon ECR の cloudwatch-agent にある最新のイメージタグに置き換えます。

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

  3. init コンテナの $IMAGE を次の場所にある最新のイメージタグに置き換えます。

  4. ステップ 4: CloudWatch エージェントを使用してアプリケーションを計測する」の手順に従って、アプリケーションコンテナの Application Signals 環境変数を更新します。

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

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

Amazon EC2 または他のアーキテクチャで実行されているサービスに応じてエージェントをアップグレードするには
  1. CloudWatch エージェントパッケージをダウンロードする」の手順に従って、CloudWatch エージェントを最新バージョンにアップデートします。必ずバージョン 1.300040.0 以降を選択してください。

  2. 以下のいずれかの場所から、最新バージョンの 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 以降を選択してください。

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