このよくある質問では、Python エージェントに関する一般的な質問にお答えします。
aliyun-bootstrap -a install によるインストールの失敗
aliyun-bootstrap -a install コマンドでエージェントをインストールすると、次のエラーが発生することがあります：
Installation aborted due to download failure.この失敗には、通常、次の2つの原因が考えられます：
-
ネットワークの問題により、エージェントが OSS エンドポイントに到達できません。ネットワーク接続を確認してください。
Starting Aliyun Python Agent installation...
agent download url: https://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/aliyun-python-agent/aliyun-python-agent.tar.gz
Checking network connectivity...
Downloading agent from https://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/aliyun-python-agent/aliyun-python-agent.tar.gz...
Downloading: 100%|████████████████████████████████████████████████████████████| 1.00M/1.00M [00:00<00:00, 6.21MB/s]
Extracting wheels from archive...
Extracting files: 100%|███████████████████████████████████████████████████████| 27/27 [00:00<00:00, 2151.05file/s]
Found 27 wheel files
Installing 27 packages...
Installing packages: 0%| | 0/27 [00:00<?, ?pkg/s]
Installing packages: 0%| | 0/27 [00:00<?, ?pkg/s]-
Python インタープリターに SSL モジュールがありません。
python3 -m sslこのコマンドでエラーが発生する場合は、Python インタープリターに SSL モジュールがないことを意味します。aliyun-bootstrap スクリプトは依存関係のダウンロードにこのモジュールを必要とするため、Python 環境にインストールする必要があります。
起動エラー： No module named 'aliyun'
このエラーは、アプリケーションがランタイムにエージェントを見つけられない場所にインストールされていることが原因です。アプリケーションの環境で、Python インタープリターが Python エージェントの依存関係を見つけられるようにしてください。
アプリケーションの環境で次のコマンドを実行し、aliyun-bootstrap がエージェントパッケージを検索可能なパスにインストールしたことを確認してください：
python3 -m siteこのコマンドは、Python インタープリターがパッケージを見つけるために使用する検索パスを出力します。以下のディレクトリ構造の例に示すように、これらのパスのいずれにも Python エージェントの依存関係が見つからない場合、インストールの場所が正しくありません。
.venv
bin
lib
python3.12
site-packages library root
_distutils_hack
aliyun
instrumentation
opentelemetry
sdk
semconv
__init__.py
aliyun_instrumentation_dashscope-1.0.0.dist-info
aliyun_instrumentation_dify-1.1.0.dist-info
aliyun_instrumentation_langchain-1.1.0.dist-info
aliyun_instrumentation_llama_index-1.0.3.dev0.dist-info
aliyun_instrumentation_openai-1.0.1.dist-info
aliyun_instrumentation_vllm-0.1.0.dist-info
aliyun_opentelemetry_exporter_otlp_proto_common-1.25.0.dist-info
aliyun_opentelemetry_exporter_otlp_proto_grpc-1.25.0.dist-info
aliyun_opentelemetry_exporter_otlp_proto_http-1.25.0.dist-info
aliyun_opentelemetry_instrumentation-0.46b0.dev0.dist-info
aliyun_opentelemetry_instrumentation_aiohttp_client-0.46b0.dev0.dist-info
aliyun_opentelemetry_instrumentation_asgi-0.46b0.dev0.dist-info
aliyun_opentelemetry_instrumentation_django-0.46b0.dev0.dist-info
aliyun_opentelemetry_instrumentation_fastapi-0.46b0.dev0.dist-info
aliyun_opentelemetry_instrumentation_flask-0.46b0.dev0.dist-info
aliyun_opentelemetry_instrumentation_httpx-0.46b0.dev0.dist-info
aliyun_opentelemetry_instrumentation_logging-0.46b0.dev0.dist-info
aliyun_opentelemetry_instrumentation_redis-0.46b0.dev0.dist-info次のコマンドを使用して、aliyun-bootstrap パッケージのインストール場所を指定できます：
aliyun-bootstrap -a install -t ${TARGET_PATH}${TARGET_PATH} をご使用の環境の正しいパスに置き換えてください。たとえば、パスは /root/demo/venv/lib/python3.12/site-packages のようになります。
Flask アプリケーションでデータが報告されない問題
デバッグモードが有効な場合、aliyun-instrument メソッドを使用して Flask アプリケーションを統合することはできません。代わりに、Flask アプリケーションのエントリファイルに次のステートメントを追加して、Python エージェントを手動でインポートする必要があります。これにより、aliyun-instrument プレフィックスを追加せずにアプリケーションを起動できます。
from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomizeDjango アプリケーションの起動失敗
Django アプリケーションの起動に失敗し、AttributeError: module 'django.conf global_settings' has no attribute 'ROOT_URLCONF' のようなエラーが表示される場合は、DJANGO_SETTINGS_MODULE 環境変数をプロジェクトの設定モジュールに設定してください。
export DJANGO_SETTINGS_MODULE=instrumentation_example.settingsDjango アプリケーションでデータが報告されない問題
python manage.py runserver 0.0.0.0:8080 のようなコマンドでデフォルトで有効になる Django のホットリロード機能は、エージェントがデータを報告するのを妨げる可能性があります。これを修正するには、--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 エージェントのバージョンが 1.6.0 以降であることを確認してください。その後、APSARA_APM_AGENT_WORKSPACE_DIR 環境変数を設定できます。エージェントは、ログファイルを ${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 エントリファイルと同じディレクトリ)
ネットワーク報告モードの指定
エージェントのバージョンが 1.6.0 以降の場合、PROFILER_NETWORK_STRATEGY 環境変数を設定してネットワーク報告モードを指定できます：
-
internal：内部ネットワーク報告を強制します。 -
public：パブリックネットワーク報告を強制します。 -
auto：ネットワークモードを自動的に検出します (デフォルトの動作)。
OpenAI ストリーミングにおけるトークン使用量の取得
詳細については、「ストリーミング出力」をご参照ください。デフォルトでは、OpenAI プロトコルはストリーミングコールでトークン使用量を返しません。この情報を受け取るには、stream_options={"include_usage": true} を設定して、最後のデータチャンクにトークン使用量の詳細が含まれるようにします。
子プロセスへのエージェントインジェクションの防止
ターゲットアプリケーションによって作成された子プロセスにエージェントがインジェクトされるのを防ぐには、APSARA_APM_INSTRUMENTATION_CHILD_PROCESS 環境変数を false に設定してください。