Docker における「.NET 」トレースのトラブルシューティング

オンラインで編集

トレースが期待通りに機能しない場合は、具体的なケースごとの対応に移る前に、まず一般的なトラブルシューティングの手順から始めてください。

一般的なトラブルシューティング

オンラインで編集

以下のステップを実行します。

  1. 前提条件を確認してください：

    • .NET のバージョン互換性を確認してください：お使いのアプリケーションが、.NET Core Runtime 5.0 以降で動作することを確認してください。

    • Instana エージェントが実行されており、コンテナからアクセス可能であることを確認してください：

      • Instana のUIでエージェントの状態を確認してください。
      • コンテナ内からエージェントのホストおよびポートへのネットワーク接続を確認します。

  2. 以下の Instana トレースパッケージがインストールされており、最新の状態であることを確認してください：

    • Instana.Tracing.Core
    • Instana.Tracing.Core.Rewriter.Linux

  3. Docker の設定において、以下の重要な Instana 環境変数が正しく設定されていることを確認してください：

    INSTANA_AGENT_HOST=<instana-agent-host>
INSTANA_AGENT_PORT=42699
CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={cf0d821e-299b-5307-a3d8-b283c03916dd}
CORECLR_PROFILER_PATH=/opt/instana/netcore/Instana.Tracing.Profiler.Native.so

  4. IL-Rewriterが正しく読み込まれているか確認するには、以下を実行してください：

    1. アプリケーションログを確認し、IL-Rewriterの初期化メッセージがないか確認してください。 正常に実行された場合の期待される出力：

      *Initializing Instana IL-Rewriter for .NET Core*
*Logging path is not set*
*Loading configuration-file /app/instana_tracing/instrumentation.json*
      注： 環境によってはパスが異なる場合があります。

    2. 「IL-Rewriter」の行が表示されない場合は、必要な CORECLR 環境変数がすべて正しく設定され、アプリケーションから利用可能になっていることを確認してください。

      • CORECLR_ENABLE_PROFILING
      • CORECLR_PROFILER_PATH
      • CORECLR_PROFILER
  5. 1.NET で診断機能が有効になっていることを確認してください：環境変数 COMPlus_EnableDiagnostics および DOTNET_EnableDiagnostics が に設定されていることを確認してください。 これらが無効になっている場合、IL-Rewriterはプロセスにアタッチできないため、呼び出しの書き換えやトレースの生成を行うことができません。

ケースごとのトラブルシューティング

オンラインで編集

一般的なトラブルシューティングを行っても問題が解決しない場合は、以下のトラブルシューティング手順をご確認ください：

シナリオ 1：トレースまたはスパンの欠落

オンラインで編集

症状： アプリケーションにメトリクスは表示されるがトレースが表示されない、一部のサービスは報告されるが他のサービスは報告されない、あるいはデプロイや更新後にトレースが停止する。

トラブルシューティングの手順

  1. .NET 版アプリケーションがサポートされていることを確認してください：

    • .NET Core 動作環境： 5.0 以降
  2. Docker の 「.NET トレースの設定」にある設定例に従い、Dockerfileに環境変数が設定されていることを確認してください。
  3. 環境変数に使用されるパスが有効であり、プロセスまたはアプリケーションからアクセス可能で、かつ正しいものであることを確認してください。
  4. エージェント configuration.yaml ファイルでトレースが有効になっていることを確認してください。
  5. 「ログの収集 」に記載されている方法に従って、トレースログを収集してください。

  6. Instana のトレースログを確認してください：

    • ログが空であるか、トレースが表示されない場合は、アプリケーションがスパンを生成していないことを意味します。
    • ログにトレースは記録されているものの、情報（ホスト名など）が欠落している場合は、.NET のトレース機能に問題があります。
    • ログにトレースが記録されており、その情報にUIには表示されていない内容が含まれている場合、問題は Instana のバックエンドまたはエージェントのいずれかで発生したことになります。

シナリオ 2： Instana エージェントの追加後にアプリケーションコンテナがクラッシュする

オンラインで編集

症状：Instana エージェントを追加するとアプリケーションコンテナがクラッシュするが、エージェントを削除すると正常に動作する。

トラブルシューティングの手順

  1. .NET 版アプリケーションがサポートされていることを確認してください：

    • .NET Core 動作環境： 5.0 以降

  2. コンテナのログを収集する：

    docker logs <container_name_or_id> > container.log

  3. さらなる分析のためにダンプファイルを収集する：

    docker exec -it <container> \
/usr/share/dotnet/shared/Microsoft.NETCore.App/*/createdump \
-p 1 \
-o /tmp/sampleapp.dmp
  4. Instana が問題の原因となっている可能性を示す例外がログに記録されていないか確認してください。

ログの収集

オンラインで編集

Log Collectorは、 Docker コンテナでホストされているアプリケーションでは動作しません。 したがって、ログは手動で収集する必要があります。

Instana 手動でログを収集するために、以下のメソッドが用意されています：

ログを手動で収集する

オンラインで編集

以下のステップを実行します。

  1. Dockerfile に以下の環境変数を追加して、デバッグログを有効にしてください：

    注： パスが有効であり、プロセスまたはアプリケーションからアクセス可能で、かつ正しいものであることを確認してください。
    ENV INSTANA_LOG_SPANS=1
ENV INSTANA_DEBUG_TRACER=1
ENV INSTANA_NET_LOG_PATH="<Log_path>"
ENV INSTANA_NET_LOG_LEVEL=DEBUG
ENV INSTANA_TRACER_ENTEREXIT_LOGGING=1
ENV INSTANA_EXTENDED_DEBUG=1
ENV INSTANA_CLRLOG_PATH=/var/tmp/clr_
  2. アプリケーションを再起動し、呼び出しを実行してください。

  3. 以下のログを収集し、調査してください：

    • CLRデバッグログ
    • Instana エージェントのデバッグログ
    • Instana エージェントがログを追跡する
    • Docker コンテナのログ

  4. Instana エージェントのログを収集するには、以下の手順を実行してください：

    1. エージェントを停止します。

      systemctl stop instana-agent.service

    2. ログを削除する：以下のコマンドを実行して、ログディレクトリ内のすべてのファイルを削除し、状態をリセットします

      sudo rm -rf /data/logs/*
    3. ログレベルを「Debug」に設定する：エージェント configuration.yaml ファイルでログレベルの深刻度を変更します。 詳細については、 「エージェント設定ファイルの設定」 を参照してください。
    4. エージェントを開始します。
    5. 問題の再現手順：問題が発生する状態にし、エージェントを約15分間実行させてください。

    Instana エージェントは、 Docker によって管理されるコンソールにログを出力します。このログは、 Docker logs から確認できます。

  5. Instana のトレースログを収集するには、以下の手順を実行してください：

    1. com.instana.agent.main.sender.File.cfgGo …に [agent-dir]\etc\instana アクセスして、ファイルを開きます。

    2. ファイルに次の行を追加してください：

      prefix=instanaTraces
type=traces

      この設定により、接頭辞「 instanaTraces 」が付いたすべてのトレースが [agent-dir]/data/log 記録されたログファイルが提供されます。

    3. instana エージェントを再始動します。
    4. アプリケーションを再起動します。
    5. アプリケーションを約15分間実行してください。

    6. 以下のパスからログを収集してください：

      • 変数で指定されたパス INSTANA_NET_LOG_PATH
      • instana-agent-installation-folder/data/log

  6. Docker のコンテナログを収集するには、次のコマンドを実行してください：

    docker logs <container_name_or_id> > container.log

Docker のバインドマウントを使用して手動でログを収集する（推奨される方法）

オンラインで編集

.NET のTracerログおよびCLRデバッグログを収集するには、既存のホストパスを使用した Docker のバインドマウントを使用してください。

以下のステップを実行します。

  1. コンテナに対して書き込み権限を持つ有効なホストパスが設定されていることを確認してください。

  2. 次の例に示すように、Bind Mount を使用し、.NET の Tracer および CLR デバッグログのパス環境変数をマッピングされたパスを指すように設定して、 Docker コンテナを実行してください

    注： パスが有効であり、プロセスまたはアプリケーションからアクセス可能で、かつ正しいものであることを確認してください。
    docker run -d \
    -p 8080:8080 \
    -v /var/log/instana:/var/tmp \
    --env=INSTANA_CLRLOG_PATH="/var/tmp/clr_" \
    --env=INSTANA_NET_LOG_PATH="/var/tmp" \
    --name sampleapp \
    myuser/sampleapp:v2.0
  3. アプリケーションを再起動し、呼び出しを実行してください。
  4. /var/log/instanaホストパスからログを収集します。

サポート・チケットのオープン

オンラインで編集

これらのトラブルシューティング手順を実行しても問題が解決しない場合は、サポートチケットを送信する前に、 MustGather のデータを収集してください。 MustGather このデータは、 IBM サポートが問題をより効率的に診断するのに役立ちます。

詳細については、 MustGather:、 Instana、.NET、Tracer - Docker をご覧ください。