Cloud Monitor:Python エージェント接続後にデータが表示されない場合のトラブルシューティング

基本確認

次の各設定を確認します。

• ARMS アプリケーションのデータ収集設定が無効になっているかどうか。

• アプリケーションのエージェントマスタースイッチが無効になっているかどうか。

• アプリケーションが無料トライアルを使用しているか、およびトライアルのトラフィッククォータを使い果たしているかどうか。

• アプリケーションがOTEL_SDK_DISABLED 環境変数をtrueに設定しているかどうか。

次のコマンドを実行して、これらの項目を確認します。コマンド内のコメントは、各確認の目的を説明しています。

# ARMS APM サービスのステータスを確認
aliyun arms CheckCommercialStatus \
  --RegionId <リージョン ID> \
  --Service apm

# アプリケーション名で ARMS アプリケーションをクエリ
aliyun arms SearchTraceAppByName \
  --RegionId <リージョン ID> \
  --TraceAppName <アプリケーション名>

# エージェントマスタースイッチをクエリ。--Enable を省略してクエリのみ実行
aliyun arms ConfigApp \
  --RegionId <リージョン ID> \
  --AppIds <アプリケーション PID> \
  --Type TRACE

# Kubernetes シナリオ：Pod設定でスイッチを確認
kubectl get pod -n <ネームスペース> <ポッド名> -o yaml

# Kubernetes シナリオ：プロセスが実際に継承する環境変数を確認
kubectl exec -n <ネームスペース> <ポッド名> -c <コンテナ名> -- \
  sh -c 'tr "\0" "\n" </proc/1/environ'

# ECS またはホストシナリオ：Python プロセスの環境変数を確認
PID=<Python プロセス ID>
tr '\0' '\n' <"/proc/$PID/environ"

ネットワーク接続性の確認

アプリケーションモニタリングのネットワーク設定を参照して、アプリケーションの実行環境からサーバーへのネットワーク接続性を確認してください。データ報告用のネットワーク接続が利用できない場合、コンソールにモニタリングデータは表示されません。

ARMS 環境変数の確認

自動および手動のいずれのインストルメンテーションシナリオでも、ARMS 環境変数 (ARMS_APP_NAME、ARMS_LICENSE_KEY、ARMS_REGION_ID、およびARMS_WORKSPACE (オプション)) が設定され、期待される値が含まれていることを確認する必要があります。値が以前に確認した設定と異なる場合、これらの環境変数が上書きされています。これらの環境変数設定を削除してください。

Kubernetes シナリオでは、まず関連する環境変数がポッド Spec に注入されているかどうかと、その valueFrom ソースを確認してから、プロセスが実際に継承する環境変数を確認します。ECS またはホストシナリオでは、Python プロセスの環境変数を直接確認します。

# ポッド Spec 内の関連環境変数とその valueFrom ソースを表示
kubectl get pod -n <ネームスペース> <ポッド名> \
  -o jsonpath='{range .spec.containers[*]}{"container="}{.name}{"\n"}{range .env[*]}{.name}{"="}{.value}{" secret="}{.valueFrom.secretKeyRef.name}{"/"}{.valueFrom.secretKeyRef.key}{" field="}{.valueFrom.fieldRef.fieldPath}{"\n"}{end}{end}'

# プロセスが実際に継承する環境変数を表示
kubectl exec -n <ネームスペース> <ポッド名> -c <コンテナ名> -- \
  sh -c 'tr "\0" "\n" </proc/1/environ'

# ECS またはホスト
PID=<Python プロセス ID>
tr '\0' '\n' <"/proc/$PID/environ"
readlink -f "/proc/$PID/exe"
tr '\0' ' ' <"/proc/$PID/cmdline"; echo

Kubernetes 自動インストルメンテーションの確認

前提条件に従ってターゲットクラスターに接続し、次の確認を順番に実行します。

1. クラスター内の ack-onepilot のバージョンを確認します。

   # ack-onepilot 関連リソースを検索
   kubectl get deployment,daemonset,pod -A -o wide
   
   # ack-onepilot ワークロードで使用されるイメージとバージョンを表示
   kubectl get deployment,daemonset -A \
     -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,IMAGES:.spec.template.spec.containers[*].image'

   確認結果に応じて、次のように対応します。

   • ack-onepilot がクラスターにインストールされていない場合は、まずコンポーネントをインストールしてください。インストール方法については、リファレンスに移動し、「ACK および ACS クラスターに ARMS Python エージェントをインストールする」を開いてください。

   • ack-onepilot のバージョンが 5.0.0 より前の場合：手動インストルメンテーションの確認に進みます。

   • ack-onepilot のバージョンが 5.0.0 以降の場合：次のステップに進みます。

2. kubectl logs コマンドを使用して ack-onepilot ログを表示します。kubectl get pod -A を使用して ack-onepilot のネームスペースなどの情報を表示し、getArmsLicenseKey および GetServiceObservabilityInfoByWorkspace に関連するログに注目します。

   # コンポーネントのPodとコンテナ名を表示
   kubectl get pod -A -o wide
   kubectl get pod -n <ack-onepilot ネームスペース> <ack-onepilot-ポッド> \
     -o jsonpath='{range .spec.containers[*]}{.name}{"\n"}{end}'
   
   # 最近のログを表示。実際のログ内容に基づいて検索し、範囲を絞り込む
   kubectl logs -n <ack-onepilot ネームスペース> <ack-onepilot-ポッド> \
     --all-containers=true --since=2h --timestamps
   
   # コンポーネントが再起動した場合、以前のコンテナログを表示
   kubectl logs -n <ack-onepilot ネームスペース> <ack-onepilot-ポッド> \
     -c <コンテナ名> --previous --tail=500
   
   kubectl describe pod -n <ack-onepilot ネームスペース> <ack-onepilot-ポッド>
   kubectl get events -n <ack-onepilot ネームスペース> \
     --sort-by='.metadata.creationTimestamp'

   関連するログにエラーが含まれている場合、コンポーネントはサーバーにアクセスできません。具体的なエラーを記録し、対応する AccessKey ペアの権限不足やネットワーク接続の問題など、考えられる原因を分析します。

3. インストルメンテーション対象の特定のポッドを特定し、kubectl コマンドを実行してポッドの YAML を表示します。PYTHONPATH 環境変数が注入されているかどうかを確認します。注入されていない場合は、手動インストルメンテーションのシナリオに該当します。手動インストルメンテーションの確認に進みます。

   kubectl get pod -n <ネームスペース> <ポッド名> -o yaml
   
   kubectl get pod -n <ネームスペース> <ポッド名> \
     -o jsonpath='{range .spec.containers[*]}{"container="}{.name}{"\n"}{range .env[?(@.name=="PYTHONPATH")]}{.name}{"="}{.value}{"\n"}{end}{end}'

4. PYTHONPATH が注入されている場合、ポッドにARMS_APP_NAME、ARMS_LICENSE_KEY、ARMS_REGION_ID、およびARMS_WORKSPACE (オプション) も期待される値で注入されていることを確認します。確認コマンドと値の解釈方法については、ARMS 環境変数の確認を参照してください。

5. kubectl logs コマンドを使用して、アプリケーションポッドのone-pilot-initcontainer init コンテナのログを表示します。init コンテナからpip3 not foundのようなメッセージが出力される場合、ランタイムイメージに pip3 が含まれておらず、Python パッケージをインストールできません。ランタイムイメージに pip3 をインストールするか、代わりに手動インストルメンテーションを使用してください。

   # initコンテナ名、イメージ、実行状態をリスト
   kubectl get pod -n <ネームスペース> <ポッド名> \
     -o jsonpath='{range .spec.initContainers[*]}name={.name}{" image="}{.image}{"\n"}{end}'
   kubectl get pod -n <ネームスペース> <ポッド名> \
     -o jsonpath='{range .status.initContainerStatuses[*]}name={.name}{" ready="}{.ready}{" restarts="}{.restartCount}{" state="}{.state}{" lastState="}{.lastState}{"\n"}{end}'
   
   # 現在および以前の initコンテナログを表示
   kubectl logs -n <ネームスペース> <ポッド名> \
     -c <エージェント init-container 名> --timestamps
   kubectl logs -n <ネームスペース> <ポッド名> \
     -c <エージェント init-container 名> --previous --tail=500

6. アプリケーションポッドが正常に起動するかどうかを確認します。

   • ポッドは正常に起動するが、接続後にデータがレポートされない場合：ポッド内の Python エージェントログを特定します。自動インストルメンテーションシナリオでは、エージェントログは通常/home/admin/.opt/.apsara-apm/python/logs ディレクトリに保存されます。aliyun-python-agent-*.log および diagnose-*.log を確認して、潜在的な問題を特定します。ログをARMS アプリケーションモニタリングでサポートされる Python コンポーネントとフレームワークと併せて使用して、Python バージョンまたは関連フレームワークがサポートされているかどうかを判断します。

     # エージェントログディレクトリと最近のログを表示
     kubectl exec -n <ネームスペース> <ポッド名> -c <コンテナ名> -- \
       sh -c '
         LOG_DIR=/home/admin/.opt/.apsara-apm/python/logs
         ls -lah "$LOG_DIR"
         for file in "$LOG_DIR"/*.log; do
           [ -f "$file" ] && {
             echo "== $file =="
             tail -n 200 "$file"
           }
         done
       '
     
     # アプリケーションが実際に使用する Python インタプリタ、sys.path、依存関係を確認
     kubectl exec -n <ネームスペース> <ポッド名> -c <コンテナ名> -- \
       sh -c '
         command -v python || command -v python3
         python -V 2>&1 || python3 -V
         python -m site 2>&1 || python3 -m site
         python -m pip freeze 2>&1 || python3 -m pip freeze
       '

   • ポッドの起動に失敗する場合：kubectl logs --previous コマンドを使用して、前回終了したコンテナのログを表示し、起動失敗の原因を分析します。

     kubectl logs -n <ネームスペース> <ポッド名> \
       -c <コンテナ名> --tail=500 --timestamps
     kubectl logs -n <ネームスペース> <ポッド名> \
       -c <コンテナ名> --previous --tail=500 --timestamps
     
     kubectl get pod -n <ネームスペース> <ポッド名> \
       -o jsonpath='{range .status.containerStatuses[*]}name={.name}{" ready="}{.ready}{" restarts="}{.restartCount}{" state="}{.state}{" lastState="}{.lastState}{"\n"}{end}'
     
     kubectl describe pod -n <ネームスペース> <ポッド名>
     kubectl get events -n <ネームスペース> \
       --field-selector involvedObject.name=<ポッド名> \
       --sort-by='.metadata.creationTimestamp'

# パッケージのインストールパスを表示
python3 -m site

# 依存関係の競合と実際にロードされる場所を確認
python3 -m pip check
python3 -c '
import google.protobuf
print(google.protobuf.__version__)
print(google.protobuf.__file__)
'

# PYTHONPATH 環境変数を設定して、ユーザーがインストールした依存関係バージョンを優先
# 異なるパスはコロンで区切る
export PYTHONPATH=/app:/usr/local/lib/python3.9:/usr/local/lib/python3.9/site-packages

手動インストルメンテーションの確認

前提条件に従って、アプリケーションのデプロイ場所を確認し、対応する認証情報を準備します。ECS にデプロイされたアプリケーションの場合、次のコマンドを使用して、Alibaba Cloud ECS インスタンスで確認コマンドを送信して実行します。

COMMAND='
ps -ef
command -v python || command -v python3
command -v aliyun-bootstrap || true
command -v aliyun-instrument || true
python -V 2>&1 || python3 -V 2>&1
python -m site 2>&1 || python3 -m site 2>&1
'

aliyun ecs RunCommand \
  --RegionId <リージョン ID> \
  --InstanceId.1 <ECS インスタンス ID> \
  --Type RunShellScript \
  --ContentEncoding Base64 \
  --Timeout 60 \
  --CommandContent "$(printf %s "$COMMAND" | base64 | tr -d '\n')"

# RunCommand から返された InvokeId を使用して実行結果をクエリ
aliyun ecs DescribeInvocationResults \
  --RegionId <リージョン ID> \
  --InvokeId <InvokeId>

Alibaba Cloud ACK のポッドにデプロイされたアプリケーションの場合、kubeconfig ファイルを取得してから、kubectl で以降の確認コマンドを実行します。次の順序で確認します。

1. 対応する Python プロセスのARMS_APP_NAME、ARMS_LICENSE_KEY、ARMS_REGION_ID、およびARMS_WORKSPACE (オプション) 環境変数が設定され、期待される値が含まれていることを確認します。確認コマンドと値の解釈方法については、ARMS 環境変数の確認を参照してください。

2. aliyun-bootstrap -a install コマンドが正常に実行されたかどうか、および関連するパッケージがアプリケーションのsys.path にインストールされているかどうかを確認します。

   重要

   常に、アプリケーションの Python 依存関係パスでaliyun-bootstrap -a install を実行してください。そうしないと、アプリケーションは実行時にパッケージを見つけることができません。たとえば、アプリケーションが Python venv で実行される場合、エージェントもその Python venv にインストールする必要があります。

   # 現在のインタプリタとインストール場所を確認
   command -v python
   python -V
   python -m pip --version
   python -m site
   command -v aliyun-bootstrap
   command -v aliyun-instrument
   
   # 現在の環境で関連する Python パッケージを表示
   python -m pip freeze
   
   # 仮想環境シナリオ
   source /path/to/venv/bin/activate
   which python
   python -m pip --version
   
   # 環境が正しいことを確認した後にのみインストールを実行
   aliyun-bootstrap -a install
   
   # 実際のアプリケーション起動コマンドを確認
   PID=<Python プロセス ID>
   tr '\0' ' ' <"/proc/$PID/cmdline"; echo

3. インストールが成功し、アプリケーションも正常に起動した場合は、Python エージェント FAQ を参照して Python エージェントログを探します。ログをARMS アプリケーションモニタリングでサポートされる Python コンポーネントとフレームワークと併せて使用して問題をトラブルシューティングし、Python バージョンまたは関連フレームワークがサポートされているか、またはログが別の原因を示しているかを判断します。

   # 一般的なログディレクトリ
   LOG_DIR=/home/admin/.opt/.apsara-apm/python/logs
   ls -lah "$LOG_DIR"
   
   # まずログを読み、次に実際のコンテキストに基づいて検索
   for file in "$LOG_DIR"/*.log; do
     [ -f "$file" ] && {
       echo "== $file =="
       tail -n 200 "$file"
     }
   done
   
   # ログディレクトリが不明な場合、ファイル名で検索
   find /home /opt /tmp -type f \
     \( -name 'aliyun-python-agent-*.log' -o -name 'diagnose-*.log' \) \
     2>/dev/null

diagnose-*.log には、詳細なプロセス情報が含まれています。

1. サーバーとそのパラメータを含むプロセス起動コマンド。

2. importlib.metadata.packages_distributions() で取得したプロセスの pip 依存関係。

3. aliyun-bootstrap で使用されるインストール場所。

4. Python インタプリタのバージョン。

5. データ報告用のネットワーク接続性。

6. プラグインが正常にインストルメンテーションされたかどうか。

7. シナリオで gevent を使用しているかどうか。

8. エージェントのアプリ名、アプリ ID、ワークスペース。

9. 正常にインストルメンテーションされたプラグインと失敗したプラグインのリスト。