このドキュメントでは、Python エージェントに関するよくある質問 (FAQ) について説明します。
aliyun-bootstrap -a install を使用したエージェントのインストール失敗
aliyun-bootstrap -a install コマンドを使用してエージェントのインストールに失敗すると、次のエラーメッセージが表示されます：
Installation aborted due to download failure.この失敗は、通常、次の 2 つの理由のいずれかが原因で発生します：
エージェントの OSS エンドポイントとのネットワーク接続に問題があります。ご利用のネットワークからエージェントの OSS エンドポイントへの接続を確認してください。
Python インタープリターが ssl モジュールなしでインストールされています。これを確認するには、次のコマンドを実行します：
python3 -m sslこのコマンドがエラーを返す場合、ssl モジュールが欠落しています。aliyun-bootstrap ツールは、依存関係をダウンロードするために ssl モジュールを必要とします。この問題を解決するには、Python 環境に ssl モジュールをインストールしてください。
インストール成功後、「No module named 'aliyun'」エラーによるアプリケーションの起動失敗
このエラーは、エージェントが、アプリケーションの Python インタープリターがランタイムに見つけられない場所にインストールされたことを示します。これを解決するには、Python エージェントの依存関係が、アプリケーションの Python インタープリターから検出可能なパスにあることを確認してください。
アプリケーションのランタイム環境で次のコマンドを実行して、エージェントパッケージが正しい場所にインストールされていることを確認できます：
python3 -m siteこのコマンドは、Python インタープリターがパッケージを検索するために使用する検索パスを出力します。次の図に示すような Python エージェントの依存関係がこれらのパスのいずれにもない場合、aliyun-bootstrap がパッケージを間違った場所にインストールしたことを意味します。
次のコマンドを使用して、aliyun-bootstrap の正しいインストール場所を指定できます：
aliyun-bootstrap -a install -t ${TARGET_PATH}${TARGET_PATH} を正しいパッケージパスに置き換えてください。たとえば、前の図に基づくと、${TARGET_PATH} は /root/demo/venv/lib/python3.12/site-packages です。
Flask アプリケーションでデータがレポートされない
デバッグモードの Flask アプリケーションは、`aliyun-instrument` を使用して統合することはできません。代わりに、次の文を Flask のエントリファイルに追加して、Python エージェントを手動でインポートできます。その後、`aliyun-instrument` プレフィックスなしでアプリケーションを起動します。
from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomizeイベントトラッキング後の Django アプリケーションの起動失敗
Django アプリケーションの起動に失敗し、AttributeError: module 'django.conf global_settings' has no attribute 'ROOT_URLCONF' のような起動エラーが表示される場合は、DJANGO_SETTINGS_MODULE 環境変数をプロジェクトの設定モジュールの名前に設定してください。
export DJANGO_SETTINGS_MODULE=instrumentation_example.settingsDjango アプリケーションでデータがレポートされない
Django の自動再読み込み機能は、python manage.py runserver 0.0.0.0:8080 のようなコマンドでアプリケーションを起動すると、デフォルトで有効になります。--noreload オプションを追加して、この機能を無効にすることができます：
python manage.py runserver 0.0.0.0:8080 --noreloadUvicorn サーバーを使用するアプリケーションでデータがレポートされない
Uvicorn サーバーで --reload パラメーターを使用してホットリロードを有効にするか、--workers パラメーターを使用して複数のワーカーを起動すると、エージェントはデータをレポートできません。これを修正するには、次の文をアプリケーションのエントリファイルに追加して、Python エージェントを手動でインポートします。アプリケーションを起動するときに、aliyun-instrument プレフィックスを追加する必要はありません。
from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomizeエージェントのアンインストール
Python エージェントをアンインストールするには、次のコマンドを実行します：
aliyun-bootstrap -a uninstall特定リージョンおよびバージョンのプローブのインストール
最適なエクスペリエンスを得るために、最も近いリージョンから特定バージョンのエージェントをインストールする必要がある場合があります。手順は次のとおりです：
ARMS_REGION_ID 環境変数を設定して、エージェントをプルするリージョンを指定します。例：
export ARMS_REGION_ID=cn-beijingサポートされているすべてのリージョンの一覧については、「利用可能なリージョン」をご参照ください。
次のコマンドを実行して、特定のバージョンの Python エージェントをインストールします。別のバージョンがインストールされている場合は、まずそれをアンインストールする必要があります。
# ${version} を実際のバージョン番号に置き換えます。
aliyun-bootstrap -a install -v ${version}「Container Service for Kubernetes (ACK) および Container Compute Service (ACS) の ack-onepilot コンポーネントを使用した Python エージェントのインストール」で説明されている非侵入型メソッドを使用して Python エージェントをインストールする場合は、「エージェントバージョンの手動制御」をご参照のうえ、aliyun.com/agent-version タグを追加してエージェントのバージョン番号を指定できます。
公開されているすべての Python エージェントのバージョンの一覧については、「Python エージェントバージョンガイド」をご参照ください。
Python エージェントのログディレクトリの指定
Python エージェント V1.6.0 以降では、APSARA_APM_AGENT_WORKSPACE_DIR 環境変数を設定して、カスタムログディレクトリを指定できます。Python エージェントは、ログファイルを ${APSARA_APM_AGENT_WORKSPACE_DIR}/.apsara-apm/python/logs ディレクトリに保存します。
デフォルトでは、プローブは次の優先順位に基づいてログディレクトリを選択します：
/home/admin/.opt/.apsara-apm/python/logs (ack-onepilot のボリュームディレクトリ)
~/.apsara-apm/python/logs (ユーザーのホームディレクトリ)
./.apsara-apm/python/logs (メインの Python ファイルと同じディレクトリ)
Python エージェントのネットワークモードの指定
エージェントバージョン 1.6.0 以降では、PROFILER_NETWORK_STRATEGY 環境変数を設定して、データレポートのネットワークモードを指定できます：
internal：エージェントが内部ネットワーク経由でデータをレポートするように強制します。
public：エージェントがパブリックネットワーク経由でデータをレポートするように強制します。
auto：ネットワークモードを自動的に検出します。これはデフォルトの動作です。