Application Signals のインストールでトラブルシューティングを行う - Amazon CloudWatch
Application Signals を有効にしたが、その後、アプリケーションを起動できないApplication Signals を有効にしたが、その後、Python アプリケーションを起動できないWSGI サーバーを使用する Python アプリケーションに関する Application Signals データがないNode.js アプリケーションが計測されていないか、または Application Signals テレメトリを生成していないApplication Signals ダッシュボードにアプリケーションデータがないサービスメトリクスまたは依存関係メトリクスに不明な値があるAmazon CloudWatch Observability EKS アドオンの管理で生じた ConfigurationConflict への対処不要なメトリクスやトレースを除外したいInternalOperation とはどういう意味か.NET アプリケーションのログ記録を有効にするにはどうすればよいですか。.NET アプリケーションにおけるアセンブリバージョンの競合を解決するにはどうすればよいですか。FluentBit を無効にできるかコンテナログをフィルタリングしてから CloudWatch Logs にエクスポートしてもよいですか。

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

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

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

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

  • アプリケーションが別のモニタリングソリューションによって計測されていないかを確認します。Application Signals は、他の計測ソリューションと共存できない場合があります。

  • アプリケーションが 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" を削除し、アプリケーションを再デプロイします。その後、アプリケーションが動作するかどうかを確認します。

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_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 にエクスポートしてもよいですか。

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